API Reference

Endpoint

POST https://build.chipp.ai/api/v1/chat/completions

Request

Headers

Body

{
  model: string;          // Your app's appNameId (e.g., "myapp-123")
  messages: Array<{       
    role: "user" | "assistant" | "system";
    content: string;
  }>;
  stream?: boolean;       // Default: false
  chatSessionId?: string; // Continue conversation
  variables?: Record<string, string>; // Session-scoped MCP header variables
}

Parameters

• model: Your Chipp application’s appNameId (format: appname-123)
• messages: Array of message objects
• stream: Enable streaming (optional)
• chatSessionId: Continue existing session (optional)
• variables: Optional object of string key/value pairs, bound to this session for use by MCP connections that declare {{session.<name>}} header placeholders (see below)

Session Variables

If one of your app’s MCP integrations is configured with a session-scoped header placeholder (e.g. a builder sets a custom header’s value to {{session.user_context}}), you can bind a value to that placeholder for this specific session:

{
  "model": "myapp-123",
  "messages": [{ "role": "user", "content": "..." }],
  "variables": { "user_context": "opaque-routing-value" }
}

• Values are opaque strings you control — typically a routing key or tenant/user identifier that lets ONE shared MCP connection serve many end users without a separate connection or OAuth flow per user.
• You only need to pass variables once, on the call that creates the session (no chatSessionId yet, or the first call with a new one) — it stays bound to that session for later chatSessionId continuation calls. You can also send updated variables on a later call in the same session; new values are merged over previously bound ones.
• Limits: up to 20 variables per request, up to 2048 characters per value. Variable names must match ^[a-zA-Z_][a-zA-Z0-9_-]{0,63}$. A request that exceeds either limit is rejected with a 400 error.
• Values are never included in any API response and are not persisted beyond the life of the session. Only the app’s builder can declare which variable names an MCP connection accepts (via the Integration Builder) — a variables key that isn’t declared on any connection is simply unused.

Response

Success (200)

{
  "chatSessionId": "550e8400-e29b-41d4-a716-446655440000",
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1699451234,
  "model": "myapp-123",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "Response text"
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 15,
    "total_tokens": 25
  }
}

Error Format

All errors return a JSON object with an error field:

{
  "error": "Error message describing the issue"
}

Status Codes

Common Errors

Invalid Request (400)

{
  "error": "`model` is required and must be a string"
}

{
  "error": "`messages` must be a non-empty array"
}

{
  "error": "variables exceeds the max of 20 entries"
}

Authentication Failed (401)

{
  "error": "Missing API key"
}

{
  "error": "Invalid API key"
}

{
  "error": "This API is only available on a paid plan.  Visit your dashboard to upgrade."
}

Model Not Found (404)

{
  "error": "Unknown model \"invalidapp-999\""
}

Server Errors (500)

{
  "error": "Internal Server Error"
}

Sessions

New Session

Omit chatSessionId to start fresh.

Continue Session

Include chatSessionId from previous response. Previous messages are loaded automatically.

Requirements

• Builder plan or higher (Free accounts cannot access the API)
• Valid API key from your application’s Access tab (Builder API Keys section)