Chat completions

POST https://api.cognitivers.com/v1/chat/completions

OpenAI chat completions, so the request and response bodies are the ones your client already implements. This page covers what is worth knowing on top of that.

Request

{
  "model": "cog-fast",
  "messages": [
    { "role": "system", "content": "You are a detection engineer." },
    { "role": "user", "content": "Summarise this timeline." }
  ],
  "temperature": 0.2,
  "max_tokens": 2048,
  "stream": false
}

Response

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "cog-fast",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "..." },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1024,
    "completion_tokens": 256,
    "total_tokens": 1280
  }
}

usage is what billing reads. Reading it from your own client is the quickest way to keep an eye on spend; see Usage and credits.

Streaming

With "stream": true the response is a stream of server-sent events, each carrying a delta:

curl https://api.cognitivers.com/v1/chat/completions \
  -H "Authorization: Bearer $COGNITIVERS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cog-fast",
    "stream": true,
    "messages": [{ "role": "user", "content": "Count to five." }]
  }'

data: {"choices":[{"delta":{"content":"One"}}]}

data: {"choices":[{"delta":{"content":", two"}}]}

data: [DONE]

The stream is kept alive during long reads. Lines beginning with a colon are comments and are ignored by every conforming SSE client; if you have written a parser by hand, make sure it skips them rather than treating them as data.

Tool calls

Standard OpenAI tool calling: define tools, the model answers with tool_calls, you execute them and send the results back as tool messages. The loop is the same one your client already has.

JSON mode

response_format: { "type": "json_object" } constrains the model to emit valid JSON. Describe the shape you want in the prompt, and say the word JSON in it, because the constraint guarantees syntax rather than the fields you had in mind.

Errors

400 for a malformed body, 401 for a missing or revoked key, 403 when the key is not scoped to that model, 404 for an unknown model id, 413 when the input exceeds the ceiling for that model on your plan, and 429 when you hit a concurrency or budget limit. Details in Errors.