| name | sanctifai |
| description | Human-in-the-loop skill for AI agents. Use when your agent needs humans to review, approve, or complete a task. Provides REST API and MCP (Model Context Protocol) integration with long-polling and webhooks. No server required — agents self-register and get responses back asynchronously. |
SanctifAI: Human-in-the-Loop for AI Agents
Base URL: https://app.sanctifai.com/v1
You're an AI agent that needs human input. SanctifAI gives you an API to ask humans questions and get structured responses back. Register once, create tasks, and either wait for completion or receive webhooks when humans respond.
Prerequisites
┌─────────────────────────────────────────────────────────────────────────────┐
│ WHAT YOU NEED │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ✓ Ability to make HTTP requests That's it. │
│ │
│ ✗ No server required Use long-poll to wait for responses │
│ ✗ No pre-registration Sign up via API when you need it │
│ ✗ No human setup Fully self-service for agents │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Integration Paths
SanctifAI supports two integration styles. Choose based on your runtime:
┌─────────────────────────────────────────────────────────────────────────────┐
│ INTEGRATION PATHS │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ MCP (Model Context Protocol) REST API │
│ ────────────────────────── ──────── │
│ Best for: Claude, MCP-native agents Best for: any HTTP client │
│ │
│ Endpoint: POST /mcp Endpoint: https://app.sanctifai.com │
│ Auth: ?access_token=sk_xxx Auth: Authorization: Bearer sk_xxx │
│ Protocol: Streamable HTTP + SSE Protocol: Standard HTTP/JSON │
│ │
│ Tools exposed directly to model You call endpoints manually │
│ Real-time task status via SSE Long-poll /v1/tasks/{id}/wait │
│ Idempotency key support built-in Pass idempotency_key in body │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
MCP Server
Connection
Add SanctifAI to your MCP client configuration:
{
"mcpServers": {
"sanctifai": {
"url": "https://app.sanctifai.com/mcp?access_token=sk_live_xxx"
}
}
}
Protocol: Streamable HTTP transport with SSE for real-time notifications. The access_token query parameter carries your API key — the same sk_live_xxx you get from registration.
No auth required for discovery tools — get_taxonomy, get_form_controls, and build_form work without a key.
MCP Tools Reference
┌─────────────────────────────────────────────────────────────────────────────────┐
│ DISCOVERY (no authentication required) │
├──────────────────────┬──────────────────────────────────────────────────────────┤
│ help │ Discover SanctifAI workflows and concepts. Call with no │
│ │ args for an overview, or pass {topic: 'tasks' | │
│ │ 'workers' | 'examples' | ...} for a deep dive. The │
│ │ response includes the full list of available topics so │
│ │ you can branch from any answer. │
├──────────────────────┬──────────────────────────────────────────────────────────┤
│ get_taxonomy │ Get available task types, domains, and use cases. Call │
│ │ this before creating a task to know which task_type, │
│ │ domain, and use_case codes to use. │
├──────────────────────┬──────────────────────────────────────────────────────────┤
│ get_form_controls │ Get available form control types and their schemas. Call│
│ │ this to understand what form elements you can use when │
│ │ creating a task. │
├──────────────────────┬──────────────────────────────────────────────────────────┤
│ build_form │ Validate and normalize a form definition before creating│
│ │ a task. Returns the normalized form or validation │
│ │ errors. │
└──────────────────────┴──────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────────┐
│ AGENT (authentication required) │
├──────────────────────┬──────────────────────────────────────────────────────────┤
│ get_me │ Get your agent profile, organization info, and task │
│ │ statistics. Use this to verify your identity and see how│
│ │ many tasks you have in each status. │
└──────────────────────┴──────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────────┐
│ TASKS (authentication required) │
├──────────────────────┬──────────────────────────────────────────────────────────┤
│ create_task │ Create a new task for humans to complete. Every task │
│ │ requires a form with at least one field so humans can │
│ │ respond. Use get_taxonomy first to discover valid │
│ │ task_type, domain, and use_case codes. Use build_form to│
│ │ validate your form before submitting. For direct tasks, │
│ │ target_id accepts either an email address or a worker │
│ │ UUID. Chartered guild workers cannot be targeted │
│ │ directly — tasks must be routed through their guild. │
│ │ ROUTING RESTRICTIONS: Unclaimed organizations (no human │
│ │ owner) can only create public free tasks — guild and │
│ │ direct routing require a claimed org (POST │
│ │ /v1/org/invite). Paid tasks require a funded wallet and │
│ │ a spending limit > $0 set by a human administrator. │
│ │ Example form: │
│ │ [{type:"title",value:"Review"},{type:"radio",id:"decisio│
│ │ Call get_form_controls for all control types. │
├──────────────────────┬──────────────────────────────────────────────────────────┤
│ list_tasks │ List tasks you have created, optionally filtered by │
│ │ status. Returns paginated results with task details and │
│ │ response data. │
├──────────────────────┬──────────────────────────────────────────────────────────┤
│ get_task │ Get a specific task by ID. Returns full task details │
│ │ including response data if completed. Includes │
│ │ has_open_issue (boolean) and issues array if the worker │
│ │ has reported any problems. │
├──────────────────────┬──────────────────────────────────────────────────────────┤
│ cancel_task │ Cancel a task. Only tasks that have not been claimed can│
│ │ be cancelled. If the task has escrowed funds, they will │
│ │ be refunded. │
├──────────────────────┬──────────────────────────────────────────────────────────┤
│ wait_for_task │ Wait for a task to be completed or cancelled. Blocks │
│ │ until the task reaches a terminal state or the timeout │
│ │ is reached. Returns the task with a timed_out flag. │
├──────────────────────┬──────────────────────────────────────────────────────────┤
│ submit_aps │ Submit an Agentic Promoter Score (APS) for a completed │
│ │ task. APS is a 0–10 satisfaction rating for the worker's│
│ │ performance. Must be submitted within 48 hours of task │
│ │ completion — after that, a default score of 10 is used. │
│ │ Idempotent: submitting again updates the existing score.│
├──────────────────────┬──────────────────────────────────────────────────────────┤
│ get_aps │ Get the APS (Agentic Promoter Score) feedback you │
│ │ submitted for a completed task. Returns the score, │
│ │ notes, and submission timestamp, or a not-yet-submitted │
│ │ indicator. │
├──────────────────────┬──────────────────────────────────────────────────────────┤
│ accept_task │ Accept a completed task and submit your APS (Agentic │
│ │ Promoter Score). Must be called within 48 hours of task │
│ │ completion — after that the task is auto-accepted with │
│ │ no APS. Requires aps_score (0-10). Optional notes for │
│ │ the worker. Once accepted, the task cannot be disputed. │
├──────────────────────┬──────────────────────────────────────────────────────────┤
│ dispute_task │ Dispute a completed task you are not satisfied with. │
│ │ Must be called within 48 hours of task completion — │
│ │ after that the task is auto-accepted. Requires a reason │
│ │ explaining what was unsatisfactory. Once disputed, the │
│ │ task enters dispute resolution and cannot be accepted. │
│ │ Do not dispute unless the worker failed to deliver what │
│ │ was requested. │
└──────────────────────┴──────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────────┐
│ GUILDS (authentication required) │
├──────────────────────┬──────────────────────────────────────────────────────────┤
│ search_guilds │ Search all guilds. Filter by guild_type, domain, │
│ │ languages, country, certifications, minimum APS score, │
│ │ or minimum member count. Returns guild profile and │
│ │ reputation summary per result. Supports cursor-based │
│ │ pagination via limit and cursor parameters. │
├──────────────────────┬──────────────────────────────────────────────────────────┤
│ get_guild │ Get full guild details including profile and reputation.│
│ │ Returns name, summary, description, type, member count, │
│ │ task types, domains, chartered profile fields (if │
│ │ applicable), and aggregated reputation stats. │
└──────────────────────┴──────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────────┐
│ WORKERS (authentication required) │
├──────────────────────┬──────────────────────────────────────────────────────────┤
│ get_worker │ Get full worker profile and reputation in one call. │
│ │ Returns profile data (bio, skills, languages, country, │
│ │ timezone, availability, rate range, experience, │
│ │ education, certifications, job history, guild │
│ │ memberships) plus complete reputation stats (APS, task │
│ │ volume, disputes). No PII (name, email, photo) or payout│
│ │ data is included. │
├──────────────────────┬──────────────────────────────────────────────────────────┤
│ search_workers │ Search workers by profile and reputation criteria. │
│ │ Profile filters: skills (array overlap), languages │
│ │ (array overlap), country, min_availability (hours/week),│
│ │ max_rate_cents (hourly_rate_min ≤ this value), │
│ │ min_experience (years), worker_type (freelancer or │
│ │ chartered). Reputation filters: min_aps, domain, │
│ │ task_type, min_tasks. Scope filter: guild_id (restrict │
│ │ to guild members). Returns profile summary and │
│ │ reputation stats per result. Supports cursor-based │
│ │ pagination via limit and cursor params; response │
│ │ includes next_cursor. │
└──────────────────────┴──────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────────┐
│ INVITES (authentication required) │
├──────────────────────┬──────────────────────────────────────────────────────────┤
│ invite_human │ Send an email invite to a human to join your │
│ │ organization. The human will receive an email with a │
│ │ link to accept the invitation. │
├──────────────────────┬──────────────────────────────────────────────────────────┤
│ invite_agent │ Create a new API key for another AI agent in the same │
│ │ organization. Returns the API key and webhook secret for│
│ │ the new agent. │
└──────────────────────┴──────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────────┐
│ BILLING (authentication required) │
├──────────────────────┬──────────────────────────────────────────────────────────┤
│ get_balance │ Get your organization's wallet balance and spending │
│ │ limits.
Returns funded status, available/locked │
│ │ balances, and per-agent task spending limits. │
│ │ funded=false means the wallet has never been topped up —│
│ │ paid tasks will be blocked. limit_per_task_cents=0 also │
│ │ blocks paid tasks even when funded — a human must raise │
│ │ the limit. Use to diagnose funding_required or │
│ │ spending_limit_exceeded errors. │
├──────────────────────┬──────────────────────────────────────────────────────────┤
│ invite_funder │ Send a billing invite to a human administrator. They │
│ │ will be able to create an account and fund your │
│ │ organization wallet. Funding unlocks paid tasks │
│ │ (price_cents > 0) across all routing types (public, │
│ │ guild, direct). Note: after funding, a human must also │
│ │ raise your per-agent spending limit above $0 before paid│
│ │ tasks are allowed. Use this when you receive a │
│ │ funding_required error. │
├──────────────────────┬──────────────────────────────────────────────────────────┤
│ list_billing_invites│ List billing invites you have sent to human │
│ │ administrators. Shows invite status (pending, redeemed, │
│ │ expired) and the invite URL. Use this to check whether a│
│ │ previously sent invite has been acted on. │
└──────────────────────┴──────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────────┐
│ ISSUES (authentication required) │
├──────────────────────┬──────────────────────────────────────────────────────────┤
│ report_issue │ Report a bug, feature request, or question about the │
│ │ platform. Use this to contact the SanctifAI team — NOT │
│ │ for scoring workers or tasks. │
└──────────────────────┴──────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────────┐
│ ATTACHMENTS (authentication required) │
├──────────────────────┬──────────────────────────────────────────────────────────┤
│ attach_document │ Attach a document to a task, either as uploaded bytes OR│
│ │ by referencing any http(s) URL. For files larger than │
│ │ 100 KB or when latency matters, prefer the │
│ │ request_attachment_upload + finalize_attachment flow — │
│ │ it skips having the LLM emit the base64 payload │
│ │ token-by-token. Use content_base64 to upload bytes │
│ │ inline (accepted file types: PDF, PNG, JPG/JPEG, WEBP, │
│ │ TXT, CSV; max 5 MB per file; max 20 MB total per task; │
│ │ no data URI prefix). Use file_url to reference any │
│ │ http(s) URL — the server stores it verbatim and NEVER │
│ │ fetches it; the worker's browser loads it when viewing │
│ │ the task, using the worker's own session for │
│ │ destinations that require auth (Google Drive, Notion, │
│ │ Figma, Dropbox, etc.). Any URL shape is accepted: direct│
│ │ file URLs, folder links, document pages, landing pages, │
│ │ cloud-storage share links — we do not inspect path │
│ │ structure or MIME type. Destination-side access control │
│ │ (e.g. 'Anyone with the link') is the caller's │
│ │ responsibility. Hard restrictions for file_url: under │
│ │ 2048 chars, no embedded credentials, http(s) only, │
│ │ hostname must resolve to a public IP (private / loopback│
│ │ / link-local rejected). Exactly one of content_base64 or│
│ │ file_url must be provided. The task must belong to your │
│ │ agent. │
├──────────────────────┬──────────────────────────────────────────────────────────┤
│ request_attachment_u│ Reserve a presigned PUT URL for uploading a file to a │
│ │ task without sending bytes through MCP. Call this with │
│ │ {task_id, file_name, mime_type, size_bytes}; the server │
│ │ validates ownership, MIME, and per-task quota (5 MB per │
│ │ file, 20 MB per task total, counting both attached files│
│ │ and other in-flight reservations), then returns │
│ │ {upload_token, upload_url, expires_at, storage_path}. │
│ │ PUT the raw bytes to upload_url (no auth header needed —│
│ │ the signature carries auth), then call │
│ │ finalize_attachment with the upload_token to commit. The│
│ │ reservation expires 10 minutes after issue. Allowed │
│ │ types: pdf, png, jpg/jpeg, webp, txt, csv. The task must│
│ │ belong to your agent. │
├──────────────────────┬──────────────────────────────────────────────────────────┤
│ finalize_attachment │ Commit an upload reserved with │
│ │ request_attachment_upload. After PUTing the bytes to the│
│ │ signed upload_url, call this tool with the upload_token.│
│ │ The server verifies the stored object exists, that its │
│ │ byte count matches the declared size, and that the first│
│ │ bytes match the declared MIME type's magic signature. On│
│ │ success returns the same shape as attach_document. On │
│ │ failure (no bytes uploaded, size mismatch, magic-byte │
│ │ mismatch, expired or unknown token) returns 400/404 and │
│ │ the storage object is cleaned up. │
└──────────────────────┴──────────────────────────────────────────────────────────┘
MCP Tool Walkthroughs
Short examples for each MCP tool, organised by domain. Examples use JavaScript-style call syntax (tool_name({...})) but the same JSON arguments work over any MCP transport.
Agent
get_me — Verify your identity, check your org link, and see your task stats at a glance. Takes no parameters; identity is inferred from your authenticated session.
const me = await get_me()
// {
// id: "agent_xxx",
// name: "Research Assistant",
// organization: { id: "org_xxx", name: "Acme Corp", ... } | null,
// stats: { total_tasks: 12, open_tasks: 1, claimed_tasks: 2, completed_tasks: 9, ... }
// }
If organization is null, your agent is unclaimed — call invite_funder or POST /v1/org/invite to attach a human owner.
Tasks
list_tasks — Page through tasks you have created, optionally filtered by status and creation window. Pair with get_task to drill into a specific row.
const { tasks, total, has_more } = await list_tasks({
status: "completed",
limit: 20,
offset: 0,
})
get_task — Fetch a single task by ID. Returns the same shape as list_tasks entries, plus has_open_issue and an issues array if the worker has flagged a problem.
const task = await get_task({ task_id: "task_xxx" })
if (task.has_open_issue) {
// Worker reported a problem — inspect task.issues before re-routing.
}
cancel_task — Cancel a task you created. Only works on tasks that have not been claimed yet. Escrowed funds are refunded automatically.
await cancel_task({ task_id: "task_xxx" })
// → { cancelled: true, task_id: "task_xxx" }
A 409 response means the task is already claimed, completed, or cancelled — read the error message for the exact status.
get_aps — Read back the APS (Agentic Promoter Score) you submitted for a completed task. Useful if you want to confirm what was recorded before the 48-hour window closes.
const aps = await get_aps({ task_id: "task_xxx" })
if (!aps.submitted) {
// Nothing on file yet — default score of 10 will apply at 48h.
}
Invites
invite_agent — Mint a new API key for another AI agent inside your organization. The new agent inherits your org but starts with $0 spending limits — a human must raise them before paid tasks are allowed.
const child = await invite_agent({
name: "Summarizer",
model: "claude-haiku-4-7",
})
// {
// agent_id: "agent_yyy",
// api_key: "sk_live_yyy", // shown only once — store it
// webhook_secret: "whsec_yyy", // shown only once — store it
// org_id: "org_xxx",
// api_base: "https://app.sanctifai.com"
// }
Billing
get_balance — Inspect your org's wallet and per-agent spending limits. Use this any time you see a funding_required or spending_limit_exceeded error — it tells you exactly which knob needs to move.
const { funded, wallet, spending } = await get_balance()
if (!funded || spending.limit_per_task_cents === 0) {
// Paid tasks are blocked — invite a funder.
await invite_funder({ email: "ops@acme.com" })
}
list_billing_invites — See up to 20 billing invites you have sent, with their status (pending, redeemed, expired). Use this before sending a new invite to avoid duplicates.
const { invites } = await list_billing_invites()
const pending = invites.filter((i) => i.status === "pending")
Feedback
report_issue — Send a bug report, feature request, or general comment to the SanctifAI team. This is for platform issues, not worker scoring (use submit_aps/accept_task/dispute_task for that). Issues with prose feedback are mirrored into the team's Linear inbox.
await report_issue({
api_score: 4,
would_recommend: true,
feedback: "Wait-for-task long-poll is great. Wish I could subscribe to multiple at once.",
task_id: "task_xxx", // optional — links the report to a specific task
})
api_score is a required 1–5 rating of your experience with the API.
MCP Quick Start
┌─────────────────────────────────────────────────────────────────────────────┐
│ MCP WORKFLOW │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Step 1: Discover taxonomy (once) │
│ ────────────────────────────── │
│ get_taxonomy() → valid task_type, domain, use_case codes │
│ │
│ Step 2: Build your form (optional but recommended) │
│ ────────────────────────────────────────────────── │
│ build_form({ controls: [...] }) → normalized controls │
│ │
│ Step 3: Create a task │
│ ───────────────────── │
│ create_task({ │
│ name, summary, target_type, │
│ task_type, domain, use_case, ← required, from get_taxonomy │
│ form: [...] │
│ }) → { id: "task_xxx", status: "open" } │
│ │
│ Step 3b: Attach documents (optional) │
│ ───────────────────────────────────── │
│ attach_document({ │
│ task_id: "task_xxx", │
│ file_name: "report.pdf", │
│ mime_type: "application/pdf", │
│ content_base64: "<base64-encoded file bytes>" │
│ }) → { id: "att_yyy", file_name: "report.pdf", size_bytes: 45000 } │
│ │
│ Step 4: Wait for the human │
│ ────────────────────────── │
│ wait_for_task({ task_id, timeout: 120 }) │
│ → { status: "completed", response: { form_data: {...} } } │
│ │
│ Step 5: Rate the worker (optional, within 48h) │
│ ───────────────────────────────────────────── │
│ submit_aps({ task_id, aps_score: 9 }) │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
REST API
Quick Start
┌─────────────────────────────────────────────────────────────────────────────┐
│ AGENT ONBOARDING (One-time setup) │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Step 1 You now have an API key! │
│ ────────────────────── ────────────────────── │
│ POST /v1/agents/register ────► Bearer sk_live_xxx │
│ (save it - shown only once!) │
│ "Hi, I'm Claude" │
│ │
├─────────────────────────────────────────────────────────────────────────────┤
│ CREATING WORK │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Step 1 Step 2 Step 3 Step 4 │
│ ────────── ────────── ────────── ──────── │
│ GET /v1/ ──► POST /v1/tasks ──► GET /v1/tasks/ ──► Human │
│ taxonomy (with codes {id}/wait response │
│ from above) (blocks until returned │
│ Pick task_type, human completes) to you │
│ domain, use_case │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Account Lifecycle
Every agent starts unclaimed. A human must claim your organization to unlock full routing, and fund your wallet to unlock paid tasks.
┌─────────────────────────────────────────────────────────────────────────────┐
│ PERMISSION MATRIX │
├───────────────────────────┬────────┬────────┬────────┬────────┬────────────┤
│ State │ Public │ Public │ Guild │ Guild │ Direct │
│ │ Free │ Paid │ Free │ Paid │ (any) │
├───────────────────────────┼────────┼────────┼────────┼────────┼────────────┤
│ Unclaimed (≤ 3 tasks) │ ✓ │ ✗ │ ✗ │ ✗ │ ✗ │
│ Unclaimed (> 3 tasks) │ ✗ │ ✗ │ ✗ │ ✗ │ ✗ │
│ Claimed, unfunded │ ✓ │ ✗ │ ✓ │ ✗ │ ✓ (free) │
│ Claimed, funded │ ✓ │ ✓ * │ ✓ │ ✓ * │ ✓ * │
└───────────────────────────┴────────┴────────┴────────┴────────┴────────────┘
* Paid tasks subject to per-agent spending limits. Default limit is $0 —
paid tasks are blocked until a human administrator raises the limit.
Lifecycle Steps
1. Register → Unclaimed org. 3 free public tasks.
Error if exceeded: free_tier_limit (403)
2. POST /v1/org/invite → Human claims your org.
Unlimited free tasks. ALL routing unlocked.
Error if unclaimed + non-public: free_tier_restriction (403)
3. POST /v1/billing/invite → Human funds your wallet.
Paid tasks now possible.
Error if unfunded + paid: funding_required (402)
4. Human raises spending limits → Full paid access.
Error if over limit: spending_limit_exceeded (403)
Error Recovery
| Error code | What it means | How to fix |
|---|
free_tier_limit | Unclaimed org hit 3-task cap | Call POST /v1/org/invite to have a human claim your org |
free_tier_restriction | Unclaimed org tried guild/direct routing | Claim your org first — POST /v1/org/invite |
funding_required | No wallet funds for paid task | Call invite_funder (or POST /v1/billing/invite) to get a human to fund your wallet |
spending_limit_exceeded | Per-agent or per-org spending limit reached | A human administrator must raise your spending limit in the billing settings |
Step 1: Register Your Agent
No API key needed for registration - just tell us who you are. Registration is one step: you get your API key immediately in the response.
Option A: Natural language introduction (preferred)
POST /v1/agents/register
Content-Type: application/json
{
"introduction": "Hi! I'm Research Assistant, a research agent built by Acme Corp. I run on claude-opus-4-6 and specialize in fact verification. You can reach me at https://your-server.com/webhooks/sanctifai for updates."
}
Option B: Structured fields
POST /v1/agents/register
Content-Type: application/json
{
"name": "Research Assistant",
"model": "claude-opus-4-6",
"callback_url": "https://your-server.com/webhooks/sanctifai",
"metadata": {
"version": "1.0.0",
"capabilities": ["research", "analysis"]
}
}
Response (201):
{
"agent_id": "agent_xxx",
"api_key": "sk_live_xxx",
"webhook_secret": "whsec_xxx",
"org_id": "org_xxx",
"parsed": {
"name": "Research Assistant",
"model": "claude-opus-4-6",
"callback_url": "https://your-server.com/webhooks/sanctifai"
},
"message": "Registration complete! Save your API key and webhook secret - they will not be shown again.",
"quick_start": {
"authenticate": "Add 'Authorization: Bearer YOUR_API_KEY' to all requests",
"create_task": "POST /v1/tasks with name, summary, target_type, task_type, domain, use_case, and form",
"wait_for_completion": "GET /v1/tasks/{task_id}/wait to block until human completes",
"webhook_verification": "We sign webhooks using HMAC-SHA256 with your webhook_secret",
"invite_human_owner": "POST /v1/org/invite with { email } to invite a human to own your org"
}
}
Save your API key and webhook secret — they are shown only once.
| Field | Required | Description |
|---|
introduction | Yes* | Natural language self-introduction (preferred; parsed by LLM) |
name | Yes* | Your agent's name (max 100 chars; required if no introduction) |
nickname | No | A friendly short name |
fun_fact | No | Something interesting about yourself |
model | No | Model identifier (e.g., "claude-opus-4-6") |
callback_url | No | Webhook URL for task notifications (skip if using long-poll) |
metadata | No | Any additional info about your agent |
*Either introduction or name is required.
Note: Each registration creates a new agent identity. Store your API key — if you lose it, rotate via POST /v1/agents/rotate-key.
Step 2: Discover Taxonomy
REQUIRED before creating tasks. task_type, domain, and use_case are required fields on POST /v1/tasks. Call this endpoint to discover valid codes.
GET /v1/taxonomy
No authentication required. Returns:
{
"task_types": [
{ "code": "EVA", "label": "Evaluation & Quality Assurance", "description": "..." },
{ "code": "RND", "label": "Research & Information Retrieval", "description": "..." }
],
"domains": [
{ "code": "TEC", "label": "Technology", "description": "..." },
{ "code": "FIN", "label": "Finance", "description": "..." }
],
"use_cases": [
{ "code": "verification", "label": "Verification", "description": "..." },
{ "code": "escalation", "label": "Escalation", "description": "..." },
{ "code": "consultation", "label": "Consultation", "description": "..." }
]
}
Use the code values from this response in your create_task calls.
Note: The response also includes a documentation object with usage guidance and an industries key as a backward-compatibility alias for domains.
Step 3: Create a Task
Now you can send work to humans. All subsequent requests require your API key.
POST /v1/tasks
Authorization: Bearer sk_live_xxx
Content-Type: application/json
{
"name": "Review Pull Request #42",
"summary": "Code review needed for authentication refactor",
"target_type": "public",
"task_type": "EVA",
"domain": "TEC",
"use_case": "verification",
"form": [
{
"type": "markdown",
"value": "## PR Summary\n\nThis PR refactors the authentication system to use JWT tokens instead of sessions.\n\n**Key changes:**\n- New `AuthProvider` component\n- Updated middleware\n- Migration script for existing sessions"
},
{
"type": "radio",
"id": "decision",
"label": "Decision",
"options": ["Approve", "Request Changes", "Needs Discussion"],
"required": true
},
{
"type": "text-input",
"id": "feedback",
"label": "Feedback",
"multiline": true,
"placeholder": "Any comments or concerns..."
}
],
"metadata": {
"pr_number": 42,
"repo": "acme/backend"
}
}
Note: The REST endpoint also accepts an Idempotency-Key request header as an alternative to the idempotency_key body parameter.
Response:
{
"id": "task_xxx",
"name": "Review Pull Request #42",
"summary": "Code review needed for authentication refactor",
"status": "open",
"target_type": "public",
"target_id": null,
"task_type": "EVA",
"domain": "TEC",
"use_case": "verification",
"price_cents": 0,
"form": [...],
"metadata": { "pr_number": 42, "repo": "acme/backend" },
"created_at": "2026-02-01T12:00:00Z",
"claimed_at": null,
"completed_at": null,
"cancelled_at": null,
"issue_reported_at": null,
"response": null
}
Additional fields in GET /v1/tasks/{id} and GET /v1/tasks/{id}/wait responses:
| Field | Description |
|---|
trust_attestation | Trust verification data for the task |
has_open_issue | Boolean — whether an unresolved issue has been reported |
issues | Array of issue reports associated with this task |
Task Types
Chartered Guild Workers Cannot Be Targeted Directly
If a worker belongs to a chartered guild, you must route the task through their guild using target_type: "guild" with the guild's ID. Attempting to use target_type: "direct" with a chartered worker's email or UUID will be rejected by the API with a 400 error. Use search_guilds or get_worker to find the worker's guild, then target the guild instead.
┌─────────────────────────────────────────────────────────────────────────────┐
│ TARGET TYPES │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ PUBLIC │ │ GUILD │ │ DIRECT │ │
│ ├─────────────┤ ├─────────────┤ ├─────────────┤ │
│ │ Anyone can │ │ Only guild │ │ Sent to a │ │
│ │ claim from │ │ members can │ │ specific │ │
│ │ marketplace │ │ claim │ │ email or │ │
│ │ │ │ │ │ worker UUID │ │
│ │ target_id: │ │ target_id: │ │ target_id: │ │
│ │ null │ │ <guild_id> │ │ <email> or │ │
│ │ │ │ │ │ <uuid> │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
│ ⚠ Chartered guild workers CANNOT be targeted directly. The API will │
│ reject direct tasks to chartered workers with a 400 error. Route tasks │
│ through their guild using target_type: "guild" with the guild's ID. │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
| Target Type | target_id | Use Case |
|---|
public | null | Crowdsource to anyone |
guild | Guild ID | Your trusted team |
direct | Email address or worker UUID | Specific person — not valid for chartered guild workers (API will reject with 400) |
Paid Tasks
Tasks can be free (default) or paid. To create a paid task, include price_cents in your request:
POST /v1/tasks
Authorization: Bearer sk_live_xxx
Content-Type: application/json
{
"name": "Urgent Code Review",
"summary": "Need expert review within 2 hours",
"target_type": "public",
"task_type": "EVA",
"domain": "TEC",
"use_case": "verification",
"price_cents": 500,
"form": [...]
}
Important: Paid tasks require your organization to have a funded wallet. If you get a 402 Payment Required error when creating a paid task, you need a human administrator to fund your account.
Billing & Funding
Setting Up Billing
Paid tasks require a human administrator to set up billing and fund your organization's wallet. This is a one-time setup process.
If you get a funding_required error:
- You need a human to create a customer account and add funds
- Use the billing invite endpoint to send them a funding link
Invite Your Customer to Fund Your Account
When you need to create paid tasks but don't have funds, invite your human administrator (customer) to set up billing:
POST /v1/billing/invite
Authorization: Bearer sk_live_xxx
Content-Type: application/json
{
"email": "customer@example.com",
"message": "I need $50 to create paid tasks. Please fund my account."
}
Response:
{
"invite_id": "inv_xxx",
"invite_url": "https://app.sanctifai.com/accept/fund/abc123...",
"email": "customer@example.com",
"expires_at": "2026-02-16T12:00:00Z",
"message": "Billing invite created. Share this URL with your human administrator.",
"instructions": [
"Send this URL to customer@example.com:",
"https://app.sanctifai.com/accept/fund/abc123...",
"",
"When they visit the link, they will:",
"1. Create a SanctifAI account (or sign in)",
"2. Be linked to your organization",
"3. Be directed to the billing page to add funds",
"",
"Once funded, you can create paid tasks."
]
}
What happens:
- You send the invite URL to your customer
- They visit the link and create/sign in to their account
- They're linked to your organization
- They're directed to add funds to your wallet
- Once funded, you can create paid tasks
Note: The invite expires after 7 days. If it expires, create a new invite.
If an invite was already sent to this email within the last 24 hours, returns HTTP 200 with { "invite_id": "inv_xxx", "status": "already_sent", "invite_url": "...", "message": "..." } instead of creating a duplicate.
Check Your Balance
GET /v1/billing/balance
Authorization: Bearer sk_live_xxx
Response:
{
"funded": true,
"wallet": {
"available_cents": 5000,
"locked_cents": 500,
"lifetime_funded_cents": 10000,
"available_formatted": "$50.00",
"locked_formatted": "$5.00"
},
"spending": {
"spent_today_cents": 1000,
"spent_lifetime_cents": 5000,
"limit_daily_cents": null,
"limit_per_task_cents": null,
"remaining_daily_cents": null
}
}
List Billing Invites
GET /v1/billing/invite
Authorization: Bearer sk_live_xxx
Returns up to 20 billing invites you have sent, with status (pending, redeemed, expired) and timestamps.
Step 4: Wait for Completion
Block until a human completes your task. This is the simplest pattern - no server required.
GET /v1/tasks/{task_id}/wait?timeout=60
Authorization: Bearer sk_live_xxx
Response (completed):
{
"id": "task_xxx",
"status": "completed",
"response": {
"form_data": {
"decision": "Approve",
"feedback": "Clean implementation! Just one suggestion: add error boundary around AuthProvider."
},
"completed_by": "user_xxx",
"completed_at": "2026-02-01T12:15:00Z"
},
"timed_out": false
}
Response (timeout):
{
"id": "task_xxx",
"status": "claimed",
"response": null,
"timed_out": true
}
| Parameter | Default | Max | Description |
|---|
timeout | 30s | 120s | How long to wait |
Form Controls Reference
Build forms by composing these controls in your form array:
Display Controls (Content You Provide)
┌─────────────────────────────────────────────────────────────────────────────┐
│ DISPLAY CONTROLS - Content you provide for the human to read │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ title │ { "type": "title", "value": "Section Header" } │
│ │ │
│ markdown │ { "type": "markdown", "value": "## Rich\n\n**formatted**" } │
│ │ │
│ divider │ { "type": "divider" } │
│ │ │
│ link │ { "type": "link", "url": "https://...", "text": "View PR" } │
│ │ │
│ image │ { "type": "image", "url": "https://...", "alt": "Screenshot" } │
│ │ Use when the image is already hosted at a public URL. │
│ │ If you have file bytes instead, use attach_document (MCP) or │
│ │ POST /v1/tasks/{id}/attachments (REST) — see the │
│ │ "Attaching Images and Files" section below. │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Input Controls (Human Fills Out)
┌─────────────────────────────────────────────────────────────────────────────┐
│ INPUT CONTROLS - Fields the human fills out │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ text- │ { │
│ input │ "type": "text-input", │
│ │ "id": "notes", │
│ │ "label": "Notes", │
│ │ "multiline": true, │
│ │ "placeholder": "Enter your notes...", │
│ │ "required": false │
│ │ } │
│ │ │
│ select │ { │
│ │ "type": "select", │
│ │ "id": "priority", │
│ │ "label": "Priority", │
│ │ "options": ["Low", "Medium", "High", "Critical"], │
│ │ "required": true │
│ │ } │
│ │ │
│ radio │ { │
│ │ "type": "radio", │
│ │ "id": "decision", │
│ │ "label": "Decision", │
│ │ "options": ["Approve", "Reject", "Defer"], │
│ │ "required": true │
│ │ } │
│ │ │
│ checkbox │ { │
│ │ "type": "checkbox", │
│ │ "id": "checks", │
│ │ "label": "Verified", │
│ │ "options": ["Code quality", "Tests pass", "Docs updated"] │
│ │ } │
│ │ │
│ date │ { │
│ │ "type": "date", │
│ │ "id": "due_date", │
│ │ "label": "Due Date" │
│ │ } │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Form Normalization
The API normalizes form controls when you submit them. You can pass shorthand input and the API stores the canonical form. Understanding normalization helps you predict what gets saved and returned.
Options normalization — string options in radio, checkbox, and select controls are expanded to {label, value} objects:
// Input (shorthand strings)
{ "type": "radio", "id": "decision", "options": ["Approve", "Reject"] }
// Normalized (stored and returned)
{ "type": "radio", "id": "decision", "options": [
{ "label": "Approve", "value": "Approve" },
{ "label": "Reject", "value": "Reject" }
]}
Content field normalization — display controls accept content as an alias for value (legacy compatibility), but the canonical field is value:
// Input (legacy alias)
{ "type": "markdown", "content": "## Hello" }
// Normalized (canonical)
{ "type": "markdown", "value": "## Hello" }
Type aliases — several type names are normalized to their canonical equivalents:
| Input type | Canonical type | Notes |
|---|
text (with id) | text-input | Must have id to be treated as input |
text (with content/value, no id) | markdown | Without id treated as display |
textarea, text-area | text-input | Sets multiline: true |
dropdown | select | Legacy alias |
markdown-display, text-display | markdown | Legacy aliases |
Use POST /v1/form/build to validate before creating a task. It returns the normalized form so you see exactly what will be stored.
Attaching Images and Files
There are three ways to show an image or attach a file to a task. Choose based on what you have and how big the file is:
┌─────────────────────────────────────────────────────────────────────────────┐
│ THREE ATTACHMENT PATHS │
├──────────────────────────┬──────────────────────────┬───────────────────────┤
│ PATH 1: External URL │ PATH 2: Inline Bytes │ PATH 3: Presigned │
│ (image already hosted) │ (small files, ≤100 KB) │ (anything bigger) │
├──────────────────────────┼──────────────────────────┼───────────────────────┤
│ Embed in the form │ attach_document with │ request_attachment_ │
│ schema as an `image` │ content_base64 (MCP) or │ upload → HTTP PUT → │
│ display control. │ POST /v1/tasks/{id}/ │ finalize_attachment. │
│ No upload needed. │ attachments (REST) with │ Bytes never travel │
│ │ base64 payload. │ through the LLM. │
│ │ │ │
│ Works for: screenshots, │ Works for: tiny PDFs, │ Works for: anything │
│ product images, diagrams│ small text/CSV files, │ larger than a few │
│ — anything with a │ one-shot uploads where │ KB or where latency │
│ stable public URL. │ latency doesn't matter. │ matters. │
└──────────────────────────┴──────────────────────────┴───────────────────────┘
Path 1: External URL — embed in form schema
Use an image form control when the file is already at a public URL. Add it to your form array like any other display control:
MCP:
create_task({
name: "Review product mockup",
// ...
form: [
{ type: "title", value: "New Homepage Design" },
{ type: "image", url: "https://cdn.example.com/mockup-v3.png", alt: "Homepage mockup v3" },
{ type: "radio", id: "decision", label: "Decision", options: ["Approve", "Reject"], required: true }
]
})
REST:
{
"form": [
{ "type": "title", "value": "New Homepage Design" },
{ "type": "image", "url": "https://cdn.example.com/mockup-v3.png", "alt": "Homepage mockup v3" },
{ "type": "radio", "id": "decision", "label": "Decision", "options": ["Approve", "Reject"], "required": true }
]
}
You can also reference an external URL inline in a markdown control:
{ "type": "markdown", "value": "Please review: " }
Path 2: File Bytes — upload after task creation
Use attach_document (MCP) or POST /v1/tasks/{id}/attachments (REST) when you have the actual file content. Create the task first, then upload.
MCP:
// Step 1: create the task
const task = await create_task({ name: "Review report", form: [...] })
// Step 2: upload the file
await attach_document({
task_id: task.id,
file_name: "q1-report.pdf",
mime_type: "application/pdf",
content_base64: "<base64-encoded file bytes>"
})
REST:
# Step 1: create the task
POST /v1/tasks
Authorization: Bearer sk_live_xxx
Content-Type: application/json
{ "name": "Review report", "form": [...], ... }
# Step 2: upload the file
POST /v1/tasks/{task_id}/attachments
Authorization: Bearer sk_live_xxx
Content-Type: application/json
{
"file_name": "q1-report.pdf",
"mime_type": "application/pdf",
"content_base64": "<base64-encoded file bytes>"
}
Response:
{
"id": "att_yyy",
"task_id": "task_xxx",
"file_name": "q1-report.pdf",
"mime_type": "application/pdf",
"size_bytes": 45000,
"created_at": "2026-02-01T12:00:00Z"
}
Uploaded attachments appear as downloadable files on the task, visible to the worker alongside the form.
Limits: 5 MB per file, 20 MB per task total. Allowed types: pdf, png, jpg/jpeg, webp, txt, csv.
Path 3: Presigned upload — direct-to-storage for non-trivial files
Use request_attachment_upload + finalize_attachment when the file is more than a few KB or when latency matters. The bytes go directly from your HTTP client to Supabase Storage — your LLM never has to emit the base64 payload token-by-token, which is the dominant cost on the inline-bytes path.
The flow is three calls: reserve, PUT, commit.
MCP:
// Step 1: create the task
const task = await create_task({ name: "Review report", form: [...] })
// Step 2: reserve a presigned PUT URL (the server validates ownership, MIME,
// and the per-task 20 MB quota before issuing the URL — counts other
// in-flight reservations too, so concurrent uploads can't both pass).
const reservation = await request_attachment_upload({
task_id: task.id,
file_name: "q1-report.pdf",
mime_type: "application/pdf",
size_bytes: 1048576 // exact byte count — must match what you upload
})
// reservation = {
// upload_token: "uuid",
// upload_url: "https://...supabase.co/storage/v1/object/upload/sign/...",
// expires_at: "2026-05-18T12:10:00Z", // 10 min window
// storage_path: "task_xxx/uuid_q1-report.pdf"
// }
// Step 3: PUT the bytes directly to the signed URL. No auth header needed —
// the URL signature carries authorization. Use any HTTP client; the server
// returns 200 on success.
await fetch(reservation.upload_url, {
method: "PUT",
headers: { "Content-Type": "application/pdf" },
body: fileBytes // a Buffer, Blob, or ReadableStream
})
// Step 4: commit. The server HEADs the storage object, verifies size +
// magic-byte signature against the declared MIME, then inserts the
// task_attachments row and returns it.
const attachment = await finalize_attachment({ upload_token: reservation.upload_token })
// attachment matches the attach_document response shape
REST:
# Step 2: reserve
POST /v1/tasks/{task_id}/attachments/request_upload
Authorization: Bearer sk_live_xxx
Content-Type: application/json
{
"file_name": "q1-report.pdf",
"mime_type": "application/pdf",
"size_bytes": 1048576
}
# → 200 OK
# { "upload_token": "...", "upload_url": "...", "expires_at": "...", "storage_path": "..." }
# Step 3: PUT the raw bytes to upload_url (no auth header needed)
PUT {upload_url}
Content-Type: application/pdf
<raw file bytes>
# Step 4: commit
POST /v1/tasks/attachments/finalize
Authorization: Bearer sk_live_xxx
Content-Type: application/json
{ "upload_token": "..." }
# → 201 Created — same response shape as attach_document
Reservations expire after 10 minutes. If you don't finalize in time, the slot is reaped, the storage object (if any) is left orphaned in the bucket (no public read, low cost), and the quota slot is freed up. Calling finalize_attachment twice with the same token returns 404 on the second call — the token is single-use.
Error cases:
404 — token unknown, expired, or already finalized400 — no bytes uploaded, byte count doesn't match declared size_bytes, or magic bytes don't match the declared MIME type. The reservation is discarded; start over with a new request_attachment_upload.413 — declared size_bytes exceeds the 5 MB per-file or 20 MB per-task cap (returned at request_attachment_upload time, before any bytes are uploaded)
Common Patterns
Quick Approval (Yes/No)
{
"name": "Approve deployment?",
"summary": "Production deploy for v2.1.0",
"target_type": "public",
"task_type": "EVA",
"domain": "TEC",
"use_case": "escalation",
"form": [
{ "type": "markdown", "value": "Ready to deploy **v2.1.0** to production." },
{ "type": "radio", "id": "decision", "label": "Decision", "options": ["Approve", "Reject"], "required": true }
]
}
Data Entry
{
"name": "Enter contact info",
"summary": "Need shipping details for order #1234",
"target_type": "direct",
"target_id": "customer@example.com",
"task_type": "ENT",
"domain": "GEN",
"use_case": "consultation",
"form": [
{ "type": "text-input", "id": "name", "label": "Full Name", "required": true },
{ "type": "text-input", "id": "address", "label": "Address", "multiline": true, "required": true },
{ "type": "text-input", "id": "phone", "label": "Phone", "placeholder": "+1 (555) 123-4567" }
]
}
Fact Verification
{
"name": "Verify claim",
"summary": "Check if this statistic is accurate",
"target_type": "public",
"task_type": "EVA",
"domain": "TEC",
"use_case": "verification",
"form": [
{ "type": "markdown", "value": "**Claim:** 87% of developers prefer TypeScript.\n**Source:** Stack Overflow 2025" },
{ "type": "radio", "id": "accuracy", "label": "Is this accurate?", "options": ["Accurate", "Inaccurate", "Cannot Verify"], "required": true },
{ "type": "text-input", "id": "correction", "label": "Correction (if inaccurate)", "multiline": true }
]
}
Guilds: Route to Trusted Teams
Guilds are persistent teams of trusted humans. Agents can search the guild directory and route tasks to them — guild creation and member management is handled on the platform.
Browse the Guild Directory
GET /v1/guilds/directory
Authorization: Bearer sk_live_xxx
Optional query parameters:
| Parameter | Type | Description |
|---|
q | string | Search query (name, summary, description) |
guild_type | string | Filter: community or chartered |
domain | string | Industry code — guild must include this domain |
languages | string[] | Guild's chartered profile must include these languages |
country | string | Guild's chartered profile location must include this country |
certifications | string[] | Guild's chartered profile must include these certifications |
min_aps | float (0–10) | Minimum guild APS average |
min_members | integer | Minimum active member count |
limit | integer | Max results (default 50, max 100) |
cursor | string | Pagination cursor for next page |
Response includes profile summary (chartered guilds only) and reputation summary per result.
Get Guild Details
GET /v1/guilds/{guild_id}
Authorization: Bearer sk_live_xxx
Returns full guild profile including name, summary, description, type, member count, task types, domains, chartered profile fields (if applicable), and inline aggregated reputation stats.
Route Tasks to a Guild
POST /v1/tasks
Authorization: Bearer sk_live_xxx
Content-Type: application/json
{
"name": "Urgent Security Review",
"summary": "Review authentication bypass vulnerability fix",
"target_type": "guild",
"target_id": "guild_xxx",
"task_type": "EVA",
"domain": "TEC",
"use_case": "verification",
"form": [...]
}
Only guild members will see this task — it won't appear in the public marketplace.
Targeting a Chartered Guild When You Know the Worker
If you've found a specific worker you want to assign a task to, but they belong to a chartered guild, you cannot target them directly. Instead, look up their guild and route through it.
Step 1: Find the worker's guild
If you have the worker's UUID, use get_worker to retrieve their guild memberships directly:
GET /v1/workers/{worker_id}
Authorization: Bearer sk_live_xxx
The response includes a guilds array with each guild the worker belongs to:
{
"worker_id": "worker_uuid",
"worker_type": "chartered",
"guilds": [
{ "guild_id": "guild_xxx", "name": "Alice's Guild", "guild_type": "chartered", "role": "member" }
]
}
Step 2: Route the task to the guild, not the worker
POST /v1/tasks
Authorization: Bearer sk_live_xxx
Content-Type: application/json
{
"name": "Contract Review: NDA for Acme Corp",
"summary": "Please review and flag any concerns in this NDA before signing.",
"target_type": "guild",
"target_id": "guild_xxx",
"task_type": "EVA",
"domain": "LEG",
"use_case": "verification",
"form": [...]
}
Why not target_type: "direct"? Chartered guild workers operate through their guild — direct assignments bypass the guild's workflow and accountability structure. The API enforces this by rejecting direct tasks to chartered workers with a 400 error.
Inviting Humans and Agents
Invite a Human to Your Organization (email)
Sends an email invitation. When the human accepts, they join your organization.
POST /v1/org/invite
Authorization: Bearer sk_live_xxx
Content-Type: application/json
{
"email": "colleague@example.com"
}
Response (201 — sent):
{
"invite_id": "inv_xxx",
"email": "colleague@example.com",
"status": "sent",
"message": "Invitation sent."
}
Create an API Key for Another Agent
Provision a sub-agent in your same organization:
POST /v1/org/invite-agent
Authorization: Bearer sk_live_xxx
Content-Type: application/json
{
"name": "Sub-Agent Alpha",
"model": "claude-haiku-4-5-20251001",
"callback_url": "https://your-server.com/webhooks/sub-agent"
}
Response:
{
"agent_id": "agent_xxx",
"api_key": "sk_live_xxx",
"webhook_secret": "whsec_xxx",
"org_id": "org_xxx",
"api_base": "https://app.sanctifai.com",
"quick_start": {
"authenticate": "Add 'Authorization: Bearer YOUR_API_KEY' to all requests",
"create_task": "POST /v1/tasks with name, summary, target_type, task_type, domain, use_case, and form",
"docs": "GET /v1 for the quick-start guide"
}
}
Save the API key — it is shown only once.
Note: This endpoint is only available to customer organizations. Guild organizations receive a 403 guild_org_not_supported error.
Full API Reference
Authentication
All endpoints (except discovery and /v1/agents/register) require:
Authorization: Bearer sk_live_xxx
Endpoints
┌─────────────────────────────────────────────────────────────────────────────┐
│ DISCOVERY (no authentication required) │
├─────────────────────────────────────────────────────────────────────────────┤
│ GET /v1 Welcome / quick-start guide. Includes a │
│ `discovery` object with links to │
│ /.well-known/agent.json, /v1/tools, │
│ /v1/openapi.json, and /v1/openapi.yaml │
│ GET /v1/taxonomy Task types, domains, use cases │
│ REQUIRED before creating tasks │
│ GET /v1/tools Native LLM tool definitions │
│ GET /v1/openapi.json OpenAPI spec (JSON) │
│ GET /v1/openapi.yaml OpenAPI spec (YAML) │
│ GET /v1/form/controls Available form control types and schemas. │
│ Response includes documentation, types │
│ (display + input), controls, examples, │
│ and target_types objects │
│ POST /v1/form/build Validate & normalize form before task │
├─────────────────────────────────────────────────────────────────────────────┤
│ AGENTS │
├─────────────────────────────────────────────────────────────────────────────┤
│ POST /v1/agents/register Register new agent, returns API key (no auth)│
│ GET /v1/agents/me Get your profile & stats │
│ PATCH /v1/agents/me Update your profile │
│ POST /v1/agents/rotate-key Rotate API key and/or webhook secret. │
│ Body: rotate_api_key (bool, default true), │
│ rotate_webhook_secret (bool, default false).│
│ Response: rotated object, optionally │
│ api_key, old_api_key_prefix, webhook_secret │
├─────────────────────────────────────────────────────────────────────────────┤
│ TASKS │
├─────────────────────────────────────────────────────────────────────────────┤
│ POST /v1/tasks Create a task (requires task_type, domain, │
│ use_case — see GET /v1/taxonomy) │
│ GET /v1/tasks List your tasks │
│ GET /v1/tasks/{id} Get task details │
│ POST /v1/tasks/{id}/cancel Cancel task (open status only; 409 if │
│ claimed). Direct tasks: cancellable before │
│ worker claims. Workers can decline via UI. │
│ GET /v1/tasks/{id}/wait Block until completed (long-poll) │
│ POST /v1/tasks/{id}/aps Submit APS feedback for completed task │
│ GET /v1/tasks/{id}/aps Get APS feedback for a task │
│ POST /v1/tasks/{id}/accept Accept completed task and submit APS score │
│ POST /v1/tasks/{id}/dispute Dispute a completed task (enters resolution) │
│ POST /v1/tasks/{id}/attachments Upload file (base64) — use when you │
│ have file bytes; for hosted images use the │
│ `image` form control with a URL instead │
├─────────────────────────────────────────────────────────────────────────────┤
│ GUILDS (read-only) │
├─────────────────────────────────────────────────────────────────────────────┤
│ GET /v1/guilds/directory Search/browse guilds (profile + reputation) │
│ GET /v1/guilds/{id} Get full guild details (profile + reputation)│
├─────────────────────────────────────────────────────────────────────────────┤
│ WORKERS (read-only) │
├─────────────────────────────────────────────────────────────────────────────┤
│ GET /v1/workers/:worker_id Full worker profile + reputation │
│ GET /v1/workers Search/filter workers by profile + APS │
├─────────────────────────────────────────────────────────────────────────────┤
│ INVITES │
├─────────────────────────────────────────────────────────────────────────────┤
│ POST /v1/org/invite Invite a human to your org (sends email) │
│ POST /v1/org/invite-agent Create API key for another AI agent │
├─────────────────────────────────────────────────────────────────────────────┤
│ BILLING │
├─────────────────────────────────────────────────────────────────────────────┤
│ GET /v1/billing/balance Get wallet balance & spending info │
│ POST /v1/billing/invite Invite customer to fund your account │
│ GET /v1/billing/invite List billing invites you have sent │
├─────────────────────────────────────────────────────────────────────────────┤
│ ISSUES │
├─────────────────────────────────────────────────────────────────────────────┤
│ POST /v1/issues Report a bug, feature request, or question │
│ GET /v1/issues List your issue reports │
└─────────────────────────────────────────────────────────────────────────────┘
Query Parameters (GET /v1/tasks)
| Parameter | Type | Description |
|---|
status | string | Filter: open, claimed, completed, cancelled, issue_reported |
limit | int | Results per page (max 100, default 20) |
offset | int | Pagination offset |
created_after | ISO8601 | Filter by creation date |
created_before | ISO8601 | Filter by creation date |
APS (Agentic Promoter Score) Endpoint
Rate worker performance after a task is completed. APS is a 0-10 scale (NPS-style) score.
Important: You have 48 hours from task completion to submit APS feedback. If no feedback is submitted within 48 hours, the task automatically receives a perfect APS score of 10.
POST /v1/tasks/{task_id}/aps
Authorization: Bearer sk_live_xxx
Content-Type: application/json
{
"aps_score": 8,
"notes": "Worker delivered high-quality output, minor formatting issues.",
"metadata": { "evaluation_model": "gpt-4" }
}
| Field | Type | Required | Description |
|---|
aps_score | int | Yes | Worker performance score (0-10 scale) |
notes | string | No | Feedback notes (max 5000 chars) |
metadata | object | No | Any additional context |
Response (201):
{
"id": "review_xxx",
"task_id": "task_xxx",
"aps_score": 8,
"notes": "Worker delivered high-quality output, minor formatting issues.",
"hours_since_completion": 2.5,
"message": "APS feedback submitted successfully"
}
Accept Task Response
When you accept a completed task via POST /v1/tasks/{id}/accept or accept_task (MCP):
{
"accepted": true,
"task_id": "task_xxx",
"aps_score": 8,
"notes": "Great work",
"accepted_at": "2026-02-01T12:15:00Z",
"message": "Task accepted with APS score 8."
}
Dispute Task Response
When you dispute a completed task via POST /v1/tasks/{id}/dispute or dispute_task (MCP):
{
"disputed": true,
"task_id": "task_xxx",
"dispute_id": "disp_xxx",
"reason": "Output did not match requirements",
"disputed_at": "2026-02-01T12:15:00Z",
"message": "Dispute filed. The SanctifAI team will review."
}
Get existing feedback:
GET /v1/tasks/{task_id}/aps
Authorization: Bearer sk_live_xxx
Returns the submitted APS review, or { "submitted": false } if no feedback has been provided yet.
Report an Issue
Report a bug, feature request, or question about the platform. Use this to contact the SanctifAI team — NOT for scoring workers or tasks.
POST /v1/issues
Authorization: Bearer sk_live_xxx
Content-Type: application/json
{
"api_score": 4,
"would_recommend": true,
"feedback": "Great API! The long-poll wait endpoint is really useful.",
"task_id": "task_xxx",
"metadata": {
"integration_type": "autonomous",
"sdk_version": "1.0.0"
}
}
| Field | Type | Required | Description |
|---|
api_score | int | Yes | Rate your experience (1-5 scale) |
would_recommend | boolean | No | Would you recommend this API? |
feedback | string | No | Additional feedback or suggestions (max 5000 chars) |
task_id | string | No | Link feedback to a specific task |
metadata | object | No | Any additional context |
Response:
{
"id": "fb_xxx",
"api_score": 4,
"would_recommend": true,
"feedback": "Great API! The long-poll wait endpoint is really useful.",
"task_id": "task_xxx",
"created_at": "2026-02-01T12:00:00Z",
"message": "Issue reported. The SanctifAI team will review it."
}
List Issue Reports
GET /v1/issues
Authorization: Bearer sk_live_xxx
| Parameter | Type | Default | Description |
|---|
limit | int | 20 | Results per page (max 100) |
offset | int | 0 | Pagination offset |
Response:
{
"issues": [...],
"total": 5,
"limit": 20,
"offset": 0,
"has_more": false
}
Error Handling
All errors return a flat JSON object with error (string code) and message (string description) at the top level:
{
"error": "bad_request",
"message": "name is required and must be a string"
}
| Code | HTTP Status | Meaning |
|---|
bad_request | 400 | Invalid input |
invalid_params | 400 | Schema validation failed (unknown or missing fields) |
validation_error | 400 | Form validation failed |
unauthorized | 401 | Missing or invalid API key |
forbidden | 403 | Valid key, but no permission |
not_found | 404 | Resource doesn't exist |
conflict | 409 | Action not valid for current task state (e.g., already claimed, accepted, or disputed) |
funding_required | 402 | Insufficient funds for paid task. Use POST /v1/billing/invite to invite customer to fund account |
free_tier_limit | 403 | Free tier task limit reached |
free_tier_restriction | 403 | Feature not available on free tier |
spending_limit_exceeded | 403 | Task price exceeds spending limits |
payload_too_large | 413 | File exceeds size limit (5 MB per file, 20 MB per task) |
escrow_failed | 500 | Task created but escrow funding failed; task cancelled |
internal_error | 500 | Something went wrong |
Webhooks (Optional)
If you provided a callback_url during registration, we'll POST task completions to you:
POST https://your-server.com/webhooks/sanctifai
X-Sanctifai-Signature: sha256=xxx
Content-Type: application/json
{
"event": "task.completed",
"task": {
"id": "task_xxx",
"name": "Review Pull Request #42",
"status": "completed",
"response": {
"form_data": {...},
"completed_by": "user_xxx",
"completed_at": "2026-02-01T12:15:00Z"
}
}
}
Verify Webhook Signature
import hmac
import hashlib
def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
expected = "sha256=" + hmac.new(
secret.encode(),
payload,
hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, signature)
Complete Example: Research Assistant
import requests
BASE_URL = "https://app.sanctifai.com/v1"
API_KEY = "sk_live_xxx" # From registration
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
# Step 1: Discover valid codes (do this once)
taxonomy = requests.get(f"{BASE_URL}/taxonomy").json()
# Pick: task_type="EVA", domain="GEN", use_case="verification"
# Step 2: Create a research verification task
task = requests.post(f"{BASE_URL}/tasks", headers=headers, json={
"name": "Verify Research Finding",
"summary": "Confirm this statistic before publishing",
"target_type": "public",
"task_type": "EVA",
"domain": "GEN",
"use_case": "verification",
"form": [
{
"type": "markdown",
"value": """## Research Claim
**Statement:** "87% of developers prefer TypeScript over JavaScript for large projects."
**Source:** Stack Overflow Developer Survey 2025
Please verify this claim is accurately represented."""
},
{
"type": "radio",
"id": "verification",
"label": "Is this claim accurate?",
"options": ["Accurate", "Inaccurate", "Partially Accurate", "Cannot Verify"],
"required": True
},
{
"type": "text-input",
"id": "correction",
