Make Agent Fast documentation

API quickstart

Create a least-privilege key, verify authentication, list sites, and handle the first failure.

At a glance

Create a least-privilege key, verify authentication, list sites, and handle the first failure.

API request pathScoped key → versioned resource → signed response

10 minutesServer onlyREST

This quickstart verifies that a backend can authenticate and read your account. You need an active paid plan, a terminal with curl, and access to Dashboard → Settings → Developer.

The current v1 API manages and synchronizes resources. It is not a custom-chat transport: conversation and lead endpoints are read-only.

1. Create a least-privilege key#

Create a key named Local API quickstart, select account:read and sites:read, and choose a short expiry. Copy the plaintext key immediately; it will not be shown again.

Do not use a provider key from OpenAI, Anthropic, Gemini, Deepgram, or ElevenLabs. The public API requires a Make Agent Fast key beginning with maf_live_.

2. Store it for this terminal#

export MAF_API_KEY="maf_live_..."

Confirm the variable exists without printing the secret:

test -n "$MAF_API_KEY" && echo "MAF_API_KEY is set"

Do not commit the key to .env, shell-history examples, test fixtures, or a browser bundle. For deployed code, use the host's secret manager.

3. Inspect the account#

curl --fail-with-body --include https://makeagent.fast/api/v1/me \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Accept: application/json"

Expected status: 200 OK. The body contains data.id, plan and entitlement information, and a wallet summary. The response also contains x-request-id; retain that value when reporting a failed request.

{
  "data": {
    "id": "ACCOUNT_ID",
    "email": "[email protected]",
    "plan": { "id": "pro", "status": "active" },
    "entitlements": { "site_limit": 3, "live_voice": true },
    "wallet": { "balance": 151 }
  }
}

Fields can be added without changing the /v1 path. Ignore unknown fields instead of rejecting the response.

4. List sites#

curl --fail-with-body "https://makeagent.fast/api/v1/sites?limit=20" \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Accept: application/json"

Collection responses use this envelope:

{
  "data": [],
  "has_more": false,
  "next_cursor": null
}

If has_more is true, send the exact next_cursor value as the next request's cursor query parameter. Do not decode or construct cursors.

5. Handle a structured error#

Temporarily remove the Authorization header and repeat /me. The response should be 401 with a stable code:

{
  "error": {
    "code": "authentication_required",
    "message": "Provide an API key in the Authorization bearer header.",
    "request_id": "6c0b2f2e-..."
  }
}

Production code should branch on error.code, not compare message. Log the operation, HTTP status, and request ID without logging the key.

6. Make the first write safely#

Create a separate key that also has sites:write, agents:write, and knowledge:write; do not expand the quickstart read key. Follow API recipes to create a site, add grounded knowledge, and publish it using explicit idempotency keys.

Common first-request failures#

Result	Cause	Fix
`401 authentication_required`	Header missing or not `Bearer TOKEN`	Add the exact Authorization header from server code
`401 invalid_api_key`	Typo, expired key, revoked key, or wrong credential type	Create and copy a new Make Agent Fast API key
`403 subscription_required`	No active paid plan	Restore the account subscription
`403 insufficient_scope`	Key does not include the operation's scope	Create a replacement with the minimum missing scope
`403 account_paused`	API access was paused for this account	Resume API access or contact the account owner
`429 rate_limit_exceeded`	One-minute key bucket exhausted	Wait for `Retry-After` and reduce concurrency

Continue with Scopes and errors, API reference, and Rate limits.