Browse docsshow

API reference

Base URL: https://api.tobeverified.com. All /v1/* endpoints require Authorization: Bearer $TBV_API_KEY. See Authentication.

Surface is small and stable as of 0.5.1. New endpoints (webhooks, batch submit, idempotency keys) marked on the roadmap.

POST

/v1/tasks

Submit a verification task.

Request body

json

{
  "prompt": "string",                          // required — the question the verifier is asked
  "context": { ... },                          // arbitrary JSON the verifier evaluates against
  "allowed_verdicts": ["yes", "no"],           // required — non-empty array of allowed strings
  "confidence_threshold": 0.85,                // 0 to 1 — below this, route to human
  "task_type": "decide",                       // optional, default "decide"
  "touchpoint": "chat",                        // optional, default "chat"
  "source": "my-app/refund-classifier"         // optional, free-form, useful for filtering later
}

Response (200)

json

{
  "id": "tsk_<hex16>",
  "status": "pending" | "agent_running" | "human_needed" | "completed",
  "task_type": "decide",
  "source": "my-app/refund-classifier",
  "touchpoint": "chat",
  "prompt": "...",
  "allowed_verdicts": ["yes", "no"],
  "confidence_threshold": 0.85,
  "final_verdict": null | "yes",
  "final_tier": null | "agent" | "human",
  "final_confidence": null | 0.0..1.0,
  "created_at": 1715284800.123,
  "completed_at": null | 1715284910.456,
  "attempts": [ ... ]
}

Errors

400 — missing prompt, empty allowed_verdicts, threshold out of range
401 — invalid bearer
429 — daily cap exceeded

GET

/v1/tasks/:id

Fetch task state. Returns the same shape as POST /v1/tasks.

Errors

404 — task ID not found, OR belongs to a different account (not disambiguated)
401 — invalid bearer

GET

/demo/tasks

no auth

List the curated demo queue used by review.tobeverified.com's anonymous mode. Useful if you want to embed the demo elsewhere.

Response (200)

json

{
  "tasks": [
    {
      "id": "tsk_demo_refund",
      "source": "demo/refund-classification",
      "prompt": "...",
      "allowed_verdicts": ["yes", "no"],
      "context": { "message": "..." },
      "created_at": 1715284800.123
    },
    ...
  ]
}

POST

/demo/verdicts

no auth

Record a verdict against a demo task. Persists in demo_verdicts for eval signal; never modifies the demo task itself.

Request body

json

{
  "task_id": "tsk_demo_refund",
  "verdict": "yes",
  "rationale": "optional reviewer note",
  "anon_session_id": "optional cookie value to group verdicts per visitor"
}

Errors

400 — missing field, or verdict not in allowed_verdicts
404 — task isn't owned by the demo account

GET

/healthz

no auth

Returns {"ok": true} if the worker is up. Useful for uptime monitors.

Conventions

Timestamps are Unix epoch seconds with fractional milliseconds, as JSON numbers.
Errors always return JSON with {"error": "human-readable description"} and an HTTP status code.
Versioning is via the URL path (/v1/...). Breaking changes get a new path; additive changes (new optional fields, new endpoints) ship under /v1 without a bump.

API reference

Base URL: https://api.tobeverified.com. All /v1/* endpoints require Authorization: Bearer $TBV_API_KEY. See Authentication.

Surface is small and stable as of 0.5.1. New endpoints (webhooks, batch submit, idempotency keys) marked on the roadmap.

POST

/v1/tasks

Submit a verification task.

Request body

json

{
  "prompt": "string",                          // required — the question the verifier is asked
  "context": { ... },                          // arbitrary JSON the verifier evaluates against
  "allowed_verdicts": ["yes", "no"],           // required — non-empty array of allowed strings
  "confidence_threshold": 0.85,                // 0 to 1 — below this, route to human
  "task_type": "decide",                       // optional, default "decide"
  "touchpoint": "chat",                        // optional, default "chat"
  "source": "my-app/refund-classifier"         // optional, free-form, useful for filtering later
}

Response (200)

json

{
  "id": "tsk_<hex16>",
  "status": "pending" | "agent_running" | "human_needed" | "completed",
  "task_type": "decide",
  "source": "my-app/refund-classifier",
  "touchpoint": "chat",
  "prompt": "...",
  "allowed_verdicts": ["yes", "no"],
  "confidence_threshold": 0.85,
  "final_verdict": null | "yes",
  "final_tier": null | "agent" | "human",
  "final_confidence": null | 0.0..1.0,
  "created_at": 1715284800.123,
  "completed_at": null | 1715284910.456,
  "attempts": [ ... ]
}

Errors

400 — missing prompt, empty allowed_verdicts, threshold out of range
401 — invalid bearer
429 — daily cap exceeded

GET

/v1/tasks/:id

Fetch task state. Returns the same shape as POST /v1/tasks.

Errors

404 — task ID not found, OR belongs to a different account (not disambiguated)
401 — invalid bearer

GET

/demo/tasks

no auth

List the curated demo queue used by review.tobeverified.com's anonymous mode. Useful if you want to embed the demo elsewhere.

Response (200)

json

{
  "tasks": [
    {
      "id": "tsk_demo_refund",
      "source": "demo/refund-classification",
      "prompt": "...",
      "allowed_verdicts": ["yes", "no"],
      "context": { "message": "..." },
      "created_at": 1715284800.123
    },
    ...
  ]
}

POST

/demo/verdicts

no auth

Record a verdict against a demo task. Persists in demo_verdicts for eval signal; never modifies the demo task itself.

Request body

json

{
  "task_id": "tsk_demo_refund",
  "verdict": "yes",
  "rationale": "optional reviewer note",
  "anon_session_id": "optional cookie value to group verdicts per visitor"
}

Errors

400 — missing field, or verdict not in allowed_verdicts
404 — task isn't owned by the demo account

GET

/healthz

no auth

Returns {"ok": true} if the worker is up. Useful for uptime monitors.

Conventions

Timestamps are Unix epoch seconds with fractional milliseconds, as JSON numbers.
Errors always return JSON with {"error": "human-readable description"} and an HTTP status code.
Versioning is via the URL path (/v1/...). Breaking changes get a new path; additive changes (new optional fields, new endpoints) ship under /v1 without a bump.