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

# API recipes

> Copy-paste, end-to-end examples for common Solya API flows — in cURL, Python, and JavaScript.

Practical, runnable examples for the most common integration flows. They build on the
concepts in [API integration](/en/developers/overview) — base URL, auth, pagination, and
the response envelope.

<CardGroup cols={2}>
  <Card title="Read data" icon="download" href="/en/developers/recipes/read-data">
    List the catalog, paginate, and read inventory risks.
  </Card>

  <Card title="Create a plan" icon="upload" href="/en/developers/recipes/create-a-plan">
    Create a restock plan and add an item — the write flow.
  </Card>
</CardGroup>

## Before you start

* **Base URL** — `https://app.solya.app`; endpoints live under `/api/`.
* **Auth** — every request sends `Authorization: Bearer solya_sa_…` (a
  [service-account token](/en/developers/authentication)).
* **Envelope** — write/action responses use `{ "success": true, "data": … }` or
  `{ "success": false, "errorCode": … }`. Branch on `errorCode`, not on the text. See
  [Error codes](/en/developers/error-codes).

## Verify your token

A quick first call confirms the token resolves to the right organization and permissions.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl https://app.solya.app/api/auth/whoami \
      -H "Authorization: Bearer solya_sa_xxx"
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    BASE = "https://app.solya.app"
    TOKEN = "solya_sa_xxx"
    headers = {"Authorization": f"Bearer {TOKEN}"}

    r = requests.get(f"{BASE}/api/auth/whoami", headers=headers)
    r.raise_for_status()
    print(r.json())  # { authKind, organizationId, effectivePermissions, ... }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const BASE = "https://app.solya.app"
    const TOKEN = "solya_sa_xxx"
    const headers = { Authorization: `Bearer ${TOKEN}` }

    const res = await fetch(`${BASE}/api/auth/whoami`, { headers })
    if (!res.ok) throw new Error(`whoami failed: ${res.status}`)
    console.log(await res.json())
    ```
  </Tab>
</Tabs>

<Note>
  Prefer not to hand-write requests? Point an AI agent at the [MCP gateway](/en/mcp/overview)
  and it will discover and call these endpoints for you.
</Note>