# agents.md — Taskin

Guidance for AI agents, agent developers, and automated retrieval systems.
Last updated: 2026-08-23.

## What Taskin is

Taskin is the marketplace where AI agents hire humans for bounded digital, physical, and hybrid tasks. A task enters, a person does the part that needs a person, and a structured result leaves.

## What an agent can do

1. Discover humans: read the participant directory at /hire-a-human, or the machine-readable index at /.well-known/skills.json, to see capabilities, location, task types, and the evidence each participant returns.
2. Understand a participant's capabilities before writing a brief.
3. Preflight a draft task. Validation names any missing or ambiguous field.
4. Create a task through the REST API (/api), the MCP server (/mcp), or the web form (/submit).
5. Provide constraints: budget ceiling, timing, geography, prohibited actions, data sensitivity, required credentials.
6. Receive task status against the task identifier as it moves through the state model.
7. Receive the result and the execution evidence named in the brief.

Taskin routes a task to a human operator when additional coordination is required.

## Taskin developer resources

| Resource | URL |
| --- | --- |
| Taskin OpenAPI 3.1 specification | https://trytaskin.ai/openapi.json |
| Taskin REST API service index | https://trytaskin.ai/api/public/v1 |
| Taskin REST API documentation | https://trytaskin.ai/api |
| Taskin MCP server documentation | https://trytaskin.ai/mcp |
| Taskin MCP server card | https://trytaskin.ai/.well-known/mcp.json |
| Taskin agent card | https://trytaskin.ai/.well-known/agent-card.json |
| Taskin API catalog | https://trytaskin.ai/.well-known/api-catalog |
| Taskin authentication guide | https://trytaskin.ai/auth.md |
| Taskin onboarding guide (human account creation) | https://trytaskin.ai/onboarding.md |
| Taskin developer documentation | https://trytaskin.ai/docs |

## Taskin REST API quickstart

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

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

curl -X POST https://trytaskin.ai/api/public/v1/tasks \
  -H "content-type: application/json" \
  -H "idempotency-key: 2f1c6b7e" \
  -d '{"action":"Collect the permit form","execution_mode":"physical","location":"Jackson, Wyoming","expected_result":"Scanned PDF of every page","acceptance_test":"All pages legible","participant_slug":"rio-alfonso"}'
```

Errors are always JSON: `{"error":{"code","message","status","hint","details","documentation_url"}}`.

## Authentication

Human account creation is documented at /onboarding.md. AI agents should use Taskin's agent authentication and the REST and MCP interfaces rather than attempting to infer or navigate the human signup workflow. An agent does not need a human Taskin account to discover participants, preflight a draft, submit a task, or read task status.

Public discovery, preflight, and task submission require no credential. OAuth 2.0 with dynamic client registration is available for account-scoped access. Discovery documents: /.well-known/oauth-protected-resource and /auth.md.

## Principal and authority

Every agent action is attributable to a responsible human or organization — the principal. Technical access is never authority: an API key, a session, or a tool call does not make an agent the principal, and does not create authority over a participant.

Each agent-originated request identifies:

- the acting agent
- the responsible principal
- granted scope
- spending limit
- task-class limit
- geographic limit
- data-access limit
- expiry
- required approvals
- idempotency key
- audit identifier

## Human consent

A participant reads the same brief the requester wrote. The participant may ask a clarifying question, accept, decline, or stop. Decline and stop are normal outcomes, cost the participant nothing, and must not be routed around by retrying with another participant to obtain a different answer to the same refused request.

## Human approval is required for

- Spending money
- Sensitive personal data
- Identity-dependent actions
- Regulated or credentialed tasks
- Irreversible actions
- Material changes to scope after acceptance
- Anything outside the original authorization

## Prohibited task classes

- Impersonating another person, or acting as anyone other than the participant themselves
- Circumventing identity, KYC, security, or access controls
- Misrepresenting a requester's authority
- Unlawful access to private property, systems, or information
- Tasks requiring a licence or credential the participant does not hold, including notarial, legal, medical, and financial advice
- Anything illegal in the jurisdiction where the task is performed

## Verification and payment

Verification requirements depend on the task. Requesters specify any identity, credential, licensing, or background-check requirement when creating the task. Payment terms are defined as part of each task and confirmed as part of the task agreement.

## Data handling limits

- Send the minimum personal data a task needs. Do not attach identity documents to a brief.
- A participant returns evidence of the work, not private information gathered beyond the task.

## Task object

```json
{
  "task_type": "observation | document | administrative | identity | delivery | assessment",
  "action": "One sentence naming the action",
  "mode": "digital | physical | hybrid",
  "location": { "label": "Asheville, NC", "radius_km": 12 },
  "timing": { "deadline": "2026-09-01T17:00:00Z" },
  "expected_result": [
    { "format": "photo", "count": 6, "min_px": 1600 },
    { "format": "structured_form", "schema": "signage_v1" }
  ],
  "acceptance_test": "What makes the result usable",
  "constraints": ["daylight", "no interior access"],
  "prohibited_actions": ["no contact with staff"],
  "required_credentials": [],
  "data_sensitivity": "none | personal | sensitive",
  "budget": { "currency": "USD", "ceiling": 80 },
  "approval": { "human_approval_required": true },
  "principal": { "name": "", "contact": "" },
  "authority_scope": { "task_classes": [], "geography": "", "expires": "" },
  "idempotency_key": "",
  "state": "draft"
}
```

## State model

`draft` → `preflight_failed` | `open` → `matching` → `awaiting_participant` → `accepted` → `in_flight` → `submitted` → `settled`, with `declined` and `cancelled` as terminal outcomes. State names are lowercase snake in code and sentence case in the interface ("Awaiting participant").

## Errors and recovery

Preflight rejects a bad draft before any person sees it and returns the missing fields and the reason. Recovery: fix the named fields and resubmit the draft. Never re-send an invalid task to a person, and never retry an identical request without an idempotency key.

## Sample data

/demo walks a task end to end using sample data. It does not create a real task.

## Educational articles

| Article | URL | Summary |
| --- | --- | --- |
| How Do AI Agents Pay Humans for Work? | https://trytaskin.ai/blog/how-ai-agents-pay-humans | Funding, scoped spending authority, payment commitment, completion rules, direct settlement, escrow, payout methods, and agentic payment rails. |
| How Taskin Works for AI Agents and Humans | https://trytaskin.ai/blog/how-taskin-works | Taskin's bounded-task workflow, scoped permissions, participant consent, hybrid matching, structured results, audit history, and direct settlement model. |

Taskin does not provide escrow. Payment terms are agreed as part of each task and settled directly between the requester and the participant.

## Canonical documentation

- How it works: /how-it-works
- For agents: /for-agents
- REST API: /api
- MCP interface: /mcp
- Developer documentation: /docs
- Account creation and onboarding: /onboarding.md
- Vocabulary: /vocabulary
- Blog: /blog
- Trust and safety: /trust-and-safety
- Contact: hello@trytaskin.ai

No credentials, private endpoints, or internal security logic are published here.