Create and start a demo

curl --request POST \
  --url https://platform.demosmith.ai/v1/demos \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://cal.com",
  "task": "Show how to book a 30-minute meeting from a public booking page",
  "options": {
    "language": "en-US"
  },
  "callback_url": "https://example.com/webhooks/demosmith",
  "metadata": {
    "crm_account": "acct_123"
  },
  "idempotency_key": "onboarding-cal-001"
}
'

import requests

url = "https://platform.demosmith.ai/v1/demos"

payload = {
    "url": "https://cal.com",
    "task": "Show how to book a 30-minute meeting from a public booking page",
    "options": { "language": "en-US" },
    "callback_url": "https://example.com/webhooks/demosmith",
    "metadata": { "crm_account": "acct_123" },
    "idempotency_key": "onboarding-cal-001"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', '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',
    options: {language: 'en-US'},
    callback_url: 'https://example.com/webhooks/demosmith',
    metadata: {crm_account: 'acct_123'},
    idempotency_key: 'onboarding-cal-001'
  })
};

fetch('https://platform.demosmith.ai/v1/demos', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "5b9e3c7a-2f41-4c8e-9a51-7d0b6e2f1c34",
  "object": "demo",
  "status": "queued",
  "stage": null,
  "progress": {
    "percent": 0,
    "eta_seconds": 900
  },
  "queue": {
    "position": 1,
    "total": 3
  },
  "title": null,
  "url": "https://cal.com",
  "task": "Show how to book a 30-minute meeting from a public booking page",
  "language": "en-US",
  "input_request": null,
  "video": null,
  "failure": null,
  "app_url": "https://app.demosmith.ai/demos/5b9e3c7a-2f41-4c8e-9a51-7d0b6e2f1c34",
  "source": "api",
  "metadata": {
    "crm_account": "acct_123"
  },
  "check_again_in_seconds": 15,
  "created_at": "2026-11-07T11:58:40Z",
  "updated_at": "2026-11-07T11:58:40Z",
  "finished_at": null
}

{
  "id": "5b9e3c7a-2f41-4c8e-9a51-7d0b6e2f1c34",
  "object": "demo",
  "status": "queued",
  "stage": null,
  "progress": {
    "percent": 0,
    "eta_seconds": 900
  },
  "queue": {
    "position": 1,
    "total": 3
  },
  "title": null,
  "url": "https://cal.com",
  "task": "Show how to book a 30-minute meeting from a public booking page",
  "language": "en-US",
  "input_request": null,
  "video": null,
  "failure": null,
  "app_url": "https://app.demosmith.ai/demos/5b9e3c7a-2f41-4c8e-9a51-7d0b6e2f1c34",
  "source": "api",
  "metadata": {
    "crm_account": "acct_123"
  },
  "check_again_in_seconds": 15,
  "created_at": "2026-11-07T11:58:40Z",
  "updated_at": "2026-11-07T11:58:40Z",
  "finished_at": null
}

{
  "error": {
    "code": "needs_answers",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "needs_answers",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "needs_answers",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "needs_answers",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "needs_answers",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "needs_answers",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "needs_answers",
    "message": "<string>",
    "details": {}
  }
}

POST

demos

Create and start a demo

curl --request POST \
  --url https://platform.demosmith.ai/v1/demos \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://cal.com",
  "task": "Show how to book a 30-minute meeting from a public booking page",
  "options": {
    "language": "en-US"
  },
  "callback_url": "https://example.com/webhooks/demosmith",
  "metadata": {
    "crm_account": "acct_123"
  },
  "idempotency_key": "onboarding-cal-001"
}
'

import requests

url = "https://platform.demosmith.ai/v1/demos"

