API Reference Overview

GhostMind exposes an OpenAI-compatible API for a subset of capabilities, plus GhostMind-specific conversation, project, asset, audio-job and Action APIs. It is not a drop-in implementation of every OpenAI API.

Source inventory reviewed: 2026-09-10, revision 9a6a273. This is a source snapshot, not confirmation that this revision is deployed. Check the deployed specification and feature availability before integrating.

API surfaces

Surface	Prefix	Authentication	Intended audience
Product API	/v1/*	Workspace API key in Authorization: Bearer …	Applications and developers
User App BFF	/me/v1/*	Login cookie; CSRF for mutations	GhostMind web app
Control Plane	/admin/v1/*	JWT and role checks	Authorized administrators/operators

The API origin is https://ghostmind.optdmsa.com. Append the full paths below. For the OpenAI SDK, use https://ghostmind.optdmsa.com/v1 as base_url. Never ship an administrator token or a provider session cookie in client code.

Public endpoint inventory

The reviewed specification contains 41 paths / 51 method-and-path operations. Multiple methods in one row are distinct operations. Auth, ownership, feature flags, quotas and provider availability still apply.

Chat, conversations and assets — 22 operations

Path	Methods	Purpose
/v1/chat/completions	POST	Chat, including SSE when stream: true
/v1/models	GET	Model discovery
/v1/conversations	GET, POST	List or explicitly create conversations
/v1/conversations/{conversation_id}	GET, PATCH, DELETE	Inspect, update or soft-delete
/v1/conversations/{conversation_id}/messages	GET	Message history
/v1/conversations/{conversation_id}/attachments	POST	Multipart upload
/v1/conversations/{conversation_id}/sync	POST	Synchronize upstream state
/v1/conversations/{conversation_id}/archive	POST	Archive
/v1/conversations/{conversation_id}/restore	POST	Restore
/v1/conversations/{conversation_id}/share	POST	Grant participant access
/v1/conversations/{conversation_id}/participants	GET	List participants
/v1/conversations/{conversation_id}/participants/{user_id}	PATCH, DELETE	Change or revoke participant access
/v1/conversations/{conversation_id}/transfer	POST	Transfer ownership, subject to authorization
/v1/conversations/{conversation_id}/assets	GET	List conversation assets
/v1/messages/{message_id}	GET	Message and asset state
/v1/assets/{asset_id}	GET	Asset metadata/state
/v1/assets/{asset_id}/retry	POST	Request failed-asset recovery
/v1/assets/{asset_id}/download	GET	Authenticated binary download

Projects — 8 operations

Path	Methods	Purpose
/v1/projects	GET, POST	List or create upstream projects
/v1/projects/{project_id}	GET, PATCH, DELETE	Read, update or delete a project
/v1/projects/{project_id}/files	GET, POST	List or upload project sources
/v1/projects/{project_id}/files/{source_id}	DELETE	Delete a project source

Audio — 11 operations

Path	Methods	Purpose
/v1/audio/transcriptions	POST	Audio-to-text multipart request
/v1/audio/providers	GET	Provider discovery
/v1/audio/providers/{provider}/capabilities	GET	Provider capabilities
/v1/audio/providers/{provider}/voices	GET	Voice catalog
/v1/audio/generations	GET, POST	List or create asynchronous speech jobs
/v1/audio/generations/{job_id}	GET	Job state
/v1/audio/generations/{job_id}/content	GET	Completed audio content
/v1/audio/generations/{job_id}/cancel	POST	Request cancellation
/v1/audio/generations/{job_id}/retry	POST	Retry a failed job
/v1/audio/speech	POST	Bounded synchronous speech request

Discovery and usage — 3 operations

Path	Methods	Purpose
/v1/capabilities	GET	Capability manifest
/v1/connections	GET	Read-only account inventory and projected health
/v1/usage	GET	Aggregated request/token counters scoped to the calling API key (?period=24h|7d|30d)

Health and capability values are projections, not a successful live probe for every feature. In particular, an active account or enabled: true does not prove that a particular image, project-file or audio request will succeed.

Actions and runs — 9 operations

Path	Methods	Required scope	Purpose
/v1/actions	GET	actions:read	Published/active catalog
/v1/actions/{slug}	GET	actions:read	Action details
/v1/actions/{slug}/assets	GET	actions:read	List uploaded run assets
/v1/actions/{slug}/assets	POST	actions:run	Multipart file upload; returns asset_id
/v1/actions/{slug}/runs	GET	actions:read	Run history
/v1/actions/{slug}/runs	POST	actions:run	Submit execution; returns HTTP 202
/v1/actions/{slug}/runs/{run_id}	GET	actions:read	Run result/state
/v1/actions/{slug}/runs/{run_id}/events	GET	actions:read	Execution events
/v1/actions/{slug}/runs/{run_id}/cancel	POST	actions:run	Request cancellation

Execution requires an enabled UAC service, an authorized beta-cohort workspace, a published Action version, appropriate risk policy and any required connection. Catalog visibility alone does not prove execution eligibility.

The run request accepts input (object), optional connection_id (UUID string), and optional idempotency_key (string). Obtain the Action’s required input contract from its publisher: the current public Action response does not expose a full input/output schema.

curl "https://ghostmind.optdmsa.com/v1/actions/$ACTION_SLUG/runs" \
  -H "Authorization: Bearer $GHOSTMIND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {}, "idempotency_key": "replace-with-your-operation-id"}'

This example requires an Action whose input accepts {}; it is not a universal payload. Use a new key for a new intended operation and reuse the same key when reconciling that operation. Audio jobs instead accept an Idempotency-Key header. Chat requests do not have a documented equivalent guarantee.

HTTP 202 means accepted, not business success. Poll the run resource and inspect status, verdict, output and error fields. needs_review is not success. Cancellation does not undo external effects that already occurred. Never blindly resubmit a write after an uncertain timeout.

File inputs (Actions that accept uploads)

Some published Actions declare file inputs (for example a photo upload Action). For each file input, upload the bytes first, then reference the returned asset_id in the run input:

# 1) Upload the file (multipart). Max 20 MiB by default.
curl -X POST "https://ghostmind.optdmsa.com/v1/actions/$ACTION_SLUG/assets" \
  -H "Authorization: Bearer $GHOSTMIND_API_KEY" \
  -F "file=@photo.png;type=image/png"
# → {"asset_id": "...", "filename": "photo.png", ...}

# 2) Reference it in the run input — one asset is consumed by exactly one run.
curl -X POST "https://ghostmind.optdmsa.com/v1/actions/$ACTION_SLUG/runs" \
  -H "Authorization: Bearer $GHOSTMIND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"photo": {"asset_id": "<asset_id>"}, "caption": "hello"}}'

Assets are scoped to the calling workspace and that Action, expire (default 24 h), are checksum-verified at execution, and are consumed on use — a second run with the same asset_id fails with ASSET_INPUT_INVALID. Missing, expired, foreign-workspace or corrupt assets fail the run loudly; an empty file is never sent upstream.

Features not exposed as public developer APIs

There are currently no /v1 routes for workspace/key/invitation management, account connect/reconnect/capture, or the complete UAC teach/compile/verify/publish journey. These use the User App or authorized Control Plane. Usage IS exposed at GET /v1/usage — key-scoped aggregates only. Do not invent routes or use administrator credentials to work around gaps.

Generic browser execution and AI repair are not generally enabled execution features. Human login, MFA and CAPTCHA remain human-mediated.

OpenAPI and compatibility

Use public OpenAPI at https://ghostmind.optdmsa.com/openapi-public.json and the interactive https://ghostmind.optdmsa.com/docs-public. The full /openapi.json and /redoc include internal surfaces.

The current public schema is incomplete: Bearer security metadata and several response, SSE and binary schemas are missing. Configure authorization explicitly in generated clients and validate against the deployed API. See Errors for envelope variations and Rate Limits for the current throttling contract.

Integration checklist

1. Use a workspace API key and least-privilege scopes; never provider credentials.
2. Discover models and capabilities, then handle runtime refusal explicitly.
3. Preserve X-GhostMind-Conversation-Id for chat continuity.
4. Send uploads as multipart without manually setting the multipart boundary.
5. Stop on response.failed in SSE; verify asset readiness before downloading.
6. Bound polling/retries and distinguish acceptance from completion.
7. Record response correlation IDs without recording credentials or sensitive content.
8. Test invalid/expired keys, insufficient scopes, wrong-workspace resources, rate limits, timeouts, cancellation and provider reconnection in a sandbox.