Conversations

Conversation Lifecycle

Conversations in GhostMind are created locally and linked to a connected ChatGPT account. The upstream ChatGPT conversation is created on the first message.

Create a Conversation

curl -X POST https://ghostmind.optdmsa.com/v1/conversations \
  -H "Authorization: Bearer $GHOSTMIND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My Research Chat",
    "upstream_project_id": "project-uuid"
  }'

Body:

• title (optional) — Human-readable title
• upstream_project_id (optional) — UUID of a project to create the conversation in
• upstream_account_id (optional) — Specific account UUID. Auto-selected if omitted.
• model (optional) — Preferred model

Response (201):

{
  "id": "conv-uuid",
  "status": "active",
  "title": "My Research Chat",
  "upstream_account_id": "account-uuid",
  "upstream_project_id": "project-uuid",
  "destination_type": "project",
  "created_at": "2026-08-25T10:00:00Z"
}

List Conversations

curl https://ghostmind.optdmsa.com/v1/conversations?limit=50 \
  -H "Authorization: Bearer $GHOSTMIND_API_KEY"

Query parameters:

• limit — Max results (default 50)
• offset — Pagination offset
• status_filter — Filter by status (active, archived, etc.)
• search — Search by title
• pinned_only — Only pinned conversations
• destination_filter — general or project
• account_filter — Filter by upstream_account_id
• project_filter — Filter by upstream_project_id

Get Conversation

curl https://ghostmind.optdmsa.com/v1/conversations/{conversation_id} \
  -H "Authorization: Bearer $GHOSTMIND_API_KEY"

Continue a Conversation

Use the X-GhostMind-Conversation-Id header to continue a conversation:

curl -X POST https://ghostmind.optdmsa.com/v1/chat/completions \
  -H "Authorization: Bearer $GHOSTMIND_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-GhostMind-Conversation-Id: conv-uuid" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "Follow-up question"}]
  }'

The conversation ID is also returned in the X-GhostMind-Conversation-Id response header from chat completions.

Conversation Messages

curl https://ghostmind.optdmsa.com/v1/conversations/{conversation_id}/messages \
  -H "Authorization: Bearer $GHOSTMIND_API_KEY"

Sync Conversation

Pull the latest state from the upstream ChatGPT conversation:

curl -X POST https://ghostmind.optdmsa.com/v1/conversations/{conversation_id}/sync \
  -H "Authorization: Bearer $GHOSTMIND_API_KEY"

Archive / Restore

# Archive
curl -X POST https://ghostmind.optdmsa.com/v1/conversations/{conversation_id}/archive \
  -H "Authorization: Bearer $GHOSTMIND_API_KEY"

# Restore
curl -X POST https://ghostmind.optdmsa.com/v1/conversations/{conversation_id}/restore \
  -H "Authorization: Bearer $GHOSTMIND_API_KEY"

Delete Conversation

curl -X DELETE https://ghostmind.optdmsa.com/v1/conversations/{conversation_id} \
  -H "Authorization: Bearer $GHOSTMIND_API_KEY"

Sticky Binding

Conversations are sticky — once started on a specific provider account, they remain on that account. GhostMind does not rebalance mid-conversation. This ensures continuity of the upstream ChatGPT conversation thread.

Continuity Status

Conversations track their upstream continuity status:

Status	Meaning
available	Conversation is healthy and can be continued
deleted_upstream	The upstream ChatGPT conversation was deleted
access_lost	Access to the upstream conversation was lost
session_expired	The upstream account session has expired
continuity_lost	The parent message chain is broken
project_unavailable	The ChatGPT project is no longer available
upstream_unavailable	The upstream account is temporarily unavailable

Next Steps

• Chat Completions — Send messages
• Projects — Project-scoped conversations
• Conversation Continuity — Concept overview