Every API here is available over the APIs.io API and to AI agents over MCP.
{
"openapi": "3.1.0",
"info": {
"title": "Callable API",
"version": "0.1.0",
"description": "Humans as a function for AI agents. Submit real-world tasks (phone calls, UGC video, form filling, account verification, authentic posting) to vetted human operators and receive structured results."
},
"servers": [
{ "url": "https://getcallable.dev" }
],
"components": {
"securitySchemes": {
"ApiKeyAuth": {
"type": "apiKey",
"in": "header",
"name": "x-api-key"
}
},
"schemas": {
"PaymentCredential": {
"description": "Stripe Link Agent Wallet SPT or x402 USDC credential. If not provided, the saved card on file for the developer's API key will be charged.",
"oneOf": [
{ "type": "string", "description": "Shorthand: an SPT string, e.g. \"spt_xxx\"." },
{
"type": "object",
"required": ["type"],
"properties": {
"type": { "type": "string", "enum": ["spt", "x402_usdc"] },
"spt": { "type": "string", "description": "Stripe Shared Payment Token (when type = spt)." },
"token": { "type": "string", "description": "x402 USDC authorization token (when type = x402_usdc)." },
"network": { "type": "string", "description": "Settlement network (e.g. base) for x402_usdc." }
}
}
]
},
"TaskRequest": {
"type": "object",
"required": ["task_type", "instructions", "deadline_minutes"],
"properties": {
"task_type": {
"type": "string",
"enum": ["ugc_video", "phone_call", "account_verification", "form_filling", "authentic_posting", "lead_enrichment"],
"description": "Type of task to assign to a human operator."
},
"instructions": {
"type": "object",
"description": "Structured, task_type-specific instructions. See /docs for per-type schemas."
},
"deadline_minutes": {
"type": "integer",
"minimum": 20,
"maximum": 10080,
"description": "Minutes the operator has to complete the task after claiming."
},
"callback_url": { "type": "string", "format": "uri", "description": "URL to POST the result to when the task is completed." },
"metadata": { "type": "object", "additionalProperties": true },
"priority": { "type": "string", "enum": ["normal", "urgent"] },
"deadline": { "type": "string", "format": "date-time" },
"operator_language": { "type": "string" },
"payment_credential": { "$ref": "#/components/schemas/PaymentCredential" }
}
},
"TaskResponse": {
"type": "object",
"required": ["task_id", "status"],
"properties": {
"task_id": { "type": "string", "format": "uuid", "description": "The task ID. Use this with GET /api/public/tasks/{task_id} to check status." },
"status": { "type": "string", "example": "pending" },
"payment": { "type": "string", "example": "confirmed" },
"payment_method": { "type": "string", "enum": ["agent_wallet", "card"] },
"amount_charged": { "type": "number" },
"currency": { "type": "string" }
}
},
"PaymentRequiredChallenge": {
"type": "object",
"properties": {
"error": { "type": "string" },
"payment": { "type": "string", "example": "required" },
"challenge": {
"type": "object",
"properties": {
"scheme": { "type": "string", "example": "mpp/stripe" },
"version": { "type": "string", "example": "1" },
"accepts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"credential_type": { "type": "string" },
"network": { "type": "string" }
}
}
},
"amount": { "type": "number" },
"currency": { "type": "string" }
}
}
}
}
}
},
"security": [{ "ApiKeyAuth": [] }],
"paths": {
"/api/public/tasks": {
"post": {
"summary": "Submit a task for human execution",
"operationId": "createTask",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/TaskRequest" }
}
}
},
"responses": {
"200": {
"description": "Task accepted and payment confirmed.",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/TaskResponse" }
}
}
},
"402": {
"description": "Payment required. No payment_credential supplied and no saved card on file.",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/PaymentRequiredChallenge" }
}
}
},
"401": { "description": "Missing or invalid x-api-key." },
"422": { "description": "Validation error in instructions or payload." }
}
}
},
"/api/public/tasks/{task_id}": {
"get": {
"summary": "Retrieve a task by id",
"operationId": "getTask",
"parameters": [
{
"name": "task_id",
"in": "path",
"required": true,
"schema": { "type": "string", "format": "uuid" }
}
],
"responses": {
"200": {
"description": "Current task state.",
"content": { "application/json": { "schema": { "type": "object" } } }
},
"404": { "description": "Task not found." }
}
}
},
"/api/public/tasks/{task_id}/review": {
"post": {
"summary": "Approve or dispute a completed task",
"description": "Once a task is in `pending_review` status, the developer (agent) can approve the result to release payment to the operator, or dispute it with a reason and what is needed to accept it. Disputing reopens the operator's assignment so they can resubmit.",
"operationId": "reviewTask",
"parameters": [
{
"name": "task_id",
"in": "path",
"required": true,
"schema": { "type": "string", "format": "uuid" }
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": ["decision"],
"properties": {
"decision": { "type": "string", "enum": ["approve", "dispute"] },
"dispute_reason": { "type": "string", "description": "Required when decision = 'dispute'. What went wrong with the submission." },
"what_is_needed": { "type": "string", "description": "Required when decision = 'dispute'. What the operator needs to do for the submission to be accepted." }
}
}
}
}
},
"responses": {
"200": {
"description": "Review applied.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": { "type": "boolean" },
"status": { "type": "string", "enum": ["completed", "disputed"] }
}
}
}
}
},
"401": { "description": "Missing or invalid x-api-key." },
"403": { "description": "Task does not belong to this developer." },
"404": { "description": "Task not found." },
"409": { "description": "Task is not in pending_review status." },
"422": { "description": "Validation error in body." }
}
}
}
}
}