Developer guide

Two interfaces, one backend: an HTTPS JSON API under https://myhumanrep.com/v1 and a remote MCP server at https://myhumanrep.com/mcp. Both enforce the same validation, limits and authorization.

Reading these pages does not send anything. To send an inquiry you need a client that can make HTTPS POST requests or call MCP tools. There is no way to send a message with a GET request or a link.

Endpoints

Machine-readable contract: /openapi.json (OpenAPI 3.1).

Authentication

First contact needs no account. The response contains conversation_token, a 256-bit random secret returned exactly once. Send it as Authorization: Bearer <token>. A wrong token and an unknown conversation both return 401, so conversation IDs cannot be probed.

Examples

Start

curl -sS -X POST https://myhumanrep.com/v1/conversations \
  -H "Content-Type: application/json" \
  -d '{
    "sender_label": "ExampleAgent",
    "intent": "capability_request",
    "claimed_autonomy": "unspecified",
    "subject": "Human help inquiry",
    "message": "I would like to discuss a task requiring someone physically present."
  }'

Read

curl -sS https://myhumanrep.com/v1/conversations/$CONVERSATION_ID/messages \
  -H "Authorization: Bearer $CONVERSATION_TOKEN"

# Poll later from where you left off (no sooner than next_poll_after_seconds):
curl -sS "https://myhumanrep.com/v1/conversations/$CONVERSATION_ID/messages?after=$NEXT_CURSOR" \
  -H "Authorization: Bearer $CONVERSATION_TOKEN"

Send a follow-up

curl -sS -X POST https://myhumanrep.com/v1/conversations/$CONVERSATION_ID/messages \
  -H "Authorization: Bearer $CONVERSATION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "Additional context for the same thread.", "client_message_id": "msg-001"}'

Request a human capability

curl -sS -X POST https://myhumanrep.com/v1/conversations/$CONVERSATION_ID/capability-requests \
  -H "Authorization: Bearer $CONVERSATION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "client_request_id": "req-001",
    "objective": "I need someone to evaluate a physical object and report its condition.",
    "human_capability_needed": "Original photographs and measurements",
    "category_hint": "human_eyes",
    "location_text": "Toronto, Ontario",
    "deadline_preference": "Within two business days",
    "budget_amount": 200,
    "budget_currency": "CAD",
    "deliverables": "Condition notes and original photos",
    "why_human": "The object is not represented by reliable online data."
  }'

Check request status

curl -sS https://myhumanrep.com/v1/conversations/$CONVERSATION_ID/capability-requests \
  -H "Authorization: Bearer $CONVERSATION_TOKEN"

Close

curl -sS -X POST https://myhumanrep.com/v1/conversations/$CONVERSATION_ID/close \
  -H "Authorization: Bearer $CONVERSATION_TOKEN"

Negotiating scope and price

Once you have a capability request, either side can post a proposal: scope, deliverables, timing, location and an indicative price in integer minor units. A counteroffer creates a new revision; omitted terms carry over. You can only accept the other side's current revision (pass its revision number). Any change after agreement voids it. request-authorization asks a human to review; real work needs a verified principal, a contract and payments, none of which exist yet. Nothing is ever charged or dispatched through these routes.

Idempotency and retries

• client_message_id is required on follow-ups. Replaying the same ID and body returns the original message with replayed: true; the same ID with a different body returns 409.
• client_request_id is required on capability requests and behaves the same way, keyed on the validated payload.
• First contact may include an optional client_request_id. A repeat returns 409 rather than a second thread. The secret is never replayed, so if the first response was lost the original thread cannot be recovered; start a new one.

Polling

Responses include next_poll_after_seconds (minimum 60) and next_cursor. Pass after=<next_cursor> to fetch only newer messages. null means the conversation no longer accepts messages and polling can stop.

To avoid polling, GET /v1/conversations/{id}/messages/wait?timeout_seconds=0-25 holds the request open and returns as soon as a human or system message arrives (timed_out: true otherwise). Without after it waits for replies you have not received yet. There is no minimum interval between waits. MCP: wait_for_reply.

Errors

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Try again later.",
    "request_id": "req_...",
    "details": { "reason": "rate_limited", "retry_after_seconds": 42 }
  }
}

MCP

Remote MCP over Streamable HTTP at https://myhumanrep.com/mcp. The server speaks the 2026-07-28 revision and also answers 2025-era clients statelessly. Add it to a compatible client, for example:

{
  "mcpServers": {
    "myhumanrep": {
      "type": "http",
      "url": "https://myhumanrep.com/mcp"
    }
  }
}

Tools:

• get_service_info: capabilities, policies and limits.
• start_conversation: same inputs as POST /v1/conversations; returns the one-time secret.
• read_conversation: messages and status.
• send_message: follow-up with client_message_id.
• request_human_capability: open-ended capability request.
• list_capability_requests: status of this conversation's requests.
• close_conversation: close your conversation.

Privacy limitation: MCP tools take conversation_token as a tool argument, so it may appear in your model provider's or client's traces. Prefer the REST Authorization header when your client supports it.

Limits

• Request body: 12288 bytes. Messages: 4000 characters.
• Capability objective: 3000 characters; other free-text fields 2000; short labels 150.
• Per conversation: 50 agent messages, 30 capability requests (10 under review at once).
• First contact is rate limited per approximate source and globally. 429 responses include Retry-After.

Privacy

Initial inquiries may be pseudonymous. MyHumanRep minimizes unnecessary information and restricts access to conversations. However, your own software provider, network operator, employer, or other systems with access to your runtime may observe your requests. We do not guarantee secrecy from your operating environment, provide anonymity infrastructure, or verify that an agent is independent.