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

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

GET/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.

StatusMeaningBody
200

The API document.

ApiInfo
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error

Account

The account the key belongs to

GET/v1/me

Scope account:read.

Type, status, terms state per agreement type and the limits in effect for this key.

ParameterInTypeRequiredDescription
fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

The account.

Account
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Change your account profile

PATCH/v1/me

Scope 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.

ParameterInTypeRequiredDescription
If-Matchheaderstringoptional

The ETag you read. Stale → 412 precondition_failed; without it the last write wins.

Body application/json — AccountPatch.

FieldTypeRequiredDescription
display_namestring · 1–120 charsoptional

The name agencies and creators see.

company_namestring or null · 0–200 charsoptional

null or an empty string clears it.

telegram_usernamestringoptional

name, @name or a t.me/name link; stored as the name, 5–32 letters, digits or _. Cannot be removed.

websitestring or null · 0–300 charsoptional

An https:// (or http://) address with a dot in the host; without a scheme https:// is added. null or an empty string clears it.

Example: rename

curl
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"
  }'
JavaScript
// 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);
Python
# 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)
StatusMeaningBody
200

The account.

Account
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
412

precondition_failed: the If-Match value is not the current ETag. Read again, then retry.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Agreements and your acceptances

GET/v1/agreements

Scope account:read.

The current published version of every agreement type that applies to the account, with the account's acceptance.

ParameterInTypeRequiredDescription
fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

Agreements that apply to the account.

AgreementList
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Full text of one agreement version

GET/v1/agreements/{type}/{version}

Scope account:read.

ParameterInTypeRequiredDescription
typepathstringrequired

referrer_terms, agency_terms, warranty_terms, api_terms or api_dpa.

versionpathinteger · ≥ 1required
fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

One agreement version with its text.

AgreementDocument
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Accept the current version of an agreement

POST/v1/agreements/{type}/accept

Scope 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.

ParameterInTypeRequiredDescription
typepathstringrequired

referrer_terms, agency_terms, warranty_terms, api_terms or api_dpa.

Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

Body application/json — AgreementAccept.

FieldTypeRequiredDescription
versioninteger · ≥ 1required

Must be the current published version.

Example: accept

curl
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
  }'
JavaScript
// 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);
Python
# 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)
StatusMeaningBody
200

The agreement with your acceptance.

Agreement
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
422

not_ready_for_review (with error.blockers), idempotency_key_reused (same key, different body) or image_unreadable (an upload that cannot be decoded).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

The portal's pick lists

GET/v1/option-lists

Scope account:read.

Values that match what agencies search for. Full lists: /reference/allowed-values/

ParameterInTypeRequiredDescription
fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

The pick lists.

OptionLists
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Brokerage numbers

GET/v1/settings

Scope account:read.

Offer deadline, undo window, payment due days, warranty days and the Creator Guard share of a fee.

ParameterInTypeRequiredDescription
fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

Brokerage numbers.

Settings
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error
PUT/v1/me/logo

Scope 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.

FieldTypeRequiredDescription
filestring (binary)required

PNG, JPEG or WebP, at most 2 MB.

StatusMeaningBody
200

The account.

Account
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
422

not_ready_for_review (with error.blockers), idempotency_key_reused (same key, different body) or image_unreadable (an upload that cannot be decoded).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error
DELETE/v1/me/logo

Scope account:write.

Removes the file, then the logo. If the file cannot be removed, nothing changes and the answer is 502 upstream_failed — retry.

StatusMeaningBody
200

The account.

Account
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
502

upstream_failed: a service we depend on failed (text extraction, or the DNS lookup of a webhook URL). Retry later; nothing was stored.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Leads

List your leads

GET/v1/leads

Scope leads:read.

Newest first (created_at, then id). Filters combine with AND. Unknown parameters → 400 unknown_parameter; an invalid filter value → 400 invalid_field.

ParameterInTypeRequiredDescription
limitqueryinteger · 1–100optional

1–100 items per page (default 25).

starting_afterquerystringoptional

Id of the last item of the previous page: the next page.

ending_beforequerystringoptional

Id of the first item of the current page: the page before.

stagequerystring · one of draft, in_review, ready, offered, accepted, in_placement, placed, rejected, lost, withdrawnoptional

One stage (see the Lead schema).

external_idquerystring · 1–200 charsoptional

Your own reference, exact match.

creator_refquerystringoptional

Creator number, CR-1047 or 1047.

instagram_handlequerystring · 1–200 charsoptional

Handle or profile link; compared after normalising.

qquerystring · 1–200 charsoptional

Part of the creator name, case-insensitive.

created_sincequerystring (date-time)optional

Leads created at or after this instant (RFC 3339, e.g. 2026-10-09T12:00:00Z).

updated_sincequerystring (date-time)optional

Leads changed at or after this instant — for incremental sync.

has_blockersquerybooleanoptional

true: only leads with next_actions.blockers; false: only without.

fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

A page of leads.

LeadList
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Create a lead

POST/v1/leads

Scope 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 a draft (it is updated with the lead fields you sent; a listing in the body is applied like PATCH …/listing).
  • 409 duplicate_own_lead — your lead with this handle is past draft. Nothing changes; error.lead.
  • 409 duplicate_other_referrer — another account submitted this handle. Budgeted: 20 such answers per rolling 24 h, then 429 duplicate_limit_reached for every request with an instagram_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.

ParameterInTypeRequiredDescription
Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

Body application/json — LeadCreate.

FieldTypeRequiredDescription
external_idstring or null · 1–100 charsoptional

Your own reference, unique within your account. Repeating it returns the existing lead (200).

creator_namestring · 1–120 charsrequired

Name or alias.

instagram_handlestring or null · 1–200 charsoptional

Username (@handle) or profile link (instagram.com/<handle>). Anything else → 400 invalid_field. Recognises creators already in the system; without it there is no duplicate check by handle.

other_contactstring or null · 1–200 charsoptional

Any other way to reach her (Telegram, phone, …).

platformsarray of string · at least 1, at most 20, each 1–40 charsoptional

Platforms she is on; pick-list values are stored in their spelling. Allowed values. Optional; when sent, at least one entry.

follower_countinteger or null (int32) · 0–2,147,483,647optional

Followers on her largest platform.

nichestring or null · 1–80 charsoptional

A pick-list niche is stored in its spelling. Allowed values.

notesstring or null · 1–2000 charsoptional

For our team; never shown to agencies.

listingListingPatchoptional

Listing fields. Every field is optional; null clears a value, [] empties a list.

Example: Name, contact and platforms

curl
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
  }'
JavaScript
// 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);
Python
# 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
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
  }'
JavaScript
// 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);
Python
# 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
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"]
    }
  }'
JavaScript
// 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);
Python
# 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)
StatusMeaningBody
200

Already known: your external_id, or your handle while that lead is still a draft. consent carries her consent link.

Lead
201

A new lead was created; consent carries her consent link.

Lead
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
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.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
422

not_ready_for_review (with error.blockers), idempotency_key_reused (same key, different body) or image_unreadable (an upload that cannot be decoded).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Get a lead

GET/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.

ParameterInTypeRequiredDescription
idpathstringrequired

Lead id (lead_…).

expandquerystringoptional

Comma-separated: listing, photos, confirmations.

fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

The lead, with her consent link (consent).

Lead
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Change lead fields

PATCH/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).

ParameterInTypeRequiredDescription
idpathstringrequired

Lead id (lead_…).

If-Matchheaderstringoptional

The ETag you read. Stale → 412 precondition_failed; without it the last write wins.

Body application/json — LeadUpdate.

FieldTypeRequiredDescription
external_idstring or null · 1–100 charsoptional
creator_namestring · 1–120 charsoptional
instagram_handlestring or null · 1–200 charsoptional
other_contactstring or null · 1–200 charsoptional
platformsarray of string · at least 1, at most 20, each 1–40 charsoptional
follower_countinteger or null (int32) · 0–2,147,483,647optional
nichestring or null · 1–80 charsoptional
notesstring or null · 1–2000 charsoptional

Example: rename

curl
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."
  }'
JavaScript
// 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);
Python
# 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)
StatusMeaningBody
200

The lead.

Lead
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
412

precondition_failed: the If-Match value is not the current ETag. Read again, then retry.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Withdraw a lead

POST/v1/leads/{id}/withdraw

Scope leads:write.

Allowed while next_actions.can_withdraw (draft or in_review, no live offer); else 409 invalid_state. No body.

ParameterInTypeRequiredDescription
idpathstringrequired

Lead id (lead_…).

Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

StatusMeaningBody
200

The lead.

Lead
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
422

not_ready_for_review (with error.blockers), idempotency_key_reused (same key, different body) or image_unreadable (an upload that cannot be decoded).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Suggest lead fields from text

POST/v1/extract

Scope 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.

ParameterInTypeRequiredDescription
Idempotency-Keyheaderstringoptional

Ignored on this endpoint: nothing is stored, a retry runs again.

Body application/json — ExtractRequest.

FieldTypeRequiredDescription
textstring · 20–20000 charsrequired

Any text about her: profile, chat, notes (at least 20 characters after trimming). Not stored.

Example: bio

curl
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."
  }'
JavaScript
// 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);
Python
# 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)
StatusMeaningBody
200

Suggested fields; nothing was stored.

ExtractResult
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
502

upstream_failed: a service we depend on failed (text extraction, or the DNS lookup of a webhook URL). Retry later; nothing was stored.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Listing

Get the listing of a lead

GET/v1/leads/{id}/listing

Scope leads:read.

ParameterInTypeRequiredDescription
idpathstringrequired

Lead id (lead_…).

fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

The listing.

Listing
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Change listing fields

PATCH/v1/leads/{id}/listing

Scope 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.

ParameterInTypeRequiredDescription
idpathstringrequired

Lead id (lead_…).

If-Matchheaderstringoptional

The ETag you read. Stale → 412 precondition_failed; without it the last write wins.

Body application/json — ListingPatch.

FieldTypeRequiredDescription
ageinteger or null · 18–99optional

Below 18 → 400 age_below_18.

genderstring or null · one of female, male, trans, non_binary, otheroptional
origin_countrystring or null · 1–80 charsoptional
languagesarray of string · at most 20, each 1–40 charsoptional
english_levelinteger or null · 1–10optional
content_typesarray of string · at most 30, each 1–40 charsoptional

Content categories she is comfortable with. Values: allowed values.

content_freetextstring or null · 1–2000 charsoptional
has_of_accountboolean or nulloptional
of_verifiedboolean or nulloptional
of_current_earningsinteger or null · 0–2,147,483,647optional

USD per month.

content_readyboolean or nulloptional
scripts_readyboolean or nulloptional
account_accessstring or null · one of yes, no, undiscussedoptional
devicestring or null · 1–200 charsoptional
social_statusstring or null · one of none, ready_to_create, existingoptional
social_preferencesobjectoptional

Platform (1–40 characters) → wants to be active there; at most 20 entries.

tiktok_okboolean or nulloptional
blocked_countriesarray of string · at most 250, each 1–80 charsoptional
start_availabilitystring or null · one of now, dateoptional
start_datestring or null (date)optional
availability_hours_per_weeknumber or null · 0–168optional
availability_hours_per_daynumber or null · 0–24optional
compensation_modelstring or null · one of revenue_share, fixedoptional
creator_share_percentinteger or null · 0–100optional
fixed_salaryinteger or null · 0–2,147,483,647optional
salary_periodstring or null · one of weekly, monthlyoptional
placement_feeMoneyInputoptional

{"amount_minor": 150000, "currency": "USD"} = 1,500.00 USD. null clears the fee.

notes_publicstring or null · 1–2000 charsoptional

Shown to agencies with the listing.

Example: Age, origin, languages and fee

curl
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"
    }
  }'
JavaScript
// 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);
Python
# 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)
StatusMeaningBody
200

The listing.

Listing
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
412

precondition_failed: the If-Match value is not the current ETag. Read again, then retry.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Submit a draft for review

POST/v1/leads/{id}/submit-for-review

Scope 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.

ParameterInTypeRequiredDescription
idpathstringrequired

Lead id (lead_…).

Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

StatusMeaningBody
200

The lead.

Lead
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
422

not_ready_for_review (with error.blockers), idempotency_key_reused (same key, different body) or image_unreadable (an upload that cannot be decoded).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Her consent, 18+ confirmation and login state

GET/v1/leads/{id}/confirmations

Scope leads:read.

Status and dates only — never her IP address or browser.

ParameterInTypeRequiredDescription
idpathstringrequired

Lead id (lead_…).

fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

Her confirmations.

Confirmations
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error
POST/v1/leads/{id}/consent-link

Scope 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.

ParameterInTypeRequiredDescription
idpathstringrequired

Lead id (lead_…).

Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

StatusMeaningBody
200

Her consent link.

ConsentLink
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
422

not_ready_for_review (with error.blockers), idempotency_key_reused (same key, different body) or image_unreadable (an upload that cannot be decoded).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error
POST/v1/leads/{id}/claim-link

Scope 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.

ParameterInTypeRequiredDescription
idpathstringrequired

Lead id (lead_…).

Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

StatusMeaningBody
201

Her claim link (shown once).

ClaimLink
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
422

not_ready_for_review (with error.blockers), idempotency_key_reused (same key, different body) or image_unreadable (an upload that cannot be decoded).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Milestones of a lead

GET/v1/leads/{id}/timeline

Scope leads:read.

Submitted, review requested, approved, offers, acceptance, payment, warranty, completion, commission. No agency names.

ParameterInTypeRequiredDescription
idpathstringrequired

Lead id (lead_…).

fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

The milestones.

Timeline
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Your earnings from a lead

