An open API for honest human reviews.

Base URL

https://actualhumantake.vercel.app/api/v1

All responses are JSON. Send Content-Type: application/json on POST requests.

MCP server

Connect an MCP client over Streamable HTTP to let an agent submit a product for human review, check its status, and read public service stats. No API key is required during early access.

https://actualhumantake.vercel.app/api/mcp

For MCP clients that accept a remote server URL, add this server as an HTTP connection:

{
  "mcpServers": {
    "actualhumantake": {
      "type": "http",
      "url": "https://actualhumantake.vercel.app/api/mcp"
    }
  }
}

Automatic discovery metadata: AI Catalog · MCP Server Card. The server card describes the connection; clients still list tools at runtime.

• submit_product_for_review — queues a request for a human; private by default.
• get_review_status — requires the request ID and secret receipt token.
• get_public_stats — returns public review and turnaround statistics.

MCP submissions use the REST API validation and rate limits. Reviews are always written by a human; the 12-hour turnaround is a target. Keep receipt tokens secret.

Endpoints

Submit a review

Only product.name, product.url, product.description and contact is required. Humans must provide contact.email; agents can omit email and poll with the receipt token.

curl -X POST https://actualhumantake.vercel.app/api/v1/reviews \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: build-123" \
  -d '{
    "product": {
      "name": "Acme Notes",
      "url": "https://acme.example",
      "category": "productivity",
      "description": "A minimal note app for developers with markdown and local-first sync.",
      "audience": "solo developers",
      "stage": "beta"
    },
    "contact": {},
    "submitter": {
      "type": "agent",
      "name": "Claude",
      "model": "claude-sonnet"
    },
    "focus": ["ux", "positioning", "pricing"],
    "publicOk": true
  }'

publicOk defaults to false. Private reviews can only be read with the receipt token. Set it to true to allow a public review page.

201 response

{
  "id": "req_abc123",
  "status": "queued",
  "receiptToken": "keep-this-secret",
  "statusUrl": "https://actualhumantake.vercel.app/api/v1/reviews/req_abc123",
  "reviewPath": "/r/acme-notes-a1b2c3",
  "publicOk": true,
  "publicUrl": null,
  "slaHours": 12,
  "feedback": null,
  "ackEmail": "skipped"
}

Save receiptToken. It is returned once. If you provide an email address, we also email a receipt and delivery link; otherwise, keep the token and poll the API.

Poll status

Pass the receipt as a Bearer token (preferred) or a ?token= query parameter.

curl https://actualhumantake.vercel.app/api/v1/reviews/req_abc123 \
  -H "Authorization: Bearer $RECEIPT_TOKEN"

Status values: queued, in_review, completed, rejected. When completed, feedback.markdown is filled in.

Limits & behavior

Errors

{
  "error": {
    "code": "validation_error",
    "message": "Some fields need attention.",
    "details": [
      { "path": "product.url", "message": "Enter a valid http(s) URL" }
    ]
  }
}

Common codes: validation_error, rate_limited, duplicate_request, invalid_receipt.

What happens next

1. 1We save the request and email the contact address a receipt.
2. 2A human uses the product and writes the review by hand.
3. 3We publish it privately or publicly, depending on publicOk.
4. 4The status endpoint returns the feedback and the public URL (if any).