# For AI agents

> Everything an AI agent needs to call the Stacksync API, on one screen

Source: https://docs.stacksync.com/api-reference/for-ai-agents

<Callout type="info">
  The whole API is one OpenAPI document, [`/openapi.json`](https://docs.stacksync.com/openapi.json), and every page of this reference is Markdown when you add `.md` to its URL.
</Callout>

| Topic     | Rule                                                                                                                                     |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Base URL  | `https://api.stacksync.com`; Genie runs: `https://genies.stacksync.com`                                                                  |
| Header    | `Authorization: Bearer <workspace_… or user_… API key>`; add `Content-Type: application/json` on `POST`, `PUT` and `PATCH`               |
| Workspace | `GET /v1/workspaces` returns each `workspace_id` and its `default_region`                                                                |
| Region    | Pass `region=<default_region>` (`besg` or `usnv`) on operations that list a `region` parameter; for an existing resource, its own region |
| Lists     | `limit` 1 to 200 (default 50) and `offset`; answer `{ "data": [], "has_more": false, "limit": 50, "offset": 0 }`                         |
| Retries   | Send an `Idempotency-Key` header on creates; `"validate_only": true` checks a write without writing (204)                                |
| Errors    | `{ "error", "msg", "field" }`; authentication failures are 403, never 401; retry `Unexpected Error` (400) later with backoff             |

## Read the reference

* Every operation page is Markdown: append `.md` to its URL, for example [`/api-reference/queues/list_queues.md`](https://docs.stacksync.com/api-reference/queues/list_queues.md), or request it with `Accept: text/markdown`.
* The OpenAPI 3.1 document: [`https://docs.stacksync.com/openapi.json`](https://docs.stacksync.com/openapi.json), and [`/openapi-genies.json`](https://docs.stacksync.com/openapi-genies.json) for Genie runs.
* The docs MCP server, `https://docs.stacksync.com/api/mcp`: `search` finds an operation, `get_page` returns its page as Markdown. See [Docs MCP server](/docs-for-ai/mcp-server).

## Act in a workspace

An AI assistant working for a person, rather than an integration with its own key, uses the [Stacksync MCP](/mcp): the person signs in, and their workspace's MCP Gateway Policies apply.