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.

Default template

Roxels maintains one product-wide default template — the template integrations run when none is specified. It is a system template curated by Roxels; discover it with:

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

Response:

{
  "id": "tpl_...",
  "name": "Workflow Documentation",
  "description": "...",
  "status": "active",
  "source": "system"
}

Returns 404 when no default is set. Any organization can start conversations against the default template (pass its id to the Conversations API). The default itself is managed by Roxels admins — PATCH {"is_default": ...} is rejected for regular API keys and for non-system templates.

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.