Agency API / public documentation

Read the API before you choose a plan.

Connect external tools to your own catalog, run documented pattern checks and receive signed scan events. Documentation is public; API keys require Agency.

What v1 does

Read your catalog and its latest stored scan results.
Scan existing listing content and save scan history.
Deliver scan.completed events to configured webhook endpoints.

v1 does not expose AI copy generation or direct marketplace publishing. Shopify connection is a separate read-only integration; availability is shown in the workspace. Agency is one account, without team seats or client logins.

1. Create and protect a key

In an Agency account, open API & Webhooks and create a personal key. Send it on every HTTPS request as Authorization: Bearer cfk_your_key. Keep keys on your server, never in public frontend code. Revoke unused keys in the same workspace.

The limit is 60 requests per minute per key. 401 indicates missing/invalid authentication; 403 can indicate unavailable plan access; 429 means slow down. Inspect each response before retrying.

Open API & Webhooks

2. Read the catalog

curl 'https://copy-forge-ai.com/api/v1/catalog?offset=0' -H 'Authorization: Bearer cfk_YOUR_KEY'

The response includes up to 200 products, hasMore and nextOffset. While hasMore is true, request the returned nextOffset. Avoid changing the catalog during a full export; deduplicate product IDs if it changes while you read it.

3. Scan existing listing content

curl -X POST 'https://copy-forge-ai.com/api/v1/catalog/scan' -H 'Authorization: Bearer cfk_YOUR_KEY' -H 'Content-Type: application/json' -d '{"productIds":["YOUR_PRODUCT_UUID"]}'

Send 1–50 product IDs owned by the key’s account. Results are reported per product: scanned, skipped_no_content, not_found or failed. HTTP success does not mean every product succeeded; inspect results before retrying a failed product.

A scan checks configured text rules. A high score does not verify product facts, grant legal approval or guarantee marketplace acceptance. Each scan creates history; repeating a successful scan can create another history entry and event.

4. Verify webhook deliveries

Register an HTTPS endpoint in API & Webhooks. CopyForge sends X-CopyForge-Event and X-CopyForge-Signature. The signature is sha256= followed by the hexadecimal HMAC-SHA256 of the exact raw request body, using your signing secret. Verify it with a constant-time comparison before processing the JSON.

Preserve the raw body bytes; re-serializing JSON changes the signature input. Do not trust the event header without the signature. The body includes event, createdAt and data. Webhook delivery is separate from the synchronous scan response.

v1 endpoint and response reference

Read the OpenAPI 3.1 reference for request and response schemas. Every request requires an active Agency API key. SDKs are not currently supplied.

CopyForge v1 endpoints, request inputs and success response fields
Endpoint	Input	Success
GET /api/v1/catalog	offset: integer 0–1,000,000, default 0	object, apiVersion, count, products, totalCount, hasMore, nextOffset
POST /api/v1/catalog/scan	productIds: 1–50 owned UUIDs	object, apiVersion, scanned, results; inspect each result status

Catalog products include identifiers, listing fields and nullable latestScan. Scan results contain an id, status and, when scanned, score, riskLevel, flagCount, findings and rulesetVersion. Findings include the exact match and source URL. Database/request errors can use an error object with code and message; shared validation/auth errors can use an error string plus a separate code. Handle both shapes and inspect HTTP status. 400/422 indicate input errors, 401/403 authentication or access, 429 throttling and 5xx temporary failures. Do not automatically retry a successful scan: it saves another history entry.

scan.completed event body

{
  "event": "scan.completed",
  "createdAt": "2026-10-16T07:00:00.000Z",
  "data": {
    "scanned": 1,
    "products": [
      {
        "id": "00000000-0000-4000-8000-000000000001",
        "score": 75,
        "riskLevel": "high",
        "flagCount": 1
      }
    ]
  }
}

Illustrative values only. Delivery is one best-effort attempt per enabled endpoint, recorded in delivery logs, with a five-second timeout. There is no automatic retry or exactly-once guarantee. Receivers must be idempotent; do not treat an absent webhook as evidence that the synchronous scan failed. Additive fields may appear in v1. Breaking response changes require a new version; a removal or retirement will be announced in the changelog before a scheduled change, except urgent security action.