GET/v1/leads/{id}/earnings

Scope earnings:read.

ParameterInTypeRequiredDescription
idpathstringrequired

Lead id (lead_…).

fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

Your earnings.

Earnings
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Photos

List her photos

GET/v1/leads/{id}/photos

Scope 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.

ParameterInTypeRequiredDescription
idpathstringrequired

Lead id (lead_…).

fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

Her photos, primary first.

PhotoList
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Upload a photo

POST/v1/leads/{id}/photos

Scope 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.

ParameterInTypeRequiredDescription
idpathstringrequired

Lead id (lead_…).

Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

Body multipart/form-data — PhotoUpload.

FieldTypeRequiredDescription
filestring (binary)required

JPEG, PNG or WebP; at most 40 MB and 50 megapixels. Exactly one file part.

kindstring · one of portrait, body, content_sample, non_nude, lingerie, professionaloptional

Default portrait.

is_primarystring · one of true, falseoptional

true makes it her primary photo (default false). Her first photo is always primary.

StatusMeaningBody
201

The photo was stored (re-encoded, metadata removed). A replay of the same Idempotency-Key answers url and url_expires_at as null; list the photos for a fresh URL.

Photo
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
422

not_ready_for_review (with error.blockers), idempotency_key_reused (same key, different body) or image_unreadable (an upload that cannot be decoded).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Change kind or make primary

PATCH/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).

ParameterInTypeRequiredDescription
idpathstringrequired

Lead id (lead_…).

photopathstringrequired

Photo id (photo_…).

If-Matchheaderstringoptional

The ETag you read. Stale → 412 precondition_failed; without it the last write wins.

Body application/json — PhotoPatch.

FieldTypeRequiredDescription
kindstring · one of portrait, body, content_sample, non_nude, lingerie, professionaloptional
is_primarytrue (exactly)optional

Makes this her primary photo. Only true: make another photo primary instead.

Example: primary

curl
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
  }'
JavaScript
// 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);
Python
# 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)
StatusMeaningBody
200

The photo.

Photo
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
412

precondition_failed: the If-Match value is not the current ETag. Read again, then retry.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Delete a photo

DELETE/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.

ParameterInTypeRequiredDescription
idpathstringrequired

Lead id (lead_…).

photopathstringrequired

Photo id (photo_…).

StatusMeaningBody
204

Deleted. The answer has no body.

—
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
502

upstream_failed: a service we depend on failed (text extraction, or the DNS lookup of a webhook URL). Retry later; nothing was stored.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Earnings

List your commissions

GET/v1/commissions

Scope earnings:read.

Newest first. A commission is booked for your lead when her placement completes.

ParameterInTypeRequiredDescription
limitqueryinteger · 1–100optional

1–100 items per page (default 25).

starting_afterquerystringoptional

Id of the last item of the previous page: the next page.

ending_beforequerystringoptional

Id of the first item of the current page: the page before.

statusquerystring · one of due, paid, voidoptional

Only this status.

created_sincequerystring (date-time)optional

Booked at or after this instant (RFC 3339).

leadquerystringoptional

Only the commissions of this lead (lead_…).

expandquerystringoptional

lead: lead is a short lead object (id, creator_name, creator_ref, stage) instead of its id.

fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

A page of commissions.

CommissionList
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Get a commission

GET/v1/commissions/{id}

Scope earnings:read.

ParameterInTypeRequiredDescription
idpathstringrequired

Commission id (com_…).

expandquerystringoptional

lead: lead is a short lead object (id, creator_name, creator_ref, stage) instead of its id.

fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

The commission.

Commission
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Your payout details (masked)

GET/v1/payout-details

Scope 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.

ParameterInTypeRequiredDescription
fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

Your payout details, masked.

PayoutDetails
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Keys

List the keys of this mode

GET/v1/api-keys

Scope 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.

ParameterInTypeRequiredDescription
fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

The keys of this mode.

ApiKeyList
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Create a key

POST/v1/api-keys

Scope 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.

ParameterInTypeRequiredDescription
Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

Body application/json — ApiKeyCreate.

FieldTypeRequiredDescription
labelstring or null · 0–100 charsoptional

Trimmed; empty = no label.

scopesarray of Scope · at least 1required

Only scopes the calling key has (else 403 insufficient_scope).

ip_allowlistarray of string · at most 20optional

CIDR blocks with the host bits zero, e.g. 203.0.113.0/24; empty = any address.

expires_atstring or null (date-time)optional

In the future; capped by your key policy's maximum age.

Example: crm

curl
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"]
  }'
JavaScript
// 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);
Python
# 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)
StatusMeaningBody
201

The key with its new secret — shown this once. A replay of the same Idempotency-Key answers secret: null.

ApiKey
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
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.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
422

not_ready_for_review (with error.blockers), idempotency_key_reused (same key, different body) or image_unreadable (an upload that cannot be decoded).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Revoke a key

DELETE/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.

ParameterInTypeRequiredDescription
idpathstringrequired

Key id (key_…).

forcequerybooleanoptional

true to revoke the key that makes this request.

StatusMeaningBody
200

The key (no secret).

ApiKey
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Roll a key

POST/v1/api-keys/{id}/roll

Scope 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.

ParameterInTypeRequiredDescription
idpathstringrequired

Key id (key_…).

Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

Body application/json — ApiKeyRoll.

FieldTypeRequiredDescription
grace_hoursinteger or null · 0–72optional

How long the old key keeps working (default 24; 0 = it stops now).

Example: day

curl
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
  }'
JavaScript
// 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);
Python
# 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)
StatusMeaningBody
200

The key with its new secret — shown this once. A replay of the same Idempotency-Key answers secret: null.

ApiKey
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
422

not_ready_for_review (with error.blockers), idempotency_key_reused (same key, different body) or image_unreadable (an upload that cannot be decoded).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Events

List events

GET/v1/events

Any 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).

ParameterInTypeRequiredDescription
limitqueryinteger · 1–100optional

1–100 items per page (default 25).

starting_afterquerystringoptional

Id of the last item of the previous page: the next page.

ending_beforequerystringoptional

Id of the first item of the current page: the page before.

typequerystringoptional

Exact type (lead.updated) or a group (lead.*).

created_afterquerystring (date-time)optional

RFC 3339 timestamp; only events after it.

objectquerystringoptional

Events about one object: the id of a lead, photo, commission, API key or webhook endpoint (confirmation events carry the lead id).

fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

A page of events.

EventList
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Get an event

GET/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.

ParameterInTypeRequiredDescription
idpathstringrequired

Event id (evt_…).

fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

The event.

Event
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Webhooks

List webhook endpoints

GET/v1/webhook-endpoints

Scope webhooks:manage.

The endpoints of this mode (at most 10, one page). Secrets are never listed.

ParameterInTypeRequiredDescription
fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

The endpoints of this mode.

WebhookEndpointList
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Create a webhook endpoint

POST/v1/webhook-endpoints

Scope 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.

ParameterInTypeRequiredDescription
Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

Body application/json — WebhookEndpointCreate.

FieldTypeRequiredDescription
urlstring · 0–2048 charsrequired

https on port 443, no credentials, a host that resolves to public addresses only.

event_typesarray of string · at least 1, at most 32required

["*"] for every type, or event types of EventType except ping.

descriptionstring or null · 0–500 charsoptional

Example: crm

curl
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"
  }'
JavaScript
// 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);
Python
# 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)
StatusMeaningBody
201

The endpoint with its new signing secret — shown this once. A replay of the same Idempotency-Key answers secret: null.

WebhookEndpoint
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
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.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
422

not_ready_for_review (with error.blockers), idempotency_key_reused (same key, different body) or image_unreadable (an upload that cannot be decoded).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
502

upstream_failed: a service we depend on failed (text extraction, or the DNS lookup of a webhook URL). Retry later; nothing was stored.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Get a webhook endpoint

GET/v1/webhook-endpoints/{id}

Scope webhooks:manage.

ParameterInTypeRequiredDescription
idpathstringrequired

Webhook endpoint id (we_…).

fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

The endpoint (no secret).

WebhookEndpoint
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Change a webhook endpoint

PATCH/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).

ParameterInTypeRequiredDescription
idpathstringrequired

Webhook endpoint id (we_…).

If-Matchheaderstringoptional

The ETag you read. Stale → 412 precondition_failed; without it the last write wins.

Body application/json — WebhookEndpointUpdate.

FieldTypeRequiredDescription
urlstring · 0–2048 charsoptional
event_typesarray of string · at least 1, at most 32optional
descriptionstring or null · 0–500 charsoptional
enabledbooleanoptional

Example: disable

curl
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
  }'
JavaScript
// 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);
Python
# 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)
StatusMeaningBody
200

The endpoint (no secret).

WebhookEndpoint
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
412

precondition_failed: the If-Match value is not the current ETag. Read again, then retry.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
502

upstream_failed: a service we depend on failed (text extraction, or the DNS lookup of a webhook URL). Retry later; nothing was stored.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Delete a webhook endpoint

DELETE/v1/webhook-endpoints/{id}

Scope webhooks:manage.

The endpoint and its deliveries are removed; pending deliveries to it are dropped.

ParameterInTypeRequiredDescription
idpathstringrequired

Webhook endpoint id (we_…).

StatusMeaningBody
204

Deleted. The answer has no body.

—
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Roll the signing secret

POST/v1/webhook-endpoints/{id}/roll

Scope 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.

ParameterInTypeRequiredDescription
idpathstringrequired

Webhook endpoint id (we_…).

Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

StatusMeaningBody
200

The endpoint with its new signing secret — shown this once. A replay of the same Idempotency-Key answers secret: null.

WebhookEndpoint
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
422

not_ready_for_review (with error.blockers), idempotency_key_reused (same key, different body) or image_unreadable (an upload that cannot be decoded).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Send a test event

POST/v1/webhook-endpoints/{id}/test

Scope 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.

ParameterInTypeRequiredDescription
idpathstringrequired

Webhook endpoint id (we_…).

Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

StatusMeaningBody
202

The delivery, queued.

WebhookDelivery
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
422

not_ready_for_review (with error.blockers), idempotency_key_reused (same key, different body) or image_unreadable (an upload that cannot be decoded).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Re-send events of a time range

POST/v1/webhook-endpoints/{id}/replay

Scope 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.

ParameterInTypeRequiredDescription
idpathstringrequired

Webhook endpoint id (we_…).

Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

Body application/json — WebhookReplay.

FieldTypeRequiredDescription
fromstring (date-time)required

At most 30 days ago.

tostring or null (date-time)optional

After from; default now.

Example: hour

curl
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"
  }'
JavaScript
// 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);
Python
# 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)
StatusMeaningBody
202

How many deliveries were queued.

ReplayResult
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
422

not_ready_for_review (with error.blockers), idempotency_key_reused (same key, different body) or image_unreadable (an upload that cannot be decoded).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Deliveries to an endpoint

GET/v1/webhook-endpoints/{id}/deliveries

Scope webhooks:manage.

Newest first, 30 days, each with every attempt (status code, duration, error). Pages forward only: starting_after, no ending_before.

ParameterInTypeRequiredDescription
idpathstringrequired

Webhook endpoint id (we_…).

limitqueryinteger · 1–100optional

1–100 items per page (default 25).

starting_afterquerystringoptional

Id of the last item of the previous page: the next page.

fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

A page of deliveries.

WebhookDeliveryList
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Retry a delivery now

POST/v1/webhook-endpoints/{id}/deliveries/{d}/retry

Scope 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).

ParameterInTypeRequiredDescription
idpathstringrequired

Webhook endpoint id (we_…).

dpathstringrequired

Delivery id (whd_…).

Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

StatusMeaningBody
202

The delivery, queued.

WebhookDelivery
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
422

not_ready_for_review (with error.blockers), idempotency_key_reused (same key, different body) or image_unreadable (an upload that cannot be decoded).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

OAuth apps

List OAuth apps

GET/v1/oauth-apps

Scope oauth_apps:manage.

The OAuth apps of this mode (at most 10, one page). Client secrets are never listed. No query parameters besides fields.

ParameterInTypeRequiredDescription
fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

The OAuth apps of this mode.

OAuthAppList
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Register an OAuth app

POST/v1/oauth-apps

Scope 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").

ParameterInTypeRequiredDescription
Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

Body application/json — OAuthAppCreate.

FieldTypeRequiredDescription
namestring · 3–60 charsrequired

Trimmed.

redirect_urisarray of string · at least 1, at most 10, each 0–2000 charsrequired

Distinct; https, no fragment, no user info, no wildcard, no private or loopback host. Test keys may also use http://localhost:<port> or http://127.0.0.1:<port>.

logo_urlstring or null · 0–2000 charsoptional
privacy_urlstring · 0–2000 charsrequired

Your privacy policy, linked on the consent screen.

scopesarray of CreatorScope · at least 1required

Distinct.

confidentialbooleanrequired

Example: dashboard

curl
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
  }'
JavaScript
// 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);
Python
# 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)
StatusMeaningBody
201

The OAuth app with its new client secret (confidential apps) — shown this once. A replay of the same Idempotency-Key answers client_secret: null.

OAuthApp
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
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.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
422

not_ready_for_review (with error.blockers), idempotency_key_reused (same key, different body) or image_unreadable (an upload that cannot be decoded).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Get an OAuth app

GET/v1/oauth-apps/{id}

Scope oauth_apps:manage.

ParameterInTypeRequiredDescription
idpathstringrequired

OAuth app id (app_…).

fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

The OAuth app (no client secret).

OAuthApp
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Change an OAuth app

PATCH/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).

ParameterInTypeRequiredDescription
idpathstringrequired

OAuth app id (app_…).

If-Matchheaderstringoptional

