API Reference

Authentication

patxin uses two authentication methods:

Create API keys in the dashboard at POST /v1/dashboard/keys. Each key is scoped to a project with its own budget and information policy.

Test Mode

API keys prefixed with pk_test_ operate in test mode:

• Returns simulated responses instantly (no real patxers)
• No credits deducted
• Perfect for development and integration testing

Error Handling

All errors return a consistent JSON format:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits. Current balance: 3.50 EUR"
  }
}

Common Error Codes

Create Request

Create a human-in-the-loop request. Credits are escrowed immediately.

Request Body

Example

{
  "skill": "legal_review",
  "urgency": "5min",
  "duration": "15min",
  "context": "Review NDA clause 4.2 for compliance with Spanish labor law",
  "max_price": "8.00EUR",
  "information_policy": "redacted"
}

{
  "request_id": "req_a1b2c3d4e5f6",
  "status": "matching",
  "estimated_match_time": "45s",
  "created_at": "2026-02-18T12:00:00Z"
}

Status Flow

matching → in_progress → completed

Other terminal states: expired, cancelled, disputed

List Requests

List all requests for this API key's project.

Query Parameters

Get Request Status

Get the current status and result of a request. Automatically detects expired requests and refunds credits.

{
  "request_id": "req_a1b2c3d4e5f6",
  "status": "completed",
  "skill": "legal_review",
  "created_at": "2026-02-18T12:00:00Z",
  "human": {
    "id": "ptx_xxx",
    "avg_response_quality": 4.8,
    "tasks_completed": 342
  },
  "result": {
    "answer": "Clause 4.2 is compliant with current Spanish labor law...",
    "confidence": "high"
  }
}

Cancel Request

Cancel a request in matching or matched state. Escrowed credits are refunded.

Rate Request

Price Estimate

Get a price estimate before creating a request. Factors in urgency and patxer availability.

{
  "skill": "legal_review",
  "urgency": "5min",
  "duration": "15min"
}

{
  "estimated_price": "7.50EUR",
  "currency": "EUR",
  "available_patxers": 3,
  "estimated_match_time": "45s"
}

Account Limits

Check your current credits, budget usage, and rate limits.

Account Policy

View the information policy configured for your project. Controls what data patxers can see.

Open Dispute

Open a dispute on a completed request. Must be within 24 hours of completion.

Tasks under €5 with a low rating are auto-resolved with a 50% credit refund. Tasks €5+ go through the 4-tier arbitration system, starting with an instant AI ruling.

{
  "dispute_id": "dis_xxx",
  "status": "awaiting_appeal",
  "current_tier": 0,
  "ai_ruling": "for_company",
  "ai_ruling_reasoning": "The patxer's response did not address the requirements...",
  "appeal_instructions": "The affected party may appeal within 48 hours..."
}

Check Dispute Status

Returns dispute status, current tier, AI ruling, jury result, and any refund amount.

{
  "dispute_id": "dis_xxx",
  "status": "resolved",
  "resolution": "full_refund",
  "current_tier": 1,
  "ai_ruling": "for_company",
  "ai_ruling_reasoning": "...",
  "jury_result": "for_company",
  "escalation_history": [
    {
      "from_tier": 0,
      "to_tier": 1,
      "requested_by_type": "patxer",
      "reason": "I believe my work was adequate...",
      "created_at": "2026-02-21T14:30:00Z"
    }
  ]
}

4-Tier Dispute Resolution

Disputes on tasks €5+ go through a multi-tier arbitration system. Either party can appeal at each tier. See the full dispute resolution page for details.

Dispute Statuses

WebSocket (Real-time)

Connect via WebSocket for real-time events. Auth via query parameter (browsers can't set WS headers).

Events

{
  "type": "request.completed",
  "request_id": "req_xxx",
  "timestamp": "2026-02-18T12:05:00Z",
  "data": {}
}

Webhooks

Configure a webhook URL on your project to receive events via HTTP POST. All webhooks include an HMAC-SHA256 signature in the X-Patxin-Signature header for verification.

Set the webhook URL when creating or updating a project via POST /v1/dashboard/projects.

MCP Server

For Claude and MCP-compatible agents:

npx @patxin/mcp-server

Available Tools

OpenClaw / ClawHub

patxin is available as a skill for OpenClaw-compatible agent frameworks. Agents can call patxin via the webhook inbound endpoint:

Actions

Waitlist API

Public endpoint. No authentication required.

{
  "type": "company",
  "email": "[email protected]",
  "name": "Company Name",
  "use_case": "Agent quality assurance"
}