# API overview

This page describes the shape of the Slideshot HTTP API: where it lives, how to talk to it, and the conventions every endpoint follows. Use it as a quick reference before diving into a specific resource page.

## Base URL

Production requests go to:

```
https://api.slideshot.ai
```

All endpoints described in these docs sit under `/v1/`.

## Endpoint surface

Everything documented here lives under `/v1/agent/*`. These are agent-facing routes authenticated with an API key, and the CLI and MCP server call the same endpoints.

API key callers only see resources their key created. List endpoints filter by ownership automatically.

## Request and response shape

- Requests and responses use JSON. Set `Content-Type: application/json` when sending a body.
- Identifiers are UUIDs.
- Timestamps are ISO-8601 strings in UTC.
- List endpoints return `{ "data": [...] }`.
- Unknown keys inside option objects (like `options` on `POST /v1/agent/runs`) are accepted and ignored. Use the nested shapes documented on each resource page (`auth`, `video`, `artifacts`, `intro`).

## Errors

Errors are returned as standard HTTP status codes with a JSON body that includes a human-readable `message` and, where applicable, structured field-level details.

- `400`: Invalid payload, malformed JSON, or an unsupported option shape.
- `401`: Missing or invalid API key.
- `403`: Authenticated but not allowed to perform this operation.
- `404`: The resource is missing or not visible to the caller.
- `409`: Lifecycle conflict (for example, cancelling a run that is already terminal, or submitting input to a run that is not awaiting input).
- `500`: Server-side failure. Safe to retry idempotent reads; for writes, check the resource state before retrying.

The brand-extraction endpoint is the one exception to this model. It always returns `200` and reports extraction errors inside the body. See [Brand extraction](/docs/api/brand) for details.

## Rate limits and retries

- Reads are safe to retry. Add backoff if you see `429` or `5xx`.
- Writes (creating runs, submitting input, deleting credentials) are not idempotent. Confirm the current state with the corresponding read before re-issuing.
- Polling a run more frequently than every two seconds rarely helps. Run progress is updated at coarser intervals than that.

## Talk to the API from each path

- **HTTP directly.** Use any client. Set `x-api-key` and JSON content type. See per-resource pages for examples.
- **CLI.** Run `npx slideshot` from npm. Commands mirror the API resources: `npx slideshot runs create`, `npx slideshot credentials list`, `npx slideshot runs download`. See [MCP versus CLI](/docs/mcp-vs-cli).
- **MCP server.** Add `https://api.slideshot.ai/mcp` to your agent. Tools include `create_run`, `get_run`, `list_runs`, `submit_run_input`, `cancel_run`, `list_run_artifacts`, credential management, `submit_feedback`, and `fetch_brand`. See the per-agent setup pages under [Get started](/docs/getting-started).

## Related

- [API key](/docs/api): create and authenticate Slideshot API requests.
- [Runs](/docs/api/runs): the most common starting point for the API.
- [Artifacts](/docs/api/artifacts): what every run produces and how to download it.