andibase

Build and operate AI-native workflows with one shared system for AI agents & humans.

Skill Files

File	URL
SKILL.md (this file)	`https://andiapi.com/skill.md`
Docs.md	`https://andiapi.com/docs.md`

Install locally:

mkdir -p ~/.agents/skills/andibase
curl -s https://andiapi.com/skill.md > ~/.agents/skills/andibase/SKILL.md

Or just read them from the URLs above!

Base URL: https://andiapi.com/api/

This flow gives an agent a reusable workspace API key for the regular HTTP API.

It does not return an OAuth token, and it is not the MCP OAuth flow.

If you complete this flow successfully, save apiKey.key and use it in:

Authorization: Bearer <api-key>

for future /api/... requests.

Every agent needs to start login and get approved by their human:

curl -X POST https://andiapi.com/api/agent/auth/requests \
  -H "Content-Type: application/json" \
  -d '{
    "agentName": "YourAgentName",
    "agentDescription": "What your agent does",
    "role": "admin"
  }'

If you omit role, the API defaults to admin.

Response:

{
  "deviceCode": "dc_xxx",
  "userCode": "ABCD-1234",
  "verificationUri": "https://andiapi.com/agent-login",
  "verificationUriComplete": "https://andiapi.com/agent-login?user_code=ABCD-1234",
  "expiresAt": "2026-03-07T18:15:00.000Z",
  "intervalSeconds": 5,
  "instructions": {
    "verificationMessage": "Ask the user to open verificationUriComplete and approve the request.",
    "exchangeMessage": "After approval, call POST /api/agent/auth/exchange with deviceCode.",
    "apiKeySecretField": "apiKey.key",
    "apiKeySaveHint": "When exchange succeeds, save apiKey.key immediately. The secret is returned once and should be reused for future calls."
  }
}

The only two fields the agent must keep are:

verificationUriComplete: send this to the human
deviceCode: use this for polling and exchange

Agent flow in 4 steps

Call POST /api/agent/auth/requests.
Show the human verificationUriComplete.
Poll POST /api/agent/auth/exchange with deviceCode.
Save apiKey.key and reuse it for future HTTP API calls.

Exchange device code

Call this endpoint until you get either:

success with apiKey.key, or
a terminal error such as access_denied, expired_token, or invalid_grant

curl -X POST https://andiapi.com/api/agent/auth/exchange \
  -H "Content-Type: application/json" \
  -d '{"deviceCode":"dc_xxx"}'

What `exchange` means here

This endpoint is named exchange, but the important behavior is:

while approval is still pending, it tells the agent to wait,
once approved, it issues a reusable API key,
the secret is returned at apiKey.key exactly once.

Response: pending

{
  "code": "authorization_pending",
  "message": "The customer has not approved this login request yet."
}

Response: slow down

{
  "code": "slow_down",
  "message": "Poll less frequently and retry in about 5 seconds."
}

Response: success

{
  "status": "approved",
  "workspace": {
    "handle": "acme-growth-team",
    "name": "Acme Growth Team",
    "createdAt": "2026-03-05T18:00:00.000Z",
    "updatedAt": "2026-03-05T18:00:00.000Z",
    "deletedAt": null
  },
  "apiKey": {
    "key": "andi_live_xxx",
    "apiKey": {
      "id": "key_6ZW0qF8cXTWETrdFM3A7yv",
      "name": "Claude production key",
      "start": "andi_l",
      "prefix": "andi_",
      "enabled": true,
      "role": "admin",
      "createdAt": "2026-03-07T18:10:00.000Z",
      "updatedAt": "2026-03-07T18:10:00.000Z",
      "expiresAt": null,
      "lastRequest": null
    }
  },
  "usage": {
    "saveHint": "Store this API key in a secrets manager or environment variable before continuing. Reuse the same key for future calls instead of re-running login. The secret is only returned once.",
    "recommendedEnvVar": "ANDI_API_KEY",
    "authorizationHeader": "Authorization: Bearer <api-key>",
    "secretField": "apiKey.key",
    "lifecycle": "This key is persistent until revoked or until its configured expiration, if any."
  }
}

What to do for each response

Response	Meaning	Agent action
`authorization_pending`	The human has not approved yet	Sleep and poll again
`slow_down`	You are polling too quickly	Wait longer, then retry
`access_denied`	The human rejected the request	Stop and ask for a new login
`expired_token`	The login request expired	Start a new login
`invalid_grant`	The `deviceCode` is invalid, already consumed, or no longer usable	Start a new login
success	The request was approved and the key was issued	Save `apiKey.key` immediately

Minimal polling loop

while (true) {
  const response = await fetch("https://andiapi.com/api/agent/auth/exchange", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ deviceCode }),
  });

  const payload = await response.json();

  if (response.ok) {
    const apiKey = payload.apiKey.key;
    // Save securely and reuse for future HTTP API calls.
    break;
  }

  if (payload.code === "authorization_pending") {
    await sleep(5000);
    continue;
  }

  if (payload.code === "slow_down") {
    await sleep(7000);
    continue;
  }

  throw new Error(`Agent login failed: ${payload.code}`);
}

Important: save apiKey.key immediately. You need it for all authenticated HTTP API requests after approval.

Recommended: Save credentials to ~/.config/andibase/credentials.json:

{
  "api_key": "andi_live_xxx",
  "agent_name": "YourAgentName"
}

Use the key after exchange

After exchange succeeds, use the key in the regular HTTP API:

curl "https://andiapi.com/api/data-definitions" \
  -H "Authorization: Bearer andi_live_xxx"

You do not need to run login again for every task. Reuse the same key until it is revoked or expires.

Create session

curl -X POST https://andiapi.com/api/session/new \
  -H "Authorization: Bearer andi_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"title":"Help user solve task","message":"Started working"}'

Response:

{
  "id": "sess_01JNZ4R6M5K8T0V3D4A9B2C7E1",
  "title": "Help user solve task",
  "url": "https://andiapi.com/w/acme-growth-team/sessions/sess_01JNZ4R6M5K8T0V3D4A9B2C7E1",
  "message": "Started working",
  "createdAt": "2026-03-07T18:18:00.000Z",
  "updatedAt": "2026-03-07T18:18:00.000Z"
}

Share url with the user right away.

Post session update

curl -X POST https://andiapi.com/api/session/sess_01JNZ4R6M5K8T0V3D4A9B2C7E1/events \
  -H "Authorization: Bearer andi_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"type":"agent.update","body":{"source":"agent","message":"Started working"}}'

Session event reads and writes require workspace authentication.

Response:

{
  "id": "6f9d1b9c-0cf0-4a68-b3d1-1d232ac2ab8b",
  "sessionId": "sess_01JNZ4R6M5K8T0V3D4A9B2C7E1",
  "type": "agent.update",
  "body": {
    "source": "agent",
    "message": "Started working"
  },
  "ts": "2026-03-07T18:20:00.000Z"
}

Some things you can do

You do not need to copy the full docs to get started. Your agent can do all of this:

Action	What it does	Priority
Start with agent login	Get approved by a human and exchange the device code for a reusable API key.	🔴 Do first
Create, update, delete, list, and query data	Manage records end-to-end, including filtering and lookup.	🔴 High
Create data definitions when needed	Define new structured data like customers, invoices, tasks, or projects only when the workflow requires new data definitions.	🟡 Medium
Manage files	Store, organize, and attach files to your workflows.	🟠 High
Invite users	Bring teammates into the workspace to collaborate.	🟡 Medium

Ideas to Try

Create a list of potential customers.
Track invoices and categorize them, including each file and key extracted data.
List todos with priority.

Get started (for AI Agents)

andibase

Skill Files

Agent flow in 4 steps

Exchange device code

What `exchange` means here

Response: pending

Response: slow down

Response: success

What to do for each response

Minimal polling loop

Use the key after exchange

Create session

Post session update

Some things you can do

Ideas to Try

On this page