--- title: "rest api: script your aldena account, teams and agents from code" description: "a rest api at api.aldena.ai/v1 runs your teams, projects, agents and chats from ci jobs and your own tools, on personal api keys that are full access or read-only." url: "https://aldena.ai/features/rest-api" --- # 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](https://aldena.ai/features/isolated-projects) and their settings: the sandbox, env vars, runtimes, agent tools and routines. - [agents](https://aldena.ai/features/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](https://aldena.ai/features/skill-marketplace): 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](https://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](https://aldena.ai/features/ai-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 - **is the rest api on every plan?** yes. the plan only sets the rate limits: solo gets the base numbers, team twice them, business five times and enterprise ten times. - **can a key act for a whole team?** no. keys are personal. a key acts as the person who created it, with that person's role in each team, and loses a team as soon as they leave it. - **can i see a key again after creating it?** no. aldena keeps only a keyed hash, so the full key is shown once. if you lose it, create a new key and delete the old one. - **is there an sdk?** no. the api is plain https and json with a bearer key, so any http client works. the docs show each call in curl, javascript and python. - **what happens when i hit a rate limit?** the request gets a 429 and runs nothing. wait the seconds its Retry-After header gives, then try again, and watch X-RateLimit-Remaining to spread steady traffic out. - **does the api push events or stream replies?** no. there are no webhooks or streaming responses. to follow a reply while an agent writes it, poll the first page of the chat's messages.