Connections

GET /v1/connections

Returns the upstream provider accounts connected to your workspace. Use this to check which providers are available and their health status.

curl https://ghostmind.optdmsa.com/v1/connections \
  -H "Authorization: Bearer $GHOSTMIND_API_KEY"

Response:

[
  {
    "id": "account-uuid",
    "label": "My ChatGPT Account",
    "provider": "chatgpt",
    "provider_family": null,
    "status": "active",
    "health": "healthy",
    "is_default": false,
    "created_at": "2026-08-25T10:00:00Z",
    "last_used_at": null
  }
]

Health Values

The health field reflects the real, actionable health of the account — not just its configured status. It is derived from the circuit breaker state and the account’s session validity.

Health	Meaning	Action
`healthy`	Account is connected, session is valid, and the circuit breaker is closed	None — ready for requests
`unhealthy`	Account is connected but the session is expired or the circuit breaker is open due to repeated failures	Reconnect the account
`rate_limited`	The upstream provider (ChatGPT) returned 429 — the account is temporarily throttled	Wait for the cooldown to expire (shown in `cooldown_seconds`)
`cooldown`	The circuit breaker is open due to repeated non-rate-limit failures	Wait for the cooldown to expire
`unknown`	Health could not be determined (e.g., account just connected, no requests yet)	Send a test request to determine health

Note: rate_limited and cooldown include a cooldown_seconds field with the remaining cooldown time. rate_limited uses a longer cooldown (5 minutes) because ChatGPT rate limits typically last minutes, not seconds.

Query Parameters

Parameter	Type	Description
`provider`	string	Filter by provider name (`chatgpt`, `google_ai_studio_savio_tts`)
`status`	string	Filter by status (`active`, `disabled`, `expired`, `cooldown`, `rate_limited`, `configured`)
`limit`	int	Max results (default 50, max 200)
`offset`	int	Pagination offset

Status Values

Status	Meaning
`active`	Account is connected and ready for use
`configured`	Account exists but not yet ready (e.g., awaiting session capture)
`disabled`	Account has been manually disabled
`expired`	Session has expired, reconnection needed
`cooldown`	Account is in cooldown after repeated failures
`rate_limited`	Account is temporarily throttled by the upstream provider (429)

Provider Values

Provider	Description
`chatgpt`	ChatGPT web account (browser-backed)
`google_ai_studio_savio_tts`	Google AI Studio / Savio TTS

Connection Management

Connection management (create, reconnect, disable, delete) is done through the GhostMind dashboard at app.ghostmind.optdmsa.com, not through the public API. This is because connecting an account requires a browser-based authentication flow (login, OTP, MFA, session capture).

Next Steps

Capabilities — Platform capability manifest
Authentication — API key setup
Connection Concept — How connections work