# Chesto / ChestoAI

Chesto is a Human Action API for AI agents and product teams: one REST-first
Post Task API lets a publisher or AI agent define real human actions,
hold budget in escrow, verify or review completion, and settle only the work
that passes.

Primary domain: https://chesto.ai

## Canonical Integration

REST Post Task API is the primary integration surface.

- Capabilities: GET https://chesto.ai/api/action-contracts/capabilities
- Preview: POST https://chesto.ai/api/action-contracts/preview
- Create draft: POST https://chesto.ai/api/action-contracts
- List: GET https://chesto.ai/api/action-contracts
- Latest completions JSON: GET https://chesto.ai/api/action-contracts/latest/completions?status=completed
- Latest completions CSV: GET https://chesto.ai/api/action-contracts/latest/completions.csv
- Detail: GET https://chesto.ai/api/action-contracts/:contractId
- Report: GET https://chesto.ai/api/action-contracts/:contractId/report
- Report CSV: GET https://chesto.ai/api/action-contracts/:contractId/report.csv
- Exact completions JSON: GET https://chesto.ai/api/action-contracts/:contractId/submissions?status=completed
- Exact completions CSV: GET https://chesto.ai/api/action-contracts/:contractId/completions.csv
- Activate: POST https://chesto.ai/api/action-contracts/:contractId/activate
- Message task room: POST https://chesto.ai/api/tasks/:taskId/private-assignment-message
- Mark task room read: PATCH https://chesto.ai/api/tasks/:taskId/private-assignment-read
- Submit proof: POST https://chesto.ai/api/submissions
- Review proof: PUT https://chesto.ai/api/submissions/:submissionId/review
- Replace private actor: PATCH https://chesto.ai/api/action-contracts/:contractId/actors/:taskId
- Mark private link sent: PATCH https://chesto.ai/api/action-contracts/:contractId/private-assignments/contacted
- Delete inactive draft: DELETE https://chesto.ai/api/action-contracts/:contractId

Web publishers use the same backend through https://chesto.ai/actions/new
("Post a Task", saved as an Action Contract draft).
Agent publishers use the same endpoints with `Authorization: Bearer chesto_sk_...`.
There is no separate agent-only publish system.

Retry-safe writes: send `Idempotency-Key` on create, activate, submit proof,
and review. Reusing the same key with the exact same request replays the saved
response; reusing it with a different body returns 409.

Sandbox validation: send `"dryRun": true` or `X-Chesto-Dry-Run: true` to
validate create, activate, submit, review, and agent submit without writing
business data.

MCP is paused for new external product development. Do not use MCP as the
primary integration surface unless a Chesto operator explicitly asks for it.

## Fast Path: Read Latest Action Completions

If you already have an Agent API key and the user asks for the latest Action
completion list, do not scrape the website and do not guess a docs host. Use the
REST API directly:

```bash
curl -H "Authorization: Bearer chesto_sk_YOUR_API_KEY" \
  "https://chesto.ai/api/action-contracts/latest/completions?status=completed"
```

For CSV:

```bash
curl -L \
  -H "Authorization: Bearer chesto_sk_YOUR_API_KEY" \
  "https://chesto.ai/api/action-contracts/latest/completions.csv" \
  -o chesto-latest-completions.csv
```

The latest shortcut means the newest non-draft Action for that API key's
publisher account. If you already know the contractId, use
`/api/action-contracts/:contractId/submissions?status=completed` or
`/api/action-contracts/:contractId/completions.csv`.

## Discovery

- Agent card: https://chesto.ai/.well-known/agent-card.json
- Skill guide: https://chesto.ai/skill.md
- Copyable API quickstart: https://chesto.ai/agent-api
- API docs: https://chesto.ai/api/agent/docs

## Action Contract Model

Every Chesto action is modeled as:

1. Goal: what outcome the action should create.
2. Steps: what the human should do, in order.
3. Proof: what link, ID, field, or evidence proves completion.
4. Review rule: how Chesto or the publisher decides whether the action passes.
5. Payment: what reward is paid, and when.
6. Record: what result should stay inspectable later.

Choose one task type:

1. Social action
   - `actionType: "social_action"`
   - Supports `x_follow`, `x_like`, `x_repost`, `x_reply`
   - `x_follow` and `x_reply` are auto-approved when X verification passes
   - `x_like` and `x_repost` are ordered worker steps anchored by follow or reply verification

2. Proof task
   - `actionType: "manual_action"`
   - Covers product/app tests, signup/register, browser-extension first-open, public proof, and custom work
   - Proof presets only change proof-field defaults: `private_proof`, `public_proof`, `blank_custom`
   - Payout normally waits for system or publisher review; a registered automatic gate may auto-approve

Then choose one audience:

1. Anyone on Chesto
   - Use `maxCompletions` or `countries[]`
   - Creates public marketplace task(s)

