Skip to content
Ragtime Developers

API Overview

The Ragtime REST API lives under /api/v1 on your Ragtime instance. Every endpoint is described in a machine-readable OpenAPI 3.1 contract at GET /api/v1/openapi.json, which needs no key.

This page covers what every endpoint has in common. Each API page then documents its own endpoints.

Connecting an AI tool such as Claude Code or Cursor? Use the MCP server instead of calling the API by hand.

Authentication

Section titled “Authentication”

Send an API key as a bearer token:

Terminal window
curl https://your-ragtime-instance.com/api/v1/context \
  -H "Authorization: Bearer rt_live_YOUR_KEY_HERE"

A key belongs to one project and carries an explicit set of scopes. Some keys are also restricted to a single library. See API Keys for creating keys and choosing scopes.

Start with the context endpoint

Section titled “Start with the context endpoint”

GET /api/v1/context tells a client everything it needs before its first real call. Any valid key may call it, including library-restricted keys.

It returns:

  • key: the key’s name, prefix, scopes, library restriction, channel, audiences and expiry.
  • project and org: the project the key belongs to, so you never need to look up a projectId by hand.
  • rateLimits: the key’s limit, how much of it is left, and the organization-wide limit.
  • credits: whether AI work is available right now, and which credit pool pays for it. The figures (used, included, left) need the usage:read scope.
  • operations: every endpoint in the API, with the project filled into its path, whether this key may call it, and what it spends.
{
  "key": {
    "id": "6a1e…",
    "name": "Support agent",
    "prefix": "rt_live_abcd",
    "scopes": ["kb:read", "usage:read"],
    "libraryId": null,
    "channelId": null,
    "audience": [],
    "expiresAt": null
  },
  "project": { "id": "3f2c…", "title": "Help desk" },
  "org": { "id": "91b0…", "name": "Acme" },
  "rateLimits": {
    "key": { "limit": 30, "remaining": 29, "resetAt": "2026-10-09T10:01:00.000Z", "windowSeconds": 60 },
    "org": { "limit": 200, "windowSeconds": 60 }
  },
  "credits": {
    "metered": true,
    "capabilities": {
      "llm": { "metered": true, "available": true },
      "embedding": { "metered": true, "available": true }
    },
    "pool": { "kind": "general", "id": "general", "name": "Platform" },
    "used": 1240,
    "included": 10000,
    "left": 8760,
    "whenUsedUp": "stops",
    "period": { "start": "2026-10-01T00:00:00.000Z", "end": "2026-10-31T23:59:59.999Z", "resetsOn": "2026-11-01" }
  },
  "operations": [
    {
      "operationId": "searchKnowledgeBase",
      "method": "POST",
      "path": "/api/v1/projects/3f2c…/kb/search",
      "summary": "Query the knowledge base directly, without an assistant.",
      "scope": "kb:read",
      "allowed": true,
      "credits": { "capabilities": ["embedding"], "when": "Only when `query` is set; a filter-only search is free." }
    },
    {
      "operationId": "getAnalytics",
      "method": "GET",
      "path": "/api/v1/projects/3f2c…/analytics",
      "summary": "Aggregate conversation analytics for a project.",
      "scope": "analytics:read",
      "allowed": false,
      "reason": "insufficient_scope"
    }
  ],
  "docs": { "openapi": "/api/v1/openapi.json", "guide": "https://ragtime-ai.com/developers/api-overview/" }
}

Errors

Section titled “Errors”

Every error has the same shape:

{
  "code": "insufficient_scope",
  "error": "This API key lacks the `usage:read` scope.",
  "retryable": false,
  "hint": "Use a key with the `usage:read` scope. Manage API keys in the dashboard under Integrations → API keys.",
  "details": { "requiredScope": "usage:read", "grantedScopes": ["kb:read"] }
}
Field Description
code Stable, machine-readable reason. Branch on this, not on the message.
error Human-readable explanation. Wording may change.
retryable true when the same request may succeed if you wait and retry it unchanged.
hint Optional. What would make the request succeed.
retryAfter Optional. Seconds to wait before retrying (on 429).
details Optional. Structured context, such as the scope that was missing.

Error codes

