> For the complete documentation index, see [llms.txt](https://docs.claret.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.claret.app/api-guide/ai-agents.md).

# AI Agent Integration

The Claret API publishes machine-readable discovery documents so AI agents and tools can learn the API surface automatically. All three are served from the Claret application host.

{% hint style="info" %}
These documents describe the public API generically; they are not tenant-specific. Replace `{tenant}` with a real tenant when an agent actually calls an endpoint.
{% endhint %}

## Discovery documents

| Document           | URL                                                  | Purpose                                                             |
| ------------------ | ---------------------------------------------------- | ------------------------------------------------------------------- |
| OpenAPI spec       | `https://plan.claret.app/api/docs/api.json`          | Full machine-readable API description (paths, parameters, schemas). |
| Interactive docs   | `https://plan.claret.app/api/docs`                   | Human-browsable rendering of the OpenAPI spec.                      |
| `llms.txt`         | `https://plan.claret.app/api/docs/llms.txt`          | Compact, plain-text orientation for LLMs.                           |
| AI plugin manifest | `https://plan.claret.app/.well-known/ai-plugin.json` | Plugin descriptor pointing to the OpenAPI spec and auth method.     |

### OpenAPI specification

The spec is generated directly from the application, so it always reflects the deployed endpoints. Point any OpenAPI-aware tool (code generators, agent frameworks, API explorers) at `https://plan.claret.app/api/docs/api.json`.

### llms.txt

A short plain-text summary an agent can read to orient itself quickly — authentication model, base URL, response envelope, and error format. Fetch it from `https://plan.claret.app/api/docs/llms.txt`.

### AI plugin manifest

The `.well-known/ai-plugin.json` manifest follows the AI plugin convention. It declares Bearer authentication and links to the OpenAPI spec:

```json
{
  "schema_version": "v1",
  "name_for_model": "claret_api",
  "description_for_model": "Claret is a multi-tenant SaaS platform for business planning and operational management. Use this API to query items, sales, inventory, and other business data.",
  "auth": { "type": "service_http", "authorization_type": "bearer" },
  "api": { "type": "openapi", "url": "https://plan.claret.app/api/docs/api.json" },
  "contact_email": "help@claret.app"
}
```

## Provisioning a token for an agent

An agent authenticates exactly like any other client: with a Bearer token (see [Authentication](/api-guide/authentication.md)). Provision it deliberately:

1. Create a token from **API Access → Tokens** scoped to only what the agent needs — usually **Read** (`public_api.read`) for a data-querying agent.
2. Set a sensible **expiration** so an unattended agent's token doesn't live forever.
3. Supply the token to the agent through a secret, never in a prompt or source file.

{% hint style="info" %}
Because of [two-gate authorization](/api-guide/authentication.md#two-gate-authorization), an agent's reach is bounded by both its scope and the permissions of the user who created the token. Provisioning from a least-privileged user is a simple way to sandbox an agent.
{% endhint %}

{% hint style="warning" %}
Programmatic, agent-initiated token provisioning (an agent minting its own scoped tokens) is not currently enabled. Provision agent tokens through the **API Access** UI for now.
{% endhint %}

## Designing agent-friendly calls

* **Start at `llms.txt`,** then load the OpenAPI spec for full parameter detail.
* **Read `meta.credits.remaining`** on responses so an agent can stay within budget. See [API Credits & Usage](/api-guide/credits-and-usage.md).
* **Respect `Retry-After`** on `429` responses rather than retrying immediately. See [Rate Limiting](/api-guide/rate-limiting.md).
* **Use `dry_run`** on write and compute calls when an agent is uncertain about a payload; it validates without consuming credits or changing data.

## Related documentation

* [Authentication & Tokens](/api-guide/authentication.md)
* [Scopes Reference](/api-guide/scopes.md)
* [Error Reference](/api-guide/errors.md)