REST API Reference

Create a new organization with initial user and API keys.

Request body:

{
  "orgName": "string (required)",
  "email": "string (required)",
  "password": "string (required, min 8 chars)"
}

Response (200):

{
  "organization": { "id": "uuid", "name": "string", "slug": "string" },
  "keys": {
    "publicKey": "pk_live_...",
    "secretKey": "sk_live_...",
    "testPublicKey": "pk_test_...",
    "testSecretKey": "sk_test_..."
  }
}

Authenticate with email/password. Sets an httpOnly cookie (da_session).

Request body:

{ "email": "string", "password": "string" }

Response (200):

{
  "user": { "id": "uuid", "email": "string", "name": "string", "role": "owner|admin|user" },
  "organization": { "id": "uuid", "name": "string", "slug": "string", "plan": "string" }
}

Clear the auth cookie.

Response (200):

{ "success": true }

Get the current authenticated user.

Response (200):

{
  "user": { "id": "uuid", "email": "string", "role": "string" },
  "organization": { "id": "uuid", "name": "string", "slug": "string", "plan": "string" }
}

List API keys for the organization.

Response (200):

{
  "keys": [{
    "id": "uuid",
    "type": "public|secret",
    "keyPrefix": "pk_live_abc...",
    "name": "string",
    "allowedDomains": ["string"],
    "lastUsedAt": "ISO8601|null",
    "isActive": true,
    "createdAt": "ISO8601"
  }]
}

Rotate an API key (deactivates old, creates new).

Request body:

{ "keyId": "uuid" }

Response (200):

{ "key": "pk_live_new...", "id": "uuid", "prefix": "pk_live_new..." }

Create a new demo session. Returns session token, greeting, and branding.

Request body:

{
  "productId": "string|'default' (required)",
  "visitorMeta": {
    "referrer": "string (optional)",
    "url": "string (optional)",
    "language": "string (optional)"
  }
}

Response (200):

{
  "sessionId": "uuid",
  "token": "JWT session token",
  "greeting": {
    "text": "string",
    "speech": "string",
    "suggestions": ["string"]
  },
  "agent": { "name": "string", "tone": "string" },
  "branding": {
    "primaryColor": "#hex",
    "widgetPosition": "bottom-right|bottom-left",
    "agentName": "string",
    "logoUrl": "string|null"
  }
}

Send a visitor message and get the agent's response.

Request body:

{ "message": "string (required)" }

Response (200):

{
  "text": "Agent's text response",
  "speech": "TTS-optimized text",
  "iframeCommands": [
    { "action": "navigate|click|type|highlight|scroll|wait", "selector": "string", "value": "string" }
  ],
  "suggestions": ["Suggested reply 1", "Suggested reply 2"],
  "agentId": "demo|qa|discovery|docs",
  "usage": { "inputTokens": 0, "outputTokens": 0 }
}

Capture lead information from the visitor.

Request body:

{
  "email": "string (optional)",
  "company": "string (optional)",
  "name": "string (optional)",
  "phone": "string (optional)"
}

Response (200):

{ "leadId": "uuid", "captured": true }

End a demo session.

Response (200):

{ "ended": true }

Upload and validate a PDP YAML file. Creates or updates the product and sets the config as active.

Request body:

{
  "yaml": "string (PDP YAML content, required)",
  "productId": "uuid (optional, auto-resolved by product name)"
}

Response (200):

{
  "id": "uuid",
  "productId": "uuid",
  "version": 1,
  "product": "Product Name",
  "screens": 5,
  "flows": 2,
  "warnings": ["string"]
}

Response (422) — Validation failed:

{
  "error": "PDP validation failed",
  "details": [{ "path": "string", "message": "string" }],
  "warnings": ["string"]
}

Validate PDP YAML without storing it.

Request body:

{ "yaml": "string" }

Response (200):

{
  "valid": true,
  "errors": [],
  "warnings": [],
  "summary": { "product": "string", "screens": 5, "flows": 2, "demoAccounts": 1, "faqs": 3 }
}

Retrieve a PDP config by ID.

Get the active PDP config for a product.

Start a discovery session. Returns a token URL to begin crawling.

Request body:

{ "productId": "uuid" }

Response (200):

{
  "sessionId": "uuid",
  "token": "JWT",
  "discoveryUrl": "https://yourapp.com?da_discover=TOKEN",
  "expiresAt": "ISO8601",
  "product": { "id": "uuid", "name": "string", "baseUrl": "string" }
}

Validate a discovery token.

Request body:

{ "token": "JWT" }

Response (200):

{ "valid": true, "sessionId": "uuid", "productId": "uuid" }

Submit a page snapshot during discovery.

Request body:

{
  "sessionId": "uuid",
  "token": "JWT",
  "snapshot": {
    "urlPath": "/dashboard",
    "pageTitle": "Dashboard",
    "headings": ["string"],
    "elements": [{}],
    "navigation": [{}],
    "forms": [{}],
    "viewport": { "width": 1920, "height": 1080 }
  }
}

Response (200):

{ "status": "saved", "id": "uuid", "uniquePages": 5 }

Chat with the discovery agent during exploration.

Request body:

{
  "sessionId": "uuid",
  "token": "JWT",
  "message": "This page is our main analytics dashboard",
  "currentSnapshot": {}
}

Response (200):

{ "reply": "Agent's response text" }

End discovery and generate a PDP YAML from collected snapshots.

Request body:

{ "sessionId": "uuid", "token": "JWT" }

Response (200):

{ "status": "complete", "pdpYaml": "YAML string" }

Check discovery progress.

Response (200):

{
  "hasSession": true,
  "status": "active|finalizing|complete|expired",
  "uniquePages": 8,
  "totalElements": 142,
  "generatedPdp": "YAML string|null",
  "sessionId": "uuid"
}

API info.

{ "name": "DemoAgent API", "version": "1.0.0" }

Health check.

{ "status": "ok" }