Social Media Tools AI API (Tools)

This page documents the Social Media Tools / SocialGPT-specific API surface.

This is intentionally separate from:

OpenAI Engine docs: /docs/en/ai/openai
Copilot docs: /docs/en/ai/copilot

Scope and auth model

Social Media Tools AI endpoints are intended for SocialGPT/browser-extension style traffic.

primary token scope: ai.socialgpt
legacy alias accepted: ai.client
token source is your personal Tools token from /keys/mine

The Facebook outcome-configuration bridge uses the same current scoped SocialGPT bearer resolver as the extension AI endpoints. Current provider_socialgpt tokens and compatible legacy SocialGPT tokens are therefore authorized by scope instead of by the old provider name alone.

Android account sign-in sync

The Android Tools client can request its dedicated SocialGPT credential during the normal unversioned POST /api/account/login request by adding the optional boolean field sync_socialgpt_token=true.

A successful response keeps the normal account-session fields and adds a separate socialgpt_token object containing access_token, token_type, scope, provider, created, and rotated. Android persists socialgpt_token.access_token for Social Media Tools. The top-level account-session JWT is a different credential and must not be substituted for the scoped SocialGPT credential.

The login-sync flow uses a dedicated owner-bound Android SocialGPT credential. Browser-pairing credentials and other manually created SocialGPT credentials are separate and are never selected for Android login sync. A healthy dedicated Android credential is reused without rewriting it. A missing credential is created, while an inactive, empty, globally scoped, incorrectly scoped, or otherwise unhealthy dedicated Android credential is rotated and narrowed back to the single ai.socialgpt scope.

If account authentication succeeds but the requested SocialGPT synchronization cannot be completed and auditable, Tools returns HTTP 503 with error_code: socialgpt_token_sync_failed. No partial SocialGPT credential is returned.

Endpoints

`POST /api/ai/socialgpt/respond`

SocialGPT-style reply/verify/modify endpoint.

Use this for extension/client contracts that depend on SocialGPT fields and behavior.

Direct context input on this endpoint remains limited to 60,000 characters. Clients that need to prepare larger context should use a prefetch session and send prefetch_session_id with the final request.

A successful SocialGPT text response must contain visible response text. If an otherwise successful reasoning-model response consumes its output budget without producing visible text, Tools performs one bounded retry with lower reasoning effort and a larger output allowance. If that retry still produces no visible answer, Tools returns HTTP 502 with error_code: empty_visible_response instead of returning ok: true with an empty response.

`POST /api/ai/prefetch-sessions/open`

Opens or reuses a SocialGPT prefetch session. A context fragment may be supplied immediately or added later.

Each prefetch context upload is limited to 500,000 characters. A complete prefetch session may contain up to 1,000,000 context characters.

If the prefetch store cannot persist the session, Tools returns HTTP 503 with the sanitized payload:

{
  "ok": false,
  "error": "Could not persist the requested prefetch session."
}

Clients should treat this as a temporary service/storage failure rather than a validation failure and must not assume that the session was created or renewed.

`POST /api/ai/prefetch-sessions/{sessionId}/context`

Adds or replaces context in an existing prefetch session. Use fragment_key to keep independent context fragments, or send replace=false to append to an existing fragment.

Accumulated fragment content is preserved when more context is appended. The response includes context_char_count, max_fragment_input_char_count, and max_context_char_count so clients can track the current session budget.

If the updated session cannot be persisted, this endpoint returns the same HTTP 503 payload shown for the open endpoint. The client must not treat that response as a successful append.

`DELETE /api/ai/prefetch-sessions/{sessionId}`

Closes a prefetch session when the client no longer needs it.

Close is idempotent. Closing a session that was already closed, expired, does not exist, or is not owned by the authenticated user still returns HTTP 200 because the caller's desired end state is already satisfied. Tools does not disclose whether a non-owned session exists and never deletes another user's session.

A close that removes a live owned session returns closed=true, already_closed=false, and the final safe session summary. An already-absent/non-owned close returns the same non-disclosing success shape:

{
  "ok": true,
  "closed": false,
  "already_closed": true,
  "session": null
}

A real prefetch-store access failure still returns HTTP 503 with a sanitized error response; backend/cache details are not exposed to the client.

`GET /api/social-media-tools/extension/validate-token`

Validates token shape/scope for extension flows.

`GET /api/social-media-tools/extension/test`

`POST /api/social-media-tools/extension/test`

Extension smoke-test endpoints.

`GET /api/social-media-tools/extension/models` (legacy alias)

Backward-compatible alias for GET /api/ai/models.

For new clients, use /api/ai/models.

`GET /api/social-media-tools/facebook/outcome-config`

Returns the Facebook admin outcome-detection configuration for an authenticated SocialGPT client. Authentication uses the ai.socialgpt scope and the same current bearer-token resolver as other SocialGPT extension endpoints.

Important separation

Social Media Tools API traffic is not the same as generic internal OpenAI runtime traffic.
For generic internal assistant/runtime integrations, use /api/ai/internal/respond and read /docs/en/ai/openai.

Tornevall Networks