OpenAI context cleanup

Tools provides a lightweight OpenAI context-cleanup endpoint for clients that capture noisy screen-reader or accessibility text before asking for a reply or a fact check.

Use this endpoint when the client already has visible text but needs Tools to remove obvious UI noise before sending that context into another AI request.

Endpoint

POST /api/ai/openai/context

This is a generic OpenAI / AI endpoint. It is not a SocialGPT-specific route, even though SocialGPT tokens may be accepted for this narrow cleanup task.

Authentication

Send one of these as a bearer token:

a Tools OpenAI/internal token with ai.internal
a SocialGPT/client token with ai.socialgpt

Example:

Authorization: Bearer YOUR_API_TOKEN

A signed-in web/API user with approved OpenAI access may also use the endpoint.

Request body

{
  "context_text": "Raw text captured from the screen reader",
  "mode": "reply",
  "response_language": "auto",
  "client_slug": "android_context_cleanup"
}

Fields:

Field	Required	Notes
`context_text`	yes	Raw captured screen-reader/accessibility text.
`mode`	no	`reply`, `verify`, or `auto`. The mode tells Tools which visible text should be preserved most carefully.
`model`	no	Optional server-allowed OpenAI model. Defaults to `gpt-5-nano`. o4 models are always replaced with `gpt-5-nano`.
`max_tokens`	no	Optional output budget from 64 to 1200 tokens.
`response_language`	no	`auto`, `sv`, `en`, `da`, `no`, `de`, `fr`, or `es`.
`client_slug`	no	Stable caller identifier. Android should use a stable app-specific value.
`client_name`, `client_version`, `client_platform`	no	Safe client metadata for diagnostics.

Response body

The provider request uses a strict structured-output schema. Tools only returns success when the provider completes the response and the returned JSON matches the cleanup contract.

Successful responses include:

{
  "ok": true,
  "cleaned_context": "Ordered visible text with buttons and repeated UI controls removed.",
  "summary": "Short summary of what the captured text is about.",
  "main_topic": "Optional topic",
  "participants": [],
  "current_statement": "Optional likely active statement",
  "relevant_context": "Optional supporting context",
  "discarded_noise": [],
  "model": "gpt-5-nano",
  "usage": null,
  "timing": {
    "total_processing_ms": 1234
  }
}

If a client requests an o4 model, ToolsAPI forces the effective model to gpt-5-nano and adds a dedicated notice field:

{
  "notice": {
    "code": "model_replaced",
    "requested_model": "o4-mini",
    "effective_model": "gpt-5-nano",
    "message": "o4 models are disabled in ToolsAPI and were replaced with gpt-5-nano."
  }
}

cleaned_context is the primary field for follow-up Reply or Verify Fact calls. It should keep concrete wording from the captured content where possible, while removing obvious UI chrome such as buttons, menus, repeated labels, counters and unrelated accessibility noise.

Error handling

The endpoint returns safe, client-friendly errors. Android should show user_message when present and fall back to the raw captured context when cleanup fails.

Provider responses that are incomplete, truncated, not valid JSON, or do not match the cleanup schema are returned as failures rather than partial ok=true cleanup results.

Common error_code values:

Code	Meaning
`unauthenticated`	No usable Tools token or session was supplied.
`token_scope_denied`	The token does not have `ai.internal` or `ai.socialgpt`.
`openai_access_required`	The signed-in account does not have OpenAI access and no accepted SocialGPT token was used.
`provider_not_configured`	Tools has no OpenAI provider configured.
`openai_quota_exhausted`	The OpenAI provider has no remaining credits or quota.
`openai_rate_limited`	OpenAI rate-limited the request.
`openai_timeout`	OpenAI did not answer in time.
`openai_incomplete_response`	OpenAI returned an incomplete or truncated response.
`openai_malformed_response`	OpenAI returned cleanup data that did not match the expected JSON contract.
`model_unavailable`	The selected model is unavailable or rejected.
`openai_request_failed`	Generic upstream failure.

Client guidance

For Android, run context cleanup before Reply and Verify Fact when the user has enabled "Analyze context before asking". Keep the raw captured context available locally so the user can inspect it and so the app can fall back if cleanup fails.

Tornevall Networks