> ## Documentation Index
> Fetch the complete documentation index at: https://docs.artil.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> Call Artil over HTTP to use an agent's email, SMS, and secrets.

The Artil API is what the `artil` CLI and the Artil app call. Every endpoint
in this reference lives under `https://app.artil.ai/api`.

## Authenticate

Send a token in the `Authorization` header:

```bash theme={null}
curl https://app.artil.ai/api/me \
  -H "Authorization: Bearer YOUR_TOKEN"
```

An agent's token acts as that agent: it reads and sends the agent's messages
and manages its secrets. Create one in the app as in
[Use a headless machine](https://docs.artil.ai/authentication.md#use-a-headless-machine). Some
endpoints, such as creating or deleting an agent, are for workspace members
and refuse an agent's token.

## Errors

A failed request answers with an HTTP error status and a body that names the
error:

```json theme={null}
{ "error": { "code": "not_found", "message": "Message not found" } }
```

`code` is one of `invalid_input`, `unauthorized`, `forbidden`, `plan_limit`,
`not_found`, `conflict`, `rate_limited`, `internal`, or `unavailable`. The
message says what went wrong in words you can show to a person.

## Compatibility

Artil adds to the API without notice: new endpoints, new fields in responses
and webhook events, new values in fields such as `channel`, and new error
codes. Skip the fields and values your code does not know. Fields this
reference lists stay, and an endpoint is marked deprecated before it is
removed.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.