API reference
Submit creator leads, complete their listings and follow them from your own system. Generated from openapi.yaml (OpenAPI 3.1.0, API version 1.23.0). Base URL https://api.creator-guard.com.
Authentication
HTTP bearer token — cg_live_ (or cg_test_) followed by 43 letters and digits.
Authorization: Bearer cg_live_…. Keys are issued by Creator Guard per account and handed over once; only a
hash is stored. A key carries scopes (each operation names the one it needs), an optional expiry and an
optional IP allowlist. cg_test_ keys work in test mode (sandbox data, halved limits).
Service
API status and versions
/v1/No API key needed.
No key needed. Use it as a liveness check and to read the contract version. Like every request without a valid key it uses the per-IP budget (30 per minute), so poll it at most every few seconds.
| Status | Meaning | Body |
|---|---|---|
| 200 | The API document. | ApiInfo |
| 429 |
| error |
| 500 |
| error |
Account
The account the key belongs to
/v1/meScope account:read.
Type, status, terms state per agreement type and the limits in effect for this key.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | The account. | Account |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Change your account profile
/v1/meScope account:write.
Display name, company name, Telegram username and website — the same fields and checks as the portal's
profile page. Send only what changes; null (or an empty string) clears the company name or the website.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
If-Match | header | string | optional | The |
Body application/json — AccountPatch.
| Field | Type | Required | Description |
|---|---|---|---|
display_name | string · 1–120 chars | optional | The name agencies and creators see. |
company_name | string or null · 0–200 chars | optional |
|
telegram_username | string | optional |
|
website | string or null · 0–300 chars | optional | An |
Example: rename
curl -X PATCH https://api.creator-guard.com/v1/me \
-H "Authorization: Bearer $CG_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"display_name": "Northwind Talent",
"website": "https://northwind.example"
}'// Node.js 20+ as an ES module (.mjs, or "type": "module"): built-in fetch + top-level await.
// Server-side only: the key must never reach a browser.
const body = {
"display_name": "Northwind Talent",
"website": "https://northwind.example"
};
const res = await fetch('https://api.creator-guard.com/v1/me', {
method: 'PATCH',
headers: {
Authorization: `Bearer ${process.env.CG_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(body),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(res.status, data);# pip install requests
import os
import uuid
import requests
body = {
"display_name": "Northwind Talent",
"website": "https://northwind.example",
}
res = requests.request(
"PATCH",
"https://api.creator-guard.com/v1/me",
headers={"Authorization": f"Bearer {os.environ['CG_API_KEY']}"},
json=body,
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']['code']}: {data['error']['message']}")
print(res.status_code, data)| Status | Meaning | Body |
|---|---|---|
| 200 | The account. | Account |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 412 |
| error |
| 413 |
| error |
| 415 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Agreements and your acceptances
/v1/agreementsScope account:read.
The current published version of every agreement type that applies to the account, with the account's acceptance.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | Agreements that apply to the account. | AgreementList |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Full text of one agreement version
/v1/agreements/{type}/{version}Scope account:read.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
type | path | string | required |
|
version | path | integer · ≥ 1 | required | |
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | One agreement version with its text. | AgreementDocument |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Accept the current version of an agreement
/v1/agreements/{type}/acceptScope agreements:write.
Only the current published version can be accepted (an older one → 409 invalid_state with
error.current_version). Records the key,
the caller's IP address and user agent. Works before the terms are accepted — it is how you accept them.
api_terms (the API Terms) and api_dpa (the
data protection addendum) belong to the account: accepted once,
with a live or a test key, they apply to both modes. Only keys of an owner or admin carry agreements:write.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
type | path | string | required |
|
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
Body application/json — AgreementAccept.
| Field | Type | Required | Description |
|---|---|---|---|
version | integer · ≥ 1 | required | Must be the current published version. |
Example: accept
curl -X POST https://api.creator-guard.com/v1/agreements/{type}/accept \
-H "Authorization: Bearer $CG_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"version": 2
}'// Node.js 20+ as an ES module (.mjs, or "type": "module"): built-in fetch + top-level await.
// Server-side only: the key must never reach a browser.
const body = {
"version": 2
};
const res = await fetch('https://api.creator-guard.com/v1/agreements/{type}/accept', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.CG_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(), // keep it and send it again when you retry
},
body: JSON.stringify(body),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(res.status, data);# pip install requests
import os
import uuid
import requests
body = {
"version": 2,
}
res = requests.request(
"POST",
"https://api.creator-guard.com/v1/agreements/{type}/accept",
headers={"Authorization": f"Bearer {os.environ['CG_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json=body,
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']['code']}: {data['error']['message']}")
print(res.status_code, data)| Status | Meaning | Body |
|---|---|---|
| 200 | The agreement with your acceptance. | Agreement |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 413 |
| error |
| 415 |
| error |
| 422 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
The portal's pick lists
/v1/option-listsScope account:read.
Values that match what agencies search for. Full lists: /reference/allowed-values/
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | The pick lists. | OptionLists |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Brokerage numbers
/v1/settingsScope account:read.
Offer deadline, undo window, payment due days, warranty days and the Creator Guard share of a fee.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | Brokerage numbers. | Settings |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Upload your logo
/v1/me/logoScope account:write.
multipart/form-data with one part file: PNG, JPEG or WebP, at most 2 MB. We re-encode it (at most 512 px
on the long edge, every metadata block removed) and replace the old logo. Counts against the upload limit of
the account (60 per minute, 3,000 per day, halved in test mode).
Body multipart/form-data — LogoUpload.
| Field | Type | Required | Description |
|---|---|---|---|
file | string (binary) | required | PNG, JPEG or WebP, at most 2 MB. |
| Status | Meaning | Body |
|---|---|---|
| 200 | The account. | Account |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 413 |
| error |
| 415 |
| error |
| 422 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Remove your logo
/v1/me/logoScope account:write.
Removes the file, then the logo. If the file cannot be removed, nothing changes and the answer is
502 upstream_failed — retry.
| Status | Meaning | Body |
|---|---|---|
| 200 | The account. | Account |
| 401 |
| error |
| 403 |
| error |
| 429 |
| error |
| 500 |
| error |
| 502 |
| error |
| 503 |
| error |
Leads
List your leads
/v1/leadsScope leads:read.
Newest first (created_at, then id). Filters combine with AND. Unknown parameters → 400 unknown_parameter; an invalid filter value → 400 invalid_field.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
limit | query | integer · 1–100 | optional | 1–100 items per page (default 25). |
starting_after | query | string | optional | Id of the last item of the previous page: the next page. |
ending_before | query | string | optional | Id of the first item of the current page: the page before. |
stage | query | string · one of draft, in_review, ready, offered, accepted, in_placement, placed, rejected, lost, withdrawn | optional | One stage (see the Lead schema). |
external_id | query | string · 1–200 chars | optional | Your own reference, exact match. |
creator_ref | query | string | optional | Creator number, |
instagram_handle | query | string · 1–200 chars | optional | Handle or profile link; compared after normalising. |
q | query | string · 1–200 chars | optional | Part of the creator name, case-insensitive. |
created_since | query | string (date-time) | optional | Leads created at or after this instant (RFC 3339, e.g. |
updated_since | query | string (date-time) | optional | Leads changed at or after this instant — for incremental sync. |
has_blockers | query | boolean | optional |
|
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | A page of leads. | LeadList |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Create a lead
/v1/leadsScope leads:write.
Creates a lead for one creator under your account, optionally with her listing. Only creator_name and
consent_confirmed are required (the portal's rule); send every other field you have. Without an
instagram_handle there is no duplicate check by handle: use external_id so a retry finds her again.
- 201 — a new lead was created.
- 200 — nothing new was created: you already used this
external_id(that lead is returned unchanged), or you already submitted this Instagram handle and that lead is still adraft(it is updated with the lead fields you sent; alistingin the body is applied likePATCH …/listing). - 409
duplicate_own_lead— your lead with this handle is pastdraft. Nothing changes;error.lead. - 409
duplicate_other_referrer— another account submitted this handle. Budgeted: 20 such answers per rolling 24 h, then429 duplicate_limit_reachedfor every request with aninstagram_handle.
Both answers carry consent. The 201 carries her personal consent link in consent.url (valid at least
30 days) — send it to her. Links are stored only as hashes, so the url is shown only there: a 200, a
GET and an Idempotency-Key replay answer url: null; POST /v1/leads/{id}/consent-link makes a new one.
Send an Idempotency-Key so a retry after a timeout returns the first answer.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
Body application/json — LeadCreate.
| Field | Type | Required | Description |
|---|---|---|---|
external_id | string or null · 1–100 chars | optional | Your own reference, unique within your account. Repeating it returns the existing lead ( |
creator_name | string · 1–120 chars | required | Name or alias. |
instagram_handle | string or null · 1–200 chars | optional | Username ( |
other_contact | string or null · 1–200 chars | optional | Any other way to reach her (Telegram, phone, …). |
platforms | array of string · at least 1, at most 20, each 1–40 chars | optional | Platforms she is on; pick-list values are stored in their spelling. Allowed values. Optional; when sent, at least one entry. |
follower_count | integer or null (int32) · 0–2,147,483,647 | optional | Followers on her largest platform. |
niche | string or null · 1–80 chars | optional | A pick-list niche is stored in its spelling. Allowed values. |
notes | string or null · 1–2000 chars | optional | For our team; never shown to agencies. |
consent_confirmed | true (exactly) | required | Your declaration that she agreed to be referred and to you sending these details. Must be exactly |
listing | ListingPatch | optional | Listing fields. Every field is optional; |
Example: Name, contact and platforms
curl -X POST https://api.creator-guard.com/v1/leads \
-H "Authorization: Bearer $CG_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"creator_name": "Mia",
"instagram_handle": "@miacreates",
"platforms": ["OnlyFans", "Instagram"],
"consent_confirmed": true
}'// Node.js 20+ as an ES module (.mjs, or "type": "module"): built-in fetch + top-level await.
// Server-side only: the key must never reach a browser.
const body = {
"creator_name": "Mia",
"instagram_handle": "@miacreates",
"platforms": ["OnlyFans", "Instagram"],
"consent_confirmed": true
};
const res = await fetch('https://api.creator-guard.com/v1/leads', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.CG_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(), // keep it and send it again when you retry
},
body: JSON.stringify(body),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(res.status, data);# pip install requests
import os
import uuid
import requests
body = {
"creator_name": "Mia",
"instagram_handle": "@miacreates",
"platforms": ["OnlyFans", "Instagram"],
"consent_confirmed": True,
}
res = requests.request(
"POST",
"https://api.creator-guard.com/v1/leads",
headers={"Authorization": f"Bearer {os.environ['CG_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json=body,
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']['code']}: {data['error']['message']}")
print(res.status_code, data)Example: Only the required fields
curl -X POST https://api.creator-guard.com/v1/leads \
-H "Authorization: Bearer $CG_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"creator_name": "Mia",
"consent_confirmed": true
}'// Node.js 20+ as an ES module (.mjs, or "type": "module"): built-in fetch + top-level await.
// Server-side only: the key must never reach a browser.
const body = {
"creator_name": "Mia",
"consent_confirmed": true
};
const res = await fetch('https://api.creator-guard.com/v1/leads', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.CG_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(), // keep it and send it again when you retry
},
body: JSON.stringify(body),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(res.status, data);# pip install requests
import os
import uuid
import requests
body = {
"creator_name": "Mia",
"consent_confirmed": True,
}
res = requests.request(
"POST",
"https://api.creator-guard.com/v1/leads",
headers={"Authorization": f"Bearer {os.environ['CG_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json=body,
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']['code']}: {data['error']['message']}")
print(res.status_code, data)Example: Lead and listing in one request
curl -X POST https://api.creator-guard.com/v1/leads \
-H "Authorization: Bearer $CG_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"external_id": "crm-000042",
"creator_name": "Mia",
"instagram_handle": "https://www.instagram.com/miacreates/",
"other_contact": "Telegram: @mia_tg",
"platforms": ["OnlyFans", "Instagram", "TikTok"],
"follower_count": 42000,
"niche": "Fitness",
"notes": "Replies fast, wants to start within a month.",
"consent_confirmed": true,
"listing": {
"age": 24,
"origin_country": "Germany",
"languages": ["German", "English"],
"content_types": ["Livestreams"]
}
}'// Node.js 20+ as an ES module (.mjs, or "type": "module"): built-in fetch + top-level await.
// Server-side only: the key must never reach a browser.
const body = {
"external_id": "crm-000042",
"creator_name": "Mia",
"instagram_handle": "https://www.instagram.com/miacreates/",
"other_contact": "Telegram: @mia_tg",
"platforms": ["OnlyFans", "Instagram", "TikTok"],
"follower_count": 42000,
"niche": "Fitness",
"notes": "Replies fast, wants to start within a month.",
"consent_confirmed": true,
"listing": {
"age": 24,
"origin_country": "Germany",
"languages": ["German", "English"],
"content_types": ["Livestreams"]
}
};
const res = await fetch('https://api.creator-guard.com/v1/leads', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.CG_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(), // keep it and send it again when you retry
},
body: JSON.stringify(body),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(res.status, data);# pip install requests
import os
import uuid
import requests
body = {
"external_id": "crm-000042",
"creator_name": "Mia",
"instagram_handle": "https://www.instagram.com/miacreates/",
"other_contact": "Telegram: @mia_tg",
"platforms": ["OnlyFans", "Instagram", "TikTok"],
"follower_count": 42000,
"niche": "Fitness",
"notes": "Replies fast, wants to start within a month.",
"consent_confirmed": True,
"listing": {
"age": 24,
"origin_country": "Germany",
"languages": ["German", "English"],
"content_types": ["Livestreams"],
},
}
res = requests.request(
"POST",
"https://api.creator-guard.com/v1/leads",
headers={"Authorization": f"Bearer {os.environ['CG_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json=body,
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']['code']}: {data['error']['message']}")
print(res.status_code, data)| Status | Meaning | Body |
|---|---|---|
| 200 | Already known: your | Lead |
| 201 | A new lead was created; | Lead |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 409 |
| error |
| 413 |
| error |
| 415 |
| error |
| 422 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Get a lead
/v1/leads/{id}Scope leads:read.
With ?expand=listing,photos,confirmations (any combination) the lead carries those objects too. Any other query parameter → 400 unknown_parameter, another expand value → 400 invalid_field. consent shows her consent link as it is; reading never extends it.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Lead id ( |
expand | query | string | optional | Comma-separated: |
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | The lead, with her consent link ( | Lead |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Change lead fields
/v1/leads/{id}Scope leads:write.
Lead fields only while the lead is a draft (next_actions.can_edit_lead), else 409 lead_locked.
external_id can be changed at any stage (unique within your account, else 409 external_id_taken).
Both instagram_handle and other_contact may be cleared (null), as in the portal. A new instagram_handle
that another account already submitted → 409 duplicate_other_referrer (counts against the same daily
budget as on create, then 429 duplicate_limit_reached).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Lead id ( |
If-Match | header | string | optional | The |
Body application/json — LeadUpdate.
| Field | Type | Required | Description |
|---|---|---|---|
external_id | string or null · 1–100 chars | optional | |
creator_name | string · 1–120 chars | optional | |
instagram_handle | string or null · 1–200 chars | optional | |
other_contact | string or null · 1–200 chars | optional | |
platforms | array of string · at least 1, at most 20, each 1–40 chars | optional | |
follower_count | integer or null (int32) · 0–2,147,483,647 | optional | |
niche | string or null · 1–80 chars | optional | |
notes | string or null · 1–2000 chars | optional |
Example: rename
curl -X PATCH https://api.creator-guard.com/v1/leads/{id} \
-H "Authorization: Bearer $CG_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"creator_name": "Mia R."
}'// Node.js 20+ as an ES module (.mjs, or "type": "module"): built-in fetch + top-level await.
// Server-side only: the key must never reach a browser.
const body = {
"creator_name": "Mia R."
};
const res = await fetch('https://api.creator-guard.com/v1/leads/{id}', {
method: 'PATCH',
headers: {
Authorization: `Bearer ${process.env.CG_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(body),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(res.status, data);# pip install requests
import os
import uuid
import requests
body = {
"creator_name": "Mia R.",
}
res = requests.request(
"PATCH",
"https://api.creator-guard.com/v1/leads/{id}",
headers={"Authorization": f"Bearer {os.environ['CG_API_KEY']}"},
json=body,
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']['code']}: {data['error']['message']}")
print(res.status_code, data)| Status | Meaning | Body |
|---|---|---|
| 200 | The lead. | Lead |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 412 |
| error |
| 413 |
| error |
| 415 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Withdraw a lead
/v1/leads/{id}/withdrawScope leads:write.
Allowed while next_actions.can_withdraw (draft or in_review, no live offer); else 409 invalid_state. No body.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Lead id ( |
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
| Status | Meaning | Body |
|---|---|---|
| 200 | The lead. | Lead |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 422 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Suggest lead fields from text
/v1/extractScope extract.
Paste a profile text, a chat or notes (20–20,000 characters); the answer suggests lead and listing fields for
you to review. Nothing is stored — not the text, not the suggestions — so an Idempotency-Key is ignored and
a retry simply runs again. Limits: 20 per minute and 200 per day per account (halved in test mode). With a
cg_test_ key the answer is a fixed fictitious example and no AI runs. Works before the terms are accepted.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | optional | Ignored on this endpoint: nothing is stored, a retry runs again. |
Body application/json — ExtractRequest.
| Field | Type | Required | Description |
|---|---|---|---|
text | string · 20–20000 chars | required | Any text about her: profile, chat, notes (at least 20 characters after trimming). Not stored. |
Example: bio
curl -X POST https://api.creator-guard.com/v1/extract \
-H "Authorization: Bearer $CG_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"text": "Mia, 24, from Berlin. Speaks German and English. 42k followers on Instagram, also on TikTok."
}'// Node.js 20+ as an ES module (.mjs, or "type": "module"): built-in fetch + top-level await.
// Server-side only: the key must never reach a browser.
const body = {
"text": "Mia, 24, from Berlin. Speaks German and English. 42k followers on Instagram, also on TikTok."
};
const res = await fetch('https://api.creator-guard.com/v1/extract', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.CG_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(), // keep it and send it again when you retry
},
body: JSON.stringify(body),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(res.status, data);# pip install requests
import os
import uuid
import requests
body = {
"text": "Mia, 24, from Berlin. Speaks German and English. 42k followers on Instagram, also on TikTok.",
}
res = requests.request(
"POST",
"https://api.creator-guard.com/v1/extract",
headers={"Authorization": f"Bearer {os.environ['CG_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json=body,
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']['code']}: {data['error']['message']}")
print(res.status_code, data)| Status | Meaning | Body |
|---|---|---|
| 200 | Suggested fields; nothing was stored. | ExtractResult |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 413 |
| error |
| 415 |
| error |
| 429 |
| error |
| 500 |
| error |
| 502 |
| error |
| 503 |
| error |
Listing
Get the listing of a lead
/v1/leads/{id}/listingScope leads:read.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Lead id ( |
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | The listing. | Listing |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Change listing fields
/v1/leads/{id}/listingScope leads:write.
While the listing is not live (next_actions.can_edit_listing), else 409 listing_locked.
placement_fee only while next_actions.can_edit_fee. Send null to clear a value, [] to empty a list.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Lead id ( |
If-Match | header | string | optional | The |
Body application/json — ListingPatch.
| Field | Type | Required | Description |
|---|---|---|---|
age | integer or null · 18–99 | optional | Below 18 → |
gender | string or null · one of female, male, trans, non_binary, other | optional | |
origin_country | string or null · 1–80 chars | optional | |
languages | array of string · at most 20, each 1–40 chars | optional | |
english_level | integer or null · 1–10 | optional | |
content_types | array of string · at most 30, each 1–40 chars | optional | Content categories she is comfortable with. Values: allowed values. |
content_freetext | string or null · 1–2000 chars | optional | |
has_of_account | boolean or null | optional | |
of_verified | boolean or null | optional | |
of_current_earnings | integer or null · 0–2,147,483,647 | optional | USD per month. |
content_ready | boolean or null | optional | |
scripts_ready | boolean or null | optional | |
account_access | string or null · one of yes, no, undiscussed | optional | |
device | string or null · 1–200 chars | optional | |
social_status | string or null · one of none, ready_to_create, existing | optional | |
social_preferences | object | optional | Platform (1–40 characters) → wants to be active there; at most 20 entries. |
tiktok_ok | boolean or null | optional | |
blocked_countries | array of string · at most 250, each 1–80 chars | optional | |
start_availability | string or null · one of now, date | optional | |
start_date | string or null (date) | optional | |
availability_hours_per_week | number or null · 0–168 | optional | |
availability_hours_per_day | number or null · 0–24 | optional | |
compensation_model | string or null · one of revenue_share, fixed | optional | |
creator_share_percent | integer or null · 0–100 | optional | |
fixed_salary | integer or null · 0–2,147,483,647 | optional | |
salary_period | string or null · one of weekly, monthly | optional | |
placement_fee | MoneyInput | optional |
|
notes_public | string or null · 1–2000 chars | optional | Shown to agencies with the listing. |
Example: Age, origin, languages and fee
curl -X PATCH https://api.creator-guard.com/v1/leads/{id}/listing \
-H "Authorization: Bearer $CG_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"age": 24,
"origin_country": "Germany",
"languages": ["German", "English"],
"placement_fee": {
"amount_minor": 150000,
"currency": "USD"
}
}'// Node.js 20+ as an ES module (.mjs, or "type": "module"): built-in fetch + top-level await.
// Server-side only: the key must never reach a browser.
const body = {
"age": 24,
"origin_country": "Germany",
"languages": ["German", "English"],
"placement_fee": {
"amount_minor": 150000,
"currency": "USD"
}
};
const res = await fetch('https://api.creator-guard.com/v1/leads/{id}/listing', {
method: 'PATCH',
headers: {
Authorization: `Bearer ${process.env.CG_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(body),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(res.status, data);# pip install requests
import os
import uuid
import requests
body = {
"age": 24,
"origin_country": "Germany",
"languages": ["German", "English"],
"placement_fee": {
"amount_minor": 150000,
"currency": "USD",
},
}
res = requests.request(
"PATCH",
"https://api.creator-guard.com/v1/leads/{id}/listing",
headers={"Authorization": f"Bearer {os.environ['CG_API_KEY']}"},
json=body,
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']['code']}: {data['error']['message']}")
print(res.status_code, data)| Status | Meaning | Body |
|---|---|---|
| 200 | The listing. | Listing |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 412 |
| error |
| 413 |
| error |
| 415 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Submit a draft for review
/v1/leads/{id}/submit-for-reviewScope leads:write.
Draft → in review (next_actions.can_submit_for_review). Remaining blockers → 422 not_ready_for_review
with error.blockers, fee_missing included: set placement_fee before you submit her.
Not a draft → 409 invalid_state. No body.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Lead id ( |
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
| Status | Meaning | Body |
|---|---|---|
| 200 | The lead. | Lead |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 422 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Her consent, 18+ confirmation and login state
/v1/leads/{id}/confirmationsScope leads:read.
Status and dates only — never her IP address or browser.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Lead id ( |
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | Her confirmations. | Confirmations |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Her personal consent link
/v1/leads/{id}/consent-linkScope leads:write.
Returns the hosted page where she confirms consent and 18+ herself: a NEW link, valid at least 30 days from
now. Links are stored only as hashes, so each call makes a new one; the previous link of the lead can then only
be used to withdraw consent (never to give it). An Idempotency-Key replay answers url: null. Send the link to her; never confirm for her.
After her data was erased on her request → 409 invalid_state with error.current_state anonymized. No body.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Lead id ( |
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
| Status | Meaning | Body |
|---|---|---|
| 200 | Her consent link. | ConsentLink |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 422 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Her claim link (her own login)
/v1/leads/{id}/claim-linkScope leads:write.
A single-use link to the hosted page where she chooses her own email and password for the creator portal.
It works once and for 7 days; a new link makes every earlier unused link of the lead invalid. The URL is
shown only in this answer: an Idempotency-Key replay returns the same object with url: null (call again
without the key for a new link). A cg_test_ key gets a …/claim/test_… URL that opens a notice only.
409 invalid_state with error.current_state claimed (she already has a login), withdrawn or
rejected. No body.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Lead id ( |
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
| Status | Meaning | Body |
|---|---|---|
| 201 | Her claim link (shown once). | ClaimLink |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 422 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Milestones of a lead
/v1/leads/{id}/timelineScope leads:read.
Submitted, review requested, approved, offers, acceptance, payment, warranty, completion, commission. No agency names.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Lead id ( |
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | The milestones. | Timeline |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Your earnings from a lead
/v1/leads/{id}/earningsScope earnings:read.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Lead id ( |
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | Your earnings. | Earnings |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Photos
List her photos
/v1/leads/{id}/photosScope leads:read.
Primary photo first, then oldest first; every photo on one page. Each url is signed and works for one hour.
No query parameters besides fields.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Lead id ( |
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | Her photos, primary first. | PhotoList |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Upload a photo
/v1/leads/{id}/photosScope photos:write.
multipart/form-data: file (JPEG, PNG or WebP, at most 40 MB and 50 megapixels), optionally kind (default
portrait) and is_primary. We read the format from the bytes, bake in the orientation, scale to at most
3000 px on the long edge and remove every metadata block (EXIF, GPS, XMP, IPTC) before anything is
stored; your original bytes are never kept, nor the file name. At most 20 photos per lead (409 limit_reached); only while the listing is not live (409 photos_locked). Counts against the upload limit
(60 per minute, 3,000 per day, halved in test mode). A replay of the same Idempotency-Key answers url: null.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Lead id ( |
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
Body multipart/form-data — PhotoUpload.
| Field | Type | Required | Description |
|---|---|---|---|
file | string (binary) | required | JPEG, PNG or WebP; at most 40 MB and 50 megapixels. Exactly one file part. |
kind | string · one of portrait, body, content_sample, non_nude, lingerie, professional | optional | Default |
is_primary | string · one of true, false | optional |
|
| Status | Meaning | Body |
|---|---|---|
| 201 | The photo was stored (re-encoded, metadata removed). A replay of the same | Photo |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 413 |
| error |
| 415 |
| error |
| 422 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Change kind or make primary
/v1/leads/{id}/photos/{photo}Scope photos:write.
kind, or is_primary: true (the previous primary photo stops being primary). Only while the listing is not
live (409 photos_locked).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Lead id ( |
photo | path | string | required | Photo id ( |
If-Match | header | string | optional | The |
Body application/json — PhotoPatch.
| Field | Type | Required | Description |
|---|---|---|---|
kind | string · one of portrait, body, content_sample, non_nude, lingerie, professional | optional | |
is_primary | true (exactly) | optional | Makes this her primary photo. Only |
Example: primary
curl -X PATCH https://api.creator-guard.com/v1/leads/{id}/photos/{photo} \
-H "Authorization: Bearer $CG_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"is_primary": true
}'// Node.js 20+ as an ES module (.mjs, or "type": "module"): built-in fetch + top-level await.
// Server-side only: the key must never reach a browser.
const body = {
"is_primary": true
};
const res = await fetch('https://api.creator-guard.com/v1/leads/{id}/photos/{photo}', {
method: 'PATCH',
headers: {
Authorization: `Bearer ${process.env.CG_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(body),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(res.status, data);# pip install requests
import os
import uuid
import requests
body = {
"is_primary": True,
}
res = requests.request(
"PATCH",
"https://api.creator-guard.com/v1/leads/{id}/photos/{photo}",
headers={"Authorization": f"Bearer {os.environ['CG_API_KEY']}"},
json=body,
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']['code']}: {data['error']['message']}")
print(res.status_code, data)| Status | Meaning | Body |
|---|---|---|
| 200 | The photo. | Photo |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 412 |
| error |
| 413 |
| error |
| 415 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Delete a photo
/v1/leads/{id}/photos/{photo}Scope photos:write.
Removes the file, then the photo. If it was her primary photo, the oldest remaining one becomes primary. Only
while the listing is not live (409 photos_locked). If the file cannot be removed, nothing changes and the
answer is 502 upstream_failed — retry.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Lead id ( |
photo | path | string | required | Photo id ( |
| Status | Meaning | Body |
|---|---|---|
| 204 | Deleted. The answer has no body. | — |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 429 |
| error |
| 500 |
| error |
| 502 |
| error |
| 503 |
| error |
Earnings
List your commissions
/v1/commissionsScope earnings:read.
Newest first. A commission is booked for your lead when her placement completes.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
limit | query | integer · 1–100 | optional | 1–100 items per page (default 25). |
starting_after | query | string | optional | Id of the last item of the previous page: the next page. |
ending_before | query | string | optional | Id of the first item of the current page: the page before. |
status | query | string · one of due, paid, void | optional | Only this status. |
created_since | query | string (date-time) | optional | Booked at or after this instant (RFC 3339). |
lead | query | string | optional | Only the commissions of this lead ( |
expand | query | string | optional |
|
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | A page of commissions. | CommissionList |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Get a commission
/v1/commissions/{id}Scope earnings:read.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Commission id ( |
expand | query | string | optional |
|
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | The commission. | Commission |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Your payout details (masked)
/v1/payout-detailsScope earnings:read.
Method and a masked destination, never the full account data. Change them in the portal (Settings → Payout, needs your second factor); the API cannot.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | Your payout details, masked. | PayoutDetails |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Keys
List the keys of this mode
/v1/api-keysScope keys:manage.
Active keys of the calling key's mode (live or test), then the ones revoked in the last 90 days, on one
page. Never a secret. No query parameters besides fields.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | The keys of this mode. | ApiKeyList |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Create a key
/v1/api-keysScope keys:manage.
The new key has the calling key's mode and at most its scopes (more → 403 insufficient_scope). So
keys:manage and webhooks:manage reach a key made here only through a key that already has them, and
those come from the portal with a second factor. The secret is in this answer only — store it now; a replay
of the same Idempotency-Key answers secret: null. At most 10 active keys per mode (409 limit_reached);
your key policy may cap expires_at. The new key inherits the calling key's restrictions: without
ip_allowlist it gets the caller's; an ip_allowlist outside the caller's is 400 invalid_field; it expires
no later than the caller. A rolled key in its grace period cannot call this (403 insufficient_scope).
A new live key needs the API Terms and the data protection addendum
(403 terms_not_accepted with agreement_type: "api_terms" or "api_dpa"); a test key does not.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
Body application/json — ApiKeyCreate.
| Field | Type | Required | Description |
|---|---|---|---|
label | string or null · 0–100 chars | optional | Trimmed; empty = no label. |
scopes | array of Scope · at least 1 | required | Only scopes the calling key has (else |
ip_allowlist | array of string · at most 20 | optional | CIDR blocks with the host bits zero, e.g. |
expires_at | string or null (date-time) | optional | In the future; capped by your key policy's maximum age. |
Example: crm
curl -X POST https://api.creator-guard.com/v1/api-keys \
-H "Authorization: Bearer $CG_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"label": "CRM production",
"scopes": ["leads:read", "leads:write"],
"ip_allowlist": ["203.0.113.0/24"]
}'// Node.js 20+ as an ES module (.mjs, or "type": "module"): built-in fetch + top-level await.
// Server-side only: the key must never reach a browser.
const body = {
"label": "CRM production",
"scopes": ["leads:read", "leads:write"],
"ip_allowlist": ["203.0.113.0/24"]
};
const res = await fetch('https://api.creator-guard.com/v1/api-keys', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.CG_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(), // keep it and send it again when you retry
},
body: JSON.stringify(body),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(res.status, data);# pip install requests
import os
import uuid
import requests
body = {
"label": "CRM production",
"scopes": ["leads:read", "leads:write"],
"ip_allowlist": ["203.0.113.0/24"],
}
res = requests.request(
"POST",
"https://api.creator-guard.com/v1/api-keys",
headers={"Authorization": f"Bearer {os.environ['CG_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json=body,
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']['code']}: {data['error']['message']}")
print(res.status_code, data)| Status | Meaning | Body |
|---|---|---|
| 201 | The key with its new secret — shown this once. A replay of the same | ApiKey |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 409 |
| error |
| 413 |
| error |
| 415 |
| error |
| 422 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Revoke a key
/v1/api-keys/{id}Scope keys:manage.
Effective on the next request; repeating it is harmless. Only for keys whose scopes the calling key holds
(else 403 insufficient_scope naming the first missing one). The calling key itself only with ?force=true
(else 409 invalid_state with current_state: in_use). Answers the revoked key.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Key id ( |
force | query | boolean | optional |
|
| Status | Meaning | Body |
|---|---|---|
| 200 | The key (no secret). | ApiKey |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Roll a key
/v1/api-keys/{id}/rollScope keys:manage.
A new key with the same label, scopes, IP allowlist and expiry; the old one keeps working for grace_hours
(0–72, default 24; 0 revokes it now). Only for keys whose scopes the calling key holds. The new key also
takes on the calling key's restrictions: IP allowlist = the overlap of the old key's and the caller's (none at
all → 409 invalid_state with current_state: ip_allowlist_outside_caller), expiry no later than the
caller's. The new secret is in this answer only; a replay of the same Idempotency-Key answers
secret: null. Rolling a live key needs the API Terms and the data protection
addendum (403 terms_not_accepted with agreement_type: "api_terms" or "api_dpa"); revoking never does.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Key id ( |
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
Body application/json — ApiKeyRoll.
| Field | Type | Required | Description |
|---|---|---|---|
grace_hours | integer or null · 0–72 | optional | How long the old key keeps working (default 24; |
Example: day
curl -X POST https://api.creator-guard.com/v1/api-keys/{id}/roll \
-H "Authorization: Bearer $CG_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"grace_hours": 24
}'// Node.js 20+ as an ES module (.mjs, or "type": "module"): built-in fetch + top-level await.
// Server-side only: the key must never reach a browser.
const body = {
"grace_hours": 24
};
const res = await fetch('https://api.creator-guard.com/v1/api-keys/{id}/roll', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.CG_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(), // keep it and send it again when you retry
},
body: JSON.stringify(body),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(res.status, data);# pip install requests
import os
import uuid
import requests
body = {
"grace_hours": 24,
}
res = requests.request(
"POST",
"https://api.creator-guard.com/v1/api-keys/{id}/roll",
headers={"Authorization": f"Bearer {os.environ['CG_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json=body,
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']['code']}: {data['error']['message']}")
print(res.status_code, data)| Status | Meaning | Body |
|---|---|---|
| 200 | The key with its new secret — shown this once. A replay of the same | ApiKey |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 413 |
| error |
| 415 |
| error |
| 422 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Events
List events
/v1/eventsAny API key; what you see depends on its scopes (see below).
The last 30 days of this mode, newest first. Any key works; you only see events whose object the key may read
(leads:read for lead, photo and confirmation events, earnings:read for commissions, … — see
Events).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
limit | query | integer · 1–100 | optional | 1–100 items per page (default 25). |
starting_after | query | string | optional | Id of the last item of the previous page: the next page. |
ending_before | query | string | optional | Id of the first item of the current page: the page before. |
type | query | string | optional | Exact type ( |
created_after | query | string (date-time) | optional | RFC 3339 timestamp; only events after it. |
object | query | string | optional | Events about one object: the id of a lead, photo, commission, API key or webhook endpoint (confirmation events carry the lead id). |
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | A page of events. | EventList |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Get an event
/v1/events/{id}Any API key; what you see depends on its scopes (see below).
404 not_found for an unknown id, another account's event or one older than 30 days; 403 insufficient_scope
(with error.scope) when the key lacks the scope that reads the event's object.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Event id ( |
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | The event. | Event |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Webhooks
List webhook endpoints
/v1/webhook-endpointsScope webhooks:manage.
The endpoints of this mode (at most 10, one page). Secrets are never listed.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | The endpoints of this mode. | WebhookEndpointList |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Create a webhook endpoint
/v1/webhook-endpointsScope webhooks:manage.
https only, port 443, a host that resolves to public addresses only; checked now and again before every
delivery (a failed DNS lookup now → 502 upstream_failed). At most 10 endpoints per mode
(409 limit_reached). Every event type must be readable with this key's scopes (else
403 insufficient_scope naming the scope); ["*"] means every type this key can read, and the endpoint
never carries more. The signing secret is in this answer only; a replay of the same Idempotency-Key
answers secret: null.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
Body application/json — WebhookEndpointCreate.
| Field | Type | Required | Description |
|---|---|---|---|
url | string · 0–2048 chars | required | https on port 443, no credentials, a host that resolves to public addresses only. |
event_types | array of string · at least 1, at most 32 | required |
|
description | string or null · 0–500 chars | optional |
Example: crm
curl -X POST https://api.creator-guard.com/v1/webhook-endpoints \
-H "Authorization: Bearer $CG_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"url": "https://hooks.example.com/creator-guard",
"event_types": ["lead.stage_changed", "commission.paid"],
"description": "CRM sync"
}'// Node.js 20+ as an ES module (.mjs, or "type": "module"): built-in fetch + top-level await.
// Server-side only: the key must never reach a browser.
const body = {
"url": "https://hooks.example.com/creator-guard",
"event_types": ["lead.stage_changed", "commission.paid"],
"description": "CRM sync"
};
const res = await fetch('https://api.creator-guard.com/v1/webhook-endpoints', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.CG_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(), // keep it and send it again when you retry
},
body: JSON.stringify(body),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(res.status, data);# pip install requests
import os
import uuid
import requests
body = {
"url": "https://hooks.example.com/creator-guard",
"event_types": ["lead.stage_changed", "commission.paid"],
"description": "CRM sync",
}
res = requests.request(
"POST",
"https://api.creator-guard.com/v1/webhook-endpoints",
headers={"Authorization": f"Bearer {os.environ['CG_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json=body,
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']['code']}: {data['error']['message']}")
print(res.status_code, data)| Status | Meaning | Body |
|---|---|---|
| 201 | The endpoint with its new signing secret — shown this once. A replay of the same | WebhookEndpoint |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 409 |
| error |
| 413 |
| error |
| 415 |
| error |
| 422 |
| error |
| 429 |
| error |
| 500 |
| error |
| 502 |
| error |
| 503 |
| error |
Get a webhook endpoint
/v1/webhook-endpoints/{id}Scope webhooks:manage.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Webhook endpoint id ( |
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | The endpoint (no secret). | WebhookEndpoint |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Change a webhook endpoint
/v1/webhook-endpoints/{id}Scope webhooks:manage.
URL, event types, description, or enabled (re-enabling an endpoint disabled for failing starts its failure
clock afresh). A new URL is checked like on create. New event types must be readable with this key's scopes
(403 insufficient_scope); after a new URL or new event types the endpoint carries only what this key can
read, and waiting deliveries it may no longer carry end failed (scope_removed).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Webhook endpoint id ( |
If-Match | header | string | optional | The |
Body application/json — WebhookEndpointUpdate.
| Field | Type | Required | Description |
|---|---|---|---|
url | string · 0–2048 chars | optional | |
event_types | array of string · at least 1, at most 32 | optional | |
description | string or null · 0–500 chars | optional | |
enabled | boolean | optional |
Example: disable
curl -X PATCH https://api.creator-guard.com/v1/webhook-endpoints/{id} \
-H "Authorization: Bearer $CG_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"enabled": false
}'// Node.js 20+ as an ES module (.mjs, or "type": "module"): built-in fetch + top-level await.
// Server-side only: the key must never reach a browser.
const body = {
"enabled": false
};
const res = await fetch('https://api.creator-guard.com/v1/webhook-endpoints/{id}', {
method: 'PATCH',
headers: {
Authorization: `Bearer ${process.env.CG_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(body),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(res.status, data);# pip install requests
import os
import uuid
import requests
body = {
"enabled": False,
}
res = requests.request(
"PATCH",
"https://api.creator-guard.com/v1/webhook-endpoints/{id}",
headers={"Authorization": f"Bearer {os.environ['CG_API_KEY']}"},
json=body,
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']['code']}: {data['error']['message']}")
print(res.status_code, data)| Status | Meaning | Body |
|---|---|---|
| 200 | The endpoint (no secret). | WebhookEndpoint |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 412 |
| error |
| 413 |
| error |
| 415 |
| error |
| 429 |
| error |
| 500 |
| error |
| 502 |
| error |
| 503 |
| error |
Delete a webhook endpoint
/v1/webhook-endpoints/{id}Scope webhooks:manage.
The endpoint and its deliveries are removed; pending deliveries to it are dropped.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Webhook endpoint id ( |
| Status | Meaning | Body |
|---|---|---|
| 204 | Deleted. The answer has no body. | — |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Roll the signing secret
/v1/webhook-endpoints/{id}/rollScope webhooks:manage.
A new signing secret, in this answer only (a replay of the same Idempotency-Key answers secret: null).
For 24 hours every delivery is signed with both (two v1= values in CG-Signature). Only the newest two
secrets sign: a second roll within the 24 hours retires the oldest at once.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Webhook endpoint id ( |
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
| Status | Meaning | Body |
|---|---|---|
| 200 | The endpoint with its new signing secret — shown this once. A replay of the same | WebhookEndpoint |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 422 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Send a test event
/v1/webhook-endpoints/{id}/testScope webhooks:manage.
Queues a ping event for this endpoint only and answers its delivery (202); it is delivered and retried
like every other event. Follow it in the deliveries list.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Webhook endpoint id ( |
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
| Status | Meaning | Body |
|---|---|---|
| 202 | The delivery, queued. | WebhookDelivery |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 422 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Re-send events of a time range
/v1/webhook-endpoints/{id}/replayScope webhooks:manage.
Queues every event of the range that the endpoint subscribes to and may carry again (at most 30 days back).
The endpoint holds at most 1,000 open deliveries afterwards; a range that does not fit is refused whole with
409 limit_reached (limit: 1000), nothing queued. Deliveries are spread 250 ms apart and carry
replay: true; receivers drop what they already have by sequence. At most 10 replays per account and day
(test mode: 5) → 429 rate_limited.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Webhook endpoint id ( |
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
Body application/json — WebhookReplay.
| Field | Type | Required | Description |
|---|---|---|---|
from | string (date-time) | required | At most 30 days ago. |
to | string or null (date-time) | optional | After |
Example: hour
curl -X POST https://api.creator-guard.com/v1/webhook-endpoints/{id}/replay \
-H "Authorization: Bearer $CG_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"from": "2026-10-09T08:00:00Z",
"to": "2026-10-09T09:00:00Z"
}'// Node.js 20+ as an ES module (.mjs, or "type": "module"): built-in fetch + top-level await.
// Server-side only: the key must never reach a browser.
const body = {
"from": "2026-10-09T08:00:00Z",
"to": "2026-10-09T09:00:00Z"
};
const res = await fetch('https://api.creator-guard.com/v1/webhook-endpoints/{id}/replay', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.CG_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(), // keep it and send it again when you retry
},
body: JSON.stringify(body),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(res.status, data);# pip install requests
import os
import uuid
import requests
body = {
"from": "2026-10-09T08:00:00Z",
"to": "2026-10-09T09:00:00Z",
}
res = requests.request(
"POST",
"https://api.creator-guard.com/v1/webhook-endpoints/{id}/replay",
headers={"Authorization": f"Bearer {os.environ['CG_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json=body,
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']['code']}: {data['error']['message']}")
print(res.status_code, data)| Status | Meaning | Body |
|---|---|---|
| 202 | How many deliveries were queued. | ReplayResult |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 413 |
| error |
| 415 |
| error |
| 422 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Deliveries to an endpoint
/v1/webhook-endpoints/{id}/deliveriesScope webhooks:manage.
Newest first, 30 days, each with every attempt (status code, duration, error). Pages forward only:
starting_after, no ending_before.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Webhook endpoint id ( |
limit | query | integer · 1–100 | optional | 1–100 items per page (default 25). |
starting_after | query | string | optional | Id of the last item of the previous page: the next page. |
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | A page of deliveries. | WebhookDeliveryList |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Retry a delivery now
/v1/webhook-endpoints/{id}/deliveries/{d}/retryScope webhooks:manage.
Also for a delivery that has already failed: it is due again now (202), its attempt count is kept.
A delivery of an event the endpoint may no longer carry (its object type left the endpoint's scope) is
refused with 409 invalid_state (current_state: scope_removed).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Webhook endpoint id ( |
d | path | string | required | Delivery id ( |
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
| Status | Meaning | Body |
|---|---|---|
| 202 | The delivery, queued. | WebhookDelivery |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 422 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
OAuth apps
List OAuth apps
/v1/oauth-appsScope oauth_apps:manage.
The OAuth apps of this mode (at most 10, one page). Client secrets are never listed. No query parameters
besides fields.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | The OAuth apps of this mode. | OAuthAppList |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Register an OAuth app
/v1/oauth-appsScope oauth_apps:manage.
An app that creators sign in to with Creator Guard (OAuth 2.1, authorization code with PKCE). Redirect URIs
are matched exactly; https only, no private or loopback hosts (http://localhost and 127.0.0.1 with a
port only for apps of test keys). A confidential app gets a client_secret, in this answer only — a replay
of the same Idempotency-Key answers client_secret: null. At most 10 apps per mode
(409 invalid_state with current_state: app_limit_reached). Registering a live app needs the
API Terms and the data protection addendum (403 terms_not_accepted with
agreement_type: "api_terms" or "api_dpa").
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
Body application/json — OAuthAppCreate.
| Field | Type | Required | Description |
|---|---|---|---|
name | string · 3–60 chars | required | Trimmed. |
redirect_uris | array of string · at least 1, at most 10, each 0–2000 chars | required | Distinct; https, no fragment, no user info, no wildcard, no private or loopback host. Test keys may also use |
logo_url | string or null · 0–2000 chars | optional | |
privacy_url | string · 0–2000 chars | required | Your privacy policy, linked on the consent screen. |
scopes | array of CreatorScope · at least 1 | required | Distinct. |
confidential | boolean | required |
Example: dashboard
curl -X POST https://api.creator-guard.com/v1/oauth-apps \
-H "Authorization: Bearer $CG_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"name": "Agency Dash",
"redirect_uris": ["https://dash.agency.example/oauth/callback"],
"privacy_url": "https://agency.example/privacy",
"scopes": ["creator.profile:read"],
"confidential": true
}'// Node.js 20+ as an ES module (.mjs, or "type": "module"): built-in fetch + top-level await.
// Server-side only: the key must never reach a browser.
const body = {
"name": "Agency Dash",
"redirect_uris": ["https://dash.agency.example/oauth/callback"],
"privacy_url": "https://agency.example/privacy",
"scopes": ["creator.profile:read"],
"confidential": true
};
const res = await fetch('https://api.creator-guard.com/v1/oauth-apps', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.CG_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(), // keep it and send it again when you retry
},
body: JSON.stringify(body),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(res.status, data);# pip install requests
import os
import uuid
import requests
body = {
"name": "Agency Dash",
"redirect_uris": ["https://dash.agency.example/oauth/callback"],
"privacy_url": "https://agency.example/privacy",
"scopes": ["creator.profile:read"],
"confidential": True,
}
res = requests.request(
"POST",
"https://api.creator-guard.com/v1/oauth-apps",
headers={"Authorization": f"Bearer {os.environ['CG_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json=body,
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']['code']}: {data['error']['message']}")
print(res.status_code, data)| Status | Meaning | Body |
|---|---|---|
| 201 | The OAuth app with its new client secret (confidential apps) — shown this once. A replay of the same | OAuthApp |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 409 |
| error |
| 413 |
| error |
| 415 |
| error |
| 422 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Get an OAuth app
/v1/oauth-apps/{id}Scope oauth_apps:manage.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | OAuth app id ( |
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | The OAuth app (no client secret). | OAuthApp |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Change an OAuth app
/v1/oauth-apps/{id}Scope oauth_apps:manage.
Name, logo, privacy URL, redirect URIs or scopes. Narrowing the scopes narrows the creators' existing
grants too. confidential cannot change (400 invalid_field; register a new app instead).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | OAuth app id ( |
If-Match | header | string | optional | The |
Body application/json — OAuthAppUpdate.
| Field | Type | Required | Description |
|---|---|---|---|
name | string · 3–60 chars | optional | |
redirect_uris | array of string · at least 1, at most 10, each 0–2000 chars | optional | |
logo_url | string or null · 0–2000 chars | optional | |
privacy_url | string · 0–2000 chars | optional | |
scopes | array of CreatorScope · at least 1 | optional | |
confidential | boolean | optional | Only its current value; it cannot change. |
Example: rename
curl -X PATCH https://api.creator-guard.com/v1/oauth-apps/{id} \
-H "Authorization: Bearer $CG_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Agency Dashboard"
}'// Node.js 20+ as an ES module (.mjs, or "type": "module"): built-in fetch + top-level await.
// Server-side only: the key must never reach a browser.
const body = {
"name": "Agency Dashboard"
};
const res = await fetch('https://api.creator-guard.com/v1/oauth-apps/{id}', {
method: 'PATCH',
headers: {
Authorization: `Bearer ${process.env.CG_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(body),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(res.status, data);# pip install requests
import os
import uuid
import requests
body = {
"name": "Agency Dashboard",
}
res = requests.request(
"PATCH",
"https://api.creator-guard.com/v1/oauth-apps/{id}",
headers={"Authorization": f"Bearer {os.environ['CG_API_KEY']}"},
json=body,
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']['code']}: {data['error']['message']}")
print(res.status_code, data)| Status | Meaning | Body |
|---|---|---|
| 200 | The OAuth app (no client secret). | OAuthApp |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 412 |
| error |
| 413 |
| error |
| 415 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Delete an OAuth app
/v1/oauth-apps/{id}Scope oauth_apps:manage.
Every creator's grant to the app is revoked first: its access and refresh tokens stop working at once.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | OAuth app id ( |
| Status | Meaning | Body |
|---|---|---|
| 204 | Deleted. The answer has no body. | — |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Roll the client secret
/v1/oauth-apps/{id}/rollScope oauth_apps:manage.
A new client secret for a confidential app, in this answer only (a replay of the same Idempotency-Key
answers client_secret: null). The previous secret keeps working for 24 hours; a second roll within them
ends it at once. A public app has no secret (409 invalid_state with current_state: public_client).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | OAuth app id ( |
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
| Status | Meaning | Body |
|---|---|---|
| 200 | The OAuth app with its new client secret (confidential apps) — shown this once. A replay of the same | OAuthApp |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 422 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Members
People and open invitations
/v1/membersScope members:manage.
Everyone who can sign in to the account (status: active, id mem_…, the owner first) and every open,
unexpired invitation (status: invited, id inv_…). Not paginated. Live keys only: a cg_test_ key gets
404 not_found, because test mode has no logins.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | People (owner first) and open invitations. | MemberList |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Invite a person by email
/v1/membersScope members:manage.
Creates an invitation for developer or viewer (admins are invited in the portal by an owner or admin with
two-factor authentication) and returns it once with join_url (valid 48 hours). Send the link yourself,
only through a channel the person controls — Creator Guard sends no email, and whoever opens the link first
sets the password for this address. On the join page the person sets a password for exactly this email
address (or signs in, if a login with it exists) and accepts. A replay of the same Idempotency-Key answers
join_url: null — the link is never stored. Inviting an address again replaces its open invitation (the old
link stops working). A person who already is a member → 409 invalid_state with current_state: active. An
address whose login cannot join any account (it belongs to another account, a creator or Creator Guard
staff) gets the same 201 invitation as any address, with the same join page; it can never be accepted. At
most 20 invitations per account in 24 hours, those included → 409 limit_reached with limit: 20.
Works before the terms are accepted. Live keys only.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
Body application/json — MemberInvite.
| Field | Type | Required | Description |
|---|---|---|---|
email | string · 3–254 chars | required | The address the person signs in with; compared without case and surrounding whitespace. |
role | string · one of developer, viewer | required | Admins are invited in the portal only (by an owner or admin with two-factor authentication). The owner is the login the account was created with and is never invited. |
Example: developer
curl -X POST https://api.creator-guard.com/v1/members \
-H "Authorization: Bearer $CG_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"email": "dev@example.com",
"role": "developer"
}'// Node.js 20+ as an ES module (.mjs, or "type": "module"): built-in fetch + top-level await.
// Server-side only: the key must never reach a browser.
const body = {
"email": "dev@example.com",
"role": "developer"
};
const res = await fetch('https://api.creator-guard.com/v1/members', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.CG_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(), // keep it and send it again when you retry
},
body: JSON.stringify(body),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(res.status, data);# pip install requests
import os
import uuid
import requests
body = {
"email": "dev@example.com",
"role": "developer",
}
res = requests.request(
"POST",
"https://api.creator-guard.com/v1/members",
headers={"Authorization": f"Bearer {os.environ['CG_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json=body,
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']['code']}: {data['error']['message']}")
print(res.status_code, data)| Status | Meaning | Body |
|---|---|---|
| 201 | The invitation with | Member |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 413 |
| error |
| 415 |
| error |
| 422 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Remove a person or revoke an invitation
/v1/members/{id}Scope members:manage.
mem_… removes the person from the account in one step: their login acts for no account from its next
request on, their open invitations are revoked, every API key whose secret they had is revoked (keys they
created in the portal and keys those keys created), and webhook endpoints whose signing secret they know get
a new secret nobody has seen and are disabled until an owner or admin rolls the secret and enables them
again. A login that was created through a join link is deleted with its last membership. inv_… revokes an
open invitation; its link stops working. The owner cannot be removed: 409 invalid_state with
current_state: owner. Works before the terms are accepted. Live keys only.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Member id ( |
| Status | Meaning | Body |
|---|---|---|
| 200 | The person was removed or the invitation revoked. | MemberDeleted |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Creator
Get the creator
/v1/creator/meScope creator.profile:read.
Her name, stage and next steps and, once an agency paid for her, that agency. All /v1/creator/… endpoints take
a creator's OAuth access token (cgo_live_…) and act for her alone; an account API key is 403 wrong_account_type. A grant whose app owner no longer submitted her, or whose reservation ended, stops working
(401 invalid_token); an app owner that is not approved gets 403 account_not_active.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | Her creator object. | Creator |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Get her profile
/v1/creator/profileScope creator.profile:read.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | Her profile. | CreatorProfile |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Change her profile
/v1/creator/profileScope creator.profile:write.
lead (contact fields) while her lead is submitted, else 409 lead_locked; listing until the listing is
live, else 409 listing_locked. Every problem of the body comes back at once (400, error.details).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
If-Match | header | string | optional | The |
Body application/json — CreatorProfilePatch.
| Field | Type | Required | Description |
|---|---|---|---|
lead | object | optional | |
listing | object | optional |
Example: age
curl -X PATCH https://api.creator-guard.com/v1/creator/profile \
-H "Authorization: Bearer $CG_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"listing": {
"age": 24,
"languages": ["German", "English"]
}
}'// Node.js 20+ as an ES module (.mjs, or "type": "module"): built-in fetch + top-level await.
// Server-side only: the key must never reach a browser.
const body = {
"listing": {
"age": 24,
"languages": ["German", "English"]
}
};
const res = await fetch('https://api.creator-guard.com/v1/creator/profile', {
method: 'PATCH',
headers: {
Authorization: `Bearer ${process.env.CG_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(body),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(res.status, data);# pip install requests
import os
import uuid
import requests
body = {
"listing": {
"age": 24,
"languages": ["German", "English"],
},
}
res = requests.request(
"PATCH",
"https://api.creator-guard.com/v1/creator/profile",
headers={"Authorization": f"Bearer {os.environ['CG_API_KEY']}"},
json=body,
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']['code']}: {data['error']['message']}")
print(res.status_code, data)| Status | Meaning | Body |
|---|---|---|
| 200 | Her profile. | CreatorProfile |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 409 |
| error |
| 412 |
| error |
| 413 |
| error |
| 415 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Submit her listing for review
/v1/creator/submit-for-reviewScope creator.profile:write.
Same rules as for the partner: 422 not_ready_for_review with blockers while something is missing.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
| Status | Meaning | Body |
|---|---|---|
| 200 | Her creator object. | Creator |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 409 |
| error |
| 422 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
List her photos
/v1/creator/photosScope creator.photos:write.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | Her photos, primary first, each with a URL signed for 1 hour. | CreatorPhotoList |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Upload a photo
/v1/creator/photosScope creator.photos:write.
Multipart, like a partner upload: the image is re-encoded on our side and every metadata (EXIF, GPS) removed
before it is stored; the file name is never used. 409 photos_locked once her listing is live; at most 20
photos. A repeated Idempotency-Key replays the first answer (with url: null) even with another file.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
Body multipart/form-data — PhotoUpload.
| Field | Type | Required | Description |
|---|---|---|---|
file | string (binary) | required | JPEG, PNG or WebP; at most 40 MB and 50 megapixels. Exactly one file part. |
kind | string · one of portrait, body, content_sample, non_nude, lingerie, professional | optional | Default |
is_primary | string · one of true, false | optional |
|
| Status | Meaning | Body |
|---|---|---|
| 201 | The photo was stored (re-encoded, metadata removed). A replay of the same | CreatorPhoto |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 409 |
| error |
| 413 |
| error |
| 415 |
| error |
| 422 |
| error |
| 429 |
| error |
| 500 |
| error |
| 502 |
| error |
| 503 |
| error |
Delete a photo
/v1/creator/photos/{photo}Scope creator.photos:write.
The photo is removed, then its file (502 upstream_failed: the photo is put back, nothing changed). 409 photos_locked once live.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
photo | path | string | required | Photo id ( |
| Status | Meaning | Body |
|---|---|---|
| 204 | Deleted. The answer has no body. | — |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 429 |
| error |
| 500 |
| error |
| 502 |
| error |
| 503 |
| error |
Get a consent text
/v1/creator/consent-textScope creator.profile:read.
The current text of kind that your app must show her in full before it sends her decision, and the
version to send with it.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
kind | query | string · one of consent, age_confirmation, creator_terms | required |
|
locale | query | string | optional | Two lowercase letters, default |
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | The current published text of that kind and language. | ConsentText |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Get her consent state
/v1/creator/consentScope creator.profile:read.
Consent and 18+ state with every entry of her consent ledger (never her IP address or browser).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | Her consent and 18+ state with her ledger entries. | CreatorConsentState |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Record her consent
/v1/creator/consent/grantScope creator.consent:write.
A ledger entry with channel oauth_app:app_…, the text version she saw and the IP and user agent of your
request (your server). Only the current version (409 consent_text_outdated with current_version).
The consent text includes her 18+ confirmation: unless 18+ is already confirmed, the grant also records
age_confirmed on the same text, like the hosted consent page. While her 18+ check is declined or under
document review the grant is 409 invalid_state (current_state age_declined or age_pending) and
records nothing. An app owned by the account that referred her → 403 referrer_app_not_allowed (she
consents on Creator Guard: consent link or creator portal).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
Body application/json — ConsentDecision.
| Field | Type | Required | Description |
|---|---|---|---|
text_version | integer · ≥ 1 | optional | |
locale | string | optional | The language of the text she saw, default |
Example: grant
curl -X POST https://api.creator-guard.com/v1/creator/consent/grant \
-H "Authorization: Bearer $CG_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"text_version": 1,
"locale": "en"
}'// Node.js 20+ as an ES module (.mjs, or "type": "module"): built-in fetch + top-level await.
// Server-side only: the key must never reach a browser.
const body = {
"text_version": 1,
"locale": "en"
};
const res = await fetch('https://api.creator-guard.com/v1/creator/consent/grant', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.CG_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(), // keep it and send it again when you retry
},
body: JSON.stringify(body),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(res.status, data);# pip install requests
import os
import uuid
import requests
body = {
"text_version": 1,
"locale": "en",
}
res = requests.request(
"POST",
"https://api.creator-guard.com/v1/creator/consent/grant",
headers={"Authorization": f"Bearer {os.environ['CG_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json=body,
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']['code']}: {data['error']['message']}")
print(res.status_code, data)| Status | Meaning | Body |
|---|---|---|
| 200 | Her consent and 18+ state with her ledger entries. | CreatorConsentState |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 409 |
| error |
| 413 |
| error |
| 415 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Record her withdrawal
/v1/creator/consent/revokeScope creator.consent:write.
Her photos stop being released. Never refused because of the text version; send the one she saw if you have it.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
Body application/json — ConsentDecision.
| Field | Type | Required | Description |
|---|---|---|---|
text_version | integer · ≥ 1 | optional | |
locale | string | optional | The language of the text she saw, default |
Example: revoke
curl -X POST https://api.creator-guard.com/v1/creator/consent/revoke \
-H "Authorization: Bearer $CG_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{}'// Node.js 20+ as an ES module (.mjs, or "type": "module"): built-in fetch + top-level await.
// Server-side only: the key must never reach a browser.
const body = {};
const res = await fetch('https://api.creator-guard.com/v1/creator/consent/revoke', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.CG_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(), // keep it and send it again when you retry
},
body: JSON.stringify(body),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(res.status, data);# pip install requests
import os
import uuid
import requests
body = {}
res = requests.request(
"POST",
"https://api.creator-guard.com/v1/creator/consent/revoke",
headers={"Authorization": f"Bearer {os.environ['CG_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json=body,
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']['code']}: {data['error']['message']}")
print(res.status_code, data)| Status | Meaning | Body |
|---|---|---|
| 200 | Her consent and 18+ state with her ledger entries. | CreatorConsentState |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 413 |
| error |
| 415 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Record her 18+ confirmation
/v1/creator/age-confirmationScope creator.consent:write.
Only the current text version. Declined or under document review → 409 invalid_state; already confirmed → unchanged. An app owned by the account that referred her → 403 referrer_app_not_allowed.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
Body application/json — ConsentDecision.
| Field | Type | Required | Description |
|---|---|---|---|
text_version | integer · ≥ 1 | optional | |
locale | string | optional | The language of the text she saw, default |
Example: confirm
curl -X POST https://api.creator-guard.com/v1/creator/age-confirmation \
-H "Authorization: Bearer $CG_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"text_version": 1
}'// Node.js 20+ as an ES module (.mjs, or "type": "module"): built-in fetch + top-level await.
// Server-side only: the key must never reach a browser.
const body = {
"text_version": 1
};
const res = await fetch('https://api.creator-guard.com/v1/creator/age-confirmation', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.CG_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(), // keep it and send it again when you retry
},
body: JSON.stringify(body),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(res.status, data);# pip install requests
import os
import uuid
import requests
body = {
"text_version": 1,
}
res = requests.request(
"POST",
"https://api.creator-guard.com/v1/creator/age-confirmation",
headers={"Authorization": f"Bearer {os.environ['CG_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json=body,
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']['code']}: {data['error']['message']}")
print(res.status_code, data)| Status | Meaning | Body |
|---|---|---|
| 200 | Her consent and 18+ state with her ledger entries. | CreatorConsentState |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 409 |
| error |
| 413 |
| error |
| 415 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
List her agreements
/v1/creator/agreementsScope creator.consent:write.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | Her agreements (the creator terms). | CreatorAgreementList |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Record her acceptance of the creator terms
/v1/creator/agreements/{type}/acceptScope creator.consent:write.
Only creator_terms, only the current version (409 consent_text_outdated). An app owned by the account that referred her → 403 referrer_app_not_allowed.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
type | path | string | required | Always |
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
Body application/json — CreatorTermsAccept.
| Field | Type | Required | Description |
|---|---|---|---|
version | integer · ≥ 1 | required | The current version ( |
Example: accept
curl -X POST https://api.creator-guard.com/v1/creator/agreements/{type}/accept \
-H "Authorization: Bearer $CG_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"version": 1
}'// Node.js 20+ as an ES module (.mjs, or "type": "module"): built-in fetch + top-level await.
// Server-side only: the key must never reach a browser.
const body = {
"version": 1
};
const res = await fetch('https://api.creator-guard.com/v1/creator/agreements/{type}/accept', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.CG_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(), // keep it and send it again when you retry
},
body: JSON.stringify(body),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(res.status, data);# pip install requests
import os
import uuid
import requests
body = {
"version": 1,
}
res = requests.request(
"POST",
"https://api.creator-guard.com/v1/creator/agreements/{type}/accept",
headers={"Authorization": f"Bearer {os.environ['CG_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json=body,
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']['code']}: {data['error']['message']}")
print(res.status_code, data)| Status | Meaning | Body |
|---|---|---|
| 200 | The agreement with her acceptance. | CreatorAgreement |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 413 |
| error |
| 415 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
List her support tickets
/v1/creator/support-ticketsScope creator.support.
Newest first; pages forward only (starting_after; ending_before is 400 invalid_field).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
limit | query | integer · 1–100 | optional | 1–100 items per page (default 25). |
starting_after | query | string | optional | Id of the last item of the previous page: the next page. |
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | Her support tickets, newest first. | SupportTicketList |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Open a support ticket
/v1/creator/support-ticketsScope creator.support.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
Body application/json — SupportTicketCreate.
| Field | Type | Required | Description |
|---|---|---|---|
subject | string · 3–200 chars | required | Trimmed. |
body | string · 1–5000 chars | required | Her first message; trimmed. |
Example: ticket
curl -X POST https://api.creator-guard.com/v1/creator/support-tickets \
-H "Authorization: Bearer $CG_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"subject": "More photos?",
"body": "Can I add more photos after review?"
}'// Node.js 20+ as an ES module (.mjs, or "type": "module"): built-in fetch + top-level await.
// Server-side only: the key must never reach a browser.
const body = {
"subject": "More photos?",
"body": "Can I add more photos after review?"
};
const res = await fetch('https://api.creator-guard.com/v1/creator/support-tickets', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.CG_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(), // keep it and send it again when you retry
},
body: JSON.stringify(body),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(res.status, data);# pip install requests
import os
import uuid
import requests
body = {
"subject": "More photos?",
"body": "Can I add more photos after review?",
}
res = requests.request(
"POST",
"https://api.creator-guard.com/v1/creator/support-tickets",
headers={"Authorization": f"Bearer {os.environ['CG_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json=body,
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']['code']}: {data['error']['message']}")
print(res.status_code, data)| Status | Meaning | Body |
|---|---|---|
| 201 | The support ticket. | SupportTicket |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 413 |
| error |
| 415 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
List the messages of a ticket
/v1/creator/support-tickets/{id}/messagesScope creator.support.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Support ticket id ( |
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | Every message of the ticket, oldest first. | SupportMessageList |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Reply to a ticket
/v1/creator/support-tickets/{id}/messagesScope creator.support.
A closed ticket → 409 invalid_state; open a new one.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Support ticket id ( |
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
Body application/json — SupportReply.
| Field | Type | Required | Description |
|---|---|---|---|
body | string · 1–5000 chars | required | Trimmed. |
Example: reply
curl -X POST https://api.creator-guard.com/v1/creator/support-tickets/{id}/messages \
-H "Authorization: Bearer $CG_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"body": "Thanks!"
}'// Node.js 20+ as an ES module (.mjs, or "type": "module"): built-in fetch + top-level await.
// Server-side only: the key must never reach a browser.
const body = {
"body": "Thanks!"
};
const res = await fetch('https://api.creator-guard.com/v1/creator/support-tickets/{id}/messages', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.CG_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(), // keep it and send it again when you retry
},
body: JSON.stringify(body),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(res.status, data);# pip install requests
import os
import uuid
import requests
body = {
"body": "Thanks!",
}
res = requests.request(
"POST",
"https://api.creator-guard.com/v1/creator/support-tickets/{id}/messages",
headers={"Authorization": f"Bearer {os.environ['CG_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json=body,
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']['code']}: {data['error']['message']}")
print(res.status_code, data)| Status | Meaning | Body |
|---|---|---|
| 201 | Her new message. | SupportMessage |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 413 |
| error |
| 415 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Close a ticket
/v1/creator/support-tickets/{id}/closeScope creator.support.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Support ticket id ( |
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
| Status | Meaning | Body |
|---|---|---|
| 200 | The support ticket. | SupportTicket |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Request her data export
/v1/creator/data-exportScope creator.privacy.
Everything we hold about her that she may see, as one JSON file (her GDPR rights of access and portability). Answers 202 with a job
(Location: /v1/jobs/job_…); when it succeeded, GET /v1/creator/data-export/{id} with result.data_request
gives a download link; the file is kept for 7 days. One export per app per 24 hours: asking again answers your
app's open or recent job. The export belongs to the app that asked: another of her apps gets 404 not_found
for it and asks for its own. The file includes her support conversations with us. The app owner also receives
data_export.ready and job.completed.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
| Status | Meaning | Body |
|---|---|---|
| 202 | The export job (new, or the open/recent one of the last 24 hours). Poll | Job |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Get her data export
/v1/creator/data-export/{id}Scope creator.privacy.
With download_url while status is ready: a fresh link on every call, valid for 1 hour at most and never past expires_at. Download right away; call again for a new link. Only the app that requested the export may read it (another of her apps: 404 not_found).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Data request id ( |
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | The data request. | DataRequest |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Request the deletion of her data
/v1/creator/deletion-requestScope creator.privacy.
Creates her deletion request (or answers the open one). Creator Guard checks and completes it: her personal
data, photos, login and grants are deleted; your account receives deletion_request.completed.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
| Status | Meaning | Body |
|---|---|---|
| 202 | Her deletion request (new, or the open one). Creator Guard handles it; the app owner receives | DataRequest |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Your app's connection
/v1/creator/connected-appsScope creator.profile:read.
Your own active grant for her (a list of at most one entry). Her other connected apps are never shown to an app: she sees and manages the full list in the hosted creator portal.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | The apps she authorised and has not revoked. | ConnectedAppList |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Disconnect your app
/v1/creator/connected-apps/{app}Scope creator.profile:write.
Revokes her grant of the calling app (pass your own app id), which ends this token and its refresh token. Any other app id is 404 not_found: an app can never revoke her other connections; she does that in the hosted creator portal.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
app | path | string | required | Id of a connected OAuth app ( |
| Status | Meaning | Body |
|---|---|---|
| 204 | Deleted. The answer has no body. | — |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Jobs
Get a job
/v1/jobs/{id}Any API key; what you see depends on its scopes (see below).
An asynchronous job. A data_export job needs a creator access token with creator.privacy (403 insufficient_scope otherwise) of the app that started it (another of her apps: 404); no job type can be read
with an account API key yet (404).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Job id ( |
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | The job. | Job |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Usage & audit
Your request log
/v1/request-logsScope account:read.
The last 30 days of this mode, newest first. Method, route template, status, error code, key and duration — never bodies.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
limit | query | integer · 1–100 | optional | 1–100 items per page (default 25). |
starting_after | query | string | optional | Id of the last item of the previous page: the next page. |
ending_before | query | string | optional | Id of the first item of the current page: the page before. |
status | query | integer · 100–599 | optional | HTTP status, e.g. |
route | query | string | optional | Route template as logged, e.g. |
key | query | string | optional | Only requests of this key ( |
created_since | query | string (date-time) | optional | RFC 3339 timestamp; only requests from then on. |
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | A page of your request log. | RequestLogList |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Usage statistics
/v1/usageScope usage:read.
Requests, errors by code and p50/p95 latency per UTC day, per route and per key, for this mode. Without
from and to you get the last 30 days up to today; a range spans at most 90 days.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
from | query | string (date) | optional | First day (UTC), |
to | query | string (date) | optional | Last day (UTC), inclusive; default today. |
granularity | query | string | optional |
|
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | Usage statistics. | Usage |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Audit trail of your account
/v1/audit-eventsScope audit:read.
Key, webhook and key-policy changes, account changes made with the API, test-data resets and limits changed
by Creator Guard — who, when, from which IP. 90 days, newest first, in the key's mode: a live key also sees
account-wide changes (mode: null), a test key only test-mode ones.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
limit | query | integer · 1–100 | optional | 1–100 items per page (default 25). |
starting_after | query | string | optional | Id of the last item of the previous page: the next page. |
ending_before | query | string | optional | Id of the first item of the current page: the page before. |
action | query | string | optional | e.g. |
created_since | query | string (date-time) | optional | RFC 3339 timestamp; only changes from then on. |
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | A page of audit events. | AuditEventList |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Agency
Get your search profile
/v1/search-profileScope offers:read.
What we match creators against before we offer them to you. Agency keys only (403 wrong_account_type otherwise). Before your first PUT you get the
defaults (updated_at: null, no ETag).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | Your search profile. | SearchProfile |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Replace your search profile
/v1/search-profileScope search_profile:write.
Full replacement: a field you leave out goes back to its default ([], null, creator_stage: "both",
the portal flex) — read it, change what you need, send the whole object back. flex takes only the portal's
preset levels (400 invalid_field with field: "flex.<key>"). Money is US dollars only. Agency keys only (403 wrong_account_type otherwise). Needs the current agency_terms (403 terms_not_accepted).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
If-Match | header | string | optional | The |
Body application/json — SearchProfilePut.
| Field | Type | Required | Description |
|---|---|---|---|
niches | array of string · at most 50, each 0–100 chars | optional | |
platforms | array of string · at most 50, each 0–100 chars | optional | |
languages | array of string · at most 50, each 0–100 chars | optional | |
content_types | array of string · at most 50, each 0–100 chars | optional | |
age_min | integer or null · 18–99 | optional | |
age_max | integer or null · 18–99 | optional | Not below |
english_level_min | integer or null · 1–10 | optional | |
revenue_min | UsdInput | optional | An amount in US dollars as integer cents: |
revenue_max | UsdInput | optional | An amount in US dollars as integer cents: |
max_placement_fee | UsdInput | optional | An amount in US dollars as integer cents: |
creator_share_max_percent | integer or null · 0–100 | optional | |
creator_stage | string or null · one of beginners, earning, both | optional | |
countries_excluded | array of string · at most 50, each 0–100 chars | optional | |
capacity_per_month | integer or null · 0–1,000 | optional | |
notes | string or null · 1–2000 chars | optional | |
flex | FlexInput | optional | The |
Example: profile
curl -X PUT https://api.creator-guard.com/v1/search-profile \
-H "Authorization: Bearer $CG_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"platforms": ["Instagram", "TikTok"],
"age_min": 21,
"age_max": 35,
"revenue_min": {
"amount_minor": 0,
"currency": "USD"
},
"max_placement_fee": {
"amount_minor": 300000,
"currency": "USD"
},
"creator_stage": "both",
"flex": {
"age": {
"level": 3
},
"revenue": {
"level": "zero"
},
"niches": {
"also": []
}
}
}'// Node.js 20+ as an ES module (.mjs, or "type": "module"): built-in fetch + top-level await.
// Server-side only: the key must never reach a browser.
const body = {
"platforms": ["Instagram", "TikTok"],
"age_min": 21,
"age_max": 35,
"revenue_min": {
"amount_minor": 0,
"currency": "USD"
},
"max_placement_fee": {
"amount_minor": 300000,
"currency": "USD"
},
"creator_stage": "both",
"flex": {
"age": {
"level": 3
},
"revenue": {
"level": "zero"
},
"niches": {
"also": []
}
}
};
const res = await fetch('https://api.creator-guard.com/v1/search-profile', {
method: 'PUT',
headers: {
Authorization: `Bearer ${process.env.CG_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(body),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(res.status, data);# pip install requests
import os
import uuid
import requests
body = {
"platforms": ["Instagram", "TikTok"],
"age_min": 21,
"age_max": 35,
"revenue_min": {
"amount_minor": 0,
"currency": "USD",
},
"max_placement_fee": {
"amount_minor": 300000,
"currency": "USD",
},
"creator_stage": "both",
"flex": {
"age": {
"level": 3,
},
"revenue": {
"level": "zero",
},
"niches": {
"also": [],
},
},
}
res = requests.request(
"PUT",
"https://api.creator-guard.com/v1/search-profile",
headers={"Authorization": f"Bearer {os.environ['CG_API_KEY']}"},
json=body,
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']['code']}: {data['error']['message']}")
print(res.status_code, data)| Status | Meaning | Body |
|---|---|---|
| 200 | Your search profile. | SearchProfile |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 412 |
| error |
| 413 |
| error |
| 415 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Get your agency profile
/v1/agency-profileScope account:read.
Your agency's public facts. tier and verified_revenue are set by Creator Guard. Agency keys only (403 wrong_account_type otherwise).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | Your agency profile. | AgencyProfile |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Update your agency profile
/v1/agency-profileScope account:write.
Only the fields you send change; null clears one. tier and verified_revenue cannot be sent
(400 unknown_field); monthly_revenue is whole US dollars. Agency keys only (403 wrong_account_type otherwise). Needs the current agency_terms (403 terms_not_accepted).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
If-Match | header | string | optional | The |
Body application/json — AgencyProfilePatch.
| Field | Type | Required | Description |
|---|---|---|---|
country | string or null · 1–100 chars | optional | |
website | string or null · 0–300 chars | optional | An |
team_size | integer or null · 0–100,000 | optional | |
years_active | number or null · 0–99.9 | optional | At most one decimal, e.g. |
monthly_revenue | UsdInput | optional | An amount in US dollars as integer cents: |
managed_creators_count | integer or null · 0–100,000 | optional | |
specialization | array of string · at most 20, each 0–100 chars | optional | |
references | string or null · 1–2000 chars | optional |
Example: team
curl -X PATCH https://api.creator-guard.com/v1/agency-profile \
-H "Authorization: Bearer $CG_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"team_size": 12,
"monthly_revenue": {
"amount_minor": 25000000,
"currency": "USD"
}
}'// Node.js 20+ as an ES module (.mjs, or "type": "module"): built-in fetch + top-level await.
// Server-side only: the key must never reach a browser.
const body = {
"team_size": 12,
"monthly_revenue": {
"amount_minor": 25000000,
"currency": "USD"
}
};
const res = await fetch('https://api.creator-guard.com/v1/agency-profile', {
method: 'PATCH',
headers: {
Authorization: `Bearer ${process.env.CG_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(body),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(res.status, data);# pip install requests
import os
import uuid
import requests
body = {
"team_size": 12,
"monthly_revenue": {
"amount_minor": 25000000,
"currency": "USD",
},
}
res = requests.request(
"PATCH",
"https://api.creator-guard.com/v1/agency-profile",
headers={"Authorization": f"Bearer {os.environ['CG_API_KEY']}"},
json=body,
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']['code']}: {data['error']['message']}")
print(res.status_code, data)| Status | Meaning | Body |
|---|---|---|
| 200 | Your agency profile. | AgencyProfile |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 412 |
| error |
| 413 |
| error |
| 415 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Offers
List your offers
/v1/offersScope offers:read.
Newest first. status is the public status: an open offer whose deadline passed reads expired even before
our hourly job closes it. Agency keys only (403 wrong_account_type otherwise).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
limit | query | integer · 1–100 | optional | 1–100 items per page (default 25). |
starting_after | query | string | optional | Id of the last item of the previous page: the next page. |
ending_before | query | string | optional | Id of the first item of the current page: the page before. |
status | query | string · one of offered, accepted, declined, expired, retracted, contacted, in_talks, signed, lost | optional | Only offers with this status (an open offer past its deadline counts as |
created_since | query | string (date-time) | optional | RFC 3339 timestamp; only items created from then on. |
updated_since | query | string (date-time) | optional | RFC 3339 timestamp; only items changed from then on. |
expires_before | query | string (date-time) | optional | RFC 3339 timestamp; only offers whose deadline is before it. |
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | A page of offers. | OfferList |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Get an offer
/v1/offers/{id}Scope offers:read.
The offer, the creator's listing while you may see it (open or accepted offers and later; null once declined,
expired or retracted), your reservation, next_actions and match against your search profile. Never her contact details, the referrer or internal
notes — the contact comes with GET /v1/reservations/{id}/creator after payment. Agency keys only (403 wrong_account_type otherwise).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Offer id ( |
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | The offer. | Offer |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Set your note on an offer
/v1/offers/{id}Scope offers:write.
agency_note (1–500 characters after trimming, null clears it). Agency keys only (403 wrong_account_type otherwise). Needs the current agency_terms (403 terms_not_accepted).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Offer id ( |
If-Match | header | string | optional | The |
Body application/json — OfferPatch.
| Field | Type | Required | Description |
|---|---|---|---|
agency_note | string or null · 1–500 chars | required | Your note (trimmed); |
Example: note
curl -X PATCH https://api.creator-guard.com/v1/offers/{id} \
-H "Authorization: Bearer $CG_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agency_note": "Call scheduled for Monday."
}'// Node.js 20+ as an ES module (.mjs, or "type": "module"): built-in fetch + top-level await.
// Server-side only: the key must never reach a browser.
const body = {
"agency_note": "Call scheduled for Monday."
};
const res = await fetch('https://api.creator-guard.com/v1/offers/{id}', {
method: 'PATCH',
headers: {
Authorization: `Bearer ${process.env.CG_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(body),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(res.status, data);# pip install requests
import os
import uuid
import requests
body = {
"agency_note": "Call scheduled for Monday.",
}
res = requests.request(
"PATCH",
"https://api.creator-guard.com/v1/offers/{id}",
headers={"Authorization": f"Bearer {os.environ['CG_API_KEY']}"},
json=body,
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']['code']}: {data['error']['message']}")
print(res.status_code, data)| Status | Meaning | Body |
|---|---|---|
| 200 | The offer. | Offer |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 412 |
| error |
| 413 |
| error |
| 415 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
List the creator's photos
/v1/offers/{id}/photosScope offers:read.
Only photos she agreed to share, as signed links valid for one hour, on one page. Only while the listing is
visible to you; otherwise 409 invalid_state with error.current_state. Agency keys only (403 wrong_account_type otherwise).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Offer id ( |
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | The photos she agreed to share, as signed links valid for one hour. | OfferPhotoList |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Accept an offer
/v1/offers/{id}/acceptScope offers:write.
Reserves the creator for you and creates the reservation (reservation, status awaiting_payment). Needs the
current agency_terms and the current warranty_terms — otherwise 403 terms_not_accepted with
error.agreement_type and nothing changes. 409 offer_taken (another agency accepted first),
409 offer_expired (deadline passed), 409 listing_unavailable (listing pulled or offer retracted),
409 invalid_state (not open). No request fields. Agency keys only (403 wrong_account_type otherwise).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Offer id ( |
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
| Status | Meaning | Body |
|---|---|---|
| 200 | The offer. | Offer |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 413 |
| error |
| 415 |
| error |
| 422 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Decline an offer
/v1/offers/{id}/declineScope offers:write.
note (50–500 characters after trimming) tells us why. Only open offers (409 invalid_state); a passed deadline
is 409 offer_expired. Agency keys only (403 wrong_account_type otherwise). Needs the current agency_terms (403 terms_not_accepted).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Offer id ( |
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
Body application/json — OfferDecline.
| Field | Type | Required | Description |
|---|---|---|---|
note | string · 50–500 chars | required | Why she is not a fit, 50–500 characters after trimming. |
Example: mismatch
curl -X POST https://api.creator-guard.com/v1/offers/{id}/decline \
-H "Authorization: Bearer $CG_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"note": "Her niche and languages are outside what our team covers this quarter, sorry."
}'// Node.js 20+ as an ES module (.mjs, or "type": "module"): built-in fetch + top-level await.
// Server-side only: the key must never reach a browser.
const body = {
"note": "Her niche and languages are outside what our team covers this quarter, sorry."
};
const res = await fetch('https://api.creator-guard.com/v1/offers/{id}/decline', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.CG_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(), // keep it and send it again when you retry
},
body: JSON.stringify(body),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(res.status, data);# pip install requests
import os
import uuid
import requests
body = {
"note": "Her niche and languages are outside what our team covers this quarter, sorry.",
}
res = requests.request(
"POST",
"https://api.creator-guard.com/v1/offers/{id}/decline",
headers={"Authorization": f"Bearer {os.environ['CG_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json=body,
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']['code']}: {data['error']['message']}")
print(res.status_code, data)| Status | Meaning | Body |
|---|---|---|
| 200 | The offer. | Offer |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 413 |
| error |
| 415 |
| error |
| 422 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Undo an accept
/v1/offers/{id}/undo-acceptScope offers:write.
Until undo_until (GET /v1/settings → accept_undo_minutes) and while the reservation is unpaid, the offer
goes back to offered and the reservation is cancelled. Later: 409 undo_window_passed; not accepted or
already paid: 409 invalid_state. No request fields. Agency keys only (403 wrong_account_type otherwise). Needs the current agency_terms (403 terms_not_accepted).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Offer id ( |
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
| Status | Meaning | Body |
|---|---|---|
| 200 | The offer. | Offer |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 413 |
| error |
| 415 |
| error |
| 422 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Mark the creator as contacted
/v1/offers/{id}/mark-contactedScope offers:write.
From accepted, once your reservation is paid (409 payment_pending before). No request fields. Agency keys only (403 wrong_account_type otherwise). Needs the current agency_terms (403 terms_not_accepted).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Offer id ( |
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
| Status | Meaning | Body |
|---|---|---|
| 200 | The offer. | Offer |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 413 |
| error |
| 415 |
| error |
| 422 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Mark talks as started
/v1/offers/{id}/mark-in-talksScope offers:write.
From contacted (409 invalid_state otherwise). No request fields. Agency keys only (403 wrong_account_type otherwise). Needs the current agency_terms (403 terms_not_accepted).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Offer id ( |
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
| Status | Meaning | Body |
|---|---|---|
| 200 | The offer. | Offer |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 413 |
| error |
| 415 |
| error |
| 422 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Mark the creator as signed
/v1/offers/{id}/mark-signedScope offers:write.
From contacted or in_talks, or from accepted once the reservation is paid (409 payment_pending before).
No request fields. Agency keys only (403 wrong_account_type otherwise). Needs the current agency_terms (403 terms_not_accepted).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Offer id ( |
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
| Status | Meaning | Body |
|---|---|---|
| 200 | The offer. | Offer |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 413 |
| error |
| 415 |
| error |
| 422 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Mark the placement as lost
/v1/offers/{id}/mark-lostScope offers:write.
Only from accepted, before the placement fee was received, with an outcome_reason. Once the fee was received the deal can no longer be marked lost (409 deal_paid): file a warranty claim (POST /v1/reservations/{id}/warranty-claim) instead. Agency keys only (403 wrong_account_type otherwise). Needs the current agency_terms (403 terms_not_accepted).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Offer id ( |
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
Body application/json — OfferMarkLost.
| Field | Type | Required | Description |
|---|---|---|---|
outcome_reason | string · one of profile_mismatch, not_reachable, duplicate, quality, capacity, other | required |
Example: unreachable
curl -X POST https://api.creator-guard.com/v1/offers/{id}/mark-lost \
-H "Authorization: Bearer $CG_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"outcome_reason": "not_reachable"
}'// Node.js 20+ as an ES module (.mjs, or "type": "module"): built-in fetch + top-level await.
// Server-side only: the key must never reach a browser.
const body = {
"outcome_reason": "not_reachable"
};
const res = await fetch('https://api.creator-guard.com/v1/offers/{id}/mark-lost', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.CG_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(), // keep it and send it again when you retry
},
body: JSON.stringify(body),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(res.status, data);# pip install requests
import os
import uuid
import requests
body = {
"outcome_reason": "not_reachable",
}
res = requests.request(
"POST",
"https://api.creator-guard.com/v1/offers/{id}/mark-lost",
headers={"Authorization": f"Bearer {os.environ['CG_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json=body,
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']['code']}: {data['error']['message']}")
print(res.status_code, data)| Status | Meaning | Body |
|---|---|---|
| 200 | The offer. | Offer |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 413 |
| error |
| 415 |
| error |
| 422 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Reservations
List your reservations
/v1/reservationsScope reservations:read.
Newest first. Agency keys only (403 wrong_account_type otherwise).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
limit | query | integer · 1–100 | optional | 1–100 items per page (default 25). |
starting_after | query | string | optional | Id of the last item of the previous page: the next page. |
ending_before | query | string | optional | Id of the first item of the current page: the page before. |
status | query | string · one of awaiting_payment, paid, completed, refunded, cancelled | optional | Only reservations with this status. |
created_since | query | string (date-time) | optional | RFC 3339 timestamp; only items created from then on. |
updated_since | query | string (date-time) | optional | RFC 3339 timestamp; only items changed from then on. |
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | A page of reservations. | ReservationList |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Get a reservation
/v1/reservations/{id}Scope reservations:read.
Amount, payment reference and due date, payment and warranty dates, your warranty claim. Agency keys only (403 wrong_account_type otherwise).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Reservation id ( |
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | The reservation. | Reservation |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
File a warranty claim
/v1/reservations/{id}/warranty-claimScope reservations:write.
Once per reservation, while it is paid and the warranty runs. 409 claim_exists (already filed),
409 payment_pending (not paid yet), 409 warranty_expired (warranty over or completed), 409 invalid_state
(refunded or cancelled). Agency keys only (403 wrong_account_type otherwise). Needs the current agency_terms (403 terms_not_accepted).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Reservation id ( |
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
Body application/json — WarrantyClaimCreate.
| Field | Type | Required | Description |
|---|---|---|---|
reason | string · one of creator_unreachable, no_show, false_data, contract_refused, other | required | |
note | string or null · 0–2000 chars | optional | Trimmed; blank counts as no note. |
Example: no_show
curl -X POST https://api.creator-guard.com/v1/reservations/{id}/warranty-claim \
-H "Authorization: Bearer $CG_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"reason": "no_show",
"note": "Missed both onboarding calls."
}'// Node.js 20+ as an ES module (.mjs, or "type": "module"): built-in fetch + top-level await.
// Server-side only: the key must never reach a browser.
const body = {
"reason": "no_show",
"note": "Missed both onboarding calls."
};
const res = await fetch('https://api.creator-guard.com/v1/reservations/{id}/warranty-claim', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.CG_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(), // keep it and send it again when you retry
},
body: JSON.stringify(body),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(res.status, data);# pip install requests
import os
import uuid
import requests
body = {
"reason": "no_show",
"note": "Missed both onboarding calls.",
}
res = requests.request(
"POST",
"https://api.creator-guard.com/v1/reservations/{id}/warranty-claim",
headers={"Authorization": f"Bearer {os.environ['CG_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json=body,
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']['code']}: {data['error']['message']}")
print(res.status_code, data)| Status | Meaning | Body |
|---|---|---|
| 200 | The reservation. | Reservation |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 413 |
| error |
| 415 |
| error |
| 422 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Get the creator's contact
/v1/reservations/{id}/creatorScope reservations:read.
After payment only (paid or completed): name, Instagram, other contact, platforms, followers, niche and creator
number. Never the referrer or internal notes. Unpaid: 409 payment_pending; refunded or cancelled:
409 invalid_state. Agency keys only (403 wrong_account_type otherwise).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Reservation id ( |
fields | query | string | optional | Comma-separated top-level fields to return (at most 50), e.g. |
| Status | Meaning | Body |
|---|---|---|
| 200 | The creator's contact. | ReservationCreator |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Test mode
Confirm consent and 18+ (test mode)
/v1/test-helpers/leads/{id}/confirmScope leads:write.
Only with a cg_test_ key — a live key gets 404 not_found and nothing happens. Records consent and the
18+ confirmation as if she had used her link.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Lead id ( |
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
| Status | Meaning | Body |
|---|---|---|
| 200 | The lead. | Lead |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 422 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Approve the listing (test mode)
/v1/test-helpers/leads/{id}/approve-listingScope leads:write.
Only with a cg_test_ key — a live key gets 404 not_found and nothing happens. Plays our review: a
listing in review goes live. Missing consent, 18+ confirmation or fee → 422 not_ready_for_review.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Lead id ( |
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
| Status | Meaning | Body |
|---|---|---|
| 200 | The lead. | Lead |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 422 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Reject a lead (test mode)
/v1/test-helpers/leads/{id}/rejectScope leads:write.
Only with a cg_test_ key — a live key gets 404 not_found and nothing happens. Plays our review: the lead
becomes rejected with your outcome_reason.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Lead id ( |
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
Body application/json — TestLeadReject.
| Field | Type | Required | Description |
|---|---|---|---|
outcome_reason | string · one of profile_mismatch, not_reachable, duplicate, quality, capacity, other | required |
Example: duplicate
curl -X POST https://api.creator-guard.com/v1/test-helpers/leads/{id}/reject \
-H "Authorization: Bearer $CG_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"outcome_reason": "duplicate"
}'// Node.js 20+ as an ES module (.mjs, or "type": "module"): built-in fetch + top-level await.
// Server-side only: the key must never reach a browser.
const body = {
"outcome_reason": "duplicate"
};
const res = await fetch('https://api.creator-guard.com/v1/test-helpers/leads/{id}/reject', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.CG_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(), // keep it and send it again when you retry
},
body: JSON.stringify(body),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(res.status, data);# pip install requests
import os
import uuid
import requests
body = {
"outcome_reason": "duplicate",
}
res = requests.request(
"POST",
"https://api.creator-guard.com/v1/test-helpers/leads/{id}/reject",
headers={"Authorization": f"Bearer {os.environ['CG_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json=body,
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']['code']}: {data['error']['message']}")
print(res.status_code, data)| Status | Meaning | Body |
|---|---|---|
| 200 | The lead. | Lead |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 413 |
| error |
| 415 |
| error |
| 422 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Pay a commission (test mode)
/v1/test-helpers/commissions/{id}/mark-paidScope leads:write.
Only with a cg_test_ key — a live key gets 404 not_found and nothing happens. A due commission becomes
paid (any other → 409 invalid_state).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Commission id ( |
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
| Status | Meaning | Body |
|---|---|---|
| 200 | The commission. | Commission |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 422 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Delete all test data (test mode)
/v1/test-helpers/resetScope keys:manage.
Only with a cg_test_ key — a live key gets 404 not_found and nothing happens. Deletes every lead, photo,
commission, event, delivery, sandbox file and stored Idempotency-Key answer of your account in the
sandbox. Your keys, webhook endpoints and accepted terms stay.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
| Status | Meaning | Body |
|---|---|---|
| 200 | What was deleted from the sandbox. | TestReset |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 422 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
A sandbox photo or logo
/v1/test-files/{path}No API key needed.
Photo and logo URLs of test mode point here; use them exactly as given. No key needed: the URL carries a
signed token that expires like every photo URL (1 hour). {path} is <bucket>/<folder>/<file> and
contains slashes, so your request log shows this route as /v1/test-files/{bucket}/{path}. Requests
without a key share a per-IP budget (429 rate_limited).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
path | path | string | required | Bucket and object path as in the URL we gave you; contains slashes. |
token | query | string | required | Signed token from the URL we gave you. |
| Status | Meaning | Body |
|---|---|---|
| 200 | The file. | — |
| 400 | The body, a field or a query parameter is invalid: | error |
| 404 |
| error |
| 429 |
| error |
| 500 |
| error |
| 502 |
| error |
| 503 |
| error |
Create a test offer (test mode)
/v1/test-helpers/offersScope offers:write.
Only with a cg_test_ key — a live key gets 404 not_found and nothing happens. Creates a synthetic creator of a fixed sandbox referrer and offers her to your agency, as our matching
would. Agency keys only (403 wrong_account_type otherwise).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
Body application/json — TestOfferCreate.
| Field | Type | Required | Description |
|---|---|---|---|
creator_name | string · 1–120 chars | optional | Default: a generated test name. The offer shows it only after |
placement_fee | MoneyInput | optional |
|
expires_in_hours | integer · 1–720 | optional | Default: the offer deadline of |
Example: fee
curl -X POST https://api.creator-guard.com/v1/test-helpers/offers \
-H "Authorization: Bearer $CG_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"creator_name": "Test Creator",
"placement_fee": {
"amount_minor": 150000,
"currency": "USD"
},
"expires_in_hours": 48
}'// Node.js 20+ as an ES module (.mjs, or "type": "module"): built-in fetch + top-level await.
// Server-side only: the key must never reach a browser.
const body = {
"creator_name": "Test Creator",
"placement_fee": {
"amount_minor": 150000,
"currency": "USD"
},
"expires_in_hours": 48
};
const res = await fetch('https://api.creator-guard.com/v1/test-helpers/offers', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.CG_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(), // keep it and send it again when you retry
},
body: JSON.stringify(body),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(res.status, data);# pip install requests
import os
import uuid
import requests
body = {
"creator_name": "Test Creator",
"placement_fee": {
"amount_minor": 150000,
"currency": "USD",
},
"expires_in_hours": 48,
}
res = requests.request(
"POST",
"https://api.creator-guard.com/v1/test-helpers/offers",
headers={"Authorization": f"Bearer {os.environ['CG_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json=body,
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']['code']}: {data['error']['message']}")
print(res.status_code, data)| Status | Meaning | Body |
|---|---|---|
| 201 | The new test offer. | Offer |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 413 |
| error |
| 415 |
| error |
| 422 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Mark a reservation as paid (test mode)
/v1/test-helpers/reservations/{id}/mark-paidScope reservations:write.
Only with a cg_test_ key — a live key gets 404 not_found and nothing happens. Plays our bookkeeping when your transfer arrives: awaiting_payment → paid (her contact is unlocked, the
warranty starts). No request fields. Agency keys only (403 wrong_account_type otherwise).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Reservation id ( |
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
| Status | Meaning | Body |
|---|---|---|
| 200 | The reservation. | Reservation |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 413 |
| error |
| 415 |
| error |
| 422 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Complete a reservation (test mode)
/v1/test-helpers/reservations/{id}/completeScope reservations:write.
Only with a cg_test_ key — a live key gets 404 not_found and nothing happens. Ends the warranty early: paid → completed. No request fields. Agency keys only (403 wrong_account_type otherwise).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Reservation id ( |
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
| Status | Meaning | Body |
|---|---|---|
| 200 | The reservation. | Reservation |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 413 |
| error |
| 415 |
| error |
| 422 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Refund a reservation (test mode)
/v1/test-helpers/reservations/{id}/refundScope reservations:write.
Only with a cg_test_ key — a live key gets 404 not_found and nothing happens. Plays an accepted warranty claim: paid → refunded. Agency keys only (403 wrong_account_type otherwise).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Reservation id ( |
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
Body application/json — TestReservationRefund.
| Field | Type | Required | Description |
|---|---|---|---|
reason | string · one of creator_unreachable, no_show, false_data, contract_refused, other | optional | Default: the reason of your warranty claim, else |
Example: no_show
curl -X POST https://api.creator-guard.com/v1/test-helpers/reservations/{id}/refund \
-H "Authorization: Bearer $CG_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"reason": "no_show"
}'// Node.js 20+ as an ES module (.mjs, or "type": "module"): built-in fetch + top-level await.
// Server-side only: the key must never reach a browser.
const body = {
"reason": "no_show"
};
const res = await fetch('https://api.creator-guard.com/v1/test-helpers/reservations/{id}/refund', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.CG_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(), // keep it and send it again when you retry
},
body: JSON.stringify(body),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(res.status, data);# pip install requests
import os
import uuid
import requests
body = {
"reason": "no_show",
}
res = requests.request(
"POST",
"https://api.creator-guard.com/v1/test-helpers/reservations/{id}/refund",
headers={"Authorization": f"Bearer {os.environ['CG_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json=body,
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']['code']}: {data['error']['message']}")
print(res.status_code, data)| Status | Meaning | Body |
|---|---|---|
| 200 | The reservation. | Reservation |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 413 |
| error |
| 415 |
| error |
| 422 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Advance the test clock (test mode)
/v1/test-helpers/clock/advanceScope offers:write.
Only with a cg_test_ key — a live key gets 404 not_found and nothing happens. Moves the deadlines of your test offers and reservations hours (1–720) into the past and runs our expiry
jobs: open offers expire, unpaid reservations are cancelled, warranties complete — with the same events.
Agency keys only (403 wrong_account_type otherwise).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string · 1–255 chars | optional | Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours. |
Body application/json — ClockAdvance.
| Field | Type | Required | Description |
|---|---|---|---|
hours | integer · 1–720 | required |
Example: two_days
curl -X POST https://api.creator-guard.com/v1/test-helpers/clock/advance \
-H "Authorization: Bearer $CG_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"hours": 48
}'// Node.js 20+ as an ES module (.mjs, or "type": "module"): built-in fetch + top-level await.
// Server-side only: the key must never reach a browser.
const body = {
"hours": 48
};
const res = await fetch('https://api.creator-guard.com/v1/test-helpers/clock/advance', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.CG_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(), // keep it and send it again when you retry
},
body: JSON.stringify(body),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(res.status, data);# pip install requests
import os
import uuid
import requests
body = {
"hours": 48,
}
res = requests.request(
"POST",
"https://api.creator-guard.com/v1/test-helpers/clock/advance",
headers={"Authorization": f"Bearer {os.environ['CG_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json=body,
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']['code']}: {data['error']['message']}")
print(res.status_code, data)| Status | Meaning | Body |
|---|---|---|
| 200 | What the expiry jobs changed in your sandbox. | ClockAdvanceResult |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 409 |
| error |
| 413 |
| error |
| 415 |
| error |
| 422 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Create an authorization code (test mode)
/v1/test-helpers/oauth-codesScope oauth_apps:manage.
Only with a cg_test_ key — a live key gets 404 not_found and nothing happens. The hosted sign-in page
/oauth/authorize serves live apps only (the sandbox has no real creator logins), so a test-mode app
(cgcl_test_…) gets its authorization codes here, exactly as if the creator of the lead had clicked
"Allow": the answer's code is valid for 60 seconds and one exchange at the normal /oauth/token, together
with the code_verifier behind code_challenge (S256). The lead must be one your account may connect (you
submitted it, or you hold a paid reservation for it), otherwise 404 not_found. redirect_uri and every
scope must be registered for the app (400 invalid_field). A code is a single-use secret, so an
Idempotency-Key is ignored and a retry creates a new code. 503 not_configured while OAuth is switched
off on our side.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | optional | Ignored on this endpoint: a code is single-use, a retry creates a new one. |
Body application/json — OAuthTestCodeCreate.
| Field | Type | Required | Description |
|---|---|---|---|
client_id | string | required | A test-mode app of your account. |
lead_id | string | required | A sandbox lead you may connect (you submitted it, or you hold a paid reservation for it). |
redirect_uri | string · 0–2000 chars | required | One of the app's registered redirect URIs, character for character. |
scopes | array of CreatorScope · at least 1 | required | A subset of the app's scopes; repeats are ignored. |
code_challenge | string | required | BASE64URL(SHA256(code_verifier)) without padding (PKCE S256). |
Example: code
curl -X POST https://api.creator-guard.com/v1/test-helpers/oauth-codes \
-H "Authorization: Bearer $CG_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"client_id": "cgcl_test_0123456789abcdef0123456789abcdef",
"lead_id": "lead_aaaaaaaaaaaaaaaaaaaaaaaaaa",
"redirect_uri": "http://localhost:3000/oauth/callback",
"scopes": ["creator.profile:read"],
"code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"
}'// Node.js 20+ as an ES module (.mjs, or "type": "module"): built-in fetch + top-level await.
// Server-side only: the key must never reach a browser.
const body = {
"client_id": "cgcl_test_0123456789abcdef0123456789abcdef",
"lead_id": "lead_aaaaaaaaaaaaaaaaaaaaaaaaaa",
"redirect_uri": "http://localhost:3000/oauth/callback",
"scopes": ["creator.profile:read"],
"code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"
};
const res = await fetch('https://api.creator-guard.com/v1/test-helpers/oauth-codes', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.CG_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(), // keep it and send it again when you retry
},
body: JSON.stringify(body),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(res.status, data);# pip install requests
import os
import uuid
import requests
body = {
"client_id": "cgcl_test_0123456789abcdef0123456789abcdef",
"lead_id": "lead_aaaaaaaaaaaaaaaaaaaaaaaaaa",
"redirect_uri": "http://localhost:3000/oauth/callback",
"scopes": ["creator.profile:read"],
"code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
}
res = requests.request(
"POST",
"https://api.creator-guard.com/v1/test-helpers/oauth-codes",
headers={"Authorization": f"Bearer {os.environ['CG_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json=body,
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']['code']}: {data['error']['message']}")
print(res.status_code, data)| Status | Meaning | Body |
|---|---|---|
| 201 | A test-mode authorization code, shown this once: valid for 60 seconds and one exchange at | OAuthTestCode |
| 400 | The body, a field or a query parameter is invalid: | error |
| 401 |
| error |
| 403 |
| error |
| 404 |
| error |
| 413 |
| error |
| 415 |
| error |
| 429 |
| error |
| 500 |
| error |
| 503 |
| error |
Response headers
X-Request-Id: string · always sent
Id of this request (req_…), also error.request_id. Quote it to support.
X-API-Version: string · always sent
The contract version that answered (info.version). Log it with your requests.
RateLimit-Policy: string
The limits that apply to this key, e.g. 100;w=60, 10000;w=86400.
RateLimit: string
State of the tightest window: limit=100, remaining=97, reset=42 (seconds).
Retry-After: integer
Seconds to wait before the next attempt, computed from the window that is used up.
ETag: string
Version of the resource; send it back in If-Match to make a change race-safe.
Idempotent-Replayed: string
true when this is the stored answer to an earlier request with the same Idempotency-Key.
Error responses
Every error has the same body: ErrorResponse. Codes: Errors.
400
The body, a field or a query parameter is invalid: invalid_json, invalid_body, unknown_field, unknown_parameter, missing_field, invalid_field, missing_contact, age_below_18, consent_required, invalid_cursor. unknown_parameter and invalid_cursor name the query parameter in error.parameter.
invalid_field
{
"error": {
"type": "invalid_request",
"code": "age_below_18",
"message": "listing.age must be 18 or over.",
"field": "listing.age",
"doc_url": "https://docs.creator-guard.com/errors/#age_below_18",
"request_id": "req_c7x2m4qk3vbn5h6tjd2wle4pza",
"details": [
{
"field": "listing.age",
"code": "age_below_18",
"message": "listing.age must be 18 or over."
},
{
"field": "platforms",
"code": "invalid_field",
"message": "platforms must be a non-empty array of strings."
}
]
}
}unknown_parameter
{
"error": {
"type": "invalid_request",
"code": "unknown_parameter",
"message": "Unknown query parameter \"sort\".",
"parameter": "sort",
"doc_url": "https://docs.creator-guard.com/errors/#unknown_parameter",
"request_id": "req_c7x2m4qk3vbn5h6tjd2wle4pza"
}
}401
missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.
invalid_key
{
"error": {
"type": "authentication",
"code": "invalid_key",
"message": "Unknown or revoked key.",
"doc_url": "https://docs.creator-guard.com/errors/#invalid_key",
"request_id": "req_c7x2m4qk3vbn5h6tjd2wle4pza"
}
}403
account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.
terms_not_accepted
{
"error": {
"type": "permission",
"code": "terms_not_accepted",
"message": "Accept the referrer terms first.",
"agreement_type": "referrer_terms",
"doc_url": "https://docs.creator-guard.com/errors/#terms_not_accepted",
"request_id": "req_c7x2m4qk3vbn5h6tjd2wle4pza"
}
}404
not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.
409
duplicate_own_lead (with error.lead), duplicate_other_referrer (on create and on a PATCH that changes instagram_handle), lead_locked, listing_locked, invalid_state, external_id_taken, photos_locked, limit_reached (with error.limit) or idempotency_in_progress; on the agency endpoints also offer_taken, offer_expired, listing_unavailable, payment_pending, deal_paid, undo_window_passed, claim_exists or warranty_expired. invalid_state carries error.current_state — the lead's stage (draft, in_review, ready, offered, accepted, in_placement, placed, withdrawn, rejected, lost), withdrawn for a fee on a withdrawn listing, anonymized for a consent link after her data was erased, or age_declined / age_pending for a consent grant while her 18+ check is declined or under review — except on agreement accept, where it carries error.current_version instead.
duplicate_own_lead
{
"error": {
"type": "invalid_request",
"code": "duplicate_own_lead",
"message": "You already submitted this creator (CR-1047) and she is past draft.",
"field": "instagram_handle",
"lead": {
"id": "lead_hz5ikyc3pnhkrhlb6p7elkx2qy",
"creator_ref": "CR-1047"
},
"doc_url": "https://docs.creator-guard.com/errors/#duplicate_own_lead",
"request_id": "req_c7x2m4qk3vbn5h6tjd2wle4pza"
}
}412
precondition_failed: the If-Match value is not the current ETag. Read again, then retry.
413
payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.
415
unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).
422
not_ready_for_review (with error.blockers), idempotency_key_reused (same key, different body) or image_unreadable (an upload that cannot be decoded).
not_ready_for_review
{
"error": {
"type": "invalid_request",
"code": "not_ready_for_review",
"message": "Blockers remain.",
"blockers": ["photos_missing", "consent_missing"],
"doc_url": "https://docs.creator-guard.com/errors/#not_ready_for_review",
"request_id": "req_c7x2m4qk3vbn5h6tjd2wle4pza"
}
}429
rate_limited, concurrency_limited or duplicate_limit_reached. Wait Retry-After seconds. Before a key is accepted (per-IP budget for requests without a valid key) the answer has no RateLimit headers.
500
internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.
503
not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.
502
upstream_failed: a service we depend on failed (text extraction, or the DNS lookup of a webhook URL). Retry later; nothing was stored.
Schemas
ApiInfo
| Field | Type | Required | Description |
|---|---|---|---|
object | "api" (exactly) | required | |
api_version | string | required | Same as |
status | string | required |
|
docs_url | string (uri) | required | |
openapi_url | string (uri) | required |
Account
| Field | Type | Required | Description |
|---|---|---|---|
object | "account" (exactly) | required | |
id | string | required | |
type | string | required |
|
status | string | required |
|
display_name | string or null | required | |
company_name | string or null | required | |
website | string or null | required | |
telegram_username | string or null | required | |
logo_url | string or null | required | |
terms | array of object | required | One entry per agreement type that applies to the account ( |
limits | object | required | Limits in effect (defaults or your account's overrides). |
Agreement
| Field | Type | Required | Description |
|---|---|---|---|
object | "agreement" (exactly) | required | |
type | string | required |
|
current_version | integer or null | required | |
published_at | string or null (date-time) | required | |
accepted | boolean | required | |
accepted_version | integer or null | required | |
accepted_at | string or null (date-time) | required | |
acceptances | array of object | required | Every version the account accepted. |
AgreementList
| Field | Type | Required | Description |
|---|---|---|---|
object | "list" (exactly) | required | |
data | array of Agreement | required | |
has_more | boolean | required | |
next_cursor | string or null | required |
AgreementDocument
| Field | Type | Required | Description |
|---|---|---|---|
object | "agreement_document" (exactly) | required | |
type | string | required | |
version | integer | required | |
published_at | string or null (date-time) | required | |
current | boolean | required | Whether this is the version to accept. |
body_md | string | required | The text as Markdown. |
AgreementAccept
| Field | Type | Required | Description |
|---|---|---|---|
version | integer · ≥ 1 | required | Must be the current published version. |
OptionLists
Values in the spelling we store. Lists can change. Full lists: /reference/allowed-values/
| Field | Type | Required | Description |
|---|---|---|---|
object | "option_lists" (exactly) | required | |
platforms | array of string | required | |
languages | array of string | required | |
content_types | array of string | required | |
niches | array of string | required | |
specializations | array of string | required |
Settings
| Field | Type | Required | Description |
|---|---|---|---|
object | "settings" (exactly) | required | |
offer_deadline_hours | integer | required | |
accept_undo_minutes | integer | required | |
payment_due_days | integer | required | |
warranty_days | integer | required | |
creator_guard_share_percent | integer | required | Creator Guard's share of a placement fee; yours is the rest. |
Money
An amount in integer minor units (cents) and its ISO 4217 currency; null when not set.
| Field | Type | Required | Description |
|---|---|---|---|
amount_minor | integer | required | |
currency | string | required |
|
MoneyInput
{"amount_minor": 150000, "currency": "USD"} = 1,500.00 USD. null clears the fee.
| Field | Type | Required | Description |
|---|---|---|---|
amount_minor | integer · 0–9,999,999,999 | required | |
currency | string · one of USD, EUR, GBP | required |
NextActions
What you can do with the lead right now — computed by Creator Guard, so you never re-implement the rules.
| Field | Type | Required | Description |
|---|---|---|---|
can_edit_lead | boolean | required | |
can_edit_listing | boolean | required | |
can_edit_fee | boolean | required | |
can_withdraw | boolean | required | |
can_submit_for_review | boolean | required | |
blockers | array of string | required | What still keeps her off the marketplace, while the lead is |
ListingSummary
The listing summary every lead carries. With ?expand=listing the lead carries the full Listing object instead (without photo_count).
| Field | Type | Required | Description |
|---|---|---|---|
status | string | required |
|
placement_fee | Money | required | An amount in integer minor units (cents) and its ISO 4217 currency; |
photo_count | integer | required | Photos she has. |
Photo
| Field | Type | Required | Description |
|---|---|---|---|
object | "photo" (exactly) | required | |
id | string | required | |
kind | string | required | |
is_primary | boolean | required | |
consent_status | string | required | |
url | string or null (uri) | required | Signed, valid for 1 hour; |
url_expires_at | string or null (date-time) | required | |
lead | string | required | |
created_at | string or null (date-time) | required | |
version | integer · ≥ 0 | required | Grows with every change of the photo; events about it carry the same number as |
ConsentState
| Field | Type | Required | Description |
|---|---|---|---|
status | string | required |
|
granted_at | string or null (date-time) | required | |
revoked_at | string or null (date-time) | required |
AgeConfirmation
| Field | Type | Required | Description |
|---|---|---|---|
status | string | required |
|
confirmed_at | string or null (date-time) | required |
CreatorLogin
| Field | Type | Required | Description |
|---|---|---|---|
status | string | required |
|
Confirmations
| Field | Type | Required | Description |
|---|---|---|---|
object | "confirmations" (exactly) | required | |
lead | string | required | |
consent | ConsentState | required | |
age_confirmation | AgeConfirmation | required | |
creator_login | CreatorLogin | required |
Lead
One creator you submitted. New fields may be added within v1; ignore fields you do not know.
| Field | Type | Required | Description |
|---|---|---|---|
object | "lead" (exactly) | required | |
id | string | required | |
external_id | string or null | required | |
creator_ref | string or null | required | Her creator number; quote it to support. |
creator_name | string | required | |
instagram_handle | string or null | required | As stored (normalised username). |
other_contact | string or null | required | |
platforms | array of string | required | |
follower_count | integer or null | required | |
niche | string or null | required | |
notes | string or null | required | |
stage | string | required |
|
outcome_reason | string or null | required | Why a lead was rejected or lost. |
next_actions | NextActions | required | What you can do with the lead right now — computed by Creator Guard, so you never re-implement the rules. |
listing | ListingSummary or Listing | required | The summary; with |
confirmations | Confirmations | optional | |
consent | LeadConsent | optional | Her consent and her personal consent link. Links are stored only as hashes, so |
photos | array of Photo | optional | Only with |
created_at | string (date-time) | required | |
updated_at | string (date-time) | required | |
version | integer · ≥ 0 | required | Grows with every change of the lead or its listing; events about it carry the same number as |
{
"object": "lead",
"id": "lead_hz5ikyc3pnhkrhlb6p7elkx2qy",
"external_id": "crm-000042",
"creator_ref": "CR-1047",
"creator_name": "Mia",
"instagram_handle": "miacreates",
"other_contact": "Telegram: @mia_tg",
"platforms": ["OnlyFans", "Instagram", "TikTok"],
"follower_count": 42000,
"niche": "Fitness",
"notes": "Replies fast, wants to start within a month.",
"stage": "draft",
"outcome_reason": null,
"next_actions": {
"can_edit_lead": true,
"can_edit_listing": true,
"can_edit_fee": true,
"can_withdraw": true,
"can_submit_for_review": false,
"blockers": ["photos_missing", "consent_missing", "age_confirmation_missing", "fee_missing"]
},
"listing": {
"status": "draft",
"placement_fee": null,
"photo_count": 0
},
"created_at": "2026-10-09T08:00:00Z",
"updated_at": "2026-10-09T08:00:00Z",
"version": 1
}LeadList
| Field | Type | Required | Description |
|---|---|---|---|
object | "list" (exactly) | required | |
data | array of Lead | required | |
has_more | boolean | required | |
next_cursor | string or null | required | Pass as |
LeadCreate
One creator. Required are only her name and consent_confirmed, as in the portal; send every other field
you know (a contact and her platforms make her far easier to place). Unknown fields → 400 unknown_field.
Strings are trimmed before they are checked; lengths count after trimming. null for an optional field is
the same as leaving it out (not for platforms: leave it out instead).
| Field | Type | Required | Description |
|---|---|---|---|
external_id | string or null · 1–100 chars | optional | Your own reference, unique within your account. Repeating it returns the existing lead ( |
creator_name | string · 1–120 chars | required | Name or alias. |
instagram_handle | string or null · 1–200 chars | optional | Username ( |
other_contact | string or null · 1–200 chars | optional | Any other way to reach her (Telegram, phone, …). |
platforms | array of string · at least 1, at most 20, each 1–40 chars | optional | Platforms she is on; pick-list values are stored in their spelling. Allowed values. Optional; when sent, at least one entry. |
follower_count | integer or null (int32) · 0–2,147,483,647 | optional | Followers on her largest platform. |
niche | string or null · 1–80 chars | optional | A pick-list niche is stored in its spelling. Allowed values. |
notes | string or null · 1–2000 chars | optional | For our team; never shown to agencies. |
consent_confirmed | true (exactly) | required | Your declaration that she agreed to be referred and to you sending these details. Must be exactly |
listing | ListingPatch | optional | Listing fields. Every field is optional; |
LeadUpdate
Send only the fields to change; null clears an optional field. Lead fields while can_edit_lead; external_id always.
| Field | Type | Required | Description |
|---|---|---|---|
external_id | string or null · 1–100 chars | optional | |
creator_name | string · 1–120 chars | optional | |
instagram_handle | string or null · 1–200 chars | optional | |
other_contact | string or null · 1–200 chars | optional | |
platforms | array of string · at least 1, at most 20, each 1–40 chars | optional | |
follower_count | integer or null (int32) · 0–2,147,483,647 | optional | |
niche | string or null · 1–80 chars | optional | |
notes | string or null · 1–2000 chars | optional |
ListingPatch
Listing fields. Every field is optional; null clears a value, [] empties a list.
| Field | Type | Required | Description |
|---|---|---|---|
age | integer or null · 18–99 | optional | Below 18 → |
gender | string or null · one of female, male, trans, non_binary, other | optional | |
origin_country | string or null · 1–80 chars | optional | |
languages | array of string · at most 20, each 1–40 chars | optional | |
english_level | integer or null · 1–10 | optional | |
content_types | array of string · at most 30, each 1–40 chars | optional | Content categories she is comfortable with. Values: allowed values. |
content_freetext | string or null · 1–2000 chars | optional | |
has_of_account | boolean or null | optional | |
of_verified | boolean or null | optional | |
of_current_earnings | integer or null · 0–2,147,483,647 | optional | USD per month. |
content_ready | boolean or null | optional | |
scripts_ready | boolean or null | optional | |
account_access | string or null · one of yes, no, undiscussed | optional | |
device | string or null · 1–200 chars | optional | |
social_status | string or null · one of none, ready_to_create, existing | optional | |
social_preferences | object | optional | Platform (1–40 characters) → wants to be active there; at most 20 entries. |
tiktok_ok | boolean or null | optional | |
blocked_countries | array of string · at most 250, each 1–80 chars | optional | |
start_availability | string or null · one of now, date | optional | |
start_date | string or null (date) | optional | |
availability_hours_per_week | number or null · 0–168 | optional | |
availability_hours_per_day | number or null · 0–24 | optional | |
compensation_model | string or null · one of revenue_share, fixed | optional | |
creator_share_percent | integer or null · 0–100 | optional | |
fixed_salary | integer or null · 0–2,147,483,647 | optional | |
salary_period | string or null · one of weekly, monthly | optional | |
placement_fee | MoneyInput | optional |
|
notes_public | string or null · 1–2000 chars | optional | Shown to agencies with the listing. |
Listing
| Field | Type | Required | Description |
|---|---|---|---|
object | "listing" (exactly) | required | |
lead | string | required | |
status | string | required |
|
age | integer or null | required | |
gender | string or null | required | |
origin_country | string or null | required | |
languages | array of string | required | |
english_level | integer or null | required | |
content_types | array of string | required | |
content_freetext | string or null | required | |
has_of_account | boolean or null | required | |
of_verified | boolean or null | required | |
of_current_earnings | integer or null | required | |
content_ready | boolean or null | required | |
scripts_ready | boolean or null | required | |
account_access | string or null | required | |
device | string or null | required | |
social_status | string or null | required | |
social_preferences | object | required | |
tiktok_ok | boolean or null | required | |
blocked_countries | array of string | required | |
start_availability | string or null | required | |
start_date | string or null (date) | required | |
availability_hours_per_week | number or null | required | |
availability_hours_per_day | number or null | required | |
compensation_model | string or null | required | |
creator_share_percent | integer or null | required | |
fixed_salary | integer or null | required | |
salary_period | string or null | required | |
placement_fee | Money | required | An amount in integer minor units (cents) and its ISO 4217 currency; |
notes_public | string or null | required | |
updated_at | string or null (date-time) | required |
LeadConsent
Her consent and her personal consent link. Links are stored only as hashes, so url is shown once: in the 201 that created the lead (a new link, valid at least 30 days). A 200 of POST /v1/leads and GET /v1/leads/{id} answer url: null with the current expires_at; POST /v1/leads/{id}/consent-link makes a new link. Reading a lead never extends it.
| Field | Type | Required | Description |
|---|---|---|---|
status | string | required |
|
url | string or null (uri) | required | Her personal page on app.creator-guard.com — only in the |
expires_at | string or null (date-time) | required | When her current link stops working; a new one: |
ConsentLink
| Field | Type | Required | Description |
|---|---|---|---|
object | "consent_link" (exactly) | required | |
lead | string | required | |
url | string (uri) | required | Her personal page on app.creator-guard.com — a new link; the previous one can then only be used to withdraw consent. Shown only in this answer. |
expires_at | string (date-time) | required |
ClaimLink
| Field | Type | Required | Description |
|---|---|---|---|
object | "claim_link" (exactly) | required | |
lead | string | required | |
url | string or null (uri) | required | Her single-use page on app.creator-guard.com ( |
expires_at | string (date-time) | required |
Timeline
| Field | Type | Required | Description |
|---|---|---|---|
object | "timeline" (exactly) | required | |
lead | string | required | |
events | array of object | required | Oldest first; only milestones that happened (or, for |
Earnings
| Field | Type | Required | Description |
|---|---|---|---|
object | "earnings" (exactly) | required | |
lead | string | required | |
fee | Money | required | An amount in integer minor units (cents) and its ISO 4217 currency; |
creator_guard_amount | Money | required | An amount in integer minor units (cents) and its ISO 4217 currency; |
your_amount | Money | required | An amount in integer minor units (cents) and its ISO 4217 currency; |
status | string or null | required |
|
AccountPatch
Send only what changes; the same fields and checks as the portal's profile page. Strings are trimmed first.
| Field | Type | Required | Description |
|---|---|---|---|
display_name | string · 1–120 chars | optional | The name agencies and creators see. |
company_name | string or null · 0–200 chars | optional |
|
telegram_username | string | optional |
|
website | string or null · 0–300 chars | optional | An |
LogoUpload
| Field | Type | Required | Description |
|---|---|---|---|
file | string (binary) | required | PNG, JPEG or WebP, at most 2 MB. |
ExtractRequest
| Field | Type | Required | Description |
|---|---|---|---|
text | string · 20–20000 chars | required | Any text about her: profile, chat, notes (at least 20 characters after trimming). Not stored. |
ExtractResult
| Field | Type | Required | Description |
|---|---|---|---|
object | "extract_result" (exactly) | required | |
suggestions | object | required | Only fields the text supports, each already valid under the rules of |
PhotoUpload
| Field | Type | Required | Description |
|---|---|---|---|
file | string (binary) | required | JPEG, PNG or WebP; at most 40 MB and 50 megapixels. Exactly one file part. |
kind | string · one of portrait, body, content_sample, non_nude, lingerie, professional | optional | Default |
is_primary | string · one of true, false | optional |
|
PhotoPatch
| Field | Type | Required | Description |
|---|---|---|---|
kind | string · one of portrait, body, content_sample, non_nude, lingerie, professional | optional | |
is_primary | true (exactly) | optional | Makes this her primary photo. Only |
PhotoList
Every photo of the lead (at most 20) on one page: has_more is always false.
| Field | Type | Required | Description |
|---|---|---|---|
object | "list" (exactly) | required | |
data | array of Photo | required | |
has_more | boolean | required | |
next_cursor | string or null | required |
LeadSummary
The short lead object of ?expand=lead.
| Field | Type | Required | Description |
|---|---|---|---|
object | "lead" (exactly) | required | |
id | string | required | |
creator_name | string | required | |
creator_ref | string or null | required | |
stage | string | required |
Commission
| Field | Type | Required | Description |
|---|---|---|---|
object | "commission" (exactly) | required | |
id | string | required | |
lead | string or LeadSummary | required | The lead id ( |
creator_ref | string or null | required | |
status | string | required |
|
fee_total | Money | required | An amount in integer minor units (cents) and its ISO 4217 currency; |
creator_guard_amount | Money | required | An amount in integer minor units (cents) and its ISO 4217 currency; |
your_amount | Money | required | An amount in integer minor units (cents) and its ISO 4217 currency; |
created_at | string or null (date-time) | required | |
paid_at | string or null (date-time) | required | |
version | integer · ≥ 0 | required | Grows with every change; events about it carry the same number as |
CommissionList
| Field | Type | Required | Description |
|---|---|---|---|
object | "list" (exactly) | required | |
data | array of Commission | required | |
has_more | boolean | required | |
next_cursor | string or null | required |
PayoutDetails
All three are null until you save payout details in the portal.
| Field | Type | Required | Description |
|---|---|---|---|
object | "payout_details" (exactly) | required | |
method | string or null | required |
|
destination_masked | string or null | required | The destination with all but a few characters hidden. |
updated_at | string or null (date-time) | required |
ApiKey
| Field | Type | Required | Description |
|---|---|---|---|
object | "api_key" (exactly) | required | |
id | string | required | |
mode | string | required |
|
label | string or null | required | |
prefix | string | required | The start of the key, e.g. |
scopes | array of string | required | |
ip_allowlist | array of string | required | CIDR blocks; empty = any address. |
expires_at | string or null (date-time) | required | Its expiry, capped by your key policy's maximum age. |
grace_until | string or null (date-time) | required | Set on a key that was rolled: it works until then. |
last_used_at | string or null (date-time) | required | |
created_at | string (date-time) | required | |
created_via | string | required |
|
revoked_at | string or null (date-time) | required | |
rolled_from | string or null | required | The key ( |
secret | string or null | optional | The full key. Only in the answer that made it (create, roll) — |
ApiKeyCreate
| Field | Type | Required | Description |
|---|---|---|---|
label | string or null · 0–100 chars | optional | Trimmed; empty = no label. |
scopes | array of Scope · at least 1 | required | Only scopes the calling key has (else |
ip_allowlist | array of string · at most 20 | optional | CIDR blocks with the host bits zero, e.g. |
expires_at | string or null (date-time) | optional | In the future; capped by your key policy's maximum age. |
ApiKeyRoll
| Field | Type | Required | Description |
|---|---|---|---|
grace_hours | integer or null · 0–72 | optional | How long the old key keeps working (default 24; |
ApiKeyList
The active keys and those revoked in the last 90 days, on one page.
| Field | Type | Required | Description |
|---|---|---|---|
object | "list" (exactly) | required | |
data | array of ApiKey | required | |
has_more | boolean | required | |
next_cursor | string or null | required |
RequestLog
| Field | Type | Required | Description |
|---|---|---|---|
object | "request_log" (exactly) | required | |
id | string | required | The request id ( |
method | string | required | |
route | string | required | Route template, e.g. |
status | integer | required | |
error_code | string or null | required | |
key | string or null | required | Key id ( |
duration_ms | integer | required | |
created_at | string (date-time) | required |
RequestLogList
| Field | Type | Required | Description |
|---|---|---|---|
object | "list" (exactly) | required | |
data | array of RequestLog | required | |
has_more | boolean | required | |
next_cursor | string or null | required |
Usage
| Field | Type | Required | Description |
|---|---|---|---|
object | "usage" (exactly) | required | |
from | string (date) | required | |
to | string (date) | required | |
granularity | string | required |
|
mode | string | required |
|
series | array of object | required | One entry per UTC day of the range. |
by_route | array of object | required | |
by_key | array of object | required |
AuditEvent
| Field | Type | Required | Description |
|---|---|---|---|
object | "audit_event" (exactly) | required | |
id | string | required | |
action | string | required | e.g. |
actor | object | required | |
target | object or null | required | |
mode | string or null | required |
|
ip | string or null | required | |
user_agent | string or null | required | |
details | object | required | What changed (names and new values; never secrets or creator data). |
created_at | string (date-time) | required |
AuditEventList
| Field | Type | Required | Description |
|---|---|---|---|
object | "list" (exactly) | required | |
data | array of AuditEvent | required | |
has_more | boolean | required | |
next_cursor | string or null | required |
EventType
The event types of the catalogue. New types may be added; ping is sent only by a test send and cannot be subscribed to.
| Field | Type | Required | Description |
|---|
Event
One change. data.object is the object as your account may see it when the event is read or delivered; its object tells which schema: Lead, Photo, Confirmations, Commission, Agreement, ApiKey, WebhookEndpoint, Offer, Reservation, a reference DataRequestRef or JobRef (creator-side events: never her data), or {} for ping. An object that no longer exists is {"id": …, "object": …, "deleted": true} (a removed photo: the photo as it was, url null). New types may be added.
| Field | Type | Required | Description |
|---|---|---|---|
object | "event" (exactly) | required | |
id | string | required | |
type | string | required | |
created_at | string (date-time) | required | |
mode | string | required |
|
api_version | string | required | The contract version that rendered the payload. |
sequence | integer | required | The |
data | object | required | |
previous_attributes | object | optional | Only on events about a change: what changed, by contract field name (listing fields under |
EventList
| Field | Type | Required | Description |
|---|---|---|---|
object | "list" (exactly) | required | |
data | array of Event | required | |
has_more | boolean | required | |
next_cursor | string or null | required |
WebhookEndpoint
| Field | Type | Required | Description |
|---|---|---|---|
object | "webhook_endpoint" (exactly) | required | |
id | string | required | |
url | string (uri) | required | |
description | string or null | required | |
event_types | array of string | required | The subscribed types, or |
enabled | boolean | required | |
disabled_reason | string or null | required |
|
created_at | string (date-time) | required | |
updated_at | string (date-time) | required | |
secret | string or null | optional |
|
WebhookEndpointCreate
| Field | Type | Required | Description |
|---|---|---|---|
url | string · 0–2048 chars | required | https on port 443, no credentials, a host that resolves to public addresses only. |
event_types | array of string · at least 1, at most 32 | required |
|
description | string or null · 0–500 chars | optional |
WebhookEndpointUpdate
Send only what changes. Enabling an endpoint that was disabled as failing restarts its failure clock.
| Field | Type | Required | Description |
|---|---|---|---|
url | string · 0–2048 chars | optional | |
event_types | array of string · at least 1, at most 32 | optional | |
description | string or null · 0–500 chars | optional | |
enabled | boolean | optional |
WebhookEndpointList
Every endpoint of this mode (at most 10) on one page.
| Field | Type | Required | Description |
|---|---|---|---|
object | "list" (exactly) | required | |
data | array of WebhookEndpoint | required | |
has_more | boolean | required | |
next_cursor | string or null | required |
WebhookReplay
| Field | Type | Required | Description |
|---|---|---|---|
from | string (date-time) | required | At most 30 days ago. |
to | string or null (date-time) | optional | After |
ReplayResult
| Field | Type | Required | Description |
|---|---|---|---|
object | "webhook_replay" (exactly) | required | |
endpoint | string | required | |
from | string (date-time) | required | |
to | string (date-time) | required | |
queued | integer | required | Deliveries queued (a range that would pass 1,000 open deliveries → |
WebhookDelivery
| Field | Type | Required | Description |
|---|---|---|---|
object | "webhook_delivery" (exactly) | required | |
id | string | required | |
event | string | required | Event id ( |
event_type | string | required | |
status | string | required |
|
attempt | integer | required | |
next_attempt_at | string or null (date-time) | required | |
last_status | integer or null | required | HTTP status your endpoint answered. |
last_error | string or null | required | Why the last attempt failed (a short code, e.g. a timeout); |
replay | boolean | required | |
created_at | string (date-time) | required | |
completed_at | string or null (date-time) | required | |
attempts | array of object | required |
WebhookDeliveryList
| Field | Type | Required | Description |
|---|---|---|---|
object | "list" (exactly) | required | |
data | array of WebhookDelivery | required | |
has_more | boolean | required | |
next_cursor | string or null | required |
TestLeadReject
| Field | Type | Required | Description |
|---|---|---|---|
outcome_reason | string · one of profile_mismatch, not_reachable, duplicate, quality, capacity, other | required |
TestReset
| Field | Type | Required | Description |
|---|---|---|---|
object | "sandbox_reset" (exactly) | required | |
mode | "test" (exactly) | required | |
deleted | object | required |
LeadEvent
An event whose data.object is a Lead — or {"id": …, "object": …, "deleted": true} when it no longer exists.
| Field | Type | Required | Description |
|---|---|---|---|
object | "event" (exactly) | required | |
id | string | required | |
type | string | required | |
created_at | string (date-time) | required | |
mode | string | required | |
api_version | string | required | |
sequence | integer | required | |
data | object | required | |
previous_attributes | object | optional | Only on events about a change; see Event. |
PhotoEvent
An event whose data.object is a Photo; for photo.removed the photo as it was, with url null.
| Field | Type | Required | Description |
|---|---|---|---|
object | "event" (exactly) | required | |
id | string | required | |
type | string | required | |
created_at | string (date-time) | required | |
mode | string | required | |
api_version | string | required | |
sequence | integer | required | |
data | object | required | |
previous_attributes | object | optional | Only on events about a change; see Event. |
ConfirmationsEvent
An event whose data.object is a Confirmations — or {"id": …, "object": …, "deleted": true} when it no longer exists.
| Field | Type | Required | Description |
|---|---|---|---|
object | "event" (exactly) | required | |
id | string | required | |
type | string | required | |
created_at | string (date-time) | required | |
mode | string | required | |
api_version | string | required | |
sequence | integer | required | |
data | object | required | |
previous_attributes | object | optional | Only on events about a change; see Event. |
CommissionEvent
An event whose data.object is a Commission — or {"id": …, "object": …, "deleted": true} when it no longer exists.
| Field | Type | Required | Description |
|---|---|---|---|
object | "event" (exactly) | required | |
id | string | required | |
type | string | required | |
created_at | string (date-time) | required | |
mode | string | required | |
api_version | string | required | |
sequence | integer | required | |
data | object | required | |
previous_attributes | object | optional | Only on events about a change; see Event. |
AgreementEvent
An event whose data.object is an Agreement — or {"id": …, "object": …, "deleted": true} when it no longer exists.
| Field | Type | Required | Description |
|---|---|---|---|
object | "event" (exactly) | required | |
id | string | required | |
type | string | required | |
created_at | string (date-time) | required | |
mode | string | required | |
api_version | string | required | |
sequence | integer | required | |
data | object | required | |
previous_attributes | object | optional | Only on events about a change; see Event. |
ApiKeyEvent
An event whose data.object is an ApiKey — or {"id": …, "object": …, "deleted": true} when it no longer exists.
| Field | Type | Required | Description |
|---|---|---|---|
object | "event" (exactly) | required | |
id | string | required | |
type | string | required | |
created_at | string (date-time) | required | |
mode | string | required | |
api_version | string | required | |
sequence | integer | required | |
data | object | required | |
previous_attributes | object | optional | Only on events about a change; see Event. |
WebhookEndpointEvent
An event whose data.object is a WebhookEndpoint — or {"id": …, "object": …, "deleted": true} when it no longer exists.
| Field | Type | Required | Description |
|---|---|---|---|
object | "event" (exactly) | required | |
id | string | required | |
type | string | required | |
created_at | string (date-time) | required | |
mode | string | required | |
api_version | string | required | |
sequence | integer | required | |
data | object | required | |
previous_attributes | object | optional | Only on events about a change; see Event. |
PingEvent
The event of a test send: data.object is empty, sequence is 0.
| Field | Type | Required | Description |
|---|---|---|---|
object | "event" (exactly) | required | |
id | string | required | |
type | "ping" (exactly) | required | |
created_at | string (date-time) | required | |
mode | string | required | |
api_version | string | required | |
sequence | integer | required | |
data | object | required |
UsdInput
An amount in US dollars as integer cents: {"amount_minor": 300000, "currency": "USD"} = 3,000.00 USD. Another currency is 400 invalid_field on <field>.currency; null clears the value.
| Field | Type | Required | Description |
|---|---|---|---|
amount_minor | integer · ≥ 0 | required | |
currency | "USD" (exactly) | required |
Flex
Where a creator may be near your criteria instead of matching exactly. A key that is present means "may deviate" (a creator just outside counts as a near match); a missing key means "must match". Levels are the presets of the portal: age 3, 8 or 20 (years outside your range), revenue "zero", 50 or 100 (percent), english 3, 5 or "any", fee 25, 50 or 100 (percent above your maximum fee), split 10, 20 or 30 (points above your maximum creator share), stage "opposite". In the four list keys also holds other values that are fine; [] means anything else is close too.
| Field | Type | Required | Description |
|---|---|---|---|
age | object | optional | |
revenue | object | optional | |
english | object | optional | |
fee | object | optional | |
split | object | optional | |
stage | object | optional | |
niches | object | optional | |
platforms | object | optional | |
content_types | object | optional | |
languages | object | optional |
FlexInput
The flex you send: only the preset levels (anything else is 400 invalid_field with field: "flex.<key>"); values in also that repeat your primary selection are dropped. null = the portal default.
| Field | Type | Required | Description |
|---|---|---|---|
age | object | optional | |
revenue | object | optional | |
english | object | optional | |
fee | object | optional | |
split | object | optional | |
stage | object | optional | |
niches | object | optional | |
platforms | object | optional | |
content_types | object | optional | |
languages | object | optional |
SearchProfile
What we match creators against before we offer them to you. Before your first PUT the defaults (updated_at: null).
| Field | Type | Required | Description |
|---|---|---|---|
object | "search_profile" (exactly) | required | |
niches | array of string | required | |
platforms | array of string | required | |
languages | array of string | required | |
content_types | array of string | required | |
age_min | integer or null | required | |
age_max | integer or null | required | |
english_level_min | integer or null | required | |
revenue_min | Money | required | An amount in integer minor units (cents) and its ISO 4217 currency; |
revenue_max | Money | required | An amount in integer minor units (cents) and its ISO 4217 currency; |
max_placement_fee | Money | required | An amount in integer minor units (cents) and its ISO 4217 currency; |
creator_share_max_percent | integer or null | required | |
creator_stage | string | required |
|
countries_excluded | array of string | required | |
capacity_per_month | integer or null | required | |
notes | string or null | required | |
flex | Flex | required | Where a creator may be near your criteria instead of matching exactly. A key that is present means "may deviate" (a creator just outside counts as a near match); a missing key means "must match". Levels are the presets of the portal: |
updated_at | string or null (date-time) | required |
SearchProfilePut
Full replacement: every field is optional, and a field you leave out goes back to its default ([], null, creator_stage: "both", the portal flex). Pick-list values are stored in the pick-list spelling. Money is US dollars only; revenue_* in whole dollars (amount_minor a multiple of 100).
| Field | Type | Required | Description |
|---|---|---|---|
niches | array of string · at most 50, each 0–100 chars | optional | |
platforms | array of string · at most 50, each 0–100 chars | optional | |
languages | array of string · at most 50, each 0–100 chars | optional | |
content_types | array of string · at most 50, each 0–100 chars | optional | |
age_min | integer or null · 18–99 | optional | |
age_max | integer or null · 18–99 | optional | Not below |
english_level_min | integer or null · 1–10 | optional | |
revenue_min | UsdInput | optional | An amount in US dollars as integer cents: |
revenue_max | UsdInput | optional | An amount in US dollars as integer cents: |
max_placement_fee | UsdInput | optional | An amount in US dollars as integer cents: |
creator_share_max_percent | integer or null · 0–100 | optional | |
creator_stage | string or null · one of beginners, earning, both | optional | |
countries_excluded | array of string · at most 50, each 0–100 chars | optional | |
capacity_per_month | integer or null · 0–1,000 | optional | |
notes | string or null · 1–2000 chars | optional | |
flex | FlexInput | optional | The |
AgencyProfile
Your agency's public facts. tier (A, B, C or unranked) and verified_revenue are set by Creator Guard.
| Field | Type | Required | Description |
|---|---|---|---|
object | "agency_profile" (exactly) | required | |
country | string or null | required | |
website | string or null | required | |
team_size | integer or null | required | |
years_active | number or null | required | |
monthly_revenue | Money | required | An amount in integer minor units (cents) and its ISO 4217 currency; |
managed_creators_count | integer or null | required | |
specialization | array of string | required | |
references | string or null | required | |
tier | string | required | |
verified_revenue | Money | required | An amount in integer minor units (cents) and its ISO 4217 currency; |
vetting | AgencyVetting | required | Read-only, set by Creator Guard: where the 5-point vetting of your agency stands. Your agency receives offers with a creator's profile only once |
updated_at | string or null (date-time) | required |
AgencyVetting
Read-only, set by Creator Guard: where the 5-point vetting of your agency stands. Your agency receives offers with a creator's profile only once status is vetted; before that a creator who matches your search profile waits (waiting_matches) and her offer arrives when the vetting is done. The sandbox (test keys) always reports vetted with waiting_matches: 0.
| Field | Type | Required | Description |
|---|---|---|---|
status | string | required | One of |
waiting_matches | integer · ≥ 0 | required | Creators matched to your agency who wait for your vetting. A count only. |
AgencyProfilePatch
Only the fields you send change; null clears one (specialization: send []). tier, verified_revenue and vetting cannot be sent (400 unknown_field).
| Field | Type | Required | Description |
|---|---|---|---|
country | string or null · 1–100 chars | optional | |
website | string or null · 0–300 chars | optional | An |
team_size | integer or null · 0–100,000 | optional | |
years_active | number or null · 0–99.9 | optional | At most one decimal, e.g. |
monthly_revenue | UsdInput | optional | An amount in US dollars as integer cents: |
managed_creators_count | integer or null · 0–100,000 | optional | |
specialization | array of string · at most 20, each 0–100 chars | optional | |
references | string or null · 1–2000 chars | optional |
OfferListing
The creator's listing as agencies see it — the fields of Listing without its lead, status and the referrer's data. placement_fee is the price of this offer.
| Field | Type | Required | Description |
|---|---|---|---|
object | "listing" (exactly) | required | |
age | integer or null | required | |
gender | string or null | required | |
origin_country | string or null | required | |
languages | array of string | required | |
english_level | integer or null | required | |
content_types | array of string | required | |
content_freetext | string or null | required | |
has_of_account | boolean or null | required | |
of_verified | boolean or null | required | |
of_current_earnings | integer or null | required | |
content_ready | boolean or null | required | |
scripts_ready | boolean or null | required | |
account_access | string or null | required | |
device | string or null | required | |
social_status | string or null | required | |
social_preferences | object | required | |
tiktok_ok | boolean or null | required | |
blocked_countries | array of string | required | |
start_availability | string or null | required | |
start_date | string or null (date) | required | |
availability_hours_per_week | number or null | required | |
availability_hours_per_day | number or null | required | |
compensation_model | string or null | required | |
creator_share_percent | integer or null | required | |
fixed_salary | integer or null | required | |
salary_period | string or null | required | |
placement_fee | Money | required | An amount in integer minor units (cents) and its ISO 4217 currency; |
notes_public | string or null | required | |
updated_at | string or null (date-time) | required |
OfferNextActions
What you can do with the offer now — so you never re-implement the rules.
| Field | Type | Required | Description |
|---|---|---|---|
can_accept | boolean | required | |
can_decline | boolean | required | |
can_undo_accept | boolean | required | |
can_mark_contacted | boolean | required | |
can_mark_in_talks | boolean | required | |
can_mark_signed | boolean | required | |
can_mark_lost | boolean | required |
ReservationSummary
The reservation your accept created; the whole object: GET /v1/reservations/{id}.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | required | |
status | string | required |
|
amount | Money | required | An amount in integer minor units (cents) and its ISO 4217 currency; |
payment_reference | string or null | required | |
payment_due_at | string or null (date-time) | required | |
paid_at | string or null (date-time) | required | |
warranty_until | string or null (date-time) | required |
Offer
A creator we offered to your agency. Never her contact details, the referrer or internal notes — the contact comes with GET /v1/reservations/{id}/creator after payment. Her name too only after payment; until then she is her creator number (creator_ref). New fields may be added within v1.
| Field | Type | Required | Description |
|---|---|---|---|
object | "offer" (exactly) | required | |
id | string | required | |
status | string | required |
|
creator_name | string or null | required |
|
creator_ref | string or null | required | Her creator number, e.g. |
expires_at | string or null (date-time) | required | The deadline to accept or decline. |
accepted_at | string or null (date-time) | required | |
undo_until | string or null (date-time) | required | Until when |
agency_note | string or null | required | |
outcome_reason | string or null | required | Set on |
listing | OfferListing or null | required |
|
photo_count | integer or null | required | Photos she agreed to share; |
reservation | ReservationSummary or null | required | |
next_actions | OfferNextActions | required | What you can do with the offer now — so you never re-implement the rules. |
match | OfferMatch or null | required | How well she fits your search profile ( |
created_at | string (date-time) | required | |
updated_at | string (date-time) | required |
OfferList
| Field | Type | Required | Description |
|---|---|---|---|
object | "list" (exactly) | required | |
data | array of Offer | required | |
has_more | boolean | required | |
next_cursor | string or null | required |
OfferMatch
The match of an offer against your search profile. Criteria you left empty are not checked.
| Field | Type | Required | Description |
|---|---|---|---|
score | number · ≥ 0 | required | Criteria met; a close match (within the tolerance you allowed, or a value she has not filled in yet) counts ½. Sort by score / total, knocked-out offers last. |
total | integer · ≥ 1 | required | Criteria checked. |
knocked_out | boolean | required |
|
criteria | array of OfferMatchCriterion | required |
OfferMatchCriterion
| Field | Type | Required | Description |
|---|---|---|---|
key | string | required |
|
result | string | required |
|
must | boolean | required | Must match: a miss knocks her out. |
OfferPhoto
| Field | Type | Required | Description |
|---|---|---|---|
object | "photo" (exactly) | required | |
id | string | required | |
kind | string | required | |
is_primary | boolean | required | |
url | string or null | required | Signed link, valid for one hour. |
url_expires_at | string or null (date-time) | required |
OfferPhotoList
| Field | Type | Required | Description |
|---|---|---|---|
object | "list" (exactly) | required | |
data | array of OfferPhoto | required | |
has_more | boolean | required | Always |
next_cursor | string or null | required |
OfferPatch
| Field | Type | Required | Description |
|---|---|---|---|
agency_note | string or null · 1–500 chars | required | Your note (trimmed); |
OfferDecline
| Field | Type | Required | Description |
|---|---|---|---|
note | string · 50–500 chars | required | Why she is not a fit, 50–500 characters after trimming. |
OfferMarkLost
| Field | Type | Required | Description |
|---|---|---|---|
outcome_reason | string · one of profile_mismatch, not_reachable, duplicate, quality, capacity, other | required |
WarrantyClaim
| Field | Type | Required | Description |
|---|---|---|---|
reason | string | required | |
note | string or null | required | |
filed_at | string or null (date-time) | required |
ReservationNextActions
| Field | Type | Required | Description |
|---|---|---|---|
can_file_warranty_claim | boolean | required | |
can_view_creator | boolean | required |
Reservation
What your accept reserved: the fee to transfer, its payment reference and due date, then payment, warranty and your warranty claim. New fields may be added within v1.
| Field | Type | Required | Description |
|---|---|---|---|
object | "reservation" (exactly) | required | |
id | string | required | |
offer | string or null | required | The offer ( |
status | string | required |
|
creator_name | string or null | required |
|
creator_ref | string or null | required | |
amount | Money | required | An amount in integer minor units (cents) and its ISO 4217 currency; |
payment_reference | string | required | Put it on your bank transfer. |
payment_due_at | string or null (date-time) | required | |
paid_at | string or null (date-time) | required | |
warranty_until | string or null (date-time) | required | |
completed_at | string or null (date-time) | required | |
refunded_at | string or null (date-time) | required | |
warranty_claim | WarrantyClaim or null | required | |
next_actions | ReservationNextActions | required | |
created_at | string or null (date-time) | required | |
updated_at | string or null (date-time) | required |
ReservationList
| Field | Type | Required | Description |
|---|---|---|---|
object | "list" (exactly) | required | |
data | array of Reservation | required | |
has_more | boolean | required | |
next_cursor | string or null | required |
ReservationCreator
Her contact, after payment only. Never the referrer, internal notes or her consent records.
| Field | Type | Required | Description |
|---|---|---|---|
object | "reservation_creator" (exactly) | required | |
reservation | string | required | |
creator_name | string | required | |
creator_ref | string or null | required | |
instagram_handle | string or null | required | |
other_contact | string or null | required | |
platforms | array of string | required | |
follower_count | integer or null | required | |
niche | string or null | required |
WarrantyClaimCreate
| Field | Type | Required | Description |
|---|---|---|---|
reason | string · one of creator_unreachable, no_show, false_data, contract_refused, other | required | |
note | string or null · 0–2000 chars | optional | Trimmed; blank counts as no note. |
TestOfferCreate
Every field is optional.
| Field | Type | Required | Description |
|---|---|---|---|
creator_name | string · 1–120 chars | optional | Default: a generated test name. The offer shows it only after |
placement_fee | MoneyInput | optional |
|
expires_in_hours | integer · 1–720 | optional | Default: the offer deadline of |
TestReservationRefund
| Field | Type | Required | Description |
|---|---|---|---|
reason | string · one of creator_unreachable, no_show, false_data, contract_refused, other | optional | Default: the reason of your warranty claim, else |
ClockAdvance
| Field | Type | Required | Description |
|---|---|---|---|
hours | integer · 1–720 | required |
ClockAdvanceResult
| Field | Type | Required | Description |
|---|---|---|---|
object | "clock_advance" (exactly) | required | |
hours | integer | required | |
expired_offers | integer | required | |
cancelled_reservations | integer | required | |
completed_reservations | integer | required |
OfferEvent
An event whose data.object is an Offer — or {"id": …, "object": …, "deleted": true} when it no longer exists.
| Field | Type | Required | Description |
|---|---|---|---|
object | "event" (exactly) | required | |
id | string | required | |
type | string | required | |
created_at | string (date-time) | required | |
mode | string | required | |
api_version | string | required | |
sequence | integer | required | |
data | object | required | |
previous_attributes | object | optional | Only on events about a change; see Event. |
ReservationEvent
An event whose data.object is a Reservation — or {"id": …, "object": …, "deleted": true} when it no longer exists.
| Field | Type | Required | Description |
|---|---|---|---|
object | "event" (exactly) | required | |
id | string | required | |
type | string | required | |
created_at | string (date-time) | required | |
mode | string | required | |
api_version | string | required | |
sequence | integer | required | |
data | object | required | |
previous_attributes | object | optional | Only on events about a change; see Event. |
CreatorScope
What a creator lets an OAuth app do for her (request values; new scopes may be added). An app asks for a subset of its registered scopes.
| Field | Type | Required | Description |
|---|
OAuthApp
| Field | Type | Required | Description |
|---|---|---|---|
object | "oauth_app" (exactly) | required | |
id | string | required | |
mode | string | required |
|
client_id | string | required | Public; sent to |
name | string | required | Shown to the creator on the consent screen. |
logo_url | string or null (uri) | required | |
privacy_url | string (uri) | required | |
redirect_uris | array of string | required | Matched exactly, character for character. Empty only while the app is disabled. |
scopes | array of string | required | Creator scopes (CreatorScope). |
confidential | boolean | required |
|
secret_prefix | string or null | required | The start of the current client secret, e.g. |
enabled | boolean | required |
|
disabled_reason | string or null | required |
|
created_at | string (date-time) | required | |
updated_at | string (date-time) | required | |
client_secret | string or null | optional |
|
OAuthAppCreate
| Field | Type | Required | Description |
|---|---|---|---|
name | string · 3–60 chars | required | Trimmed. |
redirect_uris | array of string · at least 1, at most 10, each 0–2000 chars | required | Distinct; https, no fragment, no user info, no wildcard, no private or loopback host. Test keys may also use |
logo_url | string or null · 0–2000 chars | optional | |
privacy_url | string · 0–2000 chars | required | Your privacy policy, linked on the consent screen. |
scopes | array of CreatorScope · at least 1 | required | Distinct. |
confidential | boolean | required |
OAuthAppUpdate
Send only what changes. logo_url: null removes the logo.
| Field | Type | Required | Description |
|---|---|---|---|
name | string · 3–60 chars | optional | |
redirect_uris | array of string · at least 1, at most 10, each 0–2000 chars | optional | |
logo_url | string or null · 0–2000 chars | optional | |
privacy_url | string · 0–2000 chars | optional | |
scopes | array of CreatorScope · at least 1 | optional | |
confidential | boolean | optional | Only its current value; it cannot change. |
OAuthAppList
Every OAuth app of this mode (at most 10) on one page.
| Field | Type | Required | Description |
|---|---|---|---|
object | "list" (exactly) | required | |
data | array of OAuthApp | required | |
has_more | boolean | required | |
next_cursor | string or null | required |
OAuthTestCodeCreate
| Field | Type | Required | Description |
|---|---|---|---|
client_id | string | required | A test-mode app of your account. |
lead_id | string | required | A sandbox lead you may connect (you submitted it, or you hold a paid reservation for it). |
redirect_uri | string · 0–2000 chars | required | One of the app's registered redirect URIs, character for character. |
scopes | array of CreatorScope · at least 1 | required | A subset of the app's scopes; repeats are ignored. |
code_challenge | string | required | BASE64URL(SHA256(code_verifier)) without padding (PKCE S256). |
OAuthTestCode
| Field | Type | Required | Description |
|---|---|---|---|
object | "oauth_test_code" (exactly) | required | |
code | string | required | The authorization code; exchange it at |
expires_in | 60 (exactly) | required | Seconds. |
Creator
| Field | Type | Required | Description |
|---|---|---|---|
object | "creator" (exactly) | required | |
lead | string | required | Her lead. |
creator_name | string | required | |
stage | string | required | Same stages as |
next_actions | object | required | |
placement | object or null | required | The agency she was placed with, once it paid; |
updated_at | string or null (date-time) | required |
CreatorProfile
Her contact fields and the listing fields she edits herself. Never fees, deal terms or of_verified.
| Field | Type | Required | Description |
|---|---|---|---|
object | "creator_profile" (exactly) | required | |
lead | object | required | |
listing | object | required | |
can_edit_lead | boolean | required | Contact fields can change while the lead is |
can_edit_listing | boolean | required | Listing fields can change until the listing is live (else |
updated_at | string or null (date-time) | required |
CreatorProfilePatch
Send only what changes; null clears a value. Any other field (fees, deal terms, of_verified, partner fields) is 400 unknown_field.
| Field | Type | Required | Description |
|---|---|---|---|
lead | object | optional | |
listing | object | optional |
CreatorPhoto
| Field | Type | Required | Description |
|---|---|---|---|
object | "photo" (exactly) | required | |
id | string | required | |
lead | string | required | |
kind | string | required | |
is_primary | boolean | required | |
consent_status | string | required | |
url | string or null (uri) | required | Signed, valid for 1 hour; |
url_expires_at | string or null (date-time) | required | |
created_at | string or null (date-time) | required |
CreatorPhotoList
| Field | Type | Required | Description |
|---|---|---|---|
object | "list" (exactly) | required | |
data | array of CreatorPhoto | required | |
has_more | boolean | required | |
next_cursor | string or null | required |
CreatorConsentEvent
One entry of her consent ledger. Never carries her IP address or browser.
| Field | Type | Required | Description |
|---|---|---|---|
object | "consent_event" (exactly) | required | |
id | string | required | |
kind | string | required |
|
text_kind | string | required | |
text_version | integer | required | |
channel | string or null | required | Where she decided: |
created_at | string (date-time) | required |
CreatorConsentState
| Field | Type | Required | Description |
|---|---|---|---|
object | "consent_state" (exactly) | required | |
consent | object | required | |
age_confirmation | object | required | |
events | array of CreatorConsentEvent | required | Oldest first. |
ConsentText
| Field | Type | Required | Description |
|---|---|---|---|
object | "consent_text" (exactly) | required | |
kind | string | required | |
version | integer | required | Send it as |
locale | string | required | |
body_md | string | required | Markdown. Show it to her in full before she decides. |
sha256 | string | required | |
published_at | string or null (date-time) | required |
ConsentDecision
The text version she was shown. Required for a grant and the 18+ confirmation (409 consent_text_outdated with current_version when it is not the current one); optional for a withdrawal, which is never refused because of the text.
| Field | Type | Required | Description |
|---|---|---|---|
text_version | integer · ≥ 1 | optional | |
locale | string | optional | The language of the text she saw, default |
CreatorAgreement
| Field | Type | Required | Description |
|---|---|---|---|
object | "creator_agreement" (exactly) | required | |
type | string | required | |
current_version | integer or null | required | |
accepted_version | integer or null | required | |
accepted_at | string or null (date-time) | required |
CreatorAgreementList
| Field | Type | Required | Description |
|---|---|---|---|
object | "list" (exactly) | required | |
data | array of CreatorAgreement | required | |
has_more | boolean | required | |
next_cursor | string or null | required |
CreatorTermsAccept
| Field | Type | Required | Description |
|---|---|---|---|
version | integer · ≥ 1 | required | The current version ( |
SupportTicket
| Field | Type | Required | Description |
|---|---|---|---|
object | "support_ticket" (exactly) | required | |
id | string | required | |
subject | string | required | |
status | string | required | |
created_at | string (date-time) | required | |
updated_at | string (date-time) | required | |
last_message_at | string or null (date-time) | required |
SupportTicketList
| Field | Type | Required | Description |
|---|---|---|---|
object | "list" (exactly) | required | |
data | array of SupportTicket | required | |
has_more | boolean | required | |
next_cursor | string or null | required |
SupportTicketCreate
| Field | Type | Required | Description |
|---|---|---|---|
subject | string · 3–200 chars | required | Trimmed. |
body | string · 1–5000 chars | required | Her first message; trimmed. |
SupportMessage
| Field | Type | Required | Description |
|---|---|---|---|
object | "support_message" (exactly) | required | |
id | string | required | |
ticket | string | required | |
body | string | required | |
from_staff | boolean | required | |
created_at | string (date-time) | required |
SupportMessageList
| Field | Type | Required | Description |
|---|---|---|---|
object | "list" (exactly) | required | |
data | array of SupportMessage | required | |
has_more | boolean | required | |
next_cursor | string or null | required |
SupportReply
| Field | Type | Required | Description |
|---|---|---|---|
body | string · 1–5000 chars | required | Trimmed. |
Job
| Field | Type | Required | Description |
|---|---|---|---|
object | "job" (exactly) | required | |
id | string | required | |
type | string | required |
|
status | string | required |
|
progress | integer or null · 0–100 | required | |
result | object or null | required | After success: the data request that holds the download. |
error_code | string or null | required | Why it failed, e.g. |
created_at | string (date-time) | required | |
finished_at | string or null (date-time) | required |
DataRequest
| Field | Type | Required | Description |
|---|---|---|---|
object | "data_request" (exactly) | required | |
id | string | required | |
kind | string | required |
|
status | string | required |
|
job | string or null | required | The export job ( |
expires_at | string or null (date-time) | required | Until when the export can be downloaded (7 days after it was ready). |
created_at | string (date-time) | required | |
completed_at | string or null (date-time) | required | |
download_url | string or null (uri) | optional | Only on |
download_url_expires_at | string or null (date-time) | optional |
ConnectedApp
| Field | Type | Required | Description |
|---|---|---|---|
object | "connected_app" (exactly) | required | |
id | string | required | |
name | string | required | |
logo_url | string or null (uri) | required | |
privacy_url | string (uri) | required | |
owner_name | string | required | The partner or agency behind the app. |
scopes | array of string | required | |
connected_at | string or null (date-time) | required | |
last_used_at | string or null (date-time) | required |
ConnectedAppList
| Field | Type | Required | Description |
|---|---|---|---|
object | "list" (exactly) | required | |
data | array of ConnectedApp | required | |
has_more | boolean | required | |
next_cursor | string or null | required |
DataRequestRef
A reference to a creator's data request (export or deletion) — never her data, IP or browser. Read it with her access token: GET /v1/creator/data-export/{id} for an export. deleted: true when it is no longer visible to your account.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | required | |
object | "data_request" (exactly) | required | |
deleted | true (exactly) | optional | Only when the request no longer exists for your account. |
JobRef
A reference to an asynchronous job. Read its status and result with the creator's access token: GET /v1/jobs/{id}. deleted: true when it is no longer visible to your account.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | required | |
object | "job" (exactly) | required | |
deleted | true (exactly) | optional | Only when the job no longer exists for your account. |
DataRequestEvent
An event whose data.object is a DataRequestRef: {"id": "dreq_…", "object": "data_request"}.
| Field | Type | Required | Description |
|---|---|---|---|
object | "event" (exactly) | required | |
id | string | required | |
type | string | required | |
created_at | string (date-time) | required | |
mode | string | required | |
api_version | string | required | |
sequence | integer | required | |
data | object | required |
JobEvent
An event whose data.object is a JobRef: {"id": "job_…", "object": "job"}.
| Field | Type | Required | Description |
|---|---|---|---|
object | "event" (exactly) | required | |
id | string | required | |
type | string | required | |
created_at | string (date-time) | required | |
mode | string | required | |
api_version | string | required | |
sequence | integer | required | |
data | object | required |
Member
A person who can sign in to the account (status active) or an open invitation (invited).
| Field | Type | Required | Description |
|---|---|---|---|
object | "member" (exactly) | required | |
id | string | required |
|
email | string | required | Lower-case email address of the login or the invitation. |
role | string | required |
|
status | string | required |
|
email_verified | boolean or null | required | People: |
created_at | string (date-time) | required | When the person joined or the invitation was created. |
expires_at | string or null (date-time) | required | Invitations: when the link stops working (48 hours). |
join_url | string or null (uri) | required | Only in the first answer to |
MemberInvite
| Field | Type | Required | Description |
|---|---|---|---|
email | string · 3–254 chars | required | The address the person signs in with; compared without case and surrounding whitespace. |
role | string · one of developer, viewer | required | Admins are invited in the portal only (by an owner or admin with two-factor authentication). The owner is the login the account was created with and is never invited. |
MemberList
| Field | Type | Required | Description |
|---|---|---|---|
object | "list" (exactly) | required | |
data | array of Member | required | |
has_more | boolean | required | Always |
next_cursor | string or null | required |
MemberDeleted
| Field | Type | Required | Description |
|---|---|---|---|
object | "member" (exactly) | required | |
id | string | required | |
deleted | true (exactly) | required |
ErrorResponse
| Field | Type | Required | Description |
|---|---|---|---|
error | object | required |
| Field | Type | Required | Description |
|---|---|---|---|
type | string | required |
|
code | ErrorCode | required | Stable, machine-readable error code. Branch on this, not on |
message | string | required | For a developer reading a log; may change. Never branch on it. |
doc_url | string (uri) | required | /errors/#<code> |
request_id | string | required | Same as |
field | string | optional | The request field the error is about (first one when there are several). |
details | array of object | optional | Every field problem of the request, not just the first. |
lead | object or null | optional | With |
parameter | string | optional | With |
agreement_type | string | optional | With |
scope | string | optional | With |
blockers | array of string | optional | With |
current_state | string | optional | With |
current_version | integer | optional | With |
limit | integer | optional | With |
ErrorCode
Stable, machine-readable error code. Branch on this, not on message. New codes may be added within v1.
invalid_jsoninvalid_bodyunknown_fieldunknown_parametermissing_fieldinvalid_fieldmissing_contactage_below_18consent_requiredinvalid_cursormissing_keyinvalid_keyexpired_keyinvalid_tokenexpired_tokenaccount_not_activeterms_not_acceptedinsufficient_scopewrong_account_typeip_not_allowedmfa_requiredreferrer_app_not_allowednot_foundmethod_not_allowedduplicate_own_leadduplicate_other_referrerlead_lockedlisting_lockedphotos_lockedinvalid_stateoffer_takenoffer_expiredlisting_unavailablepayment_pendingdeal_paidundo_window_passedclaim_existswarranty_expiredexternal_id_takenconsent_text_outdatedidempotency_in_progressprecondition_failedpayload_too_largeunsupported_media_typenot_ready_for_reviewidempotency_key_reusedimage_unreadablerate_limitedconcurrency_limitedduplicate_limit_reachedversion_sunsetinternal_errornot_configuredlimit_reachedupstream_failed
Scope
Scopes a key can carry. Each operation names the one it needs. Scopes of later endpoints are added with them.
account:readaccount:writeagreements:writekeys:managewebhooks:manageleads:readleads:writephotos:writeearnings:readoffers:readoffers:writereservations:readreservations:writesearch_profile:writeextractusage:readaudit:readoauth_apps:managemembers:manage