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

# API reference

> Base URL, authentication, and the objects every endpoint returns.

## Base URL

```text theme={null}
https://platform.demosmith.ai/v1
```

Send JSON with `Content-Type: application/json`. Responses are JSON too.

## Authentication

Every endpoint needs an [API key](https://developers.demosmith.ai/authentication.md#api-keys) as a bearer token:

```bash theme={null}
curl https://platform.demosmith.ai/v1/me \
  -H "Authorization: Bearer $DEMOSMITH_API_KEY"
```

`GET /me` tells you who the key belongs to and what's left on the plan, which makes it a good first request.

## The demo object

Every demo endpoint, assistant tool and webhook returns the same object.

**id** `string`

The demo's id.

**status** `string`

`queued`, `in_progress`, `input_required`, `completed`, `failed` or `canceled`.

**stage** `string | null`

While `in_progress`: `recording`, `analyzing`, `narrating`, `editing` or `rendering`.

**progress** `object`

`percent` done and `eta_seconds`, an estimate of the time left.

**input\_request** `object | null`

The question the agent is waiting on, when `status` is `input_required`. See [When the agent needs an answer](https://developers.demosmith.ai/questions.md).

**video** `object | null`

When `completed`: `url` to play, `download_url` for the MP4, `duration_seconds`, `thumbnail_url`. Links expire after 2 hours (`expires_at`).

**failure** `object | null`

When `failed`: a `message` saying why.

**check\_again\_in\_seconds** `integer`

How long to wait before polling again. `0` once the demo is finished.

**app\_url** `string`

The demo in the Demosmith app, where it can be edited and shared.

**source** `string`

Where it was created: `api`, `mcp` or `web`.

**metadata** `object`

Your own values from creation, returned as given.

## Lists

`GET /demos` returns the newest first, 30 per page by default. Use `page` and `page_size` (up to 100). The response has `count`, `next`, `previous` and `results`.

## Versioning

The API is versioned in the path (`/v1`). Within `v1` we only add things: new endpoints, new optional fields, new event types and new values in lists. Ignore fields and values you don't know.

## OpenAPI

The full specification is at [`https://platform.demosmith.ai/v1/openapi.json`](https://platform.demosmith.ai/v1/openapi.json) (OpenAPI 3.1). Use it to generate a client or import it into your API tool.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.