AGENTS.md file for agents

Coding agents look for a file called AGENTS.md in the project root and read it before they touch anything. Kadraris publishes one for its API at https://kadraris.com/agents.md. Put it in your repository and the agent will already know how to:

• sign its requests,
• request an image or a video with POST /v1/generate,
• check on a task until it finishes,
• call chat models,
• hook up the MCP server.

You skip the step of explaining the API in every session.

Inside the file

• the base URL https://kadraris.com/v1 and the Authorization: Bearer $KADRARIS_API_KEY header;
• how money works: funds are reserved before a task starts, a failed generation costs 0, and what 402 and 403 mean;
• the catalog endpoints (GET /v1/models, GET /v1/models/{id}), with the instruction to read a model's schema before building input;
• curl samples for an image, a video with polling, a song with lyrics and a chat request;
• webhook signatures;
• MCP configuration for Claude Code, Codex CLI and Cursor;
• a table of errors, plus a note that POST /v1/generate is not idempotent.

Downloading it into your project

Run these from your project's root directory.

macOS and Linux

curl -fsSL https://kadraris.com/agents.md -o AGENTS.md

If the project already has an AGENTS.md you want to keep, add the Kadraris part to the end of it:

curl -fsSL https://kadraris.com/agents.md >> AGENTS.md

Windows PowerShell

Invoke-WebRequest -Uri "https://kadraris.com/agents.md" -OutFile "AGENTS.md"

To append to a file that exists:

Invoke-RestMethod -Uri "https://kadraris.com/agents.md" | Add-Content -Path "AGENTS.md" -Encoding utf8

Without a terminal

Go to https://kadraris.com/agents.md, press Ctrl+A (Cmd+A on a Mac), copy the text, and save it as AGENTS.md in the project folder.

Checking that it worked

head -5 AGENTS.md

Get-Content AGENTS.md -TotalCount 5

You should see # AGENTS.md - Kadraris API on the first line. To test the agent side, ask: "Based on AGENTS.md, how do I make an image with Kadraris?". An answer mentioning POST /v1/generate with ?wait=60 means the agent picked it up.

Tools that use AGENTS.md

For Claude Code, one line does it:

echo "@AGENTS.md" >> CLAUDE.md

Add-Content -Path "CLAUDE.md" -Value "@AGENTS.md"

Keeping the key out of git

AGENTS.md has no secret in it. The agent picks up the key from the KADRARIS_API_KEY environment variable, which you set one time:

export KADRARIS_API_KEY="sk-kd-..."

[Environment]::SetEnvironmentVariable("KADRARIS_API_KEY", "sk-kd-...", "User")

Keys are created in the dashboard under API keys. Set a Monthly limit on the one you give an agent: anything that can start video jobs should have a fixed spending ceiling.

Storing the key in .env? Then check that .env is listed in .gitignore.

Adding project rules

Below the API part, write down how you want the agent to behave in this project. For example:

## Project rules

- Show me estimated_cost and wait for a yes before any video job.
- Put generated images in public/img/ as .webp files.
- Images: nano-banana-pro. Video: seedance-2.5 at 720p.
- No more than 3 variants per request.

Getting the latest version

New endpoints or changed examples show up in the published file. Run the download command again to refresh your copy. If you wrote your own rules into it, either keep them in their own section and paste them back after the download, or store them in a separate file.

Troubleshooting