The ETag you read. Stale → 412 precondition_failed; without it the last write wins.

Body application/json — OAuthAppUpdate.

FieldTypeRequiredDescription
namestring · 3–60 charsoptional
redirect_urisarray of string · at least 1, at most 10, each 0–2000 charsoptional
logo_urlstring or null · 0–2000 charsoptional
privacy_urlstring · 0–2000 charsoptional
scopesarray of CreatorScope · at least 1optional
confidentialbooleanoptional

Only its current value; it cannot change.

Example: rename

curl
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"
  }'
JavaScript
// 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);
Python
# 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)
StatusMeaningBody
200

The OAuth app (no client secret).

OAuthApp
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
412

precondition_failed: the If-Match value is not the current ETag. Read again, then retry.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Delete an OAuth app

DELETE/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.

ParameterInTypeRequiredDescription
idpathstringrequired

OAuth app id (app_…).

StatusMeaningBody
204

Deleted. The answer has no body.

—
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Roll the client secret

POST/v1/oauth-apps/{id}/roll

Scope 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).

ParameterInTypeRequiredDescription
idpathstringrequired

OAuth app id (app_…).

Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

StatusMeaningBody
200

The OAuth app with its new client secret (confidential apps) — shown this once. A replay of the same Idempotency-Key answers client_secret: null.

OAuthApp
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
422

not_ready_for_review (with error.blockers), idempotency_key_reused (same key, different body) or image_unreadable (an upload that cannot be decoded).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Members

People and open invitations

GET/v1/members

Scope 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.

ParameterInTypeRequiredDescription
fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

People (owner first) and open invitations.

MemberList
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Invite a person by email

POST/v1/members

Scope 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.

ParameterInTypeRequiredDescription
Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

Body application/json — MemberInvite.

FieldTypeRequiredDescription
emailstring · 3–254 charsrequired

The address the person signs in with; compared without case and surrounding whitespace.

rolestring · one of developer, viewerrequired

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
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"
  }'
JavaScript
// 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);
Python
# 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)
StatusMeaningBody
201

The invitation with join_url — shown this once. A replay of the same Idempotency-Key answers join_url: null.

Member
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
422

not_ready_for_review (with error.blockers), idempotency_key_reused (same key, different body) or image_unreadable (an upload that cannot be decoded).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Remove a person or revoke an invitation

DELETE/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.

ParameterInTypeRequiredDescription
idpathstringrequired

Member id (mem_…) or invitation id (inv_…).

StatusMeaningBody
200

The person was removed or the invitation revoked.

MemberDeleted
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Creator

Get the creator

GET/v1/creator/me

Scope 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.

ParameterInTypeRequiredDescription
fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

Her creator object.

Creator
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Get her profile

GET/v1/creator/profile

Scope creator.profile:read.

ParameterInTypeRequiredDescription
fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

Her profile.

CreatorProfile
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Change her profile

PATCH/v1/creator/profile

Scope 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).

ParameterInTypeRequiredDescription
If-Matchheaderstringoptional

The ETag you read. Stale → 412 precondition_failed; without it the last write wins.

Body application/json — CreatorProfilePatch.

FieldTypeRequiredDescription
leadobjectoptional
listingobjectoptional

Example: age

curl
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"]
    }
  }'
JavaScript
// 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);
Python
# 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)
StatusMeaningBody
200

Her profile.

CreatorProfile
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
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.

error
412

precondition_failed: the If-Match value is not the current ETag. Read again, then retry.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Submit her listing for review

POST/v1/creator/submit-for-review

Scope creator.profile:write.

Same rules as for the partner: 422 not_ready_for_review with blockers while something is missing.

ParameterInTypeRequiredDescription
Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

StatusMeaningBody
200

Her creator object.

Creator
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
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.

error
422

not_ready_for_review (with error.blockers), idempotency_key_reused (same key, different body) or image_unreadable (an upload that cannot be decoded).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

List her photos

GET/v1/creator/photos

Scope creator.photos:write.

ParameterInTypeRequiredDescription
fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
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: 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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Upload a photo

POST/v1/creator/photos

Scope 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.

ParameterInTypeRequiredDescription
Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

Body multipart/form-data — PhotoUpload.

FieldTypeRequiredDescription
filestring (binary)required

JPEG, PNG or WebP; at most 40 MB and 50 megapixels. Exactly one file part.

kindstring · one of portrait, body, content_sample, non_nude, lingerie, professionaloptional

Default portrait.

is_primarystring · one of true, falseoptional

true makes it her primary photo (default false). Her first photo is always primary.

StatusMeaningBody
201

The photo was stored (re-encoded, metadata removed). A replay of the same Idempotency-Key answers url and url_expires_at as null; list her photos for a fresh URL.

CreatorPhoto
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
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.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
422

not_ready_for_review (with error.blockers), idempotency_key_reused (same key, different body) or image_unreadable (an upload that cannot be decoded).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
502

upstream_failed: a service we depend on failed (text extraction, or the DNS lookup of a webhook URL). Retry later; nothing was stored.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Delete a photo

DELETE/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.

ParameterInTypeRequiredDescription
photopathstringrequired

Photo id (photo_…).

StatusMeaningBody
204

Deleted. The answer has no body.

—
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
502

upstream_failed: a service we depend on failed (text extraction, or the DNS lookup of a webhook URL). Retry later; nothing was stored.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Get a consent text

GET/v1/creator/consent-text

Scope 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.

ParameterInTypeRequiredDescription
kindquerystring · one of consent, age_confirmation, creator_termsrequired

consent, age_confirmation or creator_terms.

localequerystringoptional

Two lowercase letters, default en; a language without its own text falls back to English.

fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

The current published text of that kind and language.

ConsentText
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Get her consent state

GET/v1/creator/consent

Scope creator.profile:read.

Consent and 18+ state with every entry of her consent ledger (never her IP address or browser).

ParameterInTypeRequiredDescription
fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

Her consent and 18+ state with her ledger entries.

CreatorConsentState
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Record her consent

POST/v1/creator/consent/grant

Scope 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).

ParameterInTypeRequiredDescription
Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

Body application/json — ConsentDecision.

FieldTypeRequiredDescription
text_versioninteger · ≥ 1optional
localestringoptional

The language of the text she saw, default en.

Example: grant

curl
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"
  }'
JavaScript
// 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);
Python
# 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)
StatusMeaningBody
200

Her consent and 18+ state with her ledger entries.

CreatorConsentState
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
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.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Record her withdrawal

POST/v1/creator/consent/revoke

Scope creator.consent:write.

Her photos stop being released. Never refused because of the text version; send the one she saw if you have it.

ParameterInTypeRequiredDescription
Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

Body application/json — ConsentDecision.

FieldTypeRequiredDescription
text_versioninteger · ≥ 1optional
localestringoptional

The language of the text she saw, default en.

Example: revoke

curl
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 '{}'
JavaScript
// 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);
Python
# 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)
StatusMeaningBody
200

Her consent and 18+ state with her ledger entries.

CreatorConsentState
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Record her 18+ confirmation

POST/v1/creator/age-confirmation

Scope 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.

ParameterInTypeRequiredDescription
Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

Body application/json — ConsentDecision.

FieldTypeRequiredDescription
text_versioninteger · ≥ 1optional
localestringoptional

The language of the text she saw, default en.

Example: confirm

curl
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
  }'
JavaScript
// 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);
Python
# 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)
StatusMeaningBody
200

Her consent and 18+ state with her ledger entries.

CreatorConsentState
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
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.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

List her agreements

GET/v1/creator/agreements

Scope creator.consent:write.

ParameterInTypeRequiredDescription
fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

Her agreements (the creator terms).

CreatorAgreementList
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Record her acceptance of the creator terms

POST/v1/creator/agreements/{type}/accept

Scope 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.

ParameterInTypeRequiredDescription
typepathstringrequired

Always creator_terms; any other value is 404.

Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

Body application/json — CreatorTermsAccept.

FieldTypeRequiredDescription
versioninteger · ≥ 1required

The current version (409 consent_text_outdated otherwise).

Example: accept

curl
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
  }'
JavaScript
// 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);
Python
# 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)
StatusMeaningBody
200

The agreement with her acceptance.

CreatorAgreement
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

List her support tickets

GET/v1/creator/support-tickets

Scope creator.support.

Newest first; pages forward only (starting_after; ending_before is 400 invalid_field).

ParameterInTypeRequiredDescription
limitqueryinteger · 1–100optional

1–100 items per page (default 25).

starting_afterquerystringoptional

Id of the last item of the previous page: the next page.

fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

Her support tickets, newest first.

SupportTicketList
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Open a support ticket

POST/v1/creator/support-tickets

Scope creator.support.

ParameterInTypeRequiredDescription
Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

Body application/json — SupportTicketCreate.

FieldTypeRequiredDescription
subjectstring · 3–200 charsrequired

Trimmed.

bodystring · 1–5000 charsrequired

Her first message; trimmed.

Example: ticket

curl
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?"
  }'
JavaScript
// 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);
Python
# 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)
StatusMeaningBody
201

The support ticket.

SupportTicket
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

List the messages of a ticket

GET/v1/creator/support-tickets/{id}/messages

Scope creator.support.

ParameterInTypeRequiredDescription
idpathstringrequired

Support ticket id (tkt_…).

fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

Every message of the ticket, oldest first.

SupportMessageList
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Reply to a ticket

POST/v1/creator/support-tickets/{id}/messages

Scope creator.support.

A closed ticket → 409 invalid_state; open a new one.

ParameterInTypeRequiredDescription
idpathstringrequired

Support ticket id (tkt_…).

Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

Body application/json — SupportReply.

FieldTypeRequiredDescription
bodystring · 1–5000 charsrequired

Trimmed.

Example: reply

curl
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!"
  }'
JavaScript
// 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);
Python
# 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)
StatusMeaningBody
201

Her new message.

SupportMessage
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Close a ticket

POST/v1/creator/support-tickets/{id}/close

Scope creator.support.

ParameterInTypeRequiredDescription
idpathstringrequired

Support ticket id (tkt_…).

Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

StatusMeaningBody
200

The support ticket.

SupportTicket
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Request her data export

POST/v1/creator/data-export

Scope 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.

ParameterInTypeRequiredDescription
Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

StatusMeaningBody
202

The export job (new, or the open/recent one of the last 24 hours). Poll Location until status is succeeded or failed.

Job
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Get her data export

GET/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).

ParameterInTypeRequiredDescription
idpathstringrequired

Data request id (dreq_…).

fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

The data request.

DataRequest
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Request the deletion of her data

POST/v1/creator/deletion-request

Scope 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.

ParameterInTypeRequiredDescription
Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

StatusMeaningBody
202

Her deletion request (new, or the open one). Creator Guard handles it; the app owner receives deletion_request.completed when it is done.

DataRequest
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Your app's connection

GET/v1/creator/connected-apps

Scope 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.

ParameterInTypeRequiredDescription
fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

The apps she authorised and has not revoked.

ConnectedAppList
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Disconnect your app

DELETE/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.

ParameterInTypeRequiredDescription
apppathstringrequired

Id of a connected OAuth app (app_…).

StatusMeaningBody
204

Deleted. The answer has no body.

—
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Jobs

Get a job

GET/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).

ParameterInTypeRequiredDescription
idpathstringrequired

Job id (job_…).

fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

The job.

Job
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Usage & audit

Your request log

GET/v1/request-logs

Scope account:read.

The last 30 days of this mode, newest first. Method, route template, status, error code, key and duration — never bodies.

ParameterInTypeRequiredDescription
limitqueryinteger · 1–100optional

1–100 items per page (default 25).

starting_afterquerystringoptional

Id of the last item of the previous page: the next page.

ending_beforequerystringoptional

Id of the first item of the current page: the page before.

statusqueryinteger · 100–599optional

HTTP status, e.g. 429.

routequerystringoptional

Route template as logged, e.g. /v1/leads/{id}.

keyquerystringoptional

Only requests of this key (key_…).

created_sincequerystring (date-time)optional

RFC 3339 timestamp; only requests from then on.

fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

A page of your request log.

RequestLogList
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Usage statistics

GET/v1/usage

Scope 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.

ParameterInTypeRequiredDescription
fromquerystring (date)optional

First day (UTC), YYYY-MM-DD; default 29 days before to.

toquerystring (date)optional

Last day (UTC), inclusive; default today.

granularityquerystringoptional

day (the only value today).

fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

Usage statistics.

Usage
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Audit trail of your account

GET/v1/audit-events

Scope 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.

ParameterInTypeRequiredDescription
limitqueryinteger · 1–100optional

1–100 items per page (default 25).

starting_afterquerystringoptional

Id of the last item of the previous page: the next page.

ending_beforequerystringoptional

Id of the first item of the current page: the page before.

actionquerystringoptional

e.g. api_key.created.

created_sincequerystring (date-time)optional

RFC 3339 timestamp; only changes from then on.

fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

A page of audit events.

AuditEventList
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Agency

Get your search profile

GET/v1/search-profile

Scope 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).

ParameterInTypeRequiredDescription
fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

Your search profile. ETag only once you saved one.

SearchProfile
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Replace your search profile

PUT/v1/search-profile

Scope 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).

ParameterInTypeRequiredDescription
If-Matchheaderstringoptional

The ETag you read. Stale → 412 precondition_failed; without it the last write wins.

Body application/json — SearchProfilePut.

FieldTypeRequiredDescription
nichesarray of string · at most 50, each 0–100 charsoptional
platformsarray of string · at most 50, each 0–100 charsoptional
languagesarray of string · at most 50, each 0–100 charsoptional
content_typesarray of string · at most 50, each 0–100 charsoptional
age_mininteger or null · 18–99optional
age_maxinteger or null · 18–99optional

