Endpoints

API endpoints for demos, views, shares, team management, and webhooks.

This reference covers the key Demoship API endpoints. All endpoints require authentication and use the base URL https://api.demoship.com/v1.

Demos

List demos

GET /demos

Query parameters: page, per_page, status (draft, published, archived), search.

curl https://api.demoship.com/v1/demos?status=published \
  -H "Authorization: Bearer dsk_your_api_key"

Get a demo

GET /demos/:id

Returns demo details including steps, hotspots, and configuration.

Create a demo

POST /demos

{
  "title": "Product Onboarding",
  "source_url": "https://app.example.com/onboarding",
  "type": "interactive",
  "generate_with_ai": true
}

When generate_with_ai is true, Demoship captures the URL and generates steps automatically. The response includes a status field that transitions from generating to draft when complete.

Update a demo

PATCH /demos/:id

{
  "title": "Updated Product Onboarding",
  "status": "published"
}

Delete a demo

DELETE /demos/:id

Returns 204 No Content on success.

Views (Analytics)

List views for a demo

GET /demos/:id/views

Query parameters: page, per_page, start_date, end_date, viewer_email.

Response includes viewer identity, steps viewed, completion status, and timestamps.

Get aggregated analytics

GET /demos/:id/analytics

Query parameters: start_date, end_date, granularity (day, week, month).

{
  "data": {
    "total_views": 342,
    "unique_viewers": 198,
    "completion_rate": 0.67,
    "avg_time_seconds": 94,
    "steps": [
      { "number": 1, "views": 342, "avg_time": 12, "drop_off_rate": 0.05 },
      { "number": 2, "views": 325, "avg_time": 18, "drop_off_rate": 0.08 }
    ]
  }
}

POST /demos/:id/shares

{
  "password": "optional-password",
  "expires_at": "2025-12-31T23:59:59Z",
  "require_identification": true
}

GET /demos/:id/shares

DELETE /shares/:id

Team

List members

GET /team/members

Invite a member

POST /team/members

{
  "email": "user@example.com",
  "role": "editor"
}

Update a member's role

PATCH /team/members/:id

{
  "role": "admin"
}

Remove a member

DELETE /team/members/:id

Webhooks

Create a webhook

POST /webhooks

{
  "url": "https://yourapp.com/webhooks/demoship",
  "events": ["demo.viewed", "demo.completed"],
  "secret": "your-webhook-secret"
}

Webhook payload

Webhook payloads are sent as POST requests with a JSON body:

{
  "event": "demo.completed",
  "timestamp": "2025-06-15T14:30:00Z",
  "data": {
    "demo_id": "demo_abc123",
    "viewer_email": "prospect@example.com",
    "completion_time": 94
  }
}

Payloads include a X-Demoship-Signature header for verification. Compute an HMAC-SHA256 of the request body using your webhook secret and compare it to the signature.

List webhooks

GET /webhooks

Delete a webhook

DELETE /webhooks/:id

Note: Webhook delivery is retried up to 5 times with exponential backoff. Failed deliveries are logged in Settings > API > Webhooks > Delivery Logs.