Roxels/ docs
api

Templates API

Templates are the design of a conversation — see What is Roxels for the concept. This page covers the REST endpoints for managing them.

The dashboard wraps these endpoints with a UI. For most users, the dashboard is the right surface. The REST API is for: bulk creation, CI/CD pipelines, importing templates from version control, AI-assisted authoring (often via MCP).

List templates

curl https://api.roxels.ai/v1/templates \
  -H "Authorization: Bearer sk-your-key-here"

Response:

{
  "items": [
    {
      "id": "tpl_a1b2c3",
      "name": "Customer onboarding",
      "description": "...",
      "language": "en",
      "created_at": "2026-05-01T12:00:00Z",
      "updated_at": "2026-05-22T08:30:00Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Supports cursor pagination — see Pagination and errors.

Get a template

curl https://api.roxels.ai/v1/templates/tpl_a1b2c3 \
  -H "Authorization: Bearer sk-your-key-here"

Response includes the full template — phases, goals, settings, outputs, skills.

{
  "id": "tpl_a1b2c3",
  "name": "Customer onboarding",
  "description": "...",
  "language": "en",
  "phases": [
    {
      "id": "phase_1",
      "body_instructions": "...",
      "goals": [
        /* ... */
      ],
      "outputs": [
        /* ... */
      ]
    }
  ],
  "settings": {
    "greeting": "Hi there!",
    "max_session_duration_minutes": 30,
    "allow_screen_share": true,
    "system_instructions": "...",
    "speaker_skills": [
      /* ... */
    ],
    "advisors": [
      /* ... */
    ],
    "outputs": [
      /* template-level webhooks */
    ]
  },
  "created_at": "...",
  "updated_at": "..."
}

See Templates overview for what each field means.

Create a template

curl https://api.roxels.ai/v1/templates \
  -H "Authorization: Bearer sk-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer onboarding",
    "description": "Greets new users and captures basic profile info",
    "language": "en",
    "phases": [
      {
        "body_instructions": "Greet the user, then walk them through profile setup.",
        "goals": [
          {
            "id": "name",
            "type": "open",
            "prompt": "Get the user'\''s full name."
          },
          {
            "id": "use_case",
            "type": "qualitative",
            "prompt": "Find out what they plan to use our product for."
          }
        ]
      }
    ],
    "settings": {
      "greeting": "Hi! Welcome.",
      "max_session_duration_minutes": 15
    }
  }'

Response: the created template (same shape as Get).

For more complex authoring — chained goals, structured schemas, skills, outputs — see Goals and extraction and Skills and advisors. For natural-language authoring with AI assistance, see MCP overview.

Update a template

PATCH replaces only the fields you send:

curl -X PATCH https://api.roxels.ai/v1/templates/tpl_a1b2c3 \
  -H "Authorization: Bearer sk-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "greeting": "Hi! Welcome back."
    }
  }'

Nested objects merge shallowly — sending settings: { greeting: "..." } updates greeting and leaves other settings fields alone. To replace a whole array (phases, goals, outputs), send the full new array.

Export

Export a template as a portable JSON blob — useful for version-controlling templates or moving between orgs:

curl https://api.roxels.ai/v1/templates/tpl_a1b2c3/export \
  -H "Authorization: Bearer sk-your-key-here" \
  > my-template.json

Import

Import a template from an exported JSON blob:

curl https://api.roxels.ai/v1/templates/import \
  -H "Authorization: Bearer sk-your-key-here" \
  -H "Content-Type: application/json" \
  -d @my-template.json

Response: the created template, with a new id.

Create a join link for a template (useful for sharing without an embed key):

curl -X POST https://api.roxels.ai/v1/templates/tpl_a1b2c3/share \
  -H "Authorization: Bearer sk-your-key-here"

Response:

{
  "url": "https://app.roxels.ai/join/i/iv_...",
  "expires_at": null
}

Schedule conversations

Pre-create conversations bound to a template (e.g. one per upcoming customer interview):

curl -X POST https://api.roxels.ai/v1/templates/tpl_a1b2c3/schedule \
  -H "Authorization: Bearer sk-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "count": 10,
    "person_name_prefix": "Candidate"
  }'

Response:

{
  "scheduled": [
    { "session_id": "sess_...", "join_url": "..." },
    { "session_id": "sess_...", "join_url": "..." }
  ]
}
Last reviewed 2026-05-23.