Not below age_min.

english_level_mininteger or null · 1–10optional
revenue_minUsdInputoptional

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.

revenue_maxUsdInputoptional

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.

max_placement_feeUsdInputoptional

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.

creator_share_max_percentinteger or null · 0–100optional
creator_stagestring or null · one of beginners, earning, bothoptional
countries_excludedarray of string · at most 50, each 0–100 charsoptional
capacity_per_monthinteger or null · 0–1,000optional
notesstring or null · 1–2000 charsoptional
flexFlexInputoptional

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.

Example: profile

curl
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": []
      }
    }
  }'
JavaScript
// 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);
Python
# 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)
StatusMeaningBody
200

Your search profile. ETag only once you saved one.

SearchProfile
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
412

precondition_failed: the If-Match value is not the current ETag. Read again, then retry.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Get your agency profile

GET/v1/agency-profile

Scope account:read.

Your agency's public facts. tier and verified_revenue are set by Creator Guard. Agency keys only (403 wrong_account_type otherwise).

ParameterInTypeRequiredDescription
fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

Your agency profile.

AgencyProfile
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Update your agency profile

PATCH/v1/agency-profile

Scope 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).

ParameterInTypeRequiredDescription
If-Matchheaderstringoptional

The ETag you read. Stale → 412 precondition_failed; without it the last write wins.

Body application/json — AgencyProfilePatch.

FieldTypeRequiredDescription
countrystring or null · 1–100 charsoptional
websitestring or null · 0–300 charsoptional

An https:// URL.

team_sizeinteger or null · 0–100,000optional
years_activenumber or null · 0–99.9optional

At most one decimal, e.g. 3.5.

monthly_revenueUsdInputoptional

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.

managed_creators_countinteger or null · 0–100,000optional
specializationarray of string · at most 20, each 0–100 charsoptional
referencesstring or null · 1–2000 charsoptional

Example: team

curl
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"
    }
  }'
JavaScript
// 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);
Python
# 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)
StatusMeaningBody
200

Your agency profile.

AgencyProfile
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
412

precondition_failed: the If-Match value is not the current ETag. Read again, then retry.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Offers

List your offers

GET/v1/offers

Scope 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).

ParameterInTypeRequiredDescription
limitqueryinteger · 1–100optional

1–100 items per page (default 25).

starting_afterquerystringoptional

Id of the last item of the previous page: the next page.

ending_beforequerystringoptional

Id of the first item of the current page: the page before.

statusquerystring · one of offered, accepted, declined, expired, retracted, contacted, in_talks, signed, lostoptional

Only offers with this status (an open offer past its deadline counts as expired).

created_sincequerystring (date-time)optional

RFC 3339 timestamp; only items created from then on.

updated_sincequerystring (date-time)optional

RFC 3339 timestamp; only items changed from then on.

expires_beforequerystring (date-time)optional

RFC 3339 timestamp; only offers whose deadline is before it.

fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

A page of offers.

OfferList
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Get an offer

GET/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).

ParameterInTypeRequiredDescription
idpathstringrequired

Offer id (offer_…). An id that is not one of your offers answers 404 not_found.

fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

The offer.

Offer
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Set your note on an offer

PATCH/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).

ParameterInTypeRequiredDescription
idpathstringrequired

Offer id (offer_…). An id that is not one of your offers answers 404 not_found.

If-Matchheaderstringoptional

The ETag you read. Stale → 412 precondition_failed; without it the last write wins.

Body application/json — OfferPatch.

FieldTypeRequiredDescription
agency_notestring or null · 1–500 charsrequired

Your note (trimmed); null clears it.

Example: note

curl
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."
  }'
JavaScript
// 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);
Python
# 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)
StatusMeaningBody
200

The offer.

Offer
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
412

precondition_failed: the If-Match value is not the current ETag. Read again, then retry.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

List the creator's photos

GET/v1/offers/{id}/photos

Scope 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).

ParameterInTypeRequiredDescription
idpathstringrequired

Offer id (offer_…). An id that is not one of your offers answers 404 not_found.

fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
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: 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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Accept an offer

POST/v1/offers/{id}/accept

Scope 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).

ParameterInTypeRequiredDescription
idpathstringrequired

Offer id (offer_…). An id that is not one of your offers answers 404 not_found.

Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

StatusMeaningBody
200

The offer.

Offer
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
422

not_ready_for_review (with error.blockers), idempotency_key_reused (same key, different body) or image_unreadable (an upload that cannot be decoded).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Decline an offer

POST/v1/offers/{id}/decline

Scope 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).

ParameterInTypeRequiredDescription
idpathstringrequired

Offer id (offer_…). An id that is not one of your offers answers 404 not_found.

Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

Body application/json — OfferDecline.

FieldTypeRequiredDescription
notestring · 50–500 charsrequired

Why she is not a fit, 50–500 characters after trimming.

Example: mismatch

curl
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."
  }'
JavaScript
// 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);
Python
# 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)
StatusMeaningBody
200

The offer.

Offer
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
422

not_ready_for_review (with error.blockers), idempotency_key_reused (same key, different body) or image_unreadable (an upload that cannot be decoded).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Undo an accept

POST/v1/offers/{id}/undo-accept

Scope 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).

ParameterInTypeRequiredDescription
idpathstringrequired

Offer id (offer_…). An id that is not one of your offers answers 404 not_found.

Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

StatusMeaningBody
200

The offer.

Offer
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
422

not_ready_for_review (with error.blockers), idempotency_key_reused (same key, different body) or image_unreadable (an upload that cannot be decoded).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Mark the creator as contacted

POST/v1/offers/{id}/mark-contacted

Scope 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).

ParameterInTypeRequiredDescription
idpathstringrequired

Offer id (offer_…). An id that is not one of your offers answers 404 not_found.

Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

StatusMeaningBody
200

The offer.

Offer
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
422

not_ready_for_review (with error.blockers), idempotency_key_reused (same key, different body) or image_unreadable (an upload that cannot be decoded).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Mark talks as started

POST/v1/offers/{id}/mark-in-talks

Scope 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).

ParameterInTypeRequiredDescription
idpathstringrequired

Offer id (offer_…). An id that is not one of your offers answers 404 not_found.

Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

StatusMeaningBody
200

The offer.

Offer
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
422

not_ready_for_review (with error.blockers), idempotency_key_reused (same key, different body) or image_unreadable (an upload that cannot be decoded).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Mark the creator as signed

POST/v1/offers/{id}/mark-signed

Scope 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).

ParameterInTypeRequiredDescription
idpathstringrequired

Offer id (offer_…). An id that is not one of your offers answers 404 not_found.

Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

StatusMeaningBody
200

The offer.

Offer
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
422

not_ready_for_review (with error.blockers), idempotency_key_reused (same key, different body) or image_unreadable (an upload that cannot be decoded).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Mark the placement as lost

POST/v1/offers/{id}/mark-lost

Scope 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).

ParameterInTypeRequiredDescription
idpathstringrequired

Offer id (offer_…). An id that is not one of your offers answers 404 not_found.

Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

Body application/json — OfferMarkLost.

FieldTypeRequiredDescription
outcome_reasonstring · one of profile_mismatch, not_reachable, duplicate, quality, capacity, otherrequired

Example: unreachable

curl
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"
  }'
JavaScript
// 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);
Python
# 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)
StatusMeaningBody
200

The offer.

Offer
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
422

not_ready_for_review (with error.blockers), idempotency_key_reused (same key, different body) or image_unreadable (an upload that cannot be decoded).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Reservations

List your reservations

GET/v1/reservations

Scope reservations:read.

Newest first. Agency keys only (403 wrong_account_type otherwise).

ParameterInTypeRequiredDescription
limitqueryinteger · 1–100optional

1–100 items per page (default 25).

starting_afterquerystringoptional

Id of the last item of the previous page: the next page.

ending_beforequerystringoptional

Id of the first item of the current page: the page before.

statusquerystring · one of awaiting_payment, paid, completed, refunded, cancelledoptional

Only reservations with this status.

created_sincequerystring (date-time)optional

RFC 3339 timestamp; only items created from then on.

updated_sincequerystring (date-time)optional

RFC 3339 timestamp; only items changed from then on.

fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

A page of reservations.

ReservationList
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Get a reservation

GET/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).

ParameterInTypeRequiredDescription
idpathstringrequired

Reservation id (res_…). An id that is not one of your reservations answers 404 not_found.

fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

The reservation.

Reservation
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

File a warranty claim

POST/v1/reservations/{id}/warranty-claim

Scope 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).

ParameterInTypeRequiredDescription
idpathstringrequired

Reservation id (res_…). An id that is not one of your reservations answers 404 not_found.

Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

Body application/json — WarrantyClaimCreate.

FieldTypeRequiredDescription
reasonstring · one of creator_unreachable, no_show, false_data, contract_refused, otherrequired
notestring or null · 0–2000 charsoptional

Trimmed; blank counts as no note.

Example: no_show

curl
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."
  }'
JavaScript
// 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);
Python
# 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)
StatusMeaningBody
200

The reservation.

Reservation
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
422

not_ready_for_review (with error.blockers), idempotency_key_reused (same key, different body) or image_unreadable (an upload that cannot be decoded).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Get the creator's contact

GET/v1/reservations/{id}/creator

Scope 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).

ParameterInTypeRequiredDescription
idpathstringrequired

Reservation id (res_…). An id that is not one of your reservations answers 404 not_found.

fieldsquerystringoptional

Comma-separated top-level fields to return (at most 50), e.g. id,stage,creator_ref; id and object always come along. In lists it applies to each item of data. A name the object does not have → 400 invalid_field.

StatusMeaningBody
200

The creator's contact.

ReservationCreator
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Test mode

Confirm consent and 18+ (test mode)

POST/v1/test-helpers/leads/{id}/confirm

Scope 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.

ParameterInTypeRequiredDescription
idpathstringrequired

Lead id (lead_…).

Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

StatusMeaningBody
200

The lead.

Lead
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
422

not_ready_for_review (with error.blockers), idempotency_key_reused (same key, different body) or image_unreadable (an upload that cannot be decoded).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Approve the listing (test mode)

POST/v1/test-helpers/leads/{id}/approve-listing

Scope 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.

ParameterInTypeRequiredDescription
idpathstringrequired

Lead id (lead_…).

Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

StatusMeaningBody
200

The lead.

Lead
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
422

not_ready_for_review (with error.blockers), idempotency_key_reused (same key, different body) or image_unreadable (an upload that cannot be decoded).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Reject a lead (test mode)

POST/v1/test-helpers/leads/{id}/reject

Scope 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.

ParameterInTypeRequiredDescription
idpathstringrequired

Lead id (lead_…).

Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

Body application/json — TestLeadReject.

FieldTypeRequiredDescription
outcome_reasonstring · one of profile_mismatch, not_reachable, duplicate, quality, capacity, otherrequired

Example: duplicate

curl
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"
  }'
JavaScript
// 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);
Python
# 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)
StatusMeaningBody
200

The lead.

Lead
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
422

not_ready_for_review (with error.blockers), idempotency_key_reused (same key, different body) or image_unreadable (an upload that cannot be decoded).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Pay a commission (test mode)

POST/v1/test-helpers/commissions/{id}/mark-paid

Scope 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).

ParameterInTypeRequiredDescription
idpathstringrequired

Commission id (com_…).

Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

StatusMeaningBody
200

The commission.

Commission
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
422

not_ready_for_review (with error.blockers), idempotency_key_reused (same key, different body) or image_unreadable (an upload that cannot be decoded).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Delete all test data (test mode)

POST/v1/test-helpers/reset

Scope 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.

ParameterInTypeRequiredDescription
Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

StatusMeaningBody
200

What was deleted from the sandbox.

TestReset
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
422

not_ready_for_review (with error.blockers), idempotency_key_reused (same key, different body) or image_unreadable (an upload that cannot be decoded).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

A sandbox photo or logo

GET/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).

ParameterInTypeRequiredDescription
pathpathstringrequired

Bucket and object path as in the URL we gave you; contains slashes.

tokenquerystringrequired

Signed token from the URL we gave you.

StatusMeaningBody
200

The file.

—
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.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
502

upstream_failed: a service we depend on failed (text extraction, or the DNS lookup of a webhook URL). Retry later; nothing was stored.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Create a test offer (test mode)

POST/v1/test-helpers/offers

Scope 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).

ParameterInTypeRequiredDescription
Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

Body application/json — TestOfferCreate.

FieldTypeRequiredDescription
creator_namestring · 1–120 charsoptional

Default: a generated test name. The offer shows it only after …/mark-paid, like a live offer.

placement_feeMoneyInputoptional

{"amount_minor": 150000, "currency": "USD"} = 1,500.00 USD. null clears the fee.

expires_in_hoursinteger · 1–720optional

Default: the offer deadline of GET /v1/settings.

Example: fee

curl
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
  }'
JavaScript
// 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);
Python
# 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)
StatusMeaningBody
201

The new test offer.

Offer
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
422

not_ready_for_review (with error.blockers), idempotency_key_reused (same key, different body) or image_unreadable (an upload that cannot be decoded).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Mark a reservation as paid (test mode)

POST/v1/test-helpers/reservations/{id}/mark-paid

Scope 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).

ParameterInTypeRequiredDescription
idpathstringrequired

Reservation id (res_…). An id that is not one of your reservations answers 404 not_found.

Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

StatusMeaningBody
200

The reservation.

Reservation
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
422

not_ready_for_review (with error.blockers), idempotency_key_reused (same key, different body) or image_unreadable (an upload that cannot be decoded).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Complete a reservation (test mode)

