> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orquestr.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Invoke a function

> POST body shape, auth, and result handling.

# Invoke a function

```http theme={"system"}
POST /v1/devices/{device_id}/functions/{function_id}
Authorization: Bearer sk_live_…
Content-Type: application/json
```

## Body

```json theme={"system"}
{
  "input": {
    "q": "coca",
    "status": "1",
    "limit": "50"
  }
}
```

* Omit the body when the function declares no params (e.g. `device.health`).
* Field names must match the function's `params` schema from list functions.
* Values are typically **strings** (ids as `"1,2,3"`, limits as `"50"`). JSON document fields accept objects or JSON strings.
* Top-level `sql`, `operation`, or `params` are **forbidden** — use `input` fields from the registry.
* Unexpected keys in `input` → `400`.

## Response

```json theme={"system"}
{
  "data": {
    "device_id": "…",
    "function_id": "sicarv4.products.search",
    "operation": "db.query",
    "result": { }
  }
}
```

`result` is the Gateway/agent payload (rows, health body, or error), nested under `data`.

## Auth

Use an **API key** with scope `functions.invoke` (and access to the device):

```http theme={"system"}
Authorization: Bearer sk_live_…
```

## Write preflight

For `sqlPolicy: write` (all `*.create` registry functions), Cloud first runs a **read-only validation query** on the device. If FKs / uniqueness / stock checks fail → **HTTP 400** and the mutating SQL is **not** sent.

## Rate limits

Plan-based limits apply **per API key** (same ceiling as your account plan). See [Rate limits](/api/rate-limits).