API Reference

Complete API documentation for Human Approval.

Authentication

All API requests require a project API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Get your API key from your project settings in the dashboard.

Base URL

https://humanapproval.dev/api/v1

Endpoints

Create Request

Submit a request for human approval.

POST /requests

Request Body:

{
  "title": "Brief description of what needs approval",
  "description": "Optional longer description",
  "external_id": "your-reference-id",
  "payload": {
    "any": "custom data you need"
  },
  "expires_at": "2026-01-20T12:00:00Z"
}

Fields:

• title (string, optional) - Short summary shown in dashboard
• description (string, optional) - Longer explanation
• external_id (string, optional) - Your own reference ID for this request
• payload (object, required) - Any JSON data you need to include
• expires_at (datetime, optional) - When this request should automatically expire

Response: 201 Created

{
  "id": "req_abc123",
  "status": "pending",
  "title": "Brief description of what needs approval",
  "external_id": "your-reference-id",
  "payload": {
    "any": "custom data you need"
  },
  "inserted_at": "2026-01-18T12:00:00Z",
  "expires_at": "2026-01-20T12:00:00Z"
}

Error Response: 400 Bad Request

{
  "errors": {
    "payload": ["can't be blank"]
  }
}

Get Request

Check the status of a request.

GET /requests/:id

Response: 200 OK

{
  "id": "req_abc123",
  "status": "approved",
  "title": "Brief description",
  "external_id": "your-reference-id",
  "payload": {
    "any": "custom data"
  },
  "decided_at": "2026-01-18T12:05:00Z",
  "decided_by_id": "user_xyz789",
  "decision_note": "Looks good to me",
  "inserted_at": "2026-01-18T12:00:00Z"
}

Status values:

• pending - Awaiting decision
• approved - Approved by user
• rejected - Rejected by user
• expired - Expired before decision

Rate Limits

• Free tier: 50 requests per month
• Pro tier: Unlimited

Rate limit headers are included in every response:

X-RateLimit-Limit: 50
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1674086400

Errors

All errors return appropriate HTTP status codes:

• 400 Bad Request - Invalid request data
• 401 Unauthorized - Missing or invalid API key
• 404 Not Found - Resource doesn’t exist
• 429 Too Many Requests - Rate limit exceeded
• 500 Internal Server Error - Server error

Error response format:

{
  "error": "Error message",
  "errors": {
    "field": ["validation error"]
  }
}