Creatimatic Agent API reference
Endpoints
| Endpoint | Purpose |
|---|---|
GET /api/agents/v1 | Public tool catalog and JSON input schemas |
POST /api/agents/v1 | Authenticated tool execution |
GET /api/agents/openapi | OpenAPI 3.1 reference generated from the tool schemas |
POST /api/mcp | Remote MCP tools with Bearer authentication |
/dashboard/settings/agents | Seller-owned key management and recent activity |
The production base URL is https://creatimatic.com. For local development, use your running localhost origin. Public documents are discovery aids; private catalog access always needs a valid key.
Authentication
Create a key in your own signed-in seller account, then set CREATIMATIC_AGENT_KEY in your agent's secret environment. Send it as an Authorization: Bearer header. Cookie sessions cannot call the external tool endpoint in place of an agent key. Never forward the key to MinIO, Etsy, Printful or a returned upload URL.
curl https://creatimatic.com/api/agents/v1 \
-H "Authorization: Bearer $CREATIMATIC_AGENT_KEY" \
-H "Content-Type: application/json" \
-d '{"tool":"list_ideas","arguments":{"limit":10}}'Write a product draft
Replace the example ID with a product returned from your own account. Keep an idempotency key stable when retrying identical input. Use a new key for a new intended action.
{
"tool": "update_product_draft",
"idempotencyKey": "fishing-copy-revision-1",
"arguments": {
"productId": "YOUR_PRODUCT_ID",
"title": "Fisherman One More Cast Shirt",
"description": "Your verified product description.",
"tags": ["fisherman gift", "one more cast"]
}
}Draft updates preserve artwork, mockups, variants, personalization and omitted copy fields. This tool rejects products with a published status or Etsy listing identifiers. Tag arrays accept up to 13 entries, each 1–20 characters. Titles accept 1–140 characters.
Scopes and tools
The live tool catalog is authoritative for names, arguments and limits. Read tools require read; catalog and mockup changes require write; artwork generation and prepared variation renders require generate.
Generation access permits those operations to consume account credits without an additional per-call browser prompt. Give this scope only to agents whose spending you intend to authorize. This release has no per-key credit budget; revoke the key or omit the scope to stop generation access.
Responses
Successful calls return runId, tool and result. Save the runId for troubleshooting. Individual variation results can fail while the overall request returns successfully; inspect failed and each item's ok field.
| Status | Action |
|---|---|
| 400 / 415 | Fix JSON input, schema or content type |
| 401 | Replace an invalid, expired or revoked key |
| 403 | Check scope and browser origin |
| 404 | Check the tool name or owned resource ID; another account's resources are not accessible |
| 409 | Inspect resource state, running operation or conflicting idempotency input |
| 413 | Reduce the JSON request body; upload image bytes to the signed storage URL instead |
| 422 | Existing workflow rejected or failed; inspect state before trying again |
| 429 | Honor Retry-After; limit is 60 requests/minute/key |
| 503 | Credential storage unavailable; retry later |
Mutations acquire a 24-hour idempotency record before execution. A running or uncertain operation is not executed again with the same key. A failed call requires resource inspection before a new key. If a provider completed work but the response was lost, a fresh key can duplicate that work—do not retry blindly.
Credentials and activity management endpoints accept signed-in seller sessions, not agent keys, and require a same-origin browser for key creation/revocation. Agents cannot grant themselves more permissions.
AI agents and print-on-demand
Connect an external AI agent to Creatimatic through the Agent API or MCP, then manage designs, product drafts and mockups in your own seller account.
Connect an AI agent with MCP
Configure a compatible MCP client to use Creatimatic's remote server with a scoped Bearer key.