Introduction

Everything the ManyPI dashboard does is available over REST. Same endpoints, same permissions, same credit accounting.

Base URL

https://app.manypi.com

Published API endpoints live under the same host, on the /v1/e/ path.

Authentication

Send a ManyPI API key as a bearer token on every request:

curl https://app.manypi.com/api/user \
  -H "Authorization: Bearer mpi_your_api_key"

Create keys in Settings → API keys. That /api/user call is the cheapest way to confirm a key works — it returns the owning account, the key’s permissions and its rate limit. OAuth 2.1 access tokens are accepted anywhere a key is, and resolve to the same user. They are how MCP clients connect without a key.

Keys are secrets. Keep them server-side, one per integration, and scoped to the least they need. Never ship one in frontend JavaScript or commit one to a repository.

Permissions

Keys carry only the permissions you grant them. A call outside a key’s permissions is rejected exactly as an invalid key would be.

Permission	Grants
`read`	View scrapers, runs, results, leads and usage.
`write`	Create, update and delete scrapers, endpoints, folders and saved leads.
`scraper`	Start scrape runs. Spends crawl credits.
`agents`	Start agent runs, reply to them, cancel them. Spends credits.
`endpoints:invoke`	Call your published endpoints at `/v1/e/…`.
`leads:validate`	Verify lead email addresses. Spends validation credits.
`outreach:send`	Send email from your inboxes and enroll leads.
`*`	Full access.

Each endpoint below states which permission it needs.

API keys and permissions

Rotation, revocation, and the full route-to-permission mapping.

Rate limits

60 requests per minute per active key. OAuth tokens get the same. Exceeding the limit returns 429; the window is one minute, so back off and retry. How many keys you can keep active in parallel depends on your plan. Revoked keys stop counting toward that limit.

Responses

All responses are JSON. Successful calls return 200, except:

Code	When
`201`	A resource was created.
`202`	Work was accepted and is running asynchronously. Poll for the result.

Errors

Errors carry a human-readable error, and — where you might want to branch on it — a machine-readable code.

{
  "error": "Your workspace is storing all 2,500 leads your plan holds.",
  "code": "lead_limit",
  "used": 2500,
  "limit": 2500
}

Status	Meaning
`400`	The body or parameters failed validation. The message says which field.
`401`	Missing, invalid or expired credential — or a key lacking the required permission.
`402`	Out of credits, with overage off.
`403`	A plan gate, a seat limit, or a permission the key does not hold.
`404`	No such resource in this workspace.
`409`	A conflict — a slug already in use, or a run that is still working.
`429`	Rate limited.
`5xx`	Something broke on our side. Retry with backoff.

Codes worth handling

Code	Meaning	What to do
`lead_limit`	Lead storage is full.	Archive leads, or upgrade.
`outreach_locked`	Sending requires a paid plan.	Upgrade.
`validation_credits_exhausted`	Out of validation credits.	Buy credits or enable overage.

Asynchronous work

Anything that browses the web is asynchronous. The pattern is always the same:

Start it

POST returns a run id immediately — run_id for agent work, runId for scrapes.

Poll it

GET the run until its status is terminal.

Handle a pause

An agent run may reach paused, meaning it has a question for you. Read it from result_summary and answer with POST /api/agents/runs/{id}/reply — the same run resumes.

Prefer not to poll? Configure an outbound webhook in Dashboard → Webhooks.

Workspaces and brands

A credential belongs to one workspace, and every call acts on that workspace. Leads are workspace-pooled. Inboxes, campaigns and sequences are brand-scoped — most list endpoints accept ?brand=<id> to narrow or ?brand=all to widen across the workspace.

Core concepts

Workspaces, brands, seats and the three credit types.

Overview

Leads

Email validation

Outreach

Agent

Scraping

Endpoints

Account

Base URL

Authentication

Permissions

API keys and permissions

Rate limits

Responses

Errors

Codes worth handling

Asynchronous work

Workspaces and brands

Core concepts

​Base URL

​Authentication

​Permissions

API keys and permissions

​Rate limits

​Responses

​Errors

​Codes worth handling

​Asynchronous work

​Workspaces and brands

Core concepts

Base URL

Authentication

Permissions

Rate limits

Responses

Errors

Codes worth handling

Asynchronous work

Workspaces and brands