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

# Quickstart

> Create a demo video with one request, then fetch the finished video.

**1. Get an API key**

Open the [Developers page](https://app.demosmith.ai/developers) in the app and select **Create key**. Only owners and admins of a paid plan can create keys. The key starts with `dsk_live_` and is shown once, so store it somewhere safe.

```bash theme={null}
export DEMOSMITH_API_KEY="dsk_live_..."
```

**2. Create a demo**

Send the site's URL and what the demo should show. The request returns at once.

```bash curl theme={null}
curl https://platform.demosmith.ai/v1/demos \
  -H "Authorization: Bearer $DEMOSMITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://cal.com",
    "task": "Show how to book a 30-minute meeting from a public booking page"
  }'
```

```python Python theme={null}
import os
import requests

response = requests.post(
    "https://platform.demosmith.ai/v1/demos",
    headers={"Authorization": f"Bearer {os.environ['DEMOSMITH_API_KEY']}"},
    json={
        "url": "https://cal.com",
        "task": "Show how to book a 30-minute meeting from a public booking page",
    },
)
demo = response.json()
print(demo["id"], demo["status"])
```

```javascript Node.js theme={null}
const response = await fetch("https://platform.demosmith.ai/v1/demos", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DEMOSMITH_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://cal.com",
    task: "Show how to book a 30-minute meeting from a public booking page",
  }),
});
const demo = await response.json();
console.log(demo.id, demo.status);
```

```json Response (201) theme={null}
{
  "id": "5b9e3c7a-2f41-4c8e-9a51-7d0b6e2f1c34",
  "object": "demo",
  "status": "queued",
  "progress": { "percent": 0, "eta_seconds": 900 },
  "check_again_in_seconds": 15,
  "app_url": "https://app.demosmith.ai/demos/5b9e3c7a-2f41-4c8e-9a51-7d0b6e2f1c34"
}
```

> [!TIP]
>
> Add an `idempotency_key` to the request. If your request times out and you send it again with the same key, you get the same demo back instead of a second one.

**3. Wait for the video**

A demo takes about 5 to 20 minutes. Either register a [webhook](https://developers.demosmith.ai/webhooks.md) and get `demo.completed`, or poll the demo, waiting `check_again_in_seconds` between requests.

```python Python theme={null}
import time

while demo["status"] not in ("completed", "failed", "canceled"):
    time.sleep(demo["check_again_in_seconds"])
    demo = requests.get(
        f"https://platform.demosmith.ai/v1/demos/{demo['id']}",
        headers={"Authorization": f"Bearer {os.environ['DEMOSMITH_API_KEY']}"},
    ).json()
    if demo["status"] == "input_required":
        print("The agent needs an answer:", demo["input_request"]["answer_url"])
```

```javascript Node.js theme={null}
let current = demo;
while (!["completed", "failed", "canceled"].includes(current.status)) {
  await new Promise((r) => setTimeout(r, current.check_again_in_seconds * 1000));
  const res = await fetch(`https://platform.demosmith.ai/v1/demos/${current.id}`, {
    headers: { Authorization: `Bearer ${process.env.DEMOSMITH_API_KEY}` },
  });
  current = await res.json();
  if (current.status === "input_required") {
    console.log("The agent needs an answer:", current.input_request.answer_url);
  }
}
```

If the agent reaches a sign-in page, the demo pauses with `status: "input_required"`. See [When the agent needs an answer](https://developers.demosmith.ai/questions.md).

**4. Get the video**

When `status` is `completed`, the demo has a `video` object.

```json theme={null}
"video": {
  "url": "https://...",
  "download_url": "https://...",
  "expires_at": "2026-11-07T14:12:00Z",
  "duration_seconds": 63.4
}
```

`url` plays in a browser and `download_url` downloads the MP4. Both expire after 2 hours; fetch the demo again for fresh links. The demo also stays in your library in the app (`app_url`).

## Next steps

> [card] [Choose language, voice and more](https://developers.demosmith.ai/api-reference/demos/create-and-start-a-demo.md)
>
> `options` sets the language, voice, tone, subtitles, music and resolution.

> [card] [Webhooks](https://developers.demosmith.ai/webhooks.md)
>
> Stop polling and get each step as it happens.


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