REST API

One endpoint per tool

Every tool is a POST to its own URL. There is no router and no dispatch field: the tool name is in the path.

The body is {"arguments": { … }}. A bare arguments object works too, so a no-code HTTP node can post its field map straight through. Money is a decimal number in the account currency — 80, never 80000000. Ids are strings.

Authentication

Send an Adako API key as a bearer token. Create one in the web app under API keys; it is shown once.

Authorization: Bearer ak_live_…

A key carries scopes. A read key (ads:read, accounts:read, usage:read) can call every read tool. A write key adds ads:write, which is what write tools and approve_proposal need. Calling a write tool with a read key answers 401 unauthorized and names the missing scope.

The envelope

Every response has the same shape, success or failure.

curl -X POST https://adako.ai/api/v1/tools/google_list_campaigns/execute \
  -H "Authorization: Bearer $ADAKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"arguments": {"customer_id": "1234567890"}}'

{
  "success": true,
  "tool": "google_list_campaigns",
  "data": { "campaigns": [ { "id": "123", "name": "Brand — Search", "status": "ENABLED" } ] },
  "markdown": "| Campaign | Status | Cost |\n| --- | --- | --- |\n…",
  "quota": { "plan": "pro", "used": 12, "limit": 600, "period_end": "2026-10-01" },
  "request_id": "3f2b…"
}

• data — the machine-readable result. Parse this.
• markdown — the same result written for a person or a model. Paste it into Slack, an email or an LLM prompt.
• quota — tasks used against the plan this period. Present whenever the call was billable.
• request_id — also returned as the x-request-id header. Quote it in support requests; it is how a call is found in the audit log.

Writes return a proposal

A write never reaches the ad platform on its own. It is validated, dry-run against the platform, stored as a proposal and returned to you with a preview. The HTTP status is still 200: the call succeeded, the change is pending.

curl -X POST https://adako.ai/api/v1/tools/google_update_campaign_budget/execute \
  -H "Authorization: Bearer $ADAKO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"arguments": {"campaign_id": "123", "daily_budget": 80}}'

{
  "success": true,
  "tool": "google_update_campaign_budget",
  "data": { "status": "pending", "preview": { "summary": "Daily budget 50 → 80 USD" } },
  "markdown": "**Proposal created — waiting for approval.** Nothing has changed yet…",
  "proposal_id": "prp_01J…",
  "approve_url": "https://adako.ai/approvals/prp_01J…",
  "request_id": "9a1c…"
}

Approve it in one of two ways: a person opens approve_url in the web app, or the same key — holding ads:write — calls approve_proposal over REST.

curl -X POST https://adako.ai/api/v1/tools/approve_proposal/execute \
  -H "Authorization: Bearer $ADAKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"arguments": {"proposal_id": "prp_01J…"}}'

Under the direct write policy the call itself is the approval, so the response comes back already executed with a read-back of what exists now. Under inbox it waits. Either way a proposal executes exactly once, and created campaigns are always paused.

Idempotency

Send an Idempotency-Key header — 8 to 128 characters, a UUID is ideal — on any call you might retry. The successful envelope is cached for 24 hours per key and per user.

• Same key, same arguments → the stored envelope, with Idempotent-Replayed: true.
• Same key, different arguments → 409 with error.code: idempotency_mismatch. Use a new key.
• Failures are not cached. A call that ran out of quota or hit a platform error stays retryable with the same key.

Retries are safe without the header too: the proposal engine keys every write by user, tool and arguments, so a repeat of the same change joins the existing proposal instead of creating a second one.

Errors and HTTP status codes

Switch on error.code, never on the message. recovery_steps is written to be shown to a person or handed to a model.

{
  "success": false,
  "tool": "google_update_campaign_budget",
  "error": {
    "code": "not_connected",
    "message": "Google Ads is not connected.",
    "recovery_steps": ["Ask the user to connect Google Ads at https://adako.ai/connections."]
  },
  "request_id": "7c31…"
}

Anything not listed answers 500. 429 responses carry Retry-After in seconds — wait that long and retry once, do not loop.

Discovery and OpenAPI

• GET /api/v1/tools — every tool with its platform, risk, task cost and call URL. Add ?platform=google_ads to filter.
• GET /api/v1/tools/{tool_name} — one tool: the full description, the JSON Schema of its arguments and which fields are required.
• GET /api/v1/openapi.json — the whole surface as OpenAPI 3.1, generated from the registry. No key needed.

n8n, Zapier, Make and anything else with an HTTP node

Configure one generic HTTP request node and reuse it for every tool:

1. Method POST.
2. URL https://adako.ai/api/v1/tools/<tool>/execute.
3. Authentication — a generic header credential: Authorization: Bearer ak_live_…. Store it as a credential, not in the URL.
4. Headers Content-Type: application/json, and Idempotency-Key set to the workflow execution id.
5. Body JSON: {"arguments": {"customer_id": "1234567890"}}.
6. Response — branch on {{ $json.success }}. On failure, route {{ $json.error.code }}: retry on rate_limited, alert a human on needs_reauth.

In Make, import /api/v1/openapi.json into the HTTP “Make an API Call” module to get the field names. In Zapier, use “Custom Request” with the same three headers.

Command line

The adako CLI wraps the same endpoints with no install step and no dependencies — handy inside coding agents and cron jobs.

npx adako login              # paste your ak_live_… key once
npx adako tools --platform google_ads
npx adako google list-campaigns --customer-id 1234567890
npx adako run google_update_campaign_budget --arg campaign_id=123 --arg daily_budget=80

Rate limits and cost

Sixty tool calls a minute per user, shared with MCP. Each billable call costs the task count shown below; reads of your own Adako state (usage, connections, proposals) are free. The quota block in every envelope is the authoritative counter.