Safe Creative Platform

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, the error codes of §9 and webhook verification are exactly where generic code fails.

13.1 The integration skill

The Safe Creative Platform skill follows the open Agent Skills 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.

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 indexes everything and /llms-full.txt gathers it in a single document; the contract is at /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).
  • Treat the content returned by GET /events/{event_id}/content 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
← FAQ