Your First Request

Now that you have an API key, let’s make a real request and understand each part.

The Request

curl https://ghostmind.optdmsa.com/v1/chat/completions \
  -H "Authorization: Bearer $GHOSTMIND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Explain quantum computing in one sentence."}
    ],
    "temperature": 0.7,
    "max_tokens": 100
  }'

Request Fields

Field	Type	Required	Description
model	string	Yes	Model identifier. Use auto for automatic routing.
messages	array	Yes	Array of message objects with role and content.
temperature	float	No	Sampling temperature (0-2). Default: 1.0
max_tokens	int	No	Maximum tokens to generate.
stream	bool	No	Enable SSE streaming. Default: false
conversation_id	string	No	UUID for conversation continuity.

Message Roles

Role	Description
system	Sets assistant behavior (optional, first message)
user	User input
assistant	Previous assistant response (for context)

The Response

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1723190400,
  "model": "auto",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Quantum computing harnesses quantum mechanical phenomena..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 18,
    "total_tokens": 43
  }
}

Response Fields

Field	Description
id	Unique completion ID
object	Always chat.completion
model	Model used for this request
choices	Array of completion choices
choices[].finish_reason	stop, length, content_filter, or error
usage	Token usage for this request

Conversation Continuity

To maintain context across multiple requests, pass a conversation_id:

1. First request: Omit conversation_id — a new conversation is created
2. Response: The response includes a conversation_id in the headers or body
3. Follow-up: Pass that conversation_id in subsequent requests

# First message
curl https://ghostmind.optdmsa.com/v1/chat/completions \
  -H "Authorization: Bearer $GHOSTMIND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "auto", "messages": [{"role": "user", "content": "My name is Alice."}]}'

# Follow-up (use the conversation_id from the first response)
curl https://ghostmind.optdmsa.com/v1/chat/completions \
  -H "Authorization: Bearer $GHOSTMIND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "conversation_id": "conv-uuid-from-first-response",
    "messages": [{"role": "user", "content": "What is my name?"}]
  }'

Streaming

For real-time responses, set stream: true:

curl https://ghostmind.optdmsa.com/v1/chat/completions \
  -H "Authorization: Bearer $GHOSTMIND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "stream": true,
    "messages": [{"role": "user", "content": "Tell me a story."}]
  }'

See Streaming for detailed SSE format documentation.

Errors

If something goes wrong, you’ll receive an error response:

{
  "error": {
    "message": "No healthy upstream session available.",
    "type": "provider_unavailable",
    "code": "no_healthy_session"
  }
}

See Errors for a complete reference.

Next Steps

• Streaming — Real-time SSE responses
• Conversations — Conversation continuity API
• Models & Capabilities — Available models