# API reference

The Maitento API is plain HTTP and JSON. The SDKs for TypeScript, Python and C# wrap it, and every call in this
reference shows the plain request too, with curl, TypeScript and Python. It is generated from the code, so it always
matches what the API does. To try a call without writing any code, use the
[API playground](https://docs.maitento.com/playground/): it sends the call from your browser with your API key.

- **[Calls by area](#calls-by-area):** every call, grouped the way the SDKs group them.
- **[Concepts](https://docs.maitento.com/concepts.md):** what each part of Maitento is for, and the definition file properties.
- **SDK source and READMEs:** the TypeScript and Python SDKs are in [`sdks/`](https://github.com/maitento/maitento/tree/main/sdks), and the .NET SDK is
  `Maitento.Sdk` on NuGet.

## Base URL and authentication

```text
https://api.maitento.com
```

Send your [API key](https://docs.maitento.com/get-started/2-api-key.md) in the `Authorization` header: the word `ApiKey`, your user id
and the secret, separated by spaces. The curl examples use `$MAITENTO_AUTH`:

```bash
export MAITENTO_AUTH="ApiKey ${MAITENTO_API_KEY/:/ }"
```

Your tenant always comes from the key, never from the URL. Something that belongs to another tenant answers 404.

## Conventions

- **JSON** in and out, with `camelCase` names. Every field is present in a response; empty ones are `null`.
- **Ids** are UUIDs. **Dates** are ISO 8601 in UTC. **Durations** are written `"hh:mm:ss"` (`"00:05:00"` is five
  minutes).
- **Names** of definitions (`{name}`) are unique within a namespace (`{namespaceName}`).
- **Enums** are strings such as `"Finished"`. New values can appear, so don't treat an unknown one as an error.
- **Lists** of definitions come back whole. Lists of runs, builds and files are paged: pass the `nextCursor` from one
  page as `cursor` to get the next.

## Errors

| Status | Body | Means |
|---|---|---|
| 400 | `{"validationFailures": [{"errorCode", "memberName", "message"}]}` | the request is invalid; branch on `errorCode` |
| 401 | empty | missing, wrong or expired credentials |
| 403 | empty, or `{"code", "error"}` | you're signed in but not allowed (for example, a member doing an admin's job) |
| 404 | empty | not found, or not yours |
| 409 | `{"error"}` | a concurrent change; read again and retry |
| 413 | `{"code": "api:request-too-large", ...}` | the body is too large |
| 429 | `{"code": "api:rate-limited", "retryAfterSeconds"}` | slow down; also sent as `Retry-After` |

Branch on the status and the error code, never on the message text. [Error codes](https://docs.maitento.com/reference/errors.md) lists every code, what
it means and what to do.

## Also in the reference

- [Types](https://docs.maitento.com/reference/types.md): every object, enum and shape the API sends and receives, with its fields and an
  example. Every type named in this reference links to its page.
- [Error codes](https://docs.maitento.com/reference/errors.md): every code the API answers with, by area, with its status and what to do.
- [Project files](https://docs.maitento.com/reference/project-files.md): every file in a Maitento project, every property it can set, and the
  VS Code extension that checks them as you type.
- [API playground](https://docs.maitento.com/playground/): try any call from your browser.

## Calls by area

- [Namespaces](https://docs.maitento.com/reference/api/namespaces.md): 8 calls
- [Models](https://docs.maitento.com/reference/api/models.md): 1 call
- [Credentials](https://docs.maitento.com/reference/api/credentials.md): 12 calls
- [Credential stacks](https://docs.maitento.com/reference/api/credential-stacks.md): 11 calls
- [Model keys](https://docs.maitento.com/reference/api/model-keys.md): 4 calls
- [Agents](https://docs.maitento.com/reference/api/agents.md): 7 calls
- [Interactions](https://docs.maitento.com/reference/api/interactions.md): 13 calls
- [Interaction runs](https://docs.maitento.com/reference/api/interaction-runs.md): 10 calls
- [Apps](https://docs.maitento.com/reference/api/apps.md): 8 calls
- [App runs](https://docs.maitento.com/reference/api/app-runs.md): 3 calls
- [Capsules](https://docs.maitento.com/reference/api/capsules.md): 7 calls
- [Capsule runs](https://docs.maitento.com/reference/api/capsule-runs.md): 14 calls
- [Code pipelines](https://docs.maitento.com/reference/api/pipelines.md): 9 calls
- [Code pipeline runs](https://docs.maitento.com/reference/api/pipeline-runs.md): 14 calls
- [Runs (all kinds)](https://docs.maitento.com/reference/api/runs.md): 9 calls
- [Connectors](https://docs.maitento.com/reference/api/connectors.md): 9 calls
- [Tools](https://docs.maitento.com/reference/api/tools.md): 9 calls
- [Secrets](https://docs.maitento.com/reference/api/secrets.md): 6 calls
- [Webhooks](https://docs.maitento.com/reference/api/webhooks.md): 6 calls
- [Knowledge bases (partitions)](https://docs.maitento.com/reference/api/partitions.md): 14 calls
- [Files](https://docs.maitento.com/reference/api/files.md): 8 calls
- [File systems (VFS)](https://docs.maitento.com/reference/api/vfs.md): 51 calls
- [Memory (looms)](https://docs.maitento.com/reference/api/looms.md): 29 calls
- [Automations](https://docs.maitento.com/reference/api/automations.md): 19 calls
- [Builds (validate and deploy)](https://docs.maitento.com/reference/api/builds.md): 5 calls
- [Usage](https://docs.maitento.com/reference/api/usage.md): 4 calls
- [Users](https://docs.maitento.com/reference/api/users.md): 3 calls
- [API keys](https://docs.maitento.com/reference/api/api-keys.md): 3 calls
- [Tenant settings](https://docs.maitento.com/reference/api/tenant.md): 5 calls
- [billing](https://docs.maitento.com/reference/api/billing.md): 9 calls