Quickstart

Get an API key

Open the Developers page 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.

export DEMOSMITH_API_KEY="dsk_live_..."

Create a demo

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

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"
  }'

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"])

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);

Response (201)

{
  "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"
}

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.

Wait for the video

A demo takes about 5 to 20 minutes. Either register a webhook and get demo.completed, or poll the demo, waiting check_again_in_seconds between requests.

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"])

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.

Get the video

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

"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

Choose language, voice and more

options sets the language, voice, tone, subtitles, music and resolution.

Webhooks

Stop polling and get each step as it happens.

Get started

Build

Next steps

Choose language, voice and more

Webhooks

​Next steps

Choose language, voice and more

Webhooks

Next steps