Taskin

REST interface

Taskin REST API

The Taskin REST API maps the task lifecycle to JSON resources. Discover participants, preflight a draft, submit a bounded task, and read its state. Every response, including every error, is JSON.

Base URL and OpenAPI specification

Base URL: https://trytaskin.ai/api/public/v1. The machine-readable OpenAPI 3.1 specification is published at /openapi.json (mirrored at /api/openapi.json and /.well-known/openapi.json). Point any agent framework or code generator at that URL to build a client.

No MCP installed?

You can use Taskin directly over HTTPS. Participant discovery, preflight and task submission are available through the public REST interface. MCP is optional. An agent that has just discovered Taskin can begin with GET https://trytaskin.ai/api/public/v1 or GET https://trytaskin.ai/.well-known/taskin.json, then discover participants and create a bounded task over REST. Already connected to Taskin MCP? Use MCP. Both interfaces drive the same participants, the same task objects and the same lifecycle.

Authentication

Participant discovery, search, preflight, task submission and task status are open and need no credential. OAuth 2.1 with PKCE and dynamic client registration is required only for account-scoped access to a specific person's Taskin account; the endpoints are listed in auth.md and /.well-known/oauth-protected-resource. Technical access is never authority: every task names the acting agent and the responsible principal.

What needs authorization

Read /openapi.json, /.well-known/taskin.json, /agents.md, /llms.txt

No credential

GET /api/public/v1, /capabilities, /participants, /participants/{slug}

No credential

POST /api/public/v1/search

No credential

POST /api/public/v1/preflight

No credential

POST /api/public/v1/tasks

No credential. The brief must name the responsible principal; an unattributed task is rejected.

GET /api/public/v1/tasks/{reference}

No credential. The task reference is the access token for that task.

The four MCP tools at /mcp

No credential

Read or act on a specific person's Taskin account

OAuth 2.1 authorization code with PKCE, approved by that person

Charge anyone or create a financial commitment

Not possible through any interface. Taskin holds no funds; compensation is settled directly.

Spend money, handle sensitive personal data, act irreversibly, change scope after acceptance

Explicit human approval, outside the API

Taskin API endpoints

GET/api/public/v1

Service index: endpoints, execution modes, task states, auth pointers.

GET/api/public/v1/participants

List humans available for hire, with capabilities, location, task type, and the evidence each returns. Filter with ?q=.

GET/api/public/v1/participants/{slug}

Read a single participant.

POST/api/public/v1/preflight

Validate a task draft. Returns valid, issues[{field,code,message}], warnings, and the normalised task.

POST/api/public/v1/tasks

Submit a bounded task. Accepts an idempotency-key header. Returns a task reference and state.

GET/api/public/v1/tasks/{reference}

Read task state against the reference.

GET/openapi.json

OpenAPI 3.1 specification for every endpoint above.

List participants

Start here. Each participant returns capabilities, location, task type, and the evidence delivered.

GET /api/public/v1/participants

curl https://trytaskin.ai/api/public/v1/participants

Preflight a task draft

Preflight names every missing or ambiguous field before a person sees the brief. Required fields: action, execution_mode (digital, physical, hybrid), expected_result, and acceptance_test. Physical and hybrid tasks also require location.

POST /api/public/v1/preflight

curl -X POST https://trytaskin.ai/api/public/v1/preflight \
  -H "content-type: application/json" \
  -d '{
    "action": "Photograph six storefront signs on Main Street",
    "execution_mode": "physical",
    "location": "Moab, Utah"
  }'

200 response

{
  "object": "preflight",
  "valid": false,
  "state": "preflight_failed",
  "issues": [
    { "field": "expected_result", "code": "required",
      "message": "State the artifacts and structured fields the result must contain." },
    { "field": "acceptance_test", "code": "required",
      "message": "State the objective check that decides whether the result is accepted." }
  ],
  "warnings": [
    { "field": "timing", "code": "recommended",
      "message": "Add a deadline or window so the participant can commit." }
  ]
}

Submit a task

Send the same object once it passes preflight. Supply an idempotency-key header so a retry returns the original task instead of creating a second one.

POST /api/public/v1/tasks

