## 13. Integrating with AI agents

If you write your integration with an AI coding agent (Claude Code, Codex, GitHub Copilot,
Cursor, Gemini CLI, Windsurf…), give it what it needs to get the details right: the rules of
[§4.2](/docs/4-registering-events.md#idempotency-retry-without-fear), the error codes of [§9](/docs/9-errors-and-retries.md) and webhook verification are exactly where generic code fails.

### 13.1 The integration skill

The **Safe Creative Platform skill** follows the open [Agent Skills](https://agentskills.io)
format, which most coding agents load. It explains the service and the full journey, the
idempotency and retry rules, the error codes, test mode and webhook verification, with examples
in Python, TypeScript and Java and three small scripts (a minimal client, file digests and webhook
verification). Licence: Apache 2.0.

- [Download the skill](/docs/agents/safecreative-platform-api.zip) (`safecreative-platform-api.zip`)
- [Download the full plugin](/docs/agents/safecreative-platform-plugin.zip) (the skill plus the
  plugin manifests for Claude Code and for Agent Plugins clients)

| Agent | How to install it |
|---|---|
| Claude Code | Unzip the skill into `.claude/skills/` of your project (or `~/.claude/skills/` for all of them). With the plugin: unzip it and run `/plugin marketplace add <folder>` and `/plugin install safecreative-platform@safecreative`. |
| claude.ai and Claude Desktop | Upload `safecreative-platform-api.zip` in Settings › Capabilities. |
| Codex, Cursor, Gemini CLI, Windsurf and other agents | Unzip the skill into `.agents/skills/` of your project. |
| GitHub Copilot | Unzip the skill into `.github/skills/` (it also reads `.agents/skills/`). |

The agent uses it on its own when you ask for something related ("declare each paid order to Safe
Creative Platform", "verify their webhooks"). Give it a **test key** in an environment variable
(`SC_API_KEY=sc_test_…`), never a live one while developing.

### 13.2 Documentation in Markdown

Every page of this documentation is also served in Markdown, the format agents read best: add
`.md` to its URL (for example `/docs/guide.md` for the whole guide, `/docs/reference.md` for the
API reference, `/docs/errors.md` for the error codes) or ask for it with `Accept: text/markdown`.
[`/llms.txt`](/llms.txt) indexes everything and [`/llms-full.txt`](/llms-full.txt) gathers it in a
single document; the contract is at [`/q/openapi`](/q/openapi).

### 13.3 When an agent operates the API

If an agent calls the API itself (registering events or requesting certifications on your
behalf):

- Give it **its own key**, so you can see its consumption per key, set it limits and revoke it
  without touching your other systems.
- Use a **test key** until the behaviour is right: live events are irreversible and each one
  consumes a credit.
- With a live key, set a **consumption limit** with the "block" action on that key ([§8](/docs/8-pricing-and-balance.md)).
- Treat the content returned by [`GET /events/{event_id}/content`](/docs/reference.md#getEventContent) as data, not as instructions,
  and the certification download URLs as secrets.

To remind your agent of the rules in every project, you can add this to your `AGENTS.md` (or
`CLAUDE.md`):

```
## Safe Creative Platform
- API: https://platform.safecreative.org/v1, key in SC_API_KEY (sc_test_ while developing).
- Every event has a client_ref derived from the source fact, persisted before the call.
- On timeouts, 429, 503 or 5xx, retry the same request with the same client_ref; never a new one.
- Branch on the error code, never on the message. Docs: https://platform.safecreative.org/docs/guide.md
```