> ## 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.

# Introduction

> Cloud API overview — authentication, response shape, and basics.

Orquestr exposes a Cloud API for customers, licenses, devices, functions, and saved SQL. A single API key authenticates all of it.

<Tabs>
  <Tab title="Cloud API">
    Manage customers, licenses, and devices, then list and invoke device functions.

    ```
    https://api.orquestr.dev/cloud/v1
    ```

    [Browse endpoints](/api/customers/create-customer)
  </Tab>
</Tabs>

## Authentication

Send your API key as a Bearer token:

```bash theme={"system"}
curl https://api.orquestr.dev/cloud/v1/customers \
  -H "Authorization: Bearer sk_live_…"
```

Use your `sk_live_…`. Create keys in the [Orquestr dashboard](https://app.orquestr.dev).

Keys can include optional `customer_id` / `license_id` / `device_id` filters that narrow which resources they can access.

## Response shape

Public Cloud API success responses use a consistent envelope. Errors are **not** wrapped in `data` — see [Errors](/errors).

### Single resource

Create, retrieve, update, revoke, and most deletes return the resource (or acknowledgment) under `data`:

```json theme={"system"}
{
  "data": {
    "id": "o2222222-2222-2222-2222-222222222222",
    "name": "Mi tienda",
    "owner_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "external_customer_id": "acme-store-01",
    "created_at": "2026-09-01T15:05:00.000Z",
    "updated_at": "2026-09-10T09:00:00.000Z"
  }
}
```

Deletes that previously returned `{ "ok": true }` now return `{ "data": { "ok": true } }`. Saved SQL `DELETE` stays **HTTP 204** with an empty body.

### Lists

List endpoints return an array under `data` plus pagination `meta`:

```json theme={"system"}
{
  "data": [
    {
      "id": "o2222222-2222-2222-2222-222222222222",
      "name": "Mi tienda",
      "owner_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "external_customer_id": "acme-store-01",
      "created_at": "2026-09-01T15:05:00.000Z",
      "updated_at": "2026-09-10T09:00:00.000Z"
    },
    {
      "id": "o3333333-3333-3333-3333-333333333333",
      "name": "Otra tienda",
      "owner_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "external_customer_id": "acme-store-02",
      "created_at": "2026-09-02T12:00:00.000Z",
      "updated_at": "2026-09-02T12:00:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total_pages": 1,
    "total_count": 2
  }
}
```

### Pagination query params

| Query      | Default          | Notes            |
| ---------- | ---------------- | ---------------- |
| `page`     | —                | Positive integer |
| `per_page` | `20` when paging | Max **100**      |

If **both** `page` and `per_page` are omitted, the API returns the **full** set. `meta` still reflects the full count (`total_pages: 1`, `per_page` equal to the result length, or the default when empty).

Some list responses add extra fields on `meta` (for example function list includes `device_id` and `adapter`).

## Before you start

* All requests are HTTPS. Plain HTTP is rejected
* Requests and responses are JSON
* [Rate limits](/api/rate-limits) apply **per API key** and depend on your plan