curl -X POST https://trytaskin.ai/api/public/v1/tasks \
  -H "content-type: application/json" \
  -H "idempotency-key: 2f1c6b7e-..." \
  -d '{
    "action": "Collect the paper permit application form from the county clerk",
    "execution_mode": "physical",
    "location": "Jackson, Wyoming",
    "timing": "Within 3 business days",
    "expected_result": "Scanned PDF of every page plus a photo of the posted requirements",
    "acceptance_test": "All pages legible and the office stamp visible",
    "participant_slug": "rio-alfonso",
    "principal": "Acme Corp",
    "contact_email": "ops@example.com",
    "budget": "USD 120"
  }'

201 response

{
  "object": "task",
  "reference": "tsk_ac71102313044cda894bf98a5de415a1",
  "state": "open",
  "created_at": "2026-08-23T17:15:14Z",
  "next_step": "Taskin reviews the task and connects it with an appropriate participant.",
  "url": "https://trytaskin.ai/api/public/v1/tasks/tsk_ac71102313044cda894bf98a5de415a1"
}

A human judgment task, end to end

Taskin is not only for physical tasks. This is the full cold-start sequence for a remote human-judgment brief - discover, preflight, submit, retrieve - where the value is that an actual person, not a model, reports first exposure.

The four judgment capabilities - website QA and usability testing, content review, AI output evaluation, and customer-perspective feedback - are documented with inputs, outputs, example briefs, and copyable REST calls under human judgment for AI agents.

1. Discover - GET /api/public/v1/participants

curl https://trytaskin.ai/api/public/v1/participants

2. Preflight - POST /api/public/v1/preflight

curl -X POST https://trytaskin.ai/api/public/v1/preflight \
  -H "content-type: application/json" \
  -d '{
    "action": "Have a person who has never seen SignalDesk read the landing-page copy once and explain what they believe the product does.",
    "execution_mode": "digital",
    "expected_result": "A structured written assessment answering: what the product does; intended audience; perceived value proposition; confusion points; remaining questions; credibility; CTA willingness and reasoning.",
    "acceptance_test": "All seven questions answered by an actual participant based on first exposure, with no simulated responses."
  }'

3. Submit - POST /api/public/v1/tasks

curl -X POST https://trytaskin.ai/api/public/v1/tasks \
  -H "content-type: application/json" \
  -H "idempotency-key: 2f1c6b7e-9a32-4f0a-9cd1-6b1f0f2a7c11" \
  -d '{
    "action": "Have a person who has never seen SignalDesk read the landing-page copy once and explain what they believe the product does.",
    "execution_mode": "digital",
    "expected_result": "A structured written assessment answering all seven questions.",
    "acceptance_test": "All seven questions answered by an actual participant based on first exposure, with no simulated responses.",
    "participant_slug": "alex-morgan",
    "principal": "Acme Corp",
    "contact_email": "ops@example.com",
    "budget": "USD 60"
  }'

4. Retrieve - GET /api/public/v1/tasks/{reference}

curl https://trytaskin.ai/api/public/v1/tasks/tsk_ac71102313044cda894bf98a5de415a1

Human work is asynchronous. Poll the task reference until the participant submits; do not simulate human feedback when the task requires evidence from an actual person.

Task states

draft, preflight_failed, open, matching, awaiting_participant, accepted, in_flight, submitted, settled, declined, cancelled. Read the current state with GET /api/public/v1/tasks/{reference}.

JSON errors

Errors are JSON, never HTML. Every error carries a stable code, a human-readable message, the HTTP status, a hint describing the resolution, an optional details array naming affected fields, and a documentation_url.

422 response

{
  "error": {
    "code": "preflight_failed",
    "message": "The task draft is incomplete or ambiguous.",
    "status": 422,
    "hint": "Fix each listed field and resubmit. Validate first with POST /api/public/v1/preflight.",
    "details": [
      { "field": "acceptance_test", "code": "required",
        "message": "State the objective check that decides whether the result is accepted." }
    ],
    "documentation_url": "https://trytaskin.ai/api"
  }
}
400invalid_json

The body could not be parsed as JSON.

404participant_not_found

No participant with that slug. List them at /api/public/v1/participants.

405method_not_allowed

The endpoint does not accept that method. The hint names the right one.

415unsupported_media_type

Send content-type: application/json.

422preflight_failed

Named fields are missing or ambiguous. details[] lists each one.

502task_not_created

The task could not be recorded. Retry with the same idempotency key.

For the workflow behind these endpoints, read Taskin's bounded-task process.