payload = {
    "url": "https://cal.com",
    "task": "Show how to book a 30-minute meeting from a public booking page",
    "options": { "language": "en-US" },
    "callback_url": "https://example.com/webhooks/demosmith",
    "metadata": { "crm_account": "acct_123" },
    "idempotency_key": "onboarding-cal-001"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', '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',
    options: {language: 'en-US'},
    callback_url: 'https://example.com/webhooks/demosmith',
    metadata: {crm_account: 'acct_123'},
    idempotency_key: 'onboarding-cal-001'
  })
};

fetch('https://platform.demosmith.ai/v1/demos', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "5b9e3c7a-2f41-4c8e-9a51-7d0b6e2f1c34",
  "object": "demo",
  "status": "queued",
  "stage": null,
  "progress": {
    "percent": 0,
    "eta_seconds": 900
  },
  "queue": {
    "position": 1,
    "total": 3
  },
  "title": null,
  "url": "https://cal.com",
  "task": "Show how to book a 30-minute meeting from a public booking page",
  "language": "en-US",
  "input_request": null,
  "video": null,
  "failure": null,
  "app_url": "https://app.demosmith.ai/demos/5b9e3c7a-2f41-4c8e-9a51-7d0b6e2f1c34",
  "source": "api",
  "metadata": {
    "crm_account": "acct_123"
  },
  "check_again_in_seconds": 15,
  "created_at": "2026-11-07T11:58:40Z",
  "updated_at": "2026-11-07T11:58:40Z",
  "finished_at": null
}

{
  "id": "5b9e3c7a-2f41-4c8e-9a51-7d0b6e2f1c34",
  "object": "demo",
  "status": "queued",
  "stage": null,
  "progress": {
    "percent": 0,
    "eta_seconds": 900
  },
  "queue": {
    "position": 1,
    "total": 3
  },
  "title": null,
  "url": "https://cal.com",
  "task": "Show how to book a 30-minute meeting from a public booking page",
  "language": "en-US",
  "input_request": null,
  "video": null,
  "failure": null,
  "app_url": "https://app.demosmith.ai/demos/5b9e3c7a-2f41-4c8e-9a51-7d0b6e2f1c34",
  "source": "api",
  "metadata": {
    "crm_account": "acct_123"
  },
  "check_again_in_seconds": 15,
  "created_at": "2026-11-07T11:58:40Z",
  "updated_at": "2026-11-07T11:58:40Z",
  "finished_at": null
}

{
  "error": {
    "code": "needs_answers",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "needs_answers",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "needs_answers",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "needs_answers",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "needs_answers",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "needs_answers",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "needs_answers",
    "message": "<string>",
    "details": {}
  }
}

Authorizations

Authorization

string

header

required

An API key from the Developers page.

Body

application/json

url

string<uri>

required

Maximum string length: 2048

task

string

required

Required string length: 5 - 8000

check_id

string

answers

object[]

Show child attributes

options

object

Show child attributes

callback_url

string<uri>

HTTPS URL that gets this demo's webhook events.

metadata

object

Your own values, returned on the demo and in webhook payloads.

Show child attributes

idempotency_key

string

Sending the same key again returns the same demo (200).

Maximum string length: 100

Response

An earlier demo with the same idempotency_key

string<uuid>

required

object

string

required

Allowed value: "demo"

status

enum<string>

required

Available options:

canceled,

completed,

failed,

in_progress,

input_required,

queued

stage

enum<string> | null

Available options:

analyzing,

editing,

narrating,

recording,

rendering,

null

progress

object

Show child attributes

queue

object | null

Show child attributes

title

string | null

url

string<uri>

task

string

language

string | null

input_request

object | null

A question the recorder is waiting on.

Show child attributes

video

object | null

Show child attributes

failure

object | null

Show child attributes

app_url

string<uri>

source

enum<string>

Available options:

api,

mcp,

web

metadata

object

Show child attributes

check_again_in_seconds

integer

Wait at least this long before polling again. 0 when finished.

created_at

string<date-time>

updated_at

string<date-time>

finished_at

string<date-time> | null

Overview

Endpoints

Create and start a demo

Authorizations

Body

Response