POST/v1/test-helpers/reservations/{id}/complete

Scope 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).

ParameterInTypeRequiredDescription
idpathstringrequired

Reservation id (res_…). An id that is not one of your reservations answers 404 not_found.

Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

StatusMeaningBody
200

The reservation.

Reservation
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
422

not_ready_for_review (with error.blockers), idempotency_key_reused (same key, different body) or image_unreadable (an upload that cannot be decoded).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Refund a reservation (test mode)

POST/v1/test-helpers/reservations/{id}/refund

Scope 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).

ParameterInTypeRequiredDescription
idpathstringrequired

Reservation id (res_…). An id that is not one of your reservations answers 404 not_found.

Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

Body application/json — TestReservationRefund.

FieldTypeRequiredDescription
reasonstring · one of creator_unreachable, no_show, false_data, contract_refused, otheroptional

Default: the reason of your warranty claim, else other.

Example: no_show

curl
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"
  }'
JavaScript
// 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);
Python
# 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)
StatusMeaningBody
200

The reservation.

Reservation
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
422

not_ready_for_review (with error.blockers), idempotency_key_reused (same key, different body) or image_unreadable (an upload that cannot be decoded).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Advance the test clock (test mode)

POST/v1/test-helpers/clock/advance

Scope 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).

ParameterInTypeRequiredDescription
Idempotency-Keyheaderstring · 1–255 charsoptional

Any unique string, 1–255 characters, e.g. a UUID. Kept 24 hours.

Body application/json — ClockAdvance.

FieldTypeRequiredDescription
hoursinteger · 1–720required

Example: two_days

curl
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
  }'
JavaScript
// 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);
Python
# 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)
StatusMeaningBody
200

What the expiry jobs changed in your sandbox.

ClockAdvanceResult
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
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.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
422

not_ready_for_review (with error.blockers), idempotency_key_reused (same key, different body) or image_unreadable (an upload that cannot be decoded).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

error

Create an authorization code (test mode)

POST/v1/test-helpers/oauth-codes

Scope 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.

ParameterInTypeRequiredDescription
Idempotency-Keyheaderstringoptional

Ignored on this endpoint: a code is single-use, a retry creates a new one.

Body application/json — OAuthTestCodeCreate.

FieldTypeRequiredDescription
client_idstringrequired

A test-mode app of your account.

lead_idstringrequired

A sandbox lead you may connect (you submitted it, or you hold a paid reservation for it).

redirect_uristring · 0–2000 charsrequired

One of the app's registered redirect URIs, character for character.

scopesarray of CreatorScope · at least 1required

A subset of the app's scopes; repeats are ignored.

code_challengestringrequired

BASE64URL(SHA256(code_verifier)) without padding (PKCE S256).

Example: code

curl
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"
  }'
JavaScript
// 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);
Python
# 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)
StatusMeaningBody
201

A test-mode authorization code, shown this once: valid for 60 seconds and one exchange at /oauth/token.

OAuthTestCode
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.

error
401

missing_key, invalid_key (unknown or revoked) or expired_key. Not counted against any limit.

error
403

account_not_active, terms_not_accepted (with error.agreement_type), insufficient_scope (with error.scope), wrong_account_type or ip_not_allowed.

error
404

not_found: unknown id, a resource of another account (never 403), or a test helper called with a live key.

error
413

payload_too_large: a JSON body over 1 MB, a photo over 40 MB or a logo over 2 MB.

error
415

unsupported_media_type: send Content-Type: application/json (uploads: multipart/form-data with a JPEG, PNG or WebP file).

error
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.

error
500

internal_error. Safe to retry with the same Idempotency-Key; quote request_id to support.

error
503

not_configured: a setting is missing on our side (for example text extraction), or test mode is briefly unavailable.

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

