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.
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.
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.
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 200import { 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_keyinto a Postman environment as a secret variable, not into the collection, which you might share.base_urlishttps://api.creator-guard.com. - Bruno: unzip, then Open Collection → the
creatorguard-brunofolder. Pick theproductionenvironment and enterapi_keythere; 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.