Beta — the platform and this API are in beta. The rules on this page are binding; we may add features and tighten validation without notice.

SDKs & collections

Two thin clients and two collections for API tools. All four are generated from the OpenAPI contract, so every operation in the API reference is in each of them, under its operationId. Neither client has runtime dependencies.

The clients are not on npm or PyPI yet. Download them here and keep the copy in your project; the download always matches the contract version shown in the header.

Download What
creatorguard-python.zip Python client, Python 3.10 or newer, standard library only
creatorguard-typescript.zip TypeScript client (ES modules), Node 20 or newer
creatorguard.postman_collection.json Postman collection (v2.1), one request per operation
creatorguard-bruno.zip Bruno collection with a production environment (https://api.creator-guard.com)

Python

Unzip, then either copy creatorguard.py and creatorguard_operations.py next to your code or install the folder with pip install ./creatorguard-python.

python
import os
from creatorguard import Client, CreatorGuardError

cg = Client(os.environ["CG_API_KEY"])

lead = cg.create_lead(body={
    "external_id": "crm-1047",
    "creator_name": "Mia",
    "instagram_handle": "@miacreates",
    "platforms": ["OnlyFans", "Instagram"],
    "consent_confirmed": True,
})

for lead in cg.paginate("listLeads", query={"stage": "draft"}):
    print(lead["id"], lead["stage"])

A creator integration (OAuth) passes the access token instead of a key: Client(access_token=os.environ["CG_ACCESS_TOKEN"]). Pass exactly one of the two; both are sent as Authorization: Bearer ….

Every operation is also a method named after its operationId in snake case (createLead → create_lead). Path parameters are positional, everything else is a keyword: query=, body=, idempotency_key= (POST) and if_match= (PATCH and PUT). cg.request("createLead", body=...) does the same by name.

TypeScript

Unzip, build it once inside the folder with npm ci && npm run build (output in dist/), then install the folder in your project with npm install ./creatorguard-typescript. For a creator integration (OAuth) pass accessToken instead of apiKey — exactly one of the two.

ts
import { CreatorGuard, CreatorGuardError } from '@creatorguard/api';

const cg = new CreatorGuard({ apiKey: process.env.CG_API_KEY! });

const lead = await cg.request('createLead', {
  body: { external_id: 'crm-1047', creator_name: 'Mia', instagram_handle: '@miacreates',
    platforms: ['OnlyFans', 'Instagram'], consent_confirmed: true },
});

for await (const item of cg.paginate('listLeads', { query: { stage: 'draft' } })) {
  console.log(item);
}

Retries and idempotency

Both clients retry the same way, so a script behaves alike in either language:

Answer Retried?
No answer (network error, timeout) Yes
408, 429, 500, 502, 504 Yes
503 Yes, except not_configured
409 idempotency_in_progress Yes
Any other 4xx No

Up to 2 retries by default (max_retries / maxRetries). The wait is the Retry-After header when the API sends one (at most 60 seconds), otherwise an exponential backoff from 0.5 to 8 seconds with jitter.

A Retry-After longer than 60 seconds is never waited for: the call ends at once, without a retry, so a script cannot hang for an hour. For a 429 the client then raises RateLimitError with the wait in seconds (retry_after in Python, retryAfter in TypeScript) — schedule the next attempt yourself. A 429 that is still there after the last retry is a RateLimitError as well.

Every POST carries an Idempotency-Key. The client makes one (a random UUID) unless you pass your own, and it reuses the same key for every retry of that call — so a lead that was created before a timeout is not created a second time. Pass your own key when your job can restart, for example the row id of your import. See Idempotency & retries.

Pagination

paginate() follows next_cursor as starting_after until has_more is false and yields the items one by one. Pass the filters of the list operation in query; limit sets the page size (1–100).

Errors

A non-2xx answer raises CreatorGuardError with status, type, code, message, request_id, field and details — the fields of the error body. Branch on code. A 429 is a RateLimitError, a subclass of CreatorGuardError. A proxy page instead of an API error (a 502 while a release switches over) has code proxy_error. When no HTTP answer arrives after the last retry, the Python client raises ConnectionError_ and the TypeScript client ConnectionError.

Webhook signatures

Check CG-Signature against the raw request body (bytes, before any JSON parsing) and the endpoint secret. Both helpers accept every v1 signature in the header (two during a secret rotation) and reject timestamps more than 300 seconds away from now.

python
from creatorguard import verify_webhook_signature

def handle_webhook(raw_body: bytes, headers) -> int:
    if not verify_webhook_signature(raw_body, headers["CG-Signature"], os.environ["CG_WEBHOOK_SECRET"]):
        return 400
    return 200
ts
import { verifyWebhookSignature } from '@creatorguard/api';

const header = String(req.headers['cg-signature'] ?? '');
if (!verifyWebhookSignature(rawBody, header, process.env.CG_WEBHOOK_SECRET!)) {
  res.status(400).end();
}

Postman and Bruno

  • Postman: Import → the JSON file. Put api_key into a Postman environment as a secret variable, not into the collection, which you might share. base_url is https://api.creator-guard.com.
  • Bruno: unzip, then Open Collection → the creatorguard-bruno folder. Pick the production environment and enter api_key there; it is a secret variable, so Bruno keeps it out of the files.

There is one host for everything. To try requests without touching live data, use a cg_test_ key: it works on the same https://api.creator-guard.com against your account's sandbox, see Test mode. A cg_live_ key works on live data.

Every POST request sends a fresh Idempotency-Key ({{$guid}}); a resend from the tool therefore counts as a new request. Request bodies are the examples from the reference.