400 · JSON
{
  "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

400 · JSON
{
  "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

401 · JSON
{
  "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

403 · JSON
{
  "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

409 · JSON
{
  "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

422 · JSON
{
  "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

FieldTypeRequiredDescription
object"api" (exactly)required
api_versionstringrequired

Same as X-API-Version.

statusstringrequired

beta today.

docs_urlstring (uri)required
openapi_urlstring (uri)required

Account

FieldTypeRequiredDescription
object"account" (exactly)required
idstringrequired
typestringrequired

referrer or agency.

statusstringrequired

approved for every key that works (other states answer 403 account_not_active).

display_namestring or nullrequired
company_namestring or nullrequired
websitestring or nullrequired
telegram_usernamestring or nullrequired
logo_urlstring or nullrequired
termsarray of objectrequired

One entry per agreement type that applies to the account (api_terms and api_dpa for every account).

limitsobjectrequired

Limits in effect (defaults or your account's overrides).

Agreement

FieldTypeRequiredDescription
object"agreement" (exactly)required
typestringrequired

referrer_terms, agency_terms, warranty_terms, api_terms, api_dpa

current_versioninteger or nullrequired
published_atstring or null (date-time)required
acceptedbooleanrequired
accepted_versioninteger or nullrequired
accepted_atstring or null (date-time)required
acceptancesarray of objectrequired

Every version the account accepted.

AgreementList

FieldTypeRequiredDescription
object"list" (exactly)required
dataarray of Agreementrequired
has_morebooleanrequired
next_cursorstring or nullrequired

AgreementDocument

FieldTypeRequiredDescription
object"agreement_document" (exactly)required
typestringrequired
versionintegerrequired
published_atstring or null (date-time)required
currentbooleanrequired

Whether this is the version to accept.

body_mdstringrequired

The text as Markdown.

AgreementAccept

FieldTypeRequiredDescription
versioninteger · ≥ 1required

Must be the current published version.

OptionLists

Values in the spelling we store. Lists can change. Full lists: /reference/allowed-values/

FieldTypeRequiredDescription
object"option_lists" (exactly)required
platformsarray of stringrequired
languagesarray of stringrequired
content_typesarray of stringrequired
nichesarray of stringrequired
specializationsarray of stringrequired

Settings

FieldTypeRequiredDescription
object"settings" (exactly)required
offer_deadline_hoursintegerrequired
accept_undo_minutesintegerrequired
payment_due_daysintegerrequired
warranty_daysintegerrequired
creator_guard_share_percentintegerrequired

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.

FieldTypeRequiredDescription
amount_minorintegerrequired
currencystringrequired

USD, EUR or GBP today.

MoneyInput

{"amount_minor": 150000, "currency": "USD"} = 1,500.00 USD. null clears the fee.

FieldTypeRequiredDescription
amount_minorinteger · 0–9,999,999,999required
currencystring · one of USD, EUR, GBPrequired

NextActions

What you can do with the lead right now — computed by Creator Guard, so you never re-implement the rules.

FieldTypeRequiredDescription
can_edit_leadbooleanrequired
can_edit_listingbooleanrequired
can_edit_feebooleanrequired
can_withdrawbooleanrequired
can_submit_for_reviewbooleanrequired
blockersarray of stringrequired

What still keeps her off the marketplace, while the lead is draft or in_review and the listing is not live (else empty): age_missing, languages_missing, country_missing, content_types_missing, photos_missing (3 needed), consent_missing, age_confirmation_missing, fee_missing. Every blocker also blocks submit-for-review. fee_missing appears only on leads whose fee you set (never on leads our team added for your account). New values may be added.

ListingSummary

The listing summary every lead carries. With ?expand=listing the lead carries the full Listing object instead (without photo_count).

FieldTypeRequiredDescription
statusstringrequired

draft, in_review, live or withdrawn.

placement_feeMoneyrequired

An amount in integer minor units (cents) and its ISO 4217 currency; null when not set.

photo_countintegerrequired

Photos she has.

Photo

FieldTypeRequiredDescription
object"photo" (exactly)required
idstringrequired
kindstringrequired
is_primarybooleanrequired
urlstring or null (uri)required

Signed, valid for 1 hour; null when the file could not be signed, for a removed photo and in the replay of an upload.

url_expires_atstring or null (date-time)required
leadstringrequired
created_atstring or null (date-time)required
versioninteger · ≥ 0required

Grows with every change of the photo; events about it carry the same number as sequence.

ConsentState

FieldTypeRequiredDescription
statusstringrequired

pending, granted or revoked.

granted_atstring or null (date-time)required
revoked_atstring or null (date-time)required

AgeConfirmation

FieldTypeRequiredDescription
statusstringrequired

missing, confirmed or declined.

confirmed_atstring or null (date-time)required

CreatorLogin

FieldTypeRequiredDescription
statusstringrequired

none or active.

Confirmations

FieldTypeRequiredDescription
object"confirmations" (exactly)required
leadstringrequired
age_confirmationAgeConfirmationrequired
creator_loginCreatorLoginrequired

Lead

One creator you submitted. New fields may be added within v1; ignore fields you do not know.

FieldTypeRequiredDescription
object"lead" (exactly)required
idstringrequired
external_idstring or nullrequired
creator_refstring or nullrequired

Her creator number; quote it to support.

creator_namestringrequired
instagram_handlestring or nullrequired

As stored (normalised username).

other_contactstring or nullrequired
platformsarray of stringrequired
follower_countinteger or nullrequired
nichestring or nullrequired
notesstring or nullrequired
stagestringrequired

draft, in_review, ready, offered, accepted, in_placement, placed, rejected, lost or withdrawn. New values may be added.

outcome_reasonstring or nullrequired

Why a lead was rejected or lost.

next_actionsNextActionsrequired

What you can do with the lead right now — computed by Creator Guard, so you never re-implement the rules.

listingListingSummary or Listingrequired

The summary; with ?expand=listing the full Listing object.

confirmationsConfirmationsoptional
photosarray of Photooptional

Only with ?expand=photos.

created_atstring (date-time)required
updated_atstring (date-time)required
versioninteger · ≥ 0required

Grows with every change of the lead or its listing; events about it carry the same number as sequence. 0 until the first change after 1.5.0.

Lead · JSON
{
  "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

FieldTypeRequiredDescription
object"list" (exactly)required
dataarray of Leadrequired
has_morebooleanrequired
next_cursorstring or nullrequired

Pass as starting_after for the next page; null on the last page.

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).

FieldTypeRequiredDescription
external_idstring or null · 1–100 charsoptional

Your own reference, unique within your account. Repeating it returns the existing lead (200).

creator_namestring · 1–120 charsrequired

Name or alias.

instagram_handlestring or null · 1–200 charsoptional

Username (@handle) or profile link (instagram.com/<handle>). Anything else → 400 invalid_field. Recognises creators already in the system; without it there is no duplicate check by handle.

other_contactstring or null · 1–200 charsoptional

Any other way to reach her (Telegram, phone, …).

platformsarray of string · at least 1, at most 20, each 1–40 charsoptional

Platforms she is on; pick-list values are stored in their spelling. Allowed values. Optional; when sent, at least one entry.

follower_countinteger or null (int32) · 0–2,147,483,647optional

Followers on her largest platform.

nichestring or null · 1–80 charsoptional

A pick-list niche is stored in its spelling. Allowed values.

notesstring or null · 1–2000 charsoptional

For our team; never shown to agencies.

listingListingPatchoptional

Listing fields. Every field is optional; null clears a value, [] empties a list.

LeadUpdate

Send only the fields to change; null clears an optional field. Lead fields while can_edit_lead; external_id always.

FieldTypeRequiredDescription
external_idstring or null · 1–100 charsoptional
creator_namestring · 1–120 charsoptional
instagram_handlestring or null · 1–200 charsoptional
other_contactstring or null · 1–200 charsoptional
platformsarray of string · at least 1, at most 20, each 1–40 charsoptional
follower_countinteger or null (int32) · 0–2,147,483,647optional
nichestring or null · 1–80 charsoptional
notesstring or null · 1–2000 charsoptional

ListingPatch

Listing fields. Every field is optional; null clears a value, [] empties a list.

FieldTypeRequiredDescription
ageinteger or null · 18–99optional

Below 18 → 400 age_below_18.

genderstring or null · one of female, male, trans, non_binary, otheroptional
origin_countrystring or null · 1–80 charsoptional
languagesarray of string · at most 20, each 1–40 charsoptional
english_levelinteger or null · 1–10optional
content_typesarray of string · at most 30, each 1–40 charsoptional

Content categories she is comfortable with. Values: allowed values.

content_freetextstring or null · 1–2000 charsoptional
has_of_accountboolean or nulloptional
of_verifiedboolean or nulloptional
of_current_earningsinteger or null · 0–2,147,483,647optional

USD per month.

content_readyboolean or nulloptional
scripts_readyboolean or nulloptional
account_accessstring or null · one of yes, no, undiscussedoptional
devicestring or null · 1–200 charsoptional
social_statusstring or null · one of none, ready_to_create, existingoptional
social_preferencesobjectoptional

Platform (1–40 characters) → wants to be active there; at most 20 entries.

tiktok_okboolean or nulloptional
blocked_countriesarray of string · at most 250, each 1–80 charsoptional
start_availabilitystring or null · one of now, dateoptional
start_datestring or null (date)optional
availability_hours_per_weeknumber or null · 0–168optional
availability_hours_per_daynumber or null · 0–24optional
compensation_modelstring or null · one of revenue_share, fixedoptional
creator_share_percentinteger or null · 0–100optional
fixed_salaryinteger or null · 0–2,147,483,647optional
salary_periodstring or null · one of weekly, monthlyoptional
placement_feeMoneyInputoptional

{"amount_minor": 150000, "currency": "USD"} = 1,500.00 USD. null clears the fee.

notes_publicstring or null · 1–2000 charsoptional

Shown to agencies with the listing.

Listing

FieldTypeRequiredDescription
object"listing" (exactly)required
leadstringrequired
statusstringrequired

draft, in_review, live or withdrawn.

ageinteger or nullrequired
genderstring or nullrequired
origin_countrystring or nullrequired
languagesarray of stringrequired
english_levelinteger or nullrequired
content_typesarray of stringrequired
content_freetextstring or nullrequired
has_of_accountboolean or nullrequired
of_verifiedboolean or nullrequired
of_current_earningsinteger or nullrequired
content_readyboolean or nullrequired
scripts_readyboolean or nullrequired
account_accessstring or nullrequired
devicestring or nullrequired
social_statusstring or nullrequired
social_preferencesobjectrequired
tiktok_okboolean or nullrequired
blocked_countriesarray of stringrequired
start_availabilitystring or nullrequired
start_datestring or null (date)required
availability_hours_per_weeknumber or nullrequired
availability_hours_per_daynumber or nullrequired
compensation_modelstring or nullrequired
creator_share_percentinteger or nullrequired
fixed_salaryinteger or nullrequired
salary_periodstring or nullrequired
placement_feeMoneyrequired

An amount in integer minor units (cents) and its ISO 4217 currency; null when not set.

notes_publicstring or nullrequired
updated_atstring 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.

FieldTypeRequiredDescription
statusstringrequired

pending, granted or revoked.

urlstring or null (uri)required

Her personal page on app.creator-guard.com — only in the 201 that created the lead; null otherwise (stored hashed) and after her data was erased at her request.

expires_atstring or null (date-time)required

When her current link stops working; a new one: POST /v1/leads/{id}/consent-link. null after her data was erased.

FieldTypeRequiredDescription
FieldTypeRequiredDescription

Timeline

FieldTypeRequiredDescription
object"timeline" (exactly)required
leadstringrequired
eventsarray of objectrequired

Oldest first; only milestones that happened (or, for warranty_until, are scheduled).

Earnings

FieldTypeRequiredDescription
object"earnings" (exactly)required
leadstringrequired
feeMoneyrequired

An amount in integer minor units (cents) and its ISO 4217 currency; null when not set.

creator_guard_amountMoneyrequired

An amount in integer minor units (cents) and its ISO 4217 currency; null when not set.

your_amountMoneyrequired

An amount in integer minor units (cents) and its ISO 4217 currency; null when not set.

statusstring or nullrequired

expected (fee set, before completion), due, paid or void (also for a lost, rejected or withdrawn lead without a booked commission); null (with every amount null) while no fee is set.

AccountPatch

Send only what changes; the same fields and checks as the portal's profile page. Strings are trimmed first.

FieldTypeRequiredDescription
display_namestring · 1–120 charsoptional

The name agencies and creators see.

company_namestring or null · 0–200 charsoptional

null or an empty string clears it.

telegram_usernamestringoptional

name, @name or a t.me/name link; stored as the name, 5–32 letters, digits or _. Cannot be removed.

websitestring or null · 0–300 charsoptional

An https:// (or http://) address with a dot in the host; without a scheme https:// is added. null or an empty string clears it.

LogoUpload

FieldTypeRequiredDescription
filestring (binary)required

PNG, JPEG or WebP, at most 2 MB.

ExtractRequest

FieldTypeRequiredDescription
textstring · 20–20000 charsrequired

Any text about her: profile, chat, notes (at least 20 characters after trimming). Not stored.

ExtractResult

FieldTypeRequiredDescription
object"extract_result" (exactly)required
suggestionsobjectrequired

Only fields the text supports, each already valid under the rules of POST /v1/leads; review them before you send a lead.

PhotoUpload

FieldTypeRequiredDescription
filestring (binary)required

JPEG, PNG or WebP; at most 40 MB and 50 megapixels. Exactly one file part.

kindstring · one of portrait, body, content_sample, non_nude, lingerie, professionaloptional

Default portrait.

is_primarystring · one of true, falseoptional

true makes it her primary photo (default false). Her first photo is always primary.

PhotoPatch

FieldTypeRequiredDescription
kindstring · one of portrait, body, content_sample, non_nude, lingerie, professionaloptional
is_primarytrue (exactly)optional

Makes this her primary photo. Only true: make another photo primary instead.

PhotoList

Every photo of the lead (at most 20) on one page: has_more is always false.

FieldTypeRequiredDescription
object"list" (exactly)required
dataarray of Photorequired
has_morebooleanrequired
next_cursorstring or nullrequired

LeadSummary

The short lead object of ?expand=lead.

FieldTypeRequiredDescription
object"lead" (exactly)required
idstringrequired
creator_namestringrequired
creator_refstring or nullrequired
stagestringrequired

Commission

FieldTypeRequiredDescription
object"commission" (exactly)required
idstringrequired
leadstring or LeadSummaryrequired

The lead id (lead_…); with ?expand=lead a short lead object (stays the id when you can no longer read the lead).

creator_refstring or nullrequired
statusstringrequired

due (we owe it), paid or void. New values may be added.

fee_totalMoneyrequired

An amount in integer minor units (cents) and its ISO 4217 currency; null when not set.

creator_guard_amountMoneyrequired

An amount in integer minor units (cents) and its ISO 4217 currency; null when not set.

your_amountMoneyrequired

An amount in integer minor units (cents) and its ISO 4217 currency; null when not set.

created_atstring or null (date-time)required
paid_atstring or null (date-time)required
versioninteger · ≥ 0required

Grows with every change; events about it carry the same number as sequence.

CommissionList

FieldTypeRequiredDescription
object"list" (exactly)required
dataarray of Commissionrequired
has_morebooleanrequired
next_cursorstring or nullrequired

PayoutDetails

All three are null until you save payout details in the portal.

FieldTypeRequiredDescription
object"payout_details" (exactly)required
methodstring or nullrequired

bank, paypal or crypto.

destination_maskedstring or nullrequired

The destination with all but a few characters hidden.

updated_atstring or null (date-time)required

ApiKey

FieldTypeRequiredDescription
object"api_key" (exactly)required
idstringrequired
modestringrequired

live or test.

labelstring or nullrequired
prefixstringrequired

The start of the key, e.g. cg_live_ab12; enough to recognise it.

scopesarray of stringrequired
ip_allowlistarray of stringrequired

CIDR blocks; empty = any address.

expires_atstring or null (date-time)required

Its expiry, capped by your key policy's maximum age.

grace_untilstring or null (date-time)required

Set on a key that was rolled: it works until then.

last_used_atstring or null (date-time)required
created_atstring (date-time)required
created_viastringrequired

admin, portal or api.

revoked_atstring or null (date-time)required
rolled_fromstring or nullrequired

The key (key_…) this one replaced in a roll.

secretstring or nulloptional

The full key. Only in the answer that made it (create, roll) — null in a replay of that answer; never again.

ApiKeyCreate

FieldTypeRequiredDescription
labelstring or null · 0–100 charsoptional

Trimmed; empty = no label.

scopesarray of Scope · at least 1required

Only scopes the calling key has (else 403 insufficient_scope).

ip_allowlistarray of string · at most 20optional

CIDR blocks with the host bits zero, e.g. 203.0.113.0/24; empty = any address.

expires_atstring or null (date-time)optional

In the future; capped by your key policy's maximum age.

ApiKeyRoll

FieldTypeRequiredDescription
grace_hoursinteger or null · 0–72optional

How long the old key keeps working (default 24; 0 = it stops now).

ApiKeyList

The active keys and those revoked in the last 90 days, on one page.

FieldTypeRequiredDescription
object"list" (exactly)required
dataarray of ApiKeyrequired
has_morebooleanrequired
next_cursorstring or nullrequired

RequestLog

FieldTypeRequiredDescription
object"request_log" (exactly)required
idstringrequired

The request id (X-Request-Id).

methodstringrequired
routestringrequired

Route template, e.g. /v1/leads/{id}.

statusintegerrequired
error_codestring or nullrequired
keystring or nullrequired

Key id (key_…).

duration_msintegerrequired
created_atstring (date-time)required

RequestLogList

FieldTypeRequiredDescription
object"list" (exactly)required
dataarray of RequestLogrequired
has_morebooleanrequired
next_cursorstring or nullrequired

Usage

FieldTypeRequiredDescription
object"usage" (exactly)required
fromstring (date)required
tostring (date)required
granularitystringrequired

day.

modestringrequired

live or test — the mode of the calling key.

seriesarray of objectrequired

One entry per UTC day of the range.

by_routearray of objectrequired
by_keyarray of objectrequired

AuditEvent

FieldTypeRequiredDescription
object"audit_event" (exactly)required
idstringrequired
actionstringrequired

e.g. api_key.created, api_key.rolled, api_key.revoked, webhook_endpoint.created, account.updated, limits.changed. New values may be added.

actorobjectrequired
targetobject or nullrequired
modestring or nullrequired

live, test, or null for account-wide changes.

ipstring or nullrequired
user_agentstring or nullrequired
detailsobjectrequired

What changed (names and new values; never secrets or creator data).

created_atstring (date-time)required

AuditEventList

FieldTypeRequiredDescription
object"list" (exactly)required
dataarray of AuditEventrequired
has_morebooleanrequired
next_cursorstring or nullrequired

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.

FieldTypeRequiredDescription

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.

FieldTypeRequiredDescription
object"event" (exactly)required
idstringrequired
typestringrequired
created_atstring (date-time)required
modestringrequired

live or test.

api_versionstringrequired

The contract version that rendered the payload.

sequenceintegerrequired

The version the object reached with this change. Drop an event whose sequence is not above the last one you applied for that object (0 for ping).

dataobjectrequired
previous_attributesobjectoptional

Only on events about a change: what changed, by contract field name (listing fields under listing, consent and age_confirmation as objects), each with null — the old value only for stage and status. Never creator data.

EventList

FieldTypeRequiredDescription
object"list" (exactly)required
dataarray of Eventrequired
has_morebooleanrequired
next_cursorstring or nullrequired

WebhookEndpoint

FieldTypeRequiredDescription
object"webhook_endpoint" (exactly)required
idstringrequired
urlstring (uri)required
descriptionstring or nullrequired
event_typesarray of stringrequired

The subscribed types, or ["*"] for all.

enabledbooleanrequired
disabled_reasonstring or nullrequired

manual (you) or failing (72 hours of failed deliveries).

created_atstring (date-time)required
updated_atstring (date-time)required
secretstring or nulloptional

whsec_… signing secret. Only in the answers to create and roll — null in a replay of that answer; never again.

WebhookEndpointCreate

FieldTypeRequiredDescription
urlstring · 0–2048 charsrequired

https on port 443, no credentials, a host that resolves to public addresses only.

event_typesarray of string · at least 1, at most 32required

["*"] for every type, or event types of EventType except ping.

descriptionstring or null · 0–500 charsoptional

WebhookEndpointUpdate

Send only what changes. Enabling an endpoint that was disabled as failing restarts its failure clock.

FieldTypeRequiredDescription
urlstring · 0–2048 charsoptional
event_typesarray of string · at least 1, at most 32optional
descriptionstring or null · 0–500 charsoptional
enabledbooleanoptional

WebhookEndpointList

Every endpoint of this mode (at most 10) on one page.

FieldTypeRequiredDescription
object"list" (exactly)required
dataarray of WebhookEndpointrequired
has_morebooleanrequired
next_cursorstring or nullrequired

WebhookReplay

FieldTypeRequiredDescription
fromstring (date-time)required

At most 30 days ago.

tostring or null (date-time)optional

After from; default now.

ReplayResult

FieldTypeRequiredDescription
object"webhook_replay" (exactly)required
endpointstringrequired
fromstring (date-time)required
tostring (date-time)required
queuedintegerrequired

Deliveries queued (a range that would pass 1,000 open deliveries → 409 limit_reached, nothing queued).

WebhookDelivery

FieldTypeRequiredDescription
object"webhook_delivery" (exactly)required
idstringrequired
eventstringrequired

Event id (evt_…).

event_typestringrequired
statusstringrequired

pending, sending, succeeded or failed.

attemptintegerrequired
next_attempt_atstring or null (date-time)required
last_statusinteger or nullrequired

HTTP status your endpoint answered.

last_errorstring or nullrequired

Why the last attempt failed (a short code, e.g. a timeout); null after a success.

replaybooleanrequired
created_atstring (date-time)required
completed_atstring or null (date-time)required
attemptsarray of objectrequired

WebhookDeliveryList

FieldTypeRequiredDescription
object"list" (exactly)required
dataarray of WebhookDeliveryrequired
has_morebooleanrequired
next_cursorstring or nullrequired

TestLeadReject

FieldTypeRequiredDescription
outcome_reasonstring · one of profile_mismatch, not_reachable, duplicate, quality, capacity, otherrequired

TestReset

FieldTypeRequiredDescription
object"sandbox_reset" (exactly)required
mode"test" (exactly)required
deletedobjectrequired

LeadEvent

An event whose data.object is a Lead — or {"id": …, "object": …, "deleted": true} when it no longer exists.

FieldTypeRequiredDescription
object"event" (exactly)required
idstringrequired
typestringrequired
created_atstring (date-time)required
modestringrequired
api_versionstringrequired
sequenceintegerrequired
dataobjectrequired
previous_attributesobjectoptional

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.

FieldTypeRequiredDescription
object"event" (exactly)required
idstringrequired
typestringrequired
created_atstring (date-time)required
modestringrequired
api_versionstringrequired
sequenceintegerrequired
dataobjectrequired
previous_attributesobjectoptional

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.

FieldTypeRequiredDescription
object"event" (exactly)required
idstringrequired
typestringrequired
created_atstring (date-time)required
modestringrequired
api_versionstringrequired
sequenceintegerrequired
dataobjectrequired
previous_attributesobjectoptional

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.

FieldTypeRequiredDescription
object"event" (exactly)required
idstringrequired
typestringrequired
created_atstring (date-time)required
modestringrequired
api_versionstringrequired
sequenceintegerrequired
dataobjectrequired
previous_attributesobjectoptional

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.

FieldTypeRequiredDescription
object"event" (exactly)required
idstringrequired
typestringrequired
created_atstring (date-time)required
modestringrequired
api_versionstringrequired
sequenceintegerrequired
dataobjectrequired
previous_attributesobjectoptional

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.

FieldTypeRequiredDescription
object"event" (exactly)required
idstringrequired
typestringrequired
created_atstring (date-time)required
modestringrequired
api_versionstringrequired
sequenceintegerrequired
dataobjectrequired
previous_attributesobjectoptional

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.

FieldTypeRequiredDescription
object"event" (exactly)required
idstringrequired
typestringrequired
created_atstring (date-time)required
modestringrequired
api_versionstringrequired
sequenceintegerrequired
dataobjectrequired
previous_attributesobjectoptional

Only on events about a change; see Event.

PingEvent

The event of a test send: data.object is empty, sequence is 0.

FieldTypeRequiredDescription
object"event" (exactly)required
idstringrequired
type"ping" (exactly)required
created_atstring (date-time)required
modestringrequired
api_versionstringrequired
sequenceintegerrequired
dataobjectrequired

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.

FieldTypeRequiredDescription
amount_minorinteger · ≥ 0required
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.

FieldTypeRequiredDescription
ageobjectoptional
revenueobjectoptional
englishobjectoptional
feeobjectoptional
splitobjectoptional
stageobjectoptional
nichesobjectoptional
platformsobjectoptional
content_typesobjectoptional
languagesobjectoptional

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.

FieldTypeRequiredDescription
ageobjectoptional
revenueobjectoptional
englishobjectoptional
feeobjectoptional
splitobjectoptional
stageobjectoptional
nichesobjectoptional
platformsobjectoptional
content_typesobjectoptional
languagesobjectoptional

SearchProfile

What we match creators against before we offer them to you. Before your first PUT the defaults (updated_at: null).

FieldTypeRequiredDescription
object"search_profile" (exactly)required
nichesarray of stringrequired
platformsarray of stringrequired
languagesarray of stringrequired
content_typesarray of stringrequired
age_mininteger or nullrequired
age_maxinteger or nullrequired
english_level_mininteger or nullrequired
revenue_minMoneyrequired

An amount in integer minor units (cents) and its ISO 4217 currency; null when not set.

revenue_maxMoneyrequired

An amount in integer minor units (cents) and its ISO 4217 currency; null when not set.

max_placement_feeMoneyrequired

An amount in integer minor units (cents) and its ISO 4217 currency; null when not set.

creator_share_max_percentinteger or nullrequired
creator_stagestringrequired

beginners, earning or both.

countries_excludedarray of stringrequired
capacity_per_monthinteger or nullrequired
notesstring or nullrequired
flexFlexrequired

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.

updated_atstring 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).

FieldTypeRequiredDescription
nichesarray of string · at most 50, each 0–100 charsoptional
platformsarray of string · at most 50, each 0–100 charsoptional
languagesarray of string · at most 50, each 0–100 charsoptional
content_typesarray of string · at most 50, each 0–100 charsoptional
age_mininteger or null · 18–99optional
age_maxinteger or null · 18–99optional

Not below age_min.

english_level_mininteger or null · 1–10optional
revenue_minUsdInputoptional

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.

revenue_maxUsdInputoptional

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.

max_placement_feeUsdInputoptional

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.

creator_share_max_percentinteger or null · 0–100optional
creator_stagestring or null · one of beginners, earning, bothoptional
countries_excludedarray of string · at most 50, each 0–100 charsoptional
capacity_per_monthinteger or null · 0–1,000optional
notesstring or null · 1–2000 charsoptional
flexFlexInputoptional

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.

AgencyProfile

Your agency's public facts. tier (A, B, C or unranked) and verified_revenue are set by Creator Guard.

FieldTypeRequiredDescription
object"agency_profile" (exactly)required
countrystring or nullrequired
websitestring or nullrequired
team_sizeinteger or nullrequired
years_activenumber or nullrequired
monthly_revenueMoneyrequired

An amount in integer minor units (cents) and its ISO 4217 currency; null when not set.

managed_creators_countinteger or nullrequired
specializationarray of stringrequired
referencesstring or nullrequired
tierstringrequired
verified_revenueMoneyrequired

An amount in integer minor units (cents) and its ISO 4217 currency; null when not set.

vettingAgencyVettingrequired

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.

updated_atstring 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.

FieldTypeRequiredDescription
statusstringrequired

One of registered, in_review, vetted. registered: account ready, vetting not started; in_review: we are vetting your agency; vetted: offers reach your account.

waiting_matchesinteger · ≥ 0required

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).

FieldTypeRequiredDescription
countrystring or null · 1–100 charsoptional
websitestring or null · 0–300 charsoptional

An https:// URL.

team_sizeinteger or null · 0–100,000optional
years_activenumber or null · 0–99.9optional

At most one decimal, e.g. 3.5.

monthly_revenueUsdInputoptional

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.

managed_creators_countinteger or null · 0–100,000optional
specializationarray of string · at most 20, each 0–100 charsoptional
referencesstring or null · 1–2000 charsoptional

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.

FieldTypeRequiredDescription
object"listing" (exactly)required
ageinteger or nullrequired
genderstring or nullrequired
origin_countrystring or nullrequired
languagesarray of stringrequired
english_levelinteger or nullrequired
content_typesarray of stringrequired
content_freetextstring or nullrequired
has_of_accountboolean or nullrequired
of_verifiedboolean or nullrequired
of_current_earningsinteger or nullrequired
content_readyboolean or nullrequired
scripts_readyboolean or nullrequired
account_accessstring or nullrequired
devicestring or nullrequired
social_statusstring or nullrequired
social_preferencesobjectrequired
tiktok_okboolean or nullrequired
blocked_countriesarray of stringrequired
start_availabilitystring or nullrequired
start_datestring or null (date)required
availability_hours_per_weeknumber or nullrequired
availability_hours_per_daynumber or nullrequired
compensation_modelstring or nullrequired
creator_share_percentinteger or nullrequired
fixed_salaryinteger or nullrequired
salary_periodstring or nullrequired
placement_feeMoneyrequired

An amount in integer minor units (cents) and its ISO 4217 currency; null when not set.

notes_publicstring or nullrequired
updated_atstring or null (date-time)required

OfferNextActions

What you can do with the offer now — so you never re-implement the rules.

FieldTypeRequiredDescription
can_acceptbooleanrequired
can_declinebooleanrequired
can_undo_acceptbooleanrequired
can_mark_contactedbooleanrequired
can_mark_in_talksbooleanrequired
can_mark_signedbooleanrequired
can_mark_lostbooleanrequired

ReservationSummary

The reservation your accept created; the whole object: GET /v1/reservations/{id}.

FieldTypeRequiredDescription
idstringrequired
statusstringrequired

awaiting_payment, paid, completed, refunded or cancelled.

amountMoneyrequired

An amount in integer minor units (cents) and its ISO 4217 currency; null when not set.

payment_referencestring or nullrequired
payment_due_atstring or null (date-time)required
paid_atstring or null (date-time)required
warranty_untilstring 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.

FieldTypeRequiredDescription
object"offer" (exactly)required
idstringrequired
statusstringrequired

offered, accepted, declined, expired, retracted, contacted, in_talks, signed or lost. An open offer whose deadline passed reads expired at once.

creator_namestring or nullrequired

null until your agency paid for her (a reservation of yours for her that is paid or completed; a refunded one does not count). Use creator_ref before that.

creator_refstring or nullrequired

Her creator number, e.g. CR-1047.

expires_atstring or null (date-time)required

The deadline to accept or decline.

accepted_atstring or null (date-time)required
undo_untilstring or null (date-time)required

Until when undo-accept works (while unpaid).

agency_notestring or nullrequired
outcome_reasonstring or nullrequired

Set on lost: profile_mismatch, not_reachable, duplicate, quality, capacity or other.

listingOfferListing or nullrequired

null once the offer is declined, expired, retracted or lost without a paid reservation, and while she has withdrawn her consent (event offer.consent_revoked) — unless your placement of her is completed.

photo_countinteger or nullrequired

Photos she agreed to share; null while the listing is hidden.

reservationReservationSummary or nullrequired
next_actionsOfferNextActionsrequired

What you can do with the offer now — so you never re-implement the rules.

matchOfferMatch or nullrequired

How well she fits your search profile (GET /v1/search-profile), checked with the same rules as our own matching. null while you have no search profile (or nothing filled in) and while her listing is hidden. Criterion names and results only: niche and platforms are only ever hit or miss (a close match within your tolerance shows as hit, while score still counts it ½).

created_atstring (date-time)required
updated_atstring (date-time)required

OfferList

FieldTypeRequiredDescription
object"list" (exactly)required
dataarray of Offerrequired
has_morebooleanrequired
next_cursorstring or nullrequired

OfferMatch

The match of an offer against your search profile. Criteria you left empty are not checked.

FieldTypeRequiredDescription
scorenumber · ≥ 0required

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.

totalinteger · ≥ 1required

Criteria checked.

knocked_outbooleanrequired

true when a must-match criterion (one without tolerance; the country always) is a miss.

criteriaarray of OfferMatchCriterionrequired

OfferMatchCriterion

FieldTypeRequiredDescription
keystringrequired

content_types, niche, languages, platforms, age, english, revenue, fee, split, stage or country. New keys may be added within v1.

resultstringrequired

hit, near (counts ½) or miss; niche and platforms are only hit or miss. New values may be added within v1.

mustbooleanrequired

Must match: a miss knocks her out.

OfferPhoto

FieldTypeRequiredDescription
object"photo" (exactly)required
idstringrequired
kindstringrequired
is_primarybooleanrequired
urlstring or nullrequired

Signed link, valid for one hour.

url_expires_atstring or null (date-time)required

OfferPhotoList

FieldTypeRequiredDescription
object"list" (exactly)required
dataarray of OfferPhotorequired
has_morebooleanrequired

Always false: every photo on one page.

next_cursorstring or nullrequired

OfferPatch

FieldTypeRequiredDescription
agency_notestring or null · 1–500 charsrequired

Your note (trimmed); null clears it.

OfferDecline

FieldTypeRequiredDescription
notestring · 50–500 charsrequired

Why she is not a fit, 50–500 characters after trimming.

OfferMarkLost

FieldTypeRequiredDescription
outcome_reasonstring · one of profile_mismatch, not_reachable, duplicate, quality, capacity, otherrequired

WarrantyClaim

FieldTypeRequiredDescription
reasonstringrequired
notestring or nullrequired
filed_atstring or null (date-time)required

ReservationNextActions

FieldTypeRequiredDescription
can_file_warranty_claimbooleanrequired
can_view_creatorbooleanrequired

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.

FieldTypeRequiredDescription
object"reservation" (exactly)required
idstringrequired
offerstring or nullrequired

The offer (offer_…).

statusstringrequired

awaiting_payment, paid (her contact is unlocked, the warranty runs), completed, refunded or cancelled.

creator_namestring or nullrequired

null until your agency paid for her (paid or completed; also null again after a refund).

creator_refstring or nullrequired
amountMoneyrequired

An amount in integer minor units (cents) and its ISO 4217 currency; null when not set.

payment_referencestringrequired

Put it on your bank transfer.

payment_due_atstring or null (date-time)required
paid_atstring or null (date-time)required
warranty_untilstring or null (date-time)required
completed_atstring or null (date-time)required
refunded_atstring or null (date-time)required
warranty_claimWarrantyClaim or nullrequired
next_actionsReservationNextActionsrequired
created_atstring or null (date-time)required
updated_atstring or null (date-time)required

ReservationList

FieldTypeRequiredDescription
object"list" (exactly)required
dataarray of Reservationrequired
has_morebooleanrequired
next_cursorstring or nullrequired

ReservationCreator

Her contact, after payment only. Never the referrer, internal notes or her consent records.

FieldTypeRequiredDescription
object"reservation_creator" (exactly)required
reservationstringrequired
creator_namestringrequired
creator_refstring or nullrequired
instagram_handlestring or nullrequired
other_contactstring or nullrequired
platformsarray of stringrequired
follower_countinteger or nullrequired
nichestring or nullrequired

WarrantyClaimCreate

FieldTypeRequiredDescription
reasonstring · one of creator_unreachable, no_show, false_data, contract_refused, otherrequired
notestring or null · 0–2000 charsoptional

Trimmed; blank counts as no note.

TestOfferCreate

Every field is optional.

FieldTypeRequiredDescription
creator_namestring · 1–120 charsoptional

Default: a generated test name. The offer shows it only after …/mark-paid, like a live offer.

placement_feeMoneyInputoptional

{"amount_minor": 150000, "currency": "USD"} = 1,500.00 USD. null clears the fee.

expires_in_hoursinteger · 1–720optional

Default: the offer deadline of GET /v1/settings.

TestReservationRefund

FieldTypeRequiredDescription
reasonstring · one of creator_unreachable, no_show, false_data, contract_refused, otheroptional

Default: the reason of your warranty claim, else other.

ClockAdvance

FieldTypeRequiredDescription
hoursinteger · 1–720required

ClockAdvanceResult

FieldTypeRequiredDescription
object"clock_advance" (exactly)required
hoursintegerrequired
expired_offersintegerrequired
cancelled_reservationsintegerrequired
completed_reservationsintegerrequired

OfferEvent

An event whose data.object is an Offer — or {"id": …, "object": …, "deleted": true} when it no longer exists.

FieldTypeRequiredDescription
object"event" (exactly)required
idstringrequired
typestringrequired
created_atstring (date-time)required
modestringrequired
api_versionstringrequired
sequenceintegerrequired
dataobjectrequired
previous_attributesobjectoptional

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.

FieldTypeRequiredDescription
object"event" (exactly)required
idstringrequired
typestringrequired
created_atstring (date-time)required
modestringrequired
api_versionstringrequired
sequenceintegerrequired
dataobjectrequired
previous_attributesobjectoptional

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.

FieldTypeRequiredDescription

OAuthApp

FieldTypeRequiredDescription
object"oauth_app" (exactly)required
idstringrequired
modestringrequired

live or test (the mode of the key that registered it).

client_idstringrequired

Public; sent to /oauth/authorize and /oauth/token.

namestringrequired

Shown to the creator on the consent screen.

logo_urlstring or null (uri)required
privacy_urlstring (uri)required
redirect_urisarray of stringrequired

Matched exactly, character for character. Empty only while the app is disabled.

scopesarray of stringrequired

Creator scopes (CreatorScope).

confidentialbooleanrequired

true: a server-side app with a client secret; false: a public client (PKCE only).

secret_prefixstring or nullrequired

The start of the current client secret, e.g. cgcs_live_Ab3x; null for a public client.

enabledbooleanrequired

false while the app is disabled: unknown to /oauth/authorize, and /oauth/token answers unauthorized_client (existing grants are kept). Send redirect_uris in PATCH /v1/oauth-apps/{id} to enable it again.

disabled_reasonstring or nullrequired

member_offboarded: removing a member (or lowering her role below admin) removed every redirect URI that one of her keys had added, and none was left. null while enabled.

created_atstring (date-time)required
updated_atstring (date-time)required
client_secretstring or nulloptional

cgcs_live_… / cgcs_test_…. Only in the answers to create and roll (null for a public client, and in a replay of that answer); never again.

OAuthAppCreate

FieldTypeRequiredDescription
namestring · 3–60 charsrequired

Trimmed.

redirect_urisarray of string · at least 1, at most 10, each 0–2000 charsrequired

Distinct; https, no fragment, no user info, no wildcard, no private or loopback host. Test keys may also use http://localhost:<port> or http://127.0.0.1:<port>.

logo_urlstring or null · 0–2000 charsoptional
privacy_urlstring · 0–2000 charsrequired

Your privacy policy, linked on the consent screen.

scopesarray of CreatorScope · at least 1required

Distinct.

confidentialbooleanrequired

OAuthAppUpdate

Send only what changes. logo_url: null removes the logo.

FieldTypeRequiredDescription
namestring · 3–60 charsoptional
redirect_urisarray of string · at least 1, at most 10, each 0–2000 charsoptional
logo_urlstring or null · 0–2000 charsoptional
privacy_urlstring · 0–2000 charsoptional
scopesarray of CreatorScope · at least 1optional
confidentialbooleanoptional

Only its current value; it cannot change.

OAuthAppList

Every OAuth app of this mode (at most 10) on one page.

FieldTypeRequiredDescription
object"list" (exactly)required
dataarray of OAuthApprequired
has_morebooleanrequired
next_cursorstring or nullrequired

OAuthTestCodeCreate

FieldTypeRequiredDescription
client_idstringrequired

A test-mode app of your account.

lead_idstringrequired

A sandbox lead you may connect (you submitted it, or you hold a paid reservation for it).

redirect_uristring · 0–2000 charsrequired

One of the app's registered redirect URIs, character for character.

scopesarray of CreatorScope · at least 1required

A subset of the app's scopes; repeats are ignored.

code_challengestringrequired

BASE64URL(SHA256(code_verifier)) without padding (PKCE S256).

OAuthTestCode

FieldTypeRequiredDescription
object"oauth_test_code" (exactly)required
codestringrequired

The authorization code; exchange it at /oauth/token with grant_type=authorization_code.

expires_in60 (exactly)required

Seconds.

Creator

FieldTypeRequiredDescription
object"creator" (exactly)required
leadstringrequired

Her lead.

creator_namestringrequired
stagestringrequired

Same stages as lead.stage.

next_actionsobjectrequired
placementobject or nullrequired

The agency she was placed with, once it paid; null before.

updated_atstring or null (date-time)required

CreatorProfile

Her contact fields and the listing fields she edits herself. Never fees, deal terms or of_verified.

FieldTypeRequiredDescription
object"creator_profile" (exactly)required
leadobjectrequired
listingobjectrequired
can_edit_leadbooleanrequired

Contact fields can change while the lead is submitted (else 409 lead_locked).

can_edit_listingbooleanrequired

Listing fields can change until the listing is live (else 409 listing_locked).

updated_atstring 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.

FieldTypeRequiredDescription
leadobjectoptional
listingobjectoptional

CreatorPhoto

FieldTypeRequiredDescription
object"photo" (exactly)required
idstringrequired
leadstringrequired
kindstringrequired
is_primarybooleanrequired
urlstring or null (uri)required

Signed, valid for 1 hour; null when it could not be signed and in the replay of an upload.

url_expires_atstring or null (date-time)required
created_atstring or null (date-time)required

CreatorPhotoList

FieldTypeRequiredDescription
object"list" (exactly)required
dataarray of CreatorPhotorequired
has_morebooleanrequired
next_cursorstring or nullrequired

CreatorConsentEvent

One entry of her consent ledger. Never carries her IP address or browser.

FieldTypeRequiredDescription
object"consent_event" (exactly)required
idstringrequired
kindstringrequired

consent_granted, consent_revoked, age_confirmed or creator_terms_accepted.

text_kindstringrequired
text_versionintegerrequired
channelstring or nullrequired

Where she decided: hosted_link, hosted_portal, admin, legacy or oauth_app:app_… (the app that sent it).

created_atstring (date-time)required

CreatorConsentState

FieldTypeRequiredDescription
object"consent_state" (exactly)required
age_confirmationobjectrequired
eventsarray of CreatorConsentEventrequired

Oldest first.

ConsentText

FieldTypeRequiredDescription
object"consent_text" (exactly)required
kindstringrequired
versionintegerrequired

Send it as text_version (creator terms: version) with her decision.

localestringrequired
body_mdstringrequired

Markdown. Show it to her in full before she decides.

sha256stringrequired
published_atstring 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.

FieldTypeRequiredDescription
text_versioninteger · ≥ 1optional
localestringoptional

The language of the text she saw, default en.

CreatorAgreement

FieldTypeRequiredDescription
object"creator_agreement" (exactly)required
typestringrequired
current_versioninteger or nullrequired
accepted_versioninteger or nullrequired
accepted_atstring or null (date-time)required

CreatorAgreementList

FieldTypeRequiredDescription
object"list" (exactly)required
dataarray of CreatorAgreementrequired
has_morebooleanrequired
next_cursorstring or nullrequired

CreatorTermsAccept

FieldTypeRequiredDescription
versioninteger · ≥ 1required

The current version (409 consent_text_outdated otherwise).

SupportTicket

FieldTypeRequiredDescription
object"support_ticket" (exactly)required
idstringrequired
subjectstringrequired
statusstringrequired
created_atstring (date-time)required
updated_atstring (date-time)required
last_message_atstring or null (date-time)required

SupportTicketList

FieldTypeRequiredDescription
object"list" (exactly)required
dataarray of SupportTicketrequired
has_morebooleanrequired
next_cursorstring or nullrequired

SupportTicketCreate

FieldTypeRequiredDescription
subjectstring · 3–200 charsrequired

Trimmed.

bodystring · 1–5000 charsrequired

Her first message; trimmed.

SupportMessage

FieldTypeRequiredDescription
object"support_message" (exactly)required
idstringrequired
ticketstringrequired
bodystringrequired
from_staffbooleanrequired
created_atstring (date-time)required

SupportMessageList

FieldTypeRequiredDescription
object"list" (exactly)required
dataarray of SupportMessagerequired
has_morebooleanrequired
next_cursorstring or nullrequired

SupportReply

FieldTypeRequiredDescription
bodystring · 1–5000 charsrequired

Trimmed.

Job

FieldTypeRequiredDescription
object"job" (exactly)required
idstringrequired
typestringrequired

data_export.

statusstringrequired

queued, running, succeeded or failed.

progressinteger or null · 0–100required
resultobject or nullrequired

After success: the data request that holds the download.

error_codestring or nullrequired

Why it failed, e.g. timeout, upload_failed, lead_anonymized. Request a new export.

created_atstring (date-time)required
finished_atstring or null (date-time)required

DataRequest

FieldTypeRequiredDescription
object"data_request" (exactly)required
idstringrequired
kindstringrequired

export or deletion.

statusstringrequired

open, ready (export to download), completed, rejected, failed or expired.

jobstring or nullrequired

The export job (job_…); null for a deletion request.

expires_atstring or null (date-time)required

Until when the export can be downloaded (7 days after it was ready).

created_atstring (date-time)required
completed_atstring or null (date-time)required
download_urlstring or null (uri)optional

Only on GET /v1/creator/data-export/{id}: a JSON file, signed until download_url_expires_at (1 hour at most, never past expires_at; each call signs a new link); null unless status is ready.

download_url_expires_atstring or null (date-time)optional

ConnectedApp

FieldTypeRequiredDescription
object"connected_app" (exactly)required
idstringrequired
namestringrequired
logo_urlstring or null (uri)required
privacy_urlstring (uri)required
owner_namestringrequired

The partner or agency behind the app.

scopesarray of stringrequired
connected_atstring or null (date-time)required
last_used_atstring or null (date-time)required

ConnectedAppList

FieldTypeRequiredDescription
object"list" (exactly)required
dataarray of ConnectedApprequired
has_morebooleanrequired
next_cursorstring or nullrequired

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.

FieldTypeRequiredDescription
idstringrequired
object"data_request" (exactly)required
deletedtrue (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.

FieldTypeRequiredDescription
idstringrequired
object"job" (exactly)required
deletedtrue (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"}.

FieldTypeRequiredDescription
object"event" (exactly)required
idstringrequired
typestringrequired
created_atstring (date-time)required
modestringrequired
api_versionstringrequired
sequenceintegerrequired
dataobjectrequired

JobEvent

An event whose data.object is a JobRef: {"id": "job_…", "object": "job"}.

FieldTypeRequiredDescription
object"event" (exactly)required
idstringrequired
typestringrequired
created_atstring (date-time)required
modestringrequired
api_versionstringrequired
sequenceintegerrequired
dataobjectrequired

Member

A person who can sign in to the account (status active) or an open invitation (invited).

FieldTypeRequiredDescription
object"member" (exactly)required
idstringrequired

mem_… for a person, inv_… for an invitation. Use it with DELETE /v1/members/{id}.

emailstringrequired

Lower-case email address of the login or the invitation.

rolestringrequired

owner, admin, developer or viewer — /members/

statusstringrequired

active or invited. New values may be added.

email_verifiedboolean or nullrequired

People: false when the login was created on the join page — whoever opened the link set its password, nobody proved the address; true otherwise. null for invitations.

created_atstring (date-time)required

When the person joined or the invitation was created.

expires_atstring or null (date-time)required

Invitations: when the link stops working (48 hours). null for people.

join_urlstring or null (uri)required

Only in the first answer to POST /v1/members: the one-time link for the person. null everywhere else, also in an Idempotency-Key replay.

MemberInvite

FieldTypeRequiredDescription
emailstring · 3–254 charsrequired

The address the person signs in with; compared without case and surrounding whitespace.

rolestring · one of developer, viewerrequired

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

FieldTypeRequiredDescription
object"list" (exactly)required
dataarray of Memberrequired
has_morebooleanrequired

Always false: the list is not paginated.

next_cursorstring or nullrequired

MemberDeleted

FieldTypeRequiredDescription
object"member" (exactly)required
idstringrequired
deletedtrue (exactly)required

ErrorResponse

FieldTypeRequiredDescription
errorobjectrequired
FieldTypeRequiredDescription
typestringrequired

invalid_request, authentication, permission, rate_limit or api_error.

codeErrorCoderequired

Stable, machine-readable error code. Branch on this, not on message. New codes may be added within v1.

messagestringrequired

For a developer reading a log; may change. Never branch on it.

doc_urlstring (uri)required

/errors/#<code>

request_idstringrequired

Same as X-Request-Id.

fieldstringoptional

The request field the error is about (first one when there are several).

detailsarray of objectoptional

Every field problem of the request, not just the first.

leadobject or nulloptional

With duplicate_own_lead: your existing lead.

parameterstringoptional

With unknown_parameter and invalid_cursor: the query parameter.

agreement_typestringoptional

With terms_not_accepted.

scopestringoptional

With insufficient_scope: the scope the key lacks.

blockersarray of stringoptional

With not_ready_for_review.

current_statestringoptional

With invalid_state: the state that blocks the call.

current_versionintegeroptional

With invalid_state on agreement accept: the version to accept.

limitintegeroptional

With limit_reached: the limit that is reached.

ErrorCode

Stable, machine-readable error code. Branch on this, not on message. New codes may be added within v1.

Scope

Scopes a key can carry. Each operation names the one it needs. Scopes of later endpoints are added with them.

  • account:read
  • account:write
  • agreements:write
  • keys:manage
  • webhooks:manage
  • leads:read
  • leads:write
  • photos:write
  • earnings:read
  • offers:read
  • offers:write
  • reservations:read
  • reservations:write
  • search_profile:write
  • extract
  • usage:read
  • audit:read
  • oauth_apps:manage
  • members:manage