AI Agent Integration

Discovery documents and guidance for integrating Claret with AI agents.

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.

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.

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:

{
  "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": "[e-mail]"
}

Provisioning a token for an agent

An agent authenticates exactly like any other client: with a Bearer token (see Authentication). 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.

Because of 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.

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.

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.

• Respect Retry-After on 429 responses rather than retrying immediately. See Rate Limiting.

• 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

• Scopes Reference

• Error Reference