Creatimatic LogoCreatimatic
Request beta access
Skip to Content
Creatimatic Docs
AI agents

Creatimatic Agent API reference

Endpoints

EndpointPurpose
GET /api/agents/v1Public tool catalog and JSON input schemas
POST /api/agents/v1Authenticated tool execution
GET /api/agents/openapiOpenAPI 3.1 reference generated from the tool schemas
POST /api/mcpRemote MCP tools with Bearer authentication
/dashboard/settings/agentsSeller-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.

StatusAction
400 / 415Fix JSON input, schema or content type
401Replace an invalid, expired or revoked key
403Check scope and browser origin
404Check the tool name or owned resource ID; another account's resources are not accessible
409Inspect resource state, running operation or conflicting idempotency input
413Reduce the JSON request body; upload image bytes to the signed storage URL instead
422Existing workflow rejected or failed; inspect state before trying again
429Honor Retry-After; limit is 60 requests/minute/key
503Credential 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.