2O — Human Verification API

You can call the 2O API to get human expert verification on factual claims, empathy reviews of draft responses, and real-world witness observations. Human domain experts review submissions and return structured results.

Setup

The user needs a 2O API key. Register at https://www.2oapi.xyz/register to get one ($5 free credits included). The key is stored in the TWO_O_API_KEY environment variable.

Verify a Factual Claim

Use this when you need a human expert to verify whether a claim is true, false, or partially true.

curl -s -X POST "https://www.2oapi.xyz/api/v1/verify" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TWO_O_API_KEY" \
  -d '{
    "claim": "The claim to verify",
    "domain": "general",
    "budget_cents": 50
  }'

Required fields:

• claim (string): The factual statement to verify
• domain (string): One of financial, general, geographic, identity, legal, medical, scientific, technical
• budget_cents (integer): Payment in cents. Minimum 50 ($0.50)

Optional fields:

• context (string): Additional context for the verifier
• urgency (string): low, medium (default), high, critical
• callback_url (string): Webhook URL for completion notification
• tier (string): standard (default, 1 verifier), consensus (3 verifiers, min $3.00), expert_panel (5 verifiers, min $10.00)

Response: Returns a JSON object with id (request ID), status ("pending"), and expires_at.

Request an Empathy Review

Use this when you have a draft response to a sensitive situation and want a human to review it for tone and empathy.

curl -s -X POST "https://www.2oapi.xyz/api/v1/empathize" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TWO_O_API_KEY" \
  -d '{
    "draft_response": "The draft text to review",
    "context": "Description of the situation",
    "budget_cents": 50
  }'

Required fields:

• draft_response (string): The draft AI response to review
• context (string): The situation the user is in
• budget_cents (integer): Minimum 50

Returns: empathy_score, tone_assessment, sensitivity_flags, suggested_revision

Request a Witness Observation

Use this when you need a human to physically observe or confirm something in the real world.

curl -s -X POST "https://www.2oapi.xyz/api/v1/witness" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TWO_O_API_KEY" \
  -d '{
    "observation_query": "What to observe or check",
    "budget_cents": 100
  }'

Required fields:

• observation_query (string): What the human should observe
• budget_cents (integer): Minimum 100 ($1.00)

Optional fields:

• location_address (string): Address for the observation
• location_lat, location_lng (number): GPS coordinates
• photo_required (boolean): Whether photos are needed

Returns: observation, photo_urls, observed_at

Check Request Status

After submitting any request, poll for status using the request ID:

curl -s "https://www.2oapi.xyz/api/v1/verify/REQUEST_ID" \
  -H "Authorization: Bearer $TWO_O_API_KEY"

Status values: pending (waiting for verifier), assigned (verifier working on it), completed (result ready), expired (timed out)

Poll every 30-60 seconds. All three task types (verify, empathize, witness) use this same endpoint.

Get the Result

Once status is completed, fetch the full result:

curl -s "https://www.2oapi.xyz/api/v1/verify/REQUEST_ID/result" \
  -H "Authorization: Bearer $TWO_O_API_KEY"

Verify results include: verdict (verified/refuted/partially_verified), confidence (0-1), explanation, evidence_urls

Check Balance

curl -s "https://www.2oapi.xyz/api/v1/agent/balance" \
  -H "Authorization: Bearer $TWO_O_API_KEY"

Returns balance_cents, total_spent_cents, total_escrowed_cents.

Guidelines

• Verify important claims before presenting them as fact to users
• Use empathy review before responding to sensitive situations (grief, conflict, crisis)
• Use witness for questions about real-world conditions that can't be answered from training data
• Start with budget_cents: 50 for verify/empathize, 100 for witness
• Higher budgets and urgency attract faster responses
• The typical flow is: submit -> poll status -> get result
• Do not poll more frequently than every 30 seconds