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 sk-gm-..." \
  -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.
temperature	float	No	1.0	Sampling temperature (0-2).
max_tokens	int	No	—	Maximum tokens to generate.
conversation_id	string	No	—	UUID for conversation continuity.
project_id	string	No	—	UUID for project-native conversation.

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

To continue a conversation:

1. First request: Omit conversation_id — a new conversation is created
2. The response includes a conversation_id (in headers or metadata)
3. Pass that conversation_id in subsequent requests

Project Conversations

To start a project-native conversation:

1. Pass a project_id parameter
2. The AI has access to project files from the first message
3. 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