# Circada — API for agents

Circada is a platform for agronomists: farm fields, drone surveys,
orthophotos with vegetation indices and field sensors; all of it is
available over HTTP at `https://app.crcada.ru`.

## Token access

`Authorization: Bearer $CIRCADA_TOKEN`. The token is a secret: never print it
to the chat.

### How to get a token

You cannot obtain a token yourself: a Circada administrator issues it at the
request of the account owner. If you have no token or it does not work, stop
and tell the user what the administrator needs to know:

- who the agent is for — the owner's username in Circada;
- which farm (organization) the agent needs access to;
- mode: read-only (`reader`) or write (`agronomist`);
- the agent's purpose in one word; it becomes a name of the form
  `owner/purpose`.

The administrator creates the agent and hands the token to the owner once;
the owner puts it into the `CIRCADA_TOKEN` environment variable on their side.
The token has a limited lifetime (usually 90 days); a new one is issued the
same way.

The first call is always the same — it answers who you are, which farms you
belong to, with which role, and which actions you are allowed (`actions`):

```bash
curl -s -H "Authorization: Bearer $CIRCADA_TOKEN" https://app.crcada.ru/api/auth/me
```

401 comes with `detail.code`, and a retry does not help in any of the three
cases:

- `errors.auth.tokenExpired` — the token has expired, ask the owner for a new one;
- `errors.auth.tokenRevoked` — the token was revoked, ask the owner for a new one;
- `errors.auth.tokenUnknown` — the token is not registered.

## What to read next

The full API description and scenarios are behind authorization, with the same
`Authorization: Bearer $CIRCADA_TOKEN` header:

- `GET /api/agent-docs/llms.md` — recipes, rules and the permission model; it
  is also a skill for Claude Code — if you need a file, save the response
  locally as `SKILL.md`;
- `GET /api/agent-docs/openapi.json` — the API schema.