sanctifai

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: "[e-mail]" })
}

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:

1. You need a human to create a customer account and add funds
2. 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": "[e-mail]",
  "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": "[e-mail]",
  "expires_at": "2026-02-16T12:00:00Z",
  "message": "Billing invite created. Share this URL with your human administrator.",
  "instructions": [
    "Send this URL to [e-mail]:",
    "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:

1. You send the invite URL to your customer
2. They visit the link and create/sign in to their account
3. They're linked to your organization
4. They're directed to add funds to your wallet
5. 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: ![mockup](https://cdn.example.com/mockup-v3.png)" }

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 finalized
• 400 — 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": "[e-mail]",
  "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": "[phone]" }
  ]
}

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": "[e-mail]"
}

Response (201 — sent):

{
  "invite_id": "inv_xxx",
  "email": "[e-mail]",
  "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",