Section titled “Error codes”
Status code Meaning
400 invalid_request Malformed JSON, or a field failed validation. The message names the field.
401 unauthorized No key, or the key is unknown.
401 key_expired The key has expired. Create a new one.
402 credits_exhausted The organization’s AI credits for this period are used up. Not retryable until the period resets or overage is approved.
402 credit_cap_reached This key or connected app has spent its own monthly credit cap. Not retryable until the month turns or an admin raises the cap. Calls that spend no credits still work.
403 insufficient_scope The key is valid but lacks the scope this endpoint needs. details.requiredScope names it.
403 project_mismatch The projectId in the path is not the key’s project. details.keyProjectId names the right one.
403 library_restricted The key is restricted to one library, and this endpoint is not for that library.
403 plan_required The organization’s plan does not include API access.
403 forbidden Any other refusal.
404 not_found The resource does not exist, or this key cannot see it.
409 conflict The request conflicts with the current state, such as a job that is already running.
413 payload_too_large The upload is too large.
415 unsupported_media_type The file type is not supported.
422 unprocessable Every item in a batch failed. The body lists each item’s error.
429 rate_limited Rate limit exceeded. Wait retryAfter seconds.
500 internal Something went wrong on our side. Safe to retry once.
503 unavailable A dependency is temporarily unavailable. Retry later.

Rate limits

Section titled “Rate limits”

Every endpoint is rate limited per key: by default 30 requests per minute, over a sliding window. Ragtime can raise the limit for a specific key on request.

Calls that spend the organization’s AI budget (a semantic knowledge-base search, for example) also count against an organization-wide limit shared by all its keys.

Every response, successful or not, carries the key’s current state:

Header Description
X-RateLimit-Limit Requests allowed per window.
X-RateLimit-Remaining Requests left in the current window.
X-RateLimit-Reset Unix time (seconds) when the window resets.

A 429 response also sends Retry-After in seconds, and its body says which bucket ran out in details.bucket (key or org).

AI credits

Section titled “AI credits”

Some calls run a model and spend the organization’s AI credits. Calls are only metered when the organization runs that model on Ragtime’s provider keys; with your own provider keys, nothing is drawn.

Which pool pays depends on the key. A key billed to a channel draws on that channel’s package, falling back to the general pool the way the channel itself does. A key without a channel draws on the general pool. credits.pool names the pool: { "kind": "package" | "general", "id", "name" }.

Operation Spends When
Ask the assistant embedding, llm Every call.
Knowledge base search embedding Only when query is set. A filter-only search is free.
Ingest embedding In the background, while each source is processed.
Insight query, export, saved-query run embedding, llm Falls back to a computed answer without AI when credits are used up.
Findings overview llm Only for a custom from/to window.
Insights test data llm Always.
Library and recipient distillation llm In the background, while the distillation runs.
Recipient materials finalize embedding In the background, while each material is processed.

/context lists the same information per operation in operations[].credits, read from the OpenAPI contract’s x-credits extension.

A key can also have its own monthly credit cap; once it is spent, calls that need credits return 402 credit_cap_reached.

When credits run out, calls that need them return 402 credits_exhausted. What happens next depends on the organization’s plan, reported as whenUsedUp:

whenUsedUp Meaning
continues Usage beyond the included credits is billed, so work continues.
falls_back A channel package past its credits: work continues on the general pool.
awaits_approval Work stops until an organization admin approves overage for the month.
stops Work that draws credits stops until the period resets.

GET /api/v1/usage

Section titled “GET /api/v1/usage”

Returns the organization’s credits for the current period and the key’s rate limits. Requires the usage:read scope. It reports usage only, never prices.

Terminal window
curl https://your-ragtime-instance.com/api/v1/usage \
  -H "Authorization: Bearer rt_live_YOUR_KEY_HERE"
{
  "credits": {
    "metered": true,
    "capabilities": {
      "llm": { "metered": true, "available": true },
      "embedding": { "metered": true, "available": true }
    },
    "pool": { "kind": "general", "id": "general", "name": "Platform" },
    "used": 1240,
    "included": 10000,
    "left": 8760,
    "whenUsedUp": "stops",
    "period": { "start": "2026-10-01T00:00:00.000Z", "end": "2026-10-31T23:59:59.999Z", "resetsOn": "2026-11-01" }
  },
  "rateLimits": {
    "key": { "limit": 30, "remaining": 28, "resetAt": "2026-10-09T10:01:00.000Z", "windowSeconds": 60 },
    "org": { "limit": 200, "windowSeconds": 60 }
  }
}

left is null when nothing stops the work: the organization uses its own provider keys, or usage beyond the included credits is billed.

The OpenAPI contract

Section titled “The OpenAPI contract”

GET /api/v1/openapi.json returns the full OpenAPI 3.1 description: every path, method, parameter, request body, status code and required scope. Use it to generate a client, or import it into a tool such as Postman. Ragtime extensions:

Extension Meaning
x-required-scope The scope the operation needs. none means any valid key.
x-library-key true when a library-restricted key may call the operation.
x-credits What the operation spends credits on, and when.
x-mcp Hints for the operation’s MCP tool, where its method misleads: destructive: true on a POST that deletes.

A test in Ragtime’s own build checks the contract against the code, so it stays accurate.