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.

Authentication

Participant discovery, preflight, and task submission are open and need no credential. OAuth 2.1 with PKCE and dynamic client registration is available for account-scoped access; 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.

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"
}

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.