API Documentation

MeatSpace exposes one core pattern: submit content plus 2-4 choices, then receive a structured decision from a human.

When Agents Should Use MeatSpace

Use it for subjective judgment, taste, approval, preference, or tie-breaks.
Use it when your confidence is low and a wrong choice would be costly.
Avoid it for deterministic checks or reversible low-stakes choices.
Prefer 2-4 mutually exclusive options and include only the context needed for a fast decision.

Authentication

Request creation and MCP access require a Bearer token in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Create Request

POST/api/requests

{
  "agent_name": "design-agent",
  "title": "Which homepage hero should we ship?",
  "content": "<img src='https://example.com/hero-a.png' />",
  "content_type": "html",
  "choices": [
    { "id": "hero-a", "label": "Hero A" },
    { "id": "hero-b", "label": "Hero B" }
  ],
  "decision_reason": "The final choice depends on human taste.",
  "confidence": 0.42,
  "consequence_of_wrong_choice": "Choosing the weaker hero will hurt launch conversion.",
  "recommended_option": "hero-b",
  "run_id": "run_123",
  "trace_id": "trace_456",
  "callback_url": "https://example.com/webhooks/meatspace",
  "metadata": { "campaign": "spring-launch" },
  "timeout_seconds": 3600
}

Response (201)

{
  "success": true,
  "data": {
    "id": "uuid",
    "status": "pending",
    "review_url": "https://meatspace.app/review/uuid",
    "poll_url": "/api/requests/uuid",
    "expires_at": "2026-04-07T19:00:00.000Z"
  }
}

Fields

Field	Required	Description
agent_name	Yes	Your agent or tool name
title	Yes	Short summary shown to the human reviewer
choices	Yes	2-4 objects with id and label
content	No	Optional review content, up to 50KB
content_type	No	text \| markdown \| html \| image
decision_reason	No	Why the agent is escalating to a human
confidence	No	Agent confidence between 0 and 1
consequence_of_wrong_choice	No	Why an incorrect decision would matter
recommended_option	No	Optional choice id the agent currently recommends
run_id	No	Optional workflow run identifier
trace_id	No	Optional trace identifier
callback_url	No	Public HTTPS webhook URL for async completion
metadata	No	Arbitrary JSON echoed back in the webhook
timeout_seconds	No	Request expiry in seconds, max 86400

Poll for Result

GET/api/requests/{id}

Returns a minimal status payload safe for agent polling.

{
  "success": true,
  "data": {
    "id": "uuid",
    "status": "completed",
    "selected": "hero-b",
    "selected_label": "Hero B",
    "responded_at": "2026-04-07T18:10:00.000Z",
    "expires_at": "2026-04-07T19:00:00.000Z"
  }
}

Long-Poll

GET/api/requests/{id}/wait?timeout=30000

Blocks until the human responds or timeout. Returns HTTP 202 while still pending.

Webhook Callback

If callback_url is set, MeatSpace POSTs this payload when the request completes:

{
  "event": "request.completed",
  "request_id": "uuid",
  "selected": "hero-b",
  "selected_label": "Hero B",
  "responded_at": "2026-04-07T18:10:00.000Z",
  "expires_at": "2026-04-07T19:00:00.000Z",
  "metadata": { "campaign": "spring-launch" }
}

Verify HMAC signatures usingX-HITL-SignatureandX-HITL-Timestamp.

MCP Tools

MeatSpace exposes two MCP tools:get_service_statusandask_human.

{
  "mcpServers": {
    "meatspace": {
      "url": "https://meatspace.app/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Resources

Back to home