Curie API

Your applications call models through Curie with a Curie key. The model credentials stay on the Curie host, and API traffic counts against the same limits and budgets as chat.

Connecting an application

An application written for an OpenAI-compatible API needs a new base URL and a Curie key.

  1. An administrator turns on API access for your organization and issues a service-account key. A person with API access can create a personal key instead.
  2. Set the client's base URL to /openai/v1 on your Curie host.
  3. Send the Curie key where the client expects its API key.
  4. Name a model from GET /openai/v1/models, or send default.

The application then runs under your organization's limits and budget. Curie records each call without its content.

Tools

Tools work in two ways.

  • Your application's tools. Chat completions passes the tools and tool_choice fields to the model and returns the model's tool calls unchanged. Your application runs each tool and sends the result in its next request. This works with personal and service-account keys.
  • Curie's document tools. A responses request that sets internal_tools to true lets the model search documents, read a whole document and query a table. These run on the Curie host, need a personal key, and reach only the documents that person can open.
  • Tools need a model that supports tool calling. GET /openai/v1/models reports this for each model.

What the API offers

  • OpenAI-compatible chat completions, with or without streaming.
  • A stateful responses endpoint that stores each call as a conversation.
  • Conversations over server-sent events, with tool calls your application runs and returns.
  • Document uploads into a knowledge base, for a system that keeps Curie's library current.
  • Usage and cost reporting for your organization.
  • Per-key and per-address request throttles.

An administrator turns on API access for each organization. Every request is scoped to the key's organization.

Authentication

Send the key as a bearer token in the Authorization header.

  • Personal keys begin with curie_pat_. A person creates one under API Keys, and the calls run as that person with that person's document access.
  • Service-account keys begin with curie_svc_. An administrator issues them to a system, with an optional expiry date. They reach the chat completions and model list endpoints.

Curie stores a digest of each key. The full key is shown once, when it is created. A person sees their own API calls under External Interactions.

Endpoints

Model access

  • POST /v1/chat/completions
  • POST /v1/responses and GET /v1/responses/{id}
  • GET /openai/v1/models

Chat completions and responses are also served under the /openai/v1 base path.

Conversations

  • POST /v1/conversations starts a conversation and streams the reply.
  • POST /v1/conversations/{id}/messages sends a message or a tool result and resumes the stream.
  • GET /v1/conversations, GET /v1/conversations/{id} and GET /v1/conversations/{id}/items read them back.
  • DELETE /v1/conversations/{id}

Setup and reporting

  • GET /v1/bootstrap returns models, agents and defaults in one call.
  • GET /v1/service_models and GET /v1/agent_profiles
  • GET /v1/usage/summary

Documents

  • POST /v1/knowledge_bases/{id}/documents and GET /v1/knowledge_bases/{id}/documents
  • GET /v1/documents/{id} and PATCH /v1/documents/{id}
  • POST /v1/documents/{id}/reextract

Streaming

A conversation stream sends these events:

  • conversation.created or conversation.continued opens the stream.
  • tool_result.accepted confirms a tool result your application sent.
  • message.delta and message.end deliver the assistant's reply.
  • tool_call asks your application to run a tool. tool_call_cancelled withdraws one.
  • warning reports a request parameter Curie changed so the model would accept it.
  • usage reports token counts.
  • error reports a failed turn.
  • done ends the turn with a reason: stop, tool_call_pending or error.

Today the reply arrives as a single message.delta once the model finishes. Token-by-token delivery is not built. During a long model call, Curie writes a keep-alive comment after 15 seconds of silence, so client and proxy idle timeouts do not close the connection.

The chat completions and responses endpoints stream in the OpenAI-compatible event format when the request sets stream to true.

Reference

Each Curie deployment serves its OpenAPI document at GET /v1/openapi, with the same key authentication as the rest of the API. Any HTTP client that reads server-sent events can call the API.

To discuss an integration, contact us.