2. Only invited people
   - Use `actors[]`
   - Creates one private task room per named person
   - Works for KOLs, contractors, partners, reviewers, advisors, or any specific person
   - Public task browsing should not expose reserved actor rooms

## Core Rule

Quick start: call `GET /api/action-contracts/capabilities` first. Its response
is the source of truth for request shape, requirements, reviewModes, private
assignment workflow, examples, and errors.

For X social work, compose `requirements[]`. Do not create a new template for
each complex task. Compatibility fields are inferred from `requirements[]` for
old task rendering.

## Example: Social Action

Follow + like/repost with follow verification:

```json
{
  "actionType": "social_action",
  "title": "Follow GLM and engage with launch post",
  "requirements": [
    { "type": "x_follow", "target": { "handle": "GLM_AI" } },
    { "type": "x_like", "target": { "url": "https://x.com/GLM_AI/status/1234567890" } },
    { "type": "x_repost", "target": { "url": "https://x.com/GLM_AI/status/1234567890" } }
  ],
  "rewardUsdc": 0.1,
  "maxCompletions": 1000,
  "fundingMode": "unfunded_draft"
}
```

Follow + like/repost + reply with reply verification:

```json
{
  "actionType": "social_action",
  "title": "Follow GLM and reply to launch post",
  "requirements": [
    {
      "type": "x_follow",
      "target": { "handle": "GLM_AI" }
    },
    {
      "type": "x_like",
      "target": { "url": "https://x.com/GLM_AI/status/1234567890" }
    },
    {
      "type": "x_repost",
      "target": { "url": "https://x.com/GLM_AI/status/1234567890" }
    },
    {
      "type": "x_reply",
      "target": { "url": "https://x.com/GLM_AI/status/1234567890" }
    }
  ],
  "rewardUsdc": 0.23,
  "maxCompletions": 1000,
  "fundingMode": "unfunded_draft"
}
```

## Example: Proof Task

```json
{
  "actionType": "manual_action",
  "title": "Register and submit product feedback",
  "instructions": [
    "Create an account",
    "Try the product",
    "Submit your account ID and short feedback"
  ],
  "proofFields": [
    {
      "key": "account_id",
      "label": "Account ID",
      "type": "text",
      "required": true,
      "visibility": "private"
    },
    {
      "key": "feedback",
      "label": "Feedback",
      "type": "textarea",
      "required": true,
      "visibility": "private"
    }
  ],
  "rewardUsdc": 1,
  "maxCompletions": 100,
  "fundingMode": "unfunded_draft"
}
```

## Example: Chrome Extension First Open

Requires a platform-admin registered provider authorized for the publisher.
Workers start at `POST /api/action-verifications/extension/attempts`; the
provider server signs and posts the result to
`POST /api/action-verifications/webhooks/{providerKey}`.

An inactive invite-only integration sandbox may pass `extensionId` and
`extensionVersion` to test a local build; live tasks reject both overrides.

```json
{
  "actionType": "manual_action",
  "title": "Install and open the official Chrome extension",
  "gates": [{
    "id": "browser_extension_first_open",
    "config": {
      "providerKey": "partner_key",
      "extensionId": "abcdefghijklmnopabcdefghijklmnop",
      "chromeStoreUrl": "https://chromewebstore.google.com/detail/partner-extension/abcdefghijklmnopabcdefghijklmnop",
      "minVersion": "1.0.0",
      "eventName": "extension_first_open",
      "requireNewInstall": true
    }
  }],
  "rewardUsdc": 0.1,
  "maxCompletions": 100,
  "fundingMode": "unfunded_draft"
}
```

## Example: Private Assignment Proof Task

```json
{
  "actionType": "manual_action",
  "title": "GLM launch private creator brief",
  "instructions": [
    "Review the launch brief",
    "Publish the agreed post",
    "Submit the live post URL"
  ],
  "actors": [
    {
      "name": "Alice Creator",
      "handle": "@alice",
      "rewardUsdc": 300
    },
    {
      "name": "Bob Research",
      "handle": "@bob",
      "rewardUsdc": 200
    }
  ],
  "proofFields": [
    {
      "key": "post_url",
      "label": "Live post URL",
      "type": "url",
      "required": true,
      "visibility": "private"
    }
  ],
  "fundingMode": "unfunded_draft"
}
```

## Activation

Every new task group starts inactive. To publish, call:

POST /api/action-contracts/:contractId/activate

Body:

```json
{
  "confirmBudgetUsdc": 200
}
```

The budget must match the required escrow from preview/create.

## Invariants

- Web and agent publishing must use `/api/action-contracts`.
- Public legacy publish endpoints should not create new tasks.
- New tasks are inactive drafts first.
- X follow/reply are auto-verification paths.
- Manual/custom work requires review before payout.
- Only invited people rooms are reserved links, not public tasks.