API setup for developers

This guide is for someone building or maintaining software. It explains API keys, secure storage, and the technical response format.

1. Check access

Creators need an active Pro plan. Agencies need an active Pro, Scale, or Enterprise plan, and the signed-in user must be a current agency owner.

2. Create an API key

Creators manage keys from Profile → Public API. Agency owners manage agency keys from Agency settings → Public API.

When you create a key:

1. Give it a recognizable name.
2. Select only the scopes the integration needs.
3. Optionally choose a 30, 90, or 365-day expiration.
4. Copy the complete key from the one-time dialog.
5. Store it in a secret manager or protected server environment variable.

The complete key is shown once. CreatorsJet stores only a digest and cannot display the secret again.

3. Check the connection

Use the key as a Bearer credential. GET /me verifies the key, subject, scopes, and current API entitlement.

curl https://api.creatorsjet.com/public/v1/me \
  --header "Authorization: Bearer $CREATORSJET_API_KEY"

Agency response:

{
  "data": {
    "subject_type": "agency",
    "subject_id": "66b0f51d46071dc43b2db101",
    "user_id": "66b0f51d46071dc43b2db102",
    "scopes": ["roster:read", "roster:write"],
    "entitlement": "active"
  },
  "request_id": "50c20a47-bf9a-4dfa-98ae-54fd89a172e1"
}

4. Add a creator (agency developers)

Agency keys with roster:write can add one creator.

curl https://api.creatorsjet.com/public/v1/creators \
  --request POST \
  --header "Authorization: Bearer $CREATORSJET_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "display_name": "Maria Lopez",
    "email": "[email protected]",
    "country": "France",
    "languages": ["en", "fr"],
    "tags": ["fashion", "lifestyle"],
    "socials": [
      { "platform": "instagram", "handle_or_url": "@maria" }
    ]
  }'

display_name and at least one social identity are required. Supported social values are instagram, tiktok, youtube, facebook, linkedin, twitter, and x. V1 does not accept a remote avatar_url.

If one of the supplied social identities already belongs to a creator in the agency roster, the API returns that creator with created: false instead of creating a duplicate.

For a creator key, a useful first read is the creator's own profile. Use the subject_id returned by GET /me:

curl "https://api.creatorsjet.com/public/v1/creators/$CREATOR_SUBJECT_ID" \
  --header "Authorization: Bearer $CREATORSJET_API_KEY"

This request requires profile:read. Creator keys cannot retrieve a different creator ID.

Technical response details

Successful responses use:

{
  "data": {},
  "meta": {},
  "request_id": "..."
}

meta appears when the endpoint has pagination or other response metadata. Errors use application/problem+json; preserve request_id when reporting an issue.

Lists use opaque cursor pagination. The default limit is 25 and the maximum is 100. Pass the returned meta.next_cursor unchanged as the next request's cursor.

Production checklist

• Set explicit connection and read timeouts.
• Treat API keys, creator emails, and imported CSV rows as sensitive.
• Persist request_id with your operation logs, but never log the Authorization header.
• Follow Retry-After for 429 responses. Do not blindly retry a create request after an ambiguous connection failure; first check whether the resource was created.
• Store opaque IDs and cursors as strings without deriving meaning from their format.