POST /v1/chat/completions

Purpose

This endpoint starts a new chat request.

Request

POST /v1/chat/completions
Authorization: Bearer km_your_token_here
Content-Type: application/json

Minimal body

{
  "model": "group:123e4567-e89b-12d3-a456-426614174000",
  "messages": [
    {
      "role": "user",
      "content": "Summarize this document."
    }
  ]
}

Supported fields

Field	Type	Required	Notes
model	string	yes	format group:<uuid>
messages	array	yes	must include at least one user message
stream	boolean	no	enables SSE mode
max_tokens	integer	no	output limit
max_completion_tokens	integer	no	preferred output limit field
temperature	number	no	value between 0 and 2
metadata	object	no	supports request_id and mode

Standard response

In non-streaming mode, the response follows this general shape:

{
  "id": "chatcmpl_123",
  "object": "chat.completion",
  "created": 1712345678,
  "model": "group:123e4567-e89b-12d3-a456-426614174000",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Here is the summary."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 120,
    "completion_tokens": 84,
    "total_tokens": 204
  },
  "kitemesh": {
    "execution_id": "3e6f4f5d-c02a-4cae-b35d-e83420867962",
    "credits_charged": 3,
    "request_id": "req_demo_001"
  }
}

Response with tool approval

If the request requires approval before a tool can run, the non-stream response can look like this:

{
  "id": "chatcmpl_123",
  "object": "chat.completion",
  "created": 1712345678,
  "model": "group:123e4567-e89b-12d3-a456-426614174000",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "1fb2fd25-8f78-412a-a0b8-7976e3700fc4",
            "type": "function",
            "function": {
              "name": "create_ticket",
              "arguments": "{\"priority\":\"high\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ],
  "kitemesh": {
    "approval_id": "86dd028d-6f5c-4f13-83db-d4fe9bc5b865",
    "execution_id": "3e6f4f5d-c02a-4cae-b35d-e83420867962",
    "expires_at": "2026-06-08T16:20:00.000Z"
  }
}

Store approval_id. It is required for POST /v1/chat/resume.

SSE streaming

When stream is true, the API returns SSE events.

Example text chunk:

{
  "id": "chatcmpl_123",
  "object": "chat.completion.chunk",
  "created": 1712345678,
  "model": "group:123e4567-e89b-12d3-a456-426614174000",
  "choices": [
    {
      "index": 0,
      "delta": {
        "content": "Here "
      },
      "finish_reason": null
    }
  ]
}

Example approval chunk:

{
  "id": "chatcmpl_123",
  "object": "chat.completion.chunk",
  "created": 1712345678,
  "model": "group:123e4567-e89b-12d3-a456-426614174000",
  "choices": [
    {
      "index": 0,
      "delta": {
        "tool_calls": [
          {
            "id": "1fb2fd25-8f78-412a-a0b8-7976e3700fc4",
            "type": "function",
            "function": {
              "name": "create_ticket",
              "arguments": "{\"priority\":\"high\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ],
  "kitemesh": {
    "approval_id": "86dd028d-6f5c-4f13-83db-d4fe9bc5b865",
    "execution_id": "3e6f4f5d-c02a-4cae-b35d-e83420867962",
    "expires_at": "2026-06-08T16:20:00.000Z",
    "request_id": "req_demo_001"
  }
}

The end of the stream is marked with:

data: [DONE]