State API

Overview

The State API learns how the User side of your conversations writes and makes decisions, building a persistent State in the base model’s representation space without modifying its weights.

Once a State is built from your uploaded conversations, calling /completions generates the next User message for a given context. Each API key manages one State; the full OpenAPI specification is available at GET /openapi.yaml.

Authentication

All API requests are authenticated with an API key. To request a key, email hello@topovoid.com, then call /register once to activate it before making other calls.

Every endpoint except /register and /openapi.yaml requires an Authorization: Bearer $TOPOVOID_API_KEY header. Keep your API key on the server side—never embed it in browsers, mobile apps, or other client-side code.

POST/registerKey in the body

Activates and registers an API key. This endpoint is idempotent; calling it again with an already-registered key is a no-op.

Returns {"ok": true, "user_id": "..."}.

curl https://api.topovoid.com/reflecho/register \
  -H "Content-Type: application/json" \
  -d "{\"apikey\": \"$TOPOVOID_API_KEY\"}"

Upload conversations

POST/uploadBearer key

Uploads training conversations as a JSON array (optionally compressed with Content-Encoding: gzip). Uploading a conversation whose id already exists overwrites the previous version; setting value to null deletes that conversation.

Each entry in messages has the following shape:

Every conversation must end with a User message, and consecutive User messages must be separated by at least one non-User turn. AssistantThink and ToolCall entries are preserved as context but excluded from the training loss.

Returns 204 No Content on success.

[
  {
    "id": "0199f1a2-6c3e-7d10-9a4b-2f8e5c1d7a30",
    "value": {
      "messages": [
        { "type": "User", "content": "Review the service entry point." },
        { "type": "Assistant", "content": "Config and start-up are coupled." },
        { "type": "User", "content": "Don't change it. Show me the tests." }
      ]
    }
  }
]

curl https://api.topovoid.com/reflecho/upload \
  -H "Authorization: Bearer $TOPOVOID_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @sessions.json

Build a State

POST/flush-stateBearer key

Triggers a background build across all currently uploaded conversations. Once trained, the candidate State is promoted to active only after passing automated validation checks; if a build or check fails, your previously active State remains in service untouched.

Building a State requires at least 10 training examples, where each User turn preceded by at least one earlier message in the same conversation counts as one example. The request body is optional—any omitted hyperparameters fall back to the selected preset:

Returns 202 Accepted with the same status payload as /state-status.

curl https://api.topovoid.com/reflecho/flush-state \
  -H "Authorization: Bearer $TOPOVOID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"preset": "full"}'

Check build status

GET/state-statusBearer key

Returns the current status of the most recent build job. When waiting for a build to finish, polling every ~30 seconds is recommended.

curl https://api.topovoid.com/reflecho/state-status \
  -H "Authorization: Bearer $TOPOVOID_API_KEY"

{
  "status": "building",
  "phase": "training",
  "progress": { "attempt": 1, "step": 18, "total_steps": 37 },
  "start_at": "2026-10-16T08:12:03.418+00:00",
  "active": null
}

Create a completion

POST/completionsBearer key

Generates the next User message for an ongoing conversation using your active State.

curl https://api.topovoid.com/reflecho/completions \
  -H "Authorization: Bearer $TOPOVOID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "0199f1a2-8b40-7c55-a1d3-5e7f00c2b9a4",
       "context": "User: All tests pass. Ready to commit.\n\nAssistant:"}'

{
  "response": "Cover the failure paths too.",
  "time": 1842,
  "confidence": 0.74
}

Context format

Because the underlying model always completes after an Assistant: prefix while your State models the User, role labels in context are swapped relative to /upload: format prior User turns as Assistant: and prior Assistant turns as User:. Separate turns with a blank line, omit AssistantThink and ToolCall entries, and end the string with Assistant: so the model generates the next user reply:

Assistant: Review the service entry point.

User: Config and start-up are coupled.

Assistant: Don't change it. Show me the tests.

User: All tests pass. Ready to commit.

Assistant:

Errors

Failed requests return a JSON body of the form {"code": "...", "message": "..."}. Branch on code rather than the human-readable message:

Limits

• Prompts are capped at roughly 32,000 tokens.
• /completions returns a single JSON response; token streaming is not supported.
• Build and completion jobs are processed sequentially and may queue under load.
• Uploaded conversations persist until explicitly deleted via /upload with value: null. Completion requests and responses are logged on the server.