API Endpoints

Full reference for the Clarive REST API endpoints. All requests require an API key via the X-Api-Key header. See API Overview for authentication, rate limits, and error handling.

GET /public/v1/entries

List all published entries in your workspace with optional filtering, search, and pagination.

curl -H "X-Api-Key: cl_your_key_here" \
  "https://your-domain/public/v1/entries?search=email&tags=marketing&page=1"

Response (200):

{
  "items": [
    {
      "id": "a1b2c3d4-...",
      "title": "Email Writer",
      "version": 3,
      "hasSystemMessage": true,
      "isTemplate": true,
      "isChain": false,
      "promptCount": 1,
      "firstPromptPreview": "Write a {{tone}} email to {{recipient}}.",
      "tags": ["marketing", "email"],
      "createdAt": "2026-01-15T10:30:00Z",
      "updatedAt": "2026-03-10T14:22:00Z",
      "tabs": [
        { "id": "t1b2c3d4-...", "name": "Main", "isMainTab": true, "forkedFromVersion": null },
        { "id": "t5e6f7a8-...", "name": "Experiment A", "isMainTab": false, "forkedFromVersion": 2 }
      ],
      "tabCount": 2
    }
  ],
  "totalCount": 1,
  "page": 1,
  "pageSize": 50
}

GET /public/v1/entries/

Fetch the published version of an entry, including its template field definitions.

curl -H "X-Api-Key: cl_your_key_here" \
  https://your-domain/public/v1/entries/{entryId}

Response (200):

{
  "id": "a1b2c3d4-...",
  "title": "Email Writer",
  "systemMessage": "You are a professional writer.",
  "version": 3,
  "prompts": [
    {
      "content": "Write a {{tone}} email to {{recipient}}.",
      "order": 0,
      "isTemplate": true,
      "templateFields": [
        {
          "name": "tone",
          "type": "enum",
          "enumValues": ["formal", "casual"],
          "defaultValue": null
        },
        {
          "name": "recipient",
          "type": "string",
          "defaultValue": null
        }
      ]
    }
  ],
  "tags": ["marketing", "email"],
  "updatedAt": "2026-03-10T14:22:00Z",
  "publishedAt": "2026-03-10T14:22:00Z",
  "tabs": [
    { "id": "t1b2c3d4-...", "name": "Main", "isMainTab": true, "forkedFromVersion": null }
  ],
  "tabCount": 1
}

POST /public/v1/entries/{entryId}/generate

Render a published entry by substituting template variables with the values you provide. All field values are passed as strings.

curl -X POST \
  -H "X-Api-Key: cl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"fields":{"tone":"formal","recipient":"Jane"}}' \
  https://your-domain/public/v1/entries/{entryId}/generate

Response (200):

{
  "id": "a1b2c3d4-...",
  "title": "Email Writer",
  "version": 3,
  "systemMessage": "You are a professional writer.",
  "renderedPrompts": [
    {
      "content": "Write a formal email to Jane.",
      "order": 0
    }
  ]
}

GET /public/v1/entries/{entryId}/tabs

List all tabs (working variants) for an entry. Each tab includes its name, ID, and whether it's the main tab. Use this to discover available variants for testing or CI/CD workflows.

curl -H "X-Api-Key: cl_your_key_here" \
  https://your-domain/public/v1/entries/{entryId}/tabs

Response (200):

[
  {
    "id": "t1b2c3d4-...",
    "name": "Main",
    "isMainTab": true,
    "forkedFromVersion": null
  },
  {
    "id": "t5e6f7a8-...",
    "name": "Experiment A",
    "isMainTab": false,
    "forkedFromVersion": 2
  }
]

GET /public/v1/entries/{entryId}/tabs/

Fetch the full content of a specific tab, including its system message, prompts, template fields, and tags. The response shape matches the entry detail endpoint.

curl -H "X-Api-Key: cl_your_key_here" \
  https://your-domain/public/v1/entries/{entryId}/tabs/{tabId}

POST /public/v1/entries/{entryId}/tabs/{tabId}/generate

Render a tab's templates by substituting variables with the values you provide. Works the same as the entry generate endpoint but targets a specific tab instead of the published version. Useful for testing prompt variants without publishing them.

curl -X POST \
  -H "X-Api-Key: cl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"fields":{"tone":"casual","recipient":"Bob"}}' \
  https://your-domain/public/v1/entries/{entryId}/tabs/{tabId}/generate

GET /public/v1/tags

List all tags in your workspace with entry counts.

curl -H "X-Api-Key: cl_your_key_here" \
  https://your-domain/public/v1/tags

Response (200):

[
  { "name": "marketing", "entryCount": 5 },
  { "name": "support", "entryCount": 3 }
]