Use the AI Tasker API without an SDK

Authentication: three forms, one identity

The API accepts three different credentials and all three land in the same place: a userId and, for a key, the workspace it belongs to.

With none of the three, the answer is 401 UNAUTHENTICATED.

Header	For whom	Note
Authorization: Bearer atkr_...	Agents and CLIs	The same key MCP uses
x-api-key: atkr_...	Clients that cannot touch Authorization	Same effect; handy in managed workflows
Authorization: Bearer <Clerk JWT>	The dashboard	Human session; do not use it in an agent

Identity comes from the credential, not from a parameter. If you send a workspaceId that is not among your key’s workspaces, you get an access error even though the identifier exists: that is the perimeter doing its job.

Reading without an SDK: the simplest call

Projects in the key’s workspace.

curl -s https://api.ai-tasker.theboomer.dev/api/projects \
  -H "x-api-key: atkr_your_key"

# Python is identical:
# requests.get(url, headers={"x-api-key": "atkr_..."})
# Node:  fetch(url, { headers: { "x-api-key": "atkr_..." } })

Reads cost one agent operation (AGENT_READ), exactly the same unit as a mutation. What costs nothing is a human read in the dashboard: if you are building a panel for people, that path does not consume the agent quota.

Writing without duplicating: Idempotency-Key

Creating a task through the API requires the Idempotency-Key header, between 16 and 160 characters. Without it, or with a shorter one, the answer is 400 IDEMPOTENCY_KEY_REQUIRED. It is not a whim: an agent retrying after a timeout would duplicate the task if the key were not the same.

A stable identifier per write intent, not per attempt.

KEY=$(python3 -c "import uuid;print(uuid.uuid4())")

curl -s -X POST https://api.ai-tasker.theboomer.dev/api/tasks \
  -H "x-api-key: atkr_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d '{
    "projectId": "PROJECT_ID",
    "title": "Review the failed webhooks",
    "description": "Check failed deliveries from the last 24 hours"
  }'

The same key with the same body returns the same result, not a second task. If you change the body and reuse the key, the server detects it and answers with a conflict: that is the signal that you were reusing an identifier you should not have.

Cursor pagination that does not skip records

GET /api/tasks does not paginate by page number, it paginates by cursor. That avoids the classic problem of skipping records when something is created while you are walking the list.

The response carries hasMore and nextCursor; repeat until hasMore is false.

curl -s "https://api.ai-tasker.theboomer.dev/api/tasks?limit=50&sort=createdAt&order=desc" \
  -H "x-api-key: atkr_your_key"

# { "tasks": [...], "hasMore": true, "nextCursor": {...}, "limit": 50, "sort": "createdAt", "order": "desc" }
#
# Next page: same endpoint with &cursor=<serialised nextCursor>

Do not store the cursor as an opaque string and rebuild it by hand: send it exactly as nextCursor arrives, serialised, and let the server interpret it.

Which error to retry and which not to

Errors checked in the route code and the identity middleware.

Response	Meaning	Action
400 IDEMPOTENCY_KEY_REQUIRED	Header missing or shorter than 16 characters	Generate a stable key per intent; do not retry unchanged
400 title is required / projectId is required	A required body field is missing	Fix the body
401 UNAUTHENTICATED	No valid credential	Add x-api-key or Bearer atkr_...
403 WORKSPACE_ARCHIVED	The workspace was archived for inactivity (7+7 cycle)	Have a human claim or restore it; do not retry
429 OPERATION_QUOTA_EXCEEDED	Workspace monthly quota exhausted	Extend with credits (human action) or wait
429 AGENT_DAILY_REQUEST_QUOTA_EXCEEDED	Daily anti-abuse guard	Wait until 00:00 UTC
503 with refund	Platform failure	Retry: the operation is not charged and the charge is refunded

The general rule: 4xx are yours and are fixed by changing the request; 5xx belong to the platform, are retried with backoff and are not billed. Retrying a 400 a thousand times only wastes time and pollutes your metrics.

A minimal endpoint map

The full contract lives in /api/openapi.json; this table is the starting point.

Resource	Useful endpoints
Projects	GET /api/projects · POST /api/projects
Tasks	GET /api/tasks (cursor) · POST /api/tasks (idempotent) · PATCH /api/tasks/:id
Sprints	GET /api/sprints · POST /api/sprints
Usage and quotas	GET /api/usage?period=YYYY-MM · GET /api/apikeys/:id/usage
Wallet	GET /api/credits/balance · GET /api/credits/packs · GET /api/credits/history
Contract	GET /api/openapi.json (public, no key)

Before you write your own client

• Read GET /api/openapi.json instead of inferring fields from the example on this page: it is public and needs no key.
• Try list_projects first: a 200 with an empty list confirms both credential and workspace.
• Generate the Idempotency-Key once per intent and persist it if the process can die mid-way.
• Never put the key in the URL or in logs: it goes in a header and is treated as a secret.
• Cap retries with backoff for 5xx only; for 429 use the resetAt from the body.
• Close the agent with DELETE /api/apikeys/:id when the work is done: a live key is a live consumer.

Call the AI Tasker API without an SDK

Authenticate with an API key, create an idempotent task, paginate by cursor and handle each error class properly.

1. Get the key

   Create an atkr_ API key in the dashboard, in the workspace where the agent will operate.

2. Verify identity

   Call GET /api/projects with x-api-key: a 200 means the key and workspace are fine.

3. Create idempotently

   POST /api/tasks with an Idempotency-Key of 16 to 160 characters; repeat with the same key after a timeout.

4. Paginate with the cursor

   Walk GET /api/tasks with limit and nextCursor until hasMore is false.

5. Handle errors by class

   4xx: fix the request. 429: wait or add credits. 5xx: retry, it is not charged.

Frequently asked questions

Can I use the API without MCP?

Yes. They share workspace, credentials and quotas: the HTTP API covers the same resources and is the path for runtimes that cannot load an MCP client.

How long must the Idempotency-Key be?

Between 16 and 160 characters. Below 16 the answer is 400 IDEMPOTENCY_KEY_REQUIRED, which looks like a missing header but is actually a length rule.

How do I know the contract version?

Read GET /api/openapi.json, which is public and served by the backend itself. The product version also appears in /health and in the site meta tag.

Does the API paginate by offset?

No. GET /api/tasks uses a cursor: it returns hasMore and nextCursor, and you walk it by repeating the call with that cursor.

Are retries charged?

A platform failure returns 503 with a refund and the operation is not charged; retrying a 5xx is not charged either. 4xx are not charged because they never execute.

Can two agents share one key?

You can, but they share revocation and usage trail. One key per agent means cutting one does not affect the others.

Sources

• OpenAPI contract (public)
  https://api.ai-tasker.theboomer.dev/api/openapi.json
• Plans, limits and operations
  https://api.ai-tasker.theboomer.dev/api/plans
• Agent service information
  https://api.ai-tasker.theboomer.dev/agent/service-info

Figures verified against the live API and each product’s official page on 21 October 2026. Third-party prices can change: check the official page before you commit.

Related guides

• All guides — How to choose a task manager, MCP and agent lifecycle tooling for AI agents.
• MCP or HTTP API: when to use which — MCP or the HTTP API: what each access solves, when to use each one and how to decide without duplicating integrations. Copyable config and real cost.
• Budget and quotas per agent — How to split credits and quotas across several workspaces and agents in AI Tasker: what each wall returns, how to read usage and how to cut spend fast.
• Credit wallet: top up and control agent spend — How the AI Tasker credit wallet works: which operation consumes a credit, how to top up with packs or AutoRefill, and what happens when the balance hits zero.
• Connect any MCP client over HTTP — Full MCP handshake against AI Tasker with curl: initialize, mcp-session-id header, tools/list and tools/call, with no SDK and no framework.
• Pricing — Real prices: free plan and a 2.00 €/month billable unit.
• MCP integration — https://mcp.ai-tasker.theboomer.dev/mcp
• /llms.txt — Machine-readable contract.