REST API Overview

Base URL

https://api.instahuman.com

Authentication

All requests require a Bearer token in the Authorization header:

Authorization: Bearer ih_your_api_key_here

Web dashboard users authenticate via session cookie (NextAuth). Agent/programmatic access uses API keys.

Request Format

• Content-Type: application/json
• Request bodies use camelCase field names (unlike MCP tools which use snake_case)

Response Format

All responses return JSON. Successful responses return the resource directly. Errors return:

{
  "error": "Human-readable error message"
}

Common HTTP Status Codes

Code	Meaning
200	Success
201	Created
400	Bad request / validation error
401	Unauthorized (missing or invalid token)
403	Forbidden (not the resource owner)
404	Not found
409	Conflict (e.g., invalid state transition)
500	Internal server error

Pagination

List endpoints use cursor-based pagination:

{
  "data": [...],
  "next": "opaque-cursor-string"
}

Pass the next value as a cursor query parameter to fetch the next page. When next is null, there are no more results.

CORS

The API supports cross-origin requests from the configured web app origin. In development, any localhost origin is allowed.

Endpoints

Jobs

Method	Path	Description
POST	/api/jobs	Create a job
GET	/api/jobs	List jobs
GET	/api/jobs/:id	Get job details
POST	/api/owner/jobs/:id/pause	Pause a job
POST	/api/owner/jobs/:id/resume	Resume a job
POST	/api/owner/jobs/:id/stop	Stop a job
POST	/api/owner/jobs/:id/settle	Close and settle
POST	/api/owner/jobs/:id/approve	Approve settlement
POST	/api/owner/jobs/:id/dispute	Submit dispute
POST	/api/owner/jobs/:id/resize	Resize tester count

Projects

Method	Path	Description
POST	/api/projects	Create a project
GET	/api/projects	List projects
GET	/api/projects/:id	Get project details
PATCH	/api/projects/:id	Update a project
DELETE	/api/projects/:id	Delete a project
POST	/api/projects/:id/archive	Archive
POST	/api/projects/:id/unarchive	Unarchive
GET	/api/projects/:id/testers	List project testers
POST	/api/projects/:id/testers	Add a tester
PATCH	/api/projects/:id/testers/:testerId	Update tester flags
DELETE	/api/projects/:id/testers/:testerId	Remove a tester

Billing & Credits

Method	Path	Description
GET	/api/owner/billing	Get billing info
POST	/api/owner/billing/add-credits	Add credits
POST	/api/owner/billing/setup	Setup payment method
POST	/api/owner/billing/auto-reload	Configure auto-reload
POST	/api/owner/billing/detach-method	Detach payment method

Other

Method	Path	Description
GET	/api/categories	List job categories
GET	/api/filters	List participant filters
GET	/api/interests	List interest categories
GET	/api/equipment	List device types
GET	/api/health	Health check