rest api: script your aldena account, teams and agents from code

a rest api is an http interface that a program calls instead of a person clicking through screens: it sends a request with a key and gets json back.

aldena's lives at https://api.aldena.ai/v1. it does from code what you do in the app, and it acts as you through a personal api key.

use it from a ci job that starts a chat with an agent when a build fails, a dashboard that reads which chats wait on a person, or a script that sets up the same project for every new client.

what one key reaches

a key reaches what you reach in the app, in every team you belong to:

• teams: create, rename, leave or delete one, change a member's role or remove them, and invite people.
• projects and their settings: the sandbox, env vars, runtimes, agent tools and routines.
• agents: hire one from the marketplace or build your own, pin a version, set its runtime and whom it reports to, assign skills, stop a run or fire it.
• skills: built-in ones, ones shared across a team, and ones written for one project.
• chats: start one with an agent, send messages, read the replies, answer an agent's questions and approve its tool calls.
• connectors, mcp servers, repo imports, the team inbox, provider keys and models, and the team's subscription and billing portal link.

signing in, passwords, checkout and plan changes stay in the app.

personal keys, full access or read-only

create a key under account → api keys: name it and choose full access or read-only. the full key, ald_ followed by 43 characters, is shown once with a copy button.

aldena stores only a keyed hash of it, so it can check a key but never show it again. from then on the key appears as its hint, such as ald_…wxyz.

a key is personal. it acts as you in every team you belong to, with the role you hold in each, so it can do in a team exactly what you can do there. leave a team, or be removed from it, and your keys lose that team at once.

a read-only key can call every read. any other call gets 403 INSUFFICIENT_PERMISSIONS before anything runs, so nothing changes. give each integration its own key, and make it read-only when it only reads.

the key list shows each key's name, hint, access, status, created date and when it was last used, to the minute. rename, disable, re-enable or delete a key there, and the change applies from the next request.

a disabled key gets 401 API_KEY_DISABLED until you enable it again. you can hold up to 25 keys, and keys never expire.

rate limits that scale with your plan

every limit counts requests over one minute. on the solo plan a key gets 120 requests a minute across all endpoints.

each endpoint also has its own limit by kind: 60 a minute for a read, 30 for a write and 10 for a heavy call, such as creating a project or starting a chat. team doubles those numbers, business multiplies them by 5 and enterprise by 10.

a key is personal, so its plan is the best one among your teams, and the same numbers apply in every team it touches.

every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. a request over a limit gets 429 TOO_MANY_REQUESTS with Retry-After, and runs nothing.

api requests keep their own counters, apart from the per-connection repo import limit, so a busy script does not eat into the limits your team meets in the app.

responses you can branch on

every response uses one envelope: success: true with data, or success: false with a stable upper-case code in message, such as NOT_FOUND.

a 400 INVALID_DATA lists each bad field in details, and every response carries an X-Request-Id.

the chats and messages lists page with cursors, and every other list returns everything in one response.

the version sits in the path. within /v1 the api changes only in ways that keep working clients working, and a breaking change ships as a new version.

the docs

the guides and the reference live at docs.aldena.ai. there is a quickstart, a guide each to api keys, rate limits, errors, pagination and versioning, and a page for every endpoint with its parameters, responses and samples in curl, javascript and python.

the reference is generated from the api's own route definitions, and a test fails when the two drift apart. an agent-readable index sits at docs.aldena.ai/llms.txt.

the concierge reads the same docs to answer api questions. it lists your keys, and renames, disables, re-enables or deletes one after you approve.

it never creates a key or shows a secret, so a secret never lands in a chat.

faq