Chat Completions

POST /v1/chat/completions

Create a chat completion. Supports both streaming and non-streaming responses.

Request

curl https://ghostmind.optdmsa.com/v1/chat/completions \
  -H "Authorization: Bearer gmk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello!"}
    ],
    "stream": false,
    "temperature": 0.7,
    "max_tokens": 1000
  }'

Parameters

Field	Type	Required	Default	Description
model	string	Yes	—	Model identifier. Use auto for automatic routing.
messages	array	Yes	—	Array of {role, content} objects.
stream	boolean	No	false	Enable SSE streaming.
attachment_file_ids	array	No	—	file_ids from POST /v1/conversations/{id}/attachments to attach files.
temperature	float	No	—	Accepted but ignored (ChatGPT does not expose it).
top_p	float	No	—	Accepted but ignored.
max_tokens	int	No	—	Accepted but ignored.

Rejected parameters (400 UNSUPPORTED_PARAMETER): tools, tool_choice, n>1, logprobs.

NOT supported as body fields (unknown fields are silently ignored — extra: ignore): conversation_id, project_id. Use the routing headers or POST /v1/conversations instead — see below.

Response (Non-Streaming)

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "model": "auto",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 10,
    "total_tokens": 30
  }
}

Response (Streaming)

When stream: true, the response is Server-Sent Events:

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"content":"Hello"}}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"content":"!"}}]}

data: [DONE]

See Streaming for detailed SSE documentation.

Conversation Continuity

Continuity is header-based — there is NO conversation_id body field:

1. First request: send no conversation header — a new conversation is created
2. Read the X-GhostMind-Conversation-Id response header
3. Pass X-GhostMind-Conversation-Id: <id> as a request header on subsequent calls (or create the conversation up front via POST /v1/conversations and use its id)

A request with no routing lands in the account’s general space — GhostMind does not create an upstream project per request by default.

Project Conversations

Projects from POST /v1/projects are upstream projects. Either:

1. Create the conversation with POST /v1/conversations {"upstream_project_id": "<uuid>"} and continue via X-GhostMind-Conversation-Id, or
2. Route the request directly with X-GhostMind-Upstream-Project: <slug> (slug, not UUID)

The AI has access to project files from the first message, and the conversation is permanently linked to that project.

Errors

Status	Error Type	Cause
401	invalid_api_key	Missing or invalid API key
429	rate_limit_exceeded	Rate limit hit
503	provider_unavailable	No healthy upstream session
503	shutting_down	Server is shutting down

Next Steps

• Streaming — SSE format details
• Conversations — Conversation management
• Models — Available models