Helpin REST API

The Helpin REST API lets your own code read and change the data in a Helpin workspace: tasks, planning, documents, CRM, and support conversations. It can also start and monitor Helpin agent runs. Use it for scripts, scheduled jobs, CI pipelines, and back-end integrations.

The REST API is a curated, versioned set of endpoints. It is separate from the internal endpoints the Helpin web app uses, which can change without notice and aren't supported. Every REST API operation goes through the same access checks as the Helpin MCP server, so tokens, scopes, read-only mode, workspace roles, and workspace policy all apply.

Base URL

Where you use Helpin	Base URL
Helpin Cloud	`https://api.helpin.ai/public/v1`
Self-hosted	Your API host followed by `/public/v1`

The full machine-readable description (OpenAPI 3.1) is available without authentication at https://api.helpin.ai/public/v1/openapi.json. Import it into Postman, Insomnia, or a client generator.

Get a token

Requests are authenticated with a bearer token from an automation account. A token belongs to one workspace.

A workspace manager opens Settings → MCP access → Permissions, turns on access, and turns on Allow automation accounts. The same page controls which product areas and scopes automation accounts can be given.
Open the Service accounts tab and choose Create automation account. Pick a name, the scopes and product areas it needs, and whether it is read-only.
Create a token for the account and copy it right away. Tokens start with hmp_ and are shown only once. If you lose one, create another and revoke the old one.

Give each integration its own account with the smallest set of scopes it needs. Revoking an account or a token stops it working immediately.

Make your first request

Send the token in the Authorization header.

curl https://api.helpin.ai/public/v1/me \
  -H "Authorization: Bearer $HELPIN_TOKEN"

The response describes the identity, workspace, scopes, and modules the token can use:

{
  "summary": "Connected to Helpin as Build bot.",
  "data": {
    "actor": { "name": "Build bot", "role": "member" },
    "workspace": { "name": "Acme", "slug": "acme" },
    "scopes": ["helpin.context.read", "helpin.pm.read", "helpin.pm.write"],
    "modules": ["pm", "docs"],
    "read_only": false
  }
}

To create something, send a JSON body. Add an Idempotency-Key header so you can retry safely:

curl -X POST https://api.helpin.ai/public/v1/tasks \
  -H "Authorization: Bearer $HELPIN_TOKEN" \
  -H "Idempotency-Key: nightly-import-2026-09-29-0001" \
  -H "Content-Type: application/json" \
  -d '{"team_id": "TEAM_ID", "name": "Investigate slow inbox load", "priority": "high"}'

Use GET /teams to find a team ID and GET /workflows to see the states a task can be moved to.

How requests and responses work

Reads use query parameters for filters. For lists, separate values with commas, for example owner_member_ids=a,b. Unknown parameters are rejected instead of ignored.
Writes take a JSON object. An ID that is already in the URL must not be repeated in the body.
Successful responses look like { "data": …, "summary": "…", "links": { … } }. links holds deep links back into Helpin.
Errors look like { "error": { "code": "…", "message": "…" } }. Branch on the code, which is stable, rather than the message.
Agent runs are asynchronous. Start one with POST /agent-runs and poll GET /agent-runs/{run_id} until it finishes.
Request bodies are limited to 1 MiB, and each call has a 30 second deadline.

Idempotency

Every operation that changes data accepts an Idempotency-Key header of 8 to 128 characters. If you retry with the same key and the same body, Helpin returns the original result instead of repeating the change. Results are kept for 24 hours. Reusing a key with a different body returns 409 with the code idempotency_conflict.

If you leave the header out, Helpin generates a random key for you. That works, but retries are then not deduplicated, so a retry after a timeout can create a duplicate.

Scopes and permissions

Each endpoint requires one scope, listed in REST API endpoints and scopes. A token can only call an endpoint if all of these allow it:

The token has the endpoint's scope.
The workspace policy allows that scope and product area.
The product module is enabled for the workspace, for example CRM or Support.
The account is not read-only, for endpoints that change data.
The workspace role behind the account can perform the action, as in the app.

If any check fails, the call returns 403 forbidden.

Errors

Status	Code	Meaning
400	`invalid_arguments`	A parameter or body field is missing, has the wrong type, or is unknown.
401	`unauthorized`	The token is missing, invalid, expired, or revoked.
403	`forbidden`, `api_disabled`	The scopes, role, module access, read-only mode, or workspace policy don't allow this.
404	`not_found`	The record doesn't exist in this workspace.
409	`idempotency_conflict` and resource-specific codes	The key was reused with a different body, or the record's state conflicts, such as a locked document.
422	Resource-specific codes	The request is valid but can't be applied. The `code` says why.
429	`rate_limited`	Too many requests. Wait for the number of seconds in the `Retry-After` header.
504	`timeout`	The operation took longer than 30 seconds.

Rate limits

Requests are limited per token. By default that is 1,200 requests per minute, with a lower limit of 120 per minute for changes and search. When you exceed a limit, the API returns 429 with a Retry-After header. Back off and retry after that many seconds.

API access overview: every way to connect to Helpin from code.
REST API endpoints and scopes: each endpoint and the scope it needs.
Connect AI clients to the Helpin MCP server: the same access for AI tools such as Claude, Cursor, and VS Code.

Was this article helpful?