# Welcome to CreatorsJet
> Build supported creator and agency workflows with CreatorsJet Public API V1.
>
> Canonical URL: https://docs.creatorsjet.com/docs
CreatorsJet developer documentation helps engineering and operations teams build server-side creator workflows with the implemented Public API V1 contract.
> **Info — Production integrations:**
>
> Public API V1 and CreatorsJet MCP are available at `https://api.creatorsjet.com` for eligible creator and agency accounts.
## Who this documentation is for
This documentation is designed for:
* Developers building creator or agency integrations
* Agency teams importing and maintaining creator rosters
* Product and data teams reading creator identities and summary metrics
* Platform engineers implementing secure, server-side media-kit workflows
## Start here
### [Public API V1](/api)
Build server-to-server creator and agency integrations with scoped API keys.
### [Getting started](/api/getting-started)
Create an API key and make your first authenticated production request.
### [Endpoint reference](/api/reference)
Review exact requests and responses generated from the OpenAPI 3.1 contract.
### [CreatorsJet MCP](/mcp)
Connect an OAuth-compatible MCP client and use CreatorsJet tools safely.
## Supported workflows
Public API V1 currently covers:
* Agency roster creation and cursor-paginated retrieval
* Validated creator CSV imports with row-level results
* Creator profile and summary-metric retrieval
* Default media-kit creation, listing, and retrieval
* Creator-owned link-in-bio creation and editing
* Agency-owned pitch-deck creation and editing
* Creator- and agency-owned campaign listing, retrieval, creation, and metadata editing
* Page-view analytics for owned CreatorsJet resources
## Machine-readable contracts
* Append `.md` to any documentation URL for its Markdown representation
* [OpenAPI 3.1 JSON](/openapi.json)
* [Documentation index](/llms.txt)
* [Complete Markdown corpus](/llms-full.txt)
---
# Link your creator profile to an agency
> Use the agency code from your manager to connect your existing creator profile to their agency.
>
> Canonical URL: https://docs.creatorsjet.com/docs/creator-guides/link-to-an-agency
If you work with an agency, your manager can give you an **agency code**. Entering that code connects your existing CreatorsJet creator profile to the agency.
## Before you start
* Ask your agency manager for their agency code.
* Sign in to the creator account you want to link.
## Link your account
1. In the left sidebar, select **Settings**.
2. From the Settings menu, select **Account**.
3. Under **Link to an agency**, enter the agency code your manager gave you.
4. Select **Link agency**.
## Important
Linking to an agency keeps you on your creator account and connects that profile to the agency.
Do not select **Switch to Agency** for this purpose. That option permanently changes your creator account into an agency account and cannot be undone.
## If the code does not work
Check that you copied the code exactly, then ask your agency manager to confirm that it is current. If you still cannot link your account, contact CreatorsJet Support with the agency name and the email address on your creator account.
---
# MCP overview
> Connect CreatorsJet to your AI assistant and ask it to help with media kits, socials, decks, and campaigns.
>
> Canonical URL: https://docs.creatorsjet.com/mcp
CreatorsJet MCP lets you use CreatorsJet from an AI assistant. You can ask simple questions such as “Show me my media kits” or “List my active campaigns.”
> **Info — MCP server URL:**
>
> Add `https://api.creatorsjet.com/mcp` to a compatible AI assistant.
## Start here
You do not need to write code or know tool names.
1. Add the MCP server URL to your AI assistant.
2. Choose **Connect** and sign in to CreatorsJet when asked.
3. Approve the access request.
4. Return to your assistant and ask for what you need.
Start with the [plain-language quick starts](/mcp/quick-starts). Your account only sees actions it is allowed to use.
## What you can ask for
* “Show me my media kits.”
* “List my connected social accounts.”
* “Show my active campaigns.”
* “Show our pitch decks.”
* “Find sponsorship opportunities for me.”
The assistant shows only information your account can access. It should ask before any destructive change, such as removing a social account.
## Do you need the Public API?
Usually, no. MCP is the easiest option when you want to work in an AI assistant. Use the [Public API](/api) only when a developer is connecting CreatorsJet to software, a website, or an internal system.
## For technical setup
Your AI assistant must support remote MCP connections and a secure browser sign-in. CreatorsJet uses OAuth for this connection; public API keys and browser session tokens do not work as MCP credentials. The connection never changes your plan or bypasses account limits.
For the complete technical list of tool names, permissions, and limitations, see [MCP tools](/mcp/tools).
## Next steps
* [Try the quick starts](/mcp/quick-starts)
* [See all tools and permissions](/mcp/tools)
* [Learn how changes are kept safe](/mcp/safety-and-plans)
---
# Quick starts
> Plain-language prompts for common CreatorsJet MCP tasks.
>
> Canonical URL: https://docs.creatorsjet.com/mcp/quick-starts
Use these examples after connecting CreatorsJet in an MCP client such as ChatGPT, Claude, or another compatible assistant. You do not need to know tool names or write code: send the prompt as written and the assistant chooses the appropriate CreatorsJet tool.
> **Info — Before you start:**
>
> Connect `https://api.creatorsjet.com/mcp`, sign in, and approve the requested access. You will see only the actions allowed for your account and approved scopes.
## Creator: find your media kit
Send this prompt:
```text
Show me my media kits.
```
The assistant returns each media kit's name, share link, and editor link. If you have more than one, ask: “Show me the next page of media kits.”
## Creator: check connected social accounts
Send this prompt:
```text
List my connected social accounts.
```
To narrow the answer, say:
```text
Show only my Instagram accounts.
```
The result shows the platform, handle, profile link, and connection status. It never exposes account passwords or social-platform OAuth credentials.
## Creator or agency: review campaigns
Send this prompt:
```text
Show my active campaigns.
```
Or, to see all of them:
```text
List my campaigns.
```
The assistant returns owned campaigns only. Ask it to open one campaign after you identify it by name or ID.
## Agency: find a pitch deck
Send this prompt:
```text
Show our pitch decks.
```
The assistant returns decks owned by your agency. Then you can say, for example, “Open the Summer creators deck” or “Update the title of deck `…`.”
## Agency: check a roster creator's socials
First obtain the creator ID from CreatorsJet or from a prior roster-import or creator-add result. Then send:
```text
Show the connected social accounts for creator ID 66b0f51d46071dc43b2db103.
```
The assistant verifies that the creator belongs to your agency roster before returning anything. Replace the sample ID with the creator's actual ID.
## A simple rule for safe changes
These prompts only read information. For a change such as adding or removing a social account, say exactly what you want changed. The assistant should show the selected account and ask for confirmation before it removes anything.
---
# MCP safety and plans
> Understand confirmation rules, tenant isolation, plan enforcement, upgrade actions, and MCP error responses.
>
> Canonical URL: https://docs.creatorsjet.com/mcp/safety-and-plans
CreatorsJet MCP tools resolve an authenticated actor containing the OAuth principal, creator or agency subject, user, granted scopes, and request ID. Tools apply subject ownership and scope checks before calling shared application services.
## Write-safety rules
Agents should follow these rules:
1. Validate a roster import before commit, show the complete preview and capacity impact, and obtain approval before `roster_commit_import`.
2. Obtain explicit confirmation immediately before `social_remove`.
3. Use `link_in_bio_get` before choosing create or update.
4. Use `deck_list` or `deck_get` before `deck_update`.
5. Use `campaign_list` or `campaign_get` before `campaign_update`.
6. Never start checkout, subscribe the user, or modify billing on the user's behalf.
Tool annotations identify read-only, idempotent, and destructive behavior for clients that support MCP annotations. Clients should still present an understandable confirmation when a destructive or consequential action is about to run.
## Tenant isolation
Creator tools act on the creator resolved from OAuth. Agency tools act on the agency and, where required, creators already in its roster.
Cross-tenant IDs do not grant access. Owned-resource services include the subject predicate in database queries, and inaccessible resources are reported as not found.
## Plans and allowances
OAuth grants role-compatible scopes; it does not grant a paid entitlement. Every tool checks current account eligibility when invoked. Operations also reuse the applicable CreatorsJet product rules, including creator and social capacity, media-kit rules, deck capacity, active-campaign capacity, analytics eligibility, and Sponsorship Intelligence access.
A plan or allowance failure returns a safe structured action. Example:
```json
{
"ok": false,
"error": {
"code": "LIMIT_EXCEEDED",
"message": "Your agency has reached its active campaign limit.",
"retryable": false,
"details": {
"usage": {
"current": 30,
"limit": 30,
"requested": 1,
"remaining": 0
},
"upgrade_url": "https://www.creatorsjet.com/a/my-plan?tab=upgrade&source=mcp",
"action_label": "View agency plans"
}
}
}
```
Usage appears only when the service can safely provide it. The text fallback also includes the upgrade URL for clients that do not display structured content.
| Context | Authenticated CreatorsJet destination |
| ------------------------- | ------------------------------------------------------------------ |
| Creator plan or allowance | `https://www.creatorsjet.com/my-plan?tab=subscription&source=mcp` |
| Agency plan or allowance | `https://www.creatorsjet.com/a/my-plan?tab=upgrade&source=mcp` |
| Sponsorship Intelligence | `https://www.creatorsjet.com/dashboard/sponsor/my-plan?source=mcp` |
The tool proposes the relevant page only. It never initiates checkout.
## Error handling
Tool results use an `ok` envelope. Errors contain a sanitized code, message, retryability flag, optional details, and optional `retry_after_seconds`.
Common codes include:
| Code | Meaning |
| ------------------------- | ------------------------------------------------------------- |
| `AUTHENTICATION_REQUIRED` | OAuth authentication is absent or expired |
| `SCOPE_REQUIRED` | The grant lacks the tool's required scope |
| `ROLE_FORBIDDEN` | The account role cannot use the tool |
| `PLAN_REQUIRED` | The operation requires an eligible plan |
| `LIMIT_EXCEEDED` | A current product allowance is exhausted |
| `VALIDATION_FAILED` | Tool input or normalized request data is invalid |
| `NOT_FOUND` | The resource is absent or inaccessible to the subject |
| `CONFLICT` | The request conflicts with current state or another operation |
| `RATE_LIMITED` | The tool's safety limit was reached |
| `RETRYABLE_INTERNAL` | A temporary internal failure prevented completion |
MCP tool safety limits are separate from product-plan allowances. When `retry_after_seconds` is present, clients should wait at least that long and avoid parallel retries.
## Audit and data handling
MCP audit events record tool name, outcome, client and user identifiers, request ID, duration, result code, and queue ID when applicable. Tool arguments, spreadsheet rows, OAuth tokens, emails, social handles, and creator payloads must not be written to audit events or application logs.
---
# MCP tools
> Complete tool and permission list for technical setup.
>
> Canonical URL: https://docs.creatorsjet.com/mcp/tools
> **Info — Looking for the easy version?:**
>
> You do not need to use these tool names in an AI assistant. Start with the [quick starts](/mcp/quick-starts) and use plain language instead.
This page is for people configuring a technical connection. It lists every available tool and the permission needed to use it.
## Agency roster tools
| Tool | Scope | Behavior |
| -------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `roster_validate_import` | `roster:read` | Validates 1–500 normalized creator rows and creates a 30-minute preview when every row is valid. |
| `roster_commit_import` | `roster:write` | Consumes an approved preview and queues the existing creator-import workflow. Reusing the preview returns the same import. |
| `roster_get_import_status` | `roster:read` | Returns queue status, progress, created creator and media-kit IDs, and row failures. |
| `roster_add_creator` | `roster:write` | Adds or links one creator by normalized social identity and ensures the agency media kit exists. |
The MCP client parses a spreadsheet into normalized JSON rows before calling `roster_validate_import`; the tool does not receive a raw spreadsheet file. An agent must show the valid preview and its capacity impact before calling `roster_commit_import`.
## Creator and social tools
| Tool | Role | Scope | Behavior |
| ------------------ | ----------------- | ------------------ | ---------------------------------------------------------------------------------------------------------- |
| `media_kit_list` | Creator or Agency | `media_kits:read` | Lists visible media kits with opaque pagination. Agencies can filter by a roster `creator_id`. |
| `media_kit_ensure` | Creator | `media_kits:write` | Returns the latest personal media kit or creates one link-only default kit. |
| `social_list` | Creator | `profile:read` | Lists the authenticated creator's connected social accounts without OAuth credentials. |
| `social_list` | Agency | `roster:read` | Lists connected social accounts for a selected creator in the agency roster. |
| `social_add` | Creator | `media_kits:write` | Adds a social identity to the authenticated creator and synchronizes the personal default kit. |
| `social_add` | Agency | `roster:write` | Adds a social identity to a selected creator in the agency roster and synchronizes the agency default kit. |
| `social_remove` | Creator | `media_kits:write` | Removes a selected social identity from the creator and associated personal kits. |
| `social_remove` | Agency | `roster:write` | Removes a selected social identity from an agency roster creator and associated agency kits. |
Agency social calls require `creator_id`. Creator calls infer the creator from OAuth. `social_list` supports cursor pagination and an optional platform filter. Supported social platform values are `instagram`, `tiktok`, `youtube`, `facebook`, `linkedin`, `twitter`, `x`, `twitch`, `snapchat`, and `threads`.
`social_remove` is marked destructive. The agent must identify the matching social account and obtain explicit confirmation before calling it.
## Link-in-bio tools
| Tool | Role | Scope | Behavior |
| -------------------- | ------- | ------------------- | --------------------------------------------------------------------------- |
| `link_in_bio_get` | Creator | `link_in_bio:read` | Returns the creator's page, social links, and supported blocks. |
| `link_in_bio_create` | Creator | `link_in_bio:write` | Creates the creator's single page with a public slug and supported content. |
| `link_in_bio_update` | Creator | `link_in_bio:write` | Updates page copy, social links, or existing and new supported blocks. |
The tools support link, title, and text blocks. They do not delete blocks, upload image or video content, configure custom domains, or expose the complete visual designer. Agents should call `link_in_bio_get` before deciding whether to create or update.
## Pitch-deck tools
| Tool | Role | Scope | Behavior |
| ------------- | ------ | ------------- | ------------------------------------------------------------------------------------- |
| `deck_list` | Agency | `decks:read` | Lists agency-owned decks with opaque pagination. |
| `deck_get` | Agency | `decks:read` | Returns one owned deck and its selected creator IDs. |
| `deck_create` | Agency | `decks:write` | Creates a deck from creators already in the agency roster. |
| `deck_update` | Agency | `decks:write` | Updates selected creators, copy, supported branding fields, slug, or access settings. |
Password input is write-only. The tools do not upload deck images, delete decks, or add creators to the roster implicitly. Agents should list or retrieve the deck before updating it.
## Campaign tools
| Tool | Role | Scope | Behavior |
| ----------------- | ----------------- | ----------------- | -------------------------------------------------------------------------------- |
| `campaign_list` | Creator or agency | `campaigns:read` | Lists owned campaigns and optionally filters by status. |
| `campaign_get` | Creator or agency | `campaigns:read` | Returns one owned campaign and its supported settings. |
| `campaign_create` | Creator or agency | `campaigns:write` | Creates an owned campaign and applies the existing active-campaign allowance. |
| `campaign_update` | Creator or agency | `campaigns:write` | Updates metadata, dates, tracking cadence or state, CPM values, or EMV override. |
New campaigns default to `on_request` tracking. Automatic tracking requires a future end date. The tools do not manage participants, content, public-report settings, refresh execution, lifecycle actions, or deletion.
## Analytics and sponsorship tools
| Tool | Role | Scope | Behavior |
| -------------------------- | ----------------- | ------------------- | --------------------------------------------------------------------------------------------- |
| `analytics_get_views` | Creator or agency | `analytics:read` | Returns page views and unique visitors for one owned resource or an owned-resource aggregate. |
| `sponsorship_find_matches` | Creator | `sponsorships:read` | Returns evidence-backed matches for an eligible Sponsorship Intelligence account. |
Analytics resource types are `media_kit`, `link_in_bio`, `roster`, `deck`, and `campaign`. Link-in-bio analytics are creator-only; roster and deck analytics are agency-only. Campaign analytics measure public campaign-report visits, not social content views.
Sponsorship discovery is available through MCP only. There is no sponsorship endpoint in Public API V1.
---
# Page-view analytics
> Retrieve page views and unique visitors for CreatorsJet resources owned by the API subject.
>
> Canonical URL: https://docs.creatorsjet.com/api/analytics
`GET /analytics/views` returns page views, unique visitors, and a time series for one owned CreatorsJet resource or an aggregate of owned resources. It requires `analytics:read`.
> **Info — Page views are not social-platform views:**
>
> This endpoint measures visits to CreatorsJet pages. It does not return views, reach, impressions, or engagement for Instagram, TikTok, YouTube, or other social content.
## Available resources
| `resource_type` | Creator key | Agency key | Measured page |
| --------------- | ----------: | ---------: | ------------------------------- |
| `media_kit` | Yes | Yes | Owned media-kit pages |
| `link_in_bio` | Yes | No | The creator's link-in-bio page |
| `roster` | No | Yes | The agency's public roster page |
| `deck` | No | Yes | Agency-owned pitch-deck pages |
| `campaign` | Yes | Yes | Owned public campaign reports |
## Query one resource
Supply the resource's opaque ID through `resource_id`:
```bash
curl "https://api.creatorsjet.com/public/v1/analytics/views?resource_type=campaign&resource_id=$CAMPAIGN_ID&timeframe=last7d&timezone=Europe/Paris" \
--header "Authorization: Bearer $CREATORSJET_API_KEY"
```
The timezone must be an IANA timezone. It controls calendar boundaries and time-series buckets.
## Query an aggregate
Omit `resource_id` to aggregate every owned resource of that type:
```bash
curl "https://api.creatorsjet.com/public/v1/analytics/views?resource_type=media_kit&timeframe=mtd&timezone=UTC" \
--header "Authorization: Bearer $CREATORSJET_API_KEY"
```
The response reports whether the request covered one resource or an aggregate:
```json
{
"data": {
"resource_type": "campaign",
"resource_scope": "resource",
"resource_count": 1,
"resource_ids": ["66b0f51d46071dc43b2db103"],
"metric": "page_views",
"totals": {
"page_views": 482,
"unique_visitors": 361
},
"timeframe": "last7d",
"timezone": "Europe/Paris",
"period": {
"start": "2026-08-07T00:00:00.000Z",
"end": "2026-08-14T10:00:00.000Z"
},
"granularity": "day",
"series": []
},
"request_id": "50c20a47-bf9a-4dfa-98ae-54fd89a172e1"
}
```
Supported `timeframe` values are `last24h`, `today`, `yesterday`, `last7d`, `wtd`, `mtd`, `ytd`, and `all`.
## Empty and inaccessible resources
An aggregate with no owned resources returns zero totals. A specific resource that is absent or belongs to another subject returns `404 NOT_FOUND`.
Do not sum overlapping aggregate and resource responses. Use one aggregation strategy in your application and retain the response timezone with any stored series.
See the [analytics endpoint reference](/api/reference/analytics/getViewAnalytics) for the complete schema.
---
# Authentication
> Authenticate Public API V1 requests with scoped CreatorsJet API keys.
>
> Canonical URL: https://docs.creatorsjet.com/api/authentication
The Public API uses scoped Bearer API keys. Session JWTs, browser sessions, and MCP OAuth tokens are not accepted under `/public/v1`.
## Authorization header
Send the complete key on every request:
```http
Authorization: Bearer cj_live_.
```
The secret is a 32-byte base64url value. Treat the entire key as sensitive even though the public ID and display prefix remain visible in settings.
## Key ownership and eligibility
| Subject | Who manages keys | Plan requirement |
| ------- | ----------------------------------------- | -------------------------------- |
| Creator | The signed-in user linked to that creator | Active Pro |
| Agency | Any current agency owner | Active Pro, Scale, or Enterprise |
Entitlement and subject ownership are checked on every API request. A plan downgrade disables requests without deleting the key. Current agency owners can manage keys owned by their agency.
## Scopes
| Scope | Creator keys | Agency keys | Grants |
| ------------------- | -----------: | ----------: | ------------------------------------------------------------------------- |
| `profile:read` | Yes | No | Read the creator subject's own profile summary |
| `roster:read` | No | Yes | List and retrieve creators in the agency roster and inspect import status |
| `roster:write` | No | Yes | Add creators and start CSV imports |
| `media_kits:read` | Yes | Yes | List and retrieve visible owned media kits |
| `media_kits:write` | Yes | Yes | Ensure the subject's default media kit exists |
| `link_in_bio:read` | Yes | No | Retrieve the creator subject's link-in-bio page |
| `link_in_bio:write` | Yes | No | Create or edit the creator subject's link-in-bio page |
| `decks:read` | No | Yes | List and retrieve pitch decks owned by the agency subject |
| `decks:write` | No | Yes | Create or edit pitch decks owned by the agency subject |
| `campaigns:read` | Yes | Yes | List and retrieve campaigns owned by the subject |
| `campaigns:write` | Yes | Yes | Create or edit campaigns owned by the subject |
| `analytics:read` | Yes | Yes | Read page views and unique visitors for resources owned by the subject |
`sponsorships:read` is reserved for future compatibility and cannot be selected for a V1 API key.
Create separate keys for integrations with different responsibilities. Do not give a read-only integration write scopes.
## Lifecycle
* A subject can have at most 10 active keys.
* A key can have no expiration or expire after 30, 90, or 365 days.
* The complete secret appears only when the key is created.
* Revocation is immediate and permanent.
* Rotation is create a replacement, deploy it, verify it, then revoke the previous key.
* `last_used_at` is updated at most once every 15 minutes, so it is an activity indicator rather than a request log.
## Secret handling
* Keep API keys in a server-side secret manager or protected environment variable.
* Never expose a key through browser JavaScript, mobile binaries, screenshots, support messages, analytics, or source control.
* Redact `Authorization` before logging requests.
* Revoke and replace a key immediately if it may have been exposed.
Malformed, expired, revoked, or incorrect keys return `401 INVALID_API_KEY`. A missing credential returns `401 AUTHENTICATION_REQUIRED`.
---
# Campaigns
> Create, list, retrieve, and edit creator- or agency-owned campaigns through Public API V1.
>
> Canonical URL: https://docs.creatorsjet.com/api/campaigns
Creator and agency keys can manage campaigns owned directly by their authenticated subject.
| Operation | Scope |
| -------------------------- | ----------------- |
| List or retrieve campaigns | `campaigns:read` |
| Create or update campaigns | `campaigns:write` |
## Create a campaign
Only `name` is required. If `refresh_cadence` is omitted, the campaign uses `on_request` tracking.
```bash
curl https://api.creatorsjet.com/public/v1/campaigns \
--request POST \
--header "Authorization: Bearer $CREATORSJET_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"name": "Summer launch",
"description": "Track creator content for the summer launch.",
"refresh_cadence": "on_request",
"cpm": {
"instagram": 14,
"tiktok": 11
}
}'
```
Automatic tracking supports `daily` and `every_2_days`. Both require `ends_at` to be a future ISO 8601 timestamp. Use `on_request` when the integration should create the campaign without scheduling automatic collection.
Campaign creation uses the account's existing active-campaign allowance. When the allowance is exhausted, the API returns `403 LIMIT_EXCEEDED`.
## List and retrieve campaigns
List campaigns with opaque cursor pagination. The optional `status` filter accepts `active`, `completed`, or `archived`.
```bash
curl "https://api.creatorsjet.com/public/v1/campaigns?status=active&limit=25" \
--header "Authorization: Bearer $CREATORSJET_API_KEY"
```
The list response includes summary values when they are available. Retrieve one campaign by its returned `id`:
```bash
curl "https://api.creatorsjet.com/public/v1/campaigns/$CAMPAIGN_ID" \
--header "Authorization: Bearer $CREATORSJET_API_KEY"
```
## Update supported settings
`PATCH /campaigns/{campaign_id}` updates only supplied fields.
```bash
curl "https://api.creatorsjet.com/public/v1/campaigns/$CAMPAIGN_ID" \
--request PATCH \
--header "Authorization: Bearer $CREATORSJET_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"description": "Updated launch reporting scope.",
"cpm": {
"instagram": 16
},
"emv_override": 2500
}'
```
Supported fields are:
* `name`
* `description`
* `starts_at`
* `ends_at`
* `refresh_cadence`
* `refresh_state`, limited to `active` or `paused`
* `cpm` values for Instagram, TikTok, YouTube, or Twitter
* `emv_override`
Partial `cpm` updates preserve platform values that are not supplied. Set `emv_override` to `null` to remove the override.
An `on_request` campaign remains paused even if an update asks for an active refresh state. Automatic cadence is required for an active schedule.
## Public-report state
Campaign responses include public-report state and an editor URL. `public_report.share_url` is `null` while the report is disabled.
Public API V1 does not enable reports or change their slug, password, visible metrics, sections, or branding. Configure those settings in CreatorsJet.
## Not included
Public API V1 does not manage campaign participants, tracked content, short links, metric overrides, refresh execution, completion, reopening, archiving, report publication, passwords, or deletion.
Use the [endpoint reference](/api/reference/campaigns/listCampaigns) for exact request and response schemas.
---
# Media kits, link in bio, and decks
> Work with the supported CreatorsJet publishing resources through Public API V1.
>
> Canonical URL: https://docs.creatorsjet.com/api/content-pages
Public API V1 exposes a deliberately small publishing surface: ensure and retrieve default media kits, manage one creator link-in-bio page, and manage agency pitch decks.
## Media kits
Creator and agency keys can ensure, list, and retrieve visible media kits.
For a creator key, omit `creator_id`; the creator is inferred from the key:
```bash
curl https://api.creatorsjet.com/public/v1/media-kits \
--request POST \
--header "Authorization: Bearer $CREATORSJET_API_KEY" \
--header "Content-Type: application/json" \
--data '{}'
```
For an agency key, supply a creator already in the agency roster:
```json
{
"creator_id": "66b0f51d46071dc43b2db103"
}
```
The endpoint returns `201` when it creates the default kit and `200` when it returns the existing kit. Repeated calls do not create customizable or duplicate kits.
Public API V1 does not edit kit blocks, themes, analytics configuration, publication settings, or platform synchronization.
## Connected social accounts
`GET /socials` lists the connected social accounts for a creator. Creator keys infer the creator from the key and require `profile:read`. Agency keys require `roster:read` and an explicit `creator_id` for a creator already in the agency roster.
The response contains only the account ID, platform, username, profile URL, and connection status. OAuth tokens and synchronization credentials are never returned. Use `platform`, `cursor`, and `limit` to filter and paginate the list.
## Link in bio
Link-in-bio management is creator-only. Call `GET /link-in-bio` before choosing whether to create or update the page.
Create the creator's single page with a public slug:
```bash
curl https://api.creatorsjet.com/public/v1/link-in-bio \
--request POST \
--header "Authorization: Bearer $CREATORSJET_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"slug": "maria-links",
"username": "Maria",
"bio": "Fashion creator and stylist",
"social_links": [
{ "platform": "instagram", "handle_or_url": "@maria" }
],
"blocks": [
{
"client_id": "portfolio",
"type": "link",
"title": "My portfolio",
"url": "https://maria.example.com",
"visible": true,
"order": 0
}
]
}'
```
New blocks require a stable `client_id`. Keep that value in your system and reuse it when updating the same block. Existing blocks are selected by their returned `id`.
`PATCH /link-in-bio` changes only supplied page fields and blocks. Omitting a field leaves it unchanged. V1 supports `link`, `title`, and `text` blocks; it does not delete blocks, upload media, configure custom domains, or expose the complete designer.
Social links on a link-in-bio page are presentation links. They do not attach or remove the creator's underlying CreatorsJet social accounts.
## Pitch decks
Pitch decks are agency-only. Every `creator_id` selected for a deck must belong to the authenticated agency's roster.
Create a deck with `POST /decks`:
```bash
curl https://api.creatorsjet.com/public/v1/decks \
--request POST \
--header "Authorization: Bearer $CREATORSJET_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"slug": "summer-creators",
"title": "Summer creator shortlist",
"bio": "Creators selected for the summer launch.",
"contact_email": "partnerships@agency.example",
"creator_ids": ["66b0f51d46071dc43b2db103"],
"tags": ["summer", "fashion"],
"visibility": "link"
}'
```
`PATCH /decks/{deck_id}` changes only supplied fields, except `creator_ids`, which replaces the deck's complete creator selection when provided.
For private visibility, provide a password in the same write. Passwords are write-only and never returned. The response reports only `has_password`.
Deck creation applies the agency's current deck allowance. V1 does not upload pictures or covers, ingest remote images, delete decks, or implicitly add creators to the roster.
## Use returned URLs
Media-kit, link-in-bio, and deck responses include editor and public share URLs where applicable. Use those returned URLs instead of constructing frontend routes in your integration.
For exact field constraints, themes, CTA values, visibility behavior, and response schemas, use the [generated endpoint reference](/api/reference).
---
# Errors
> Handle CreatorsJet Public API V1 problem responses and stable error codes.
>
> Canonical URL: https://docs.creatorsjet.com/api/errors
Errors use `application/problem+json`.
```json
{
"type": "https://api.creatorsjet.com/problems/validation-failed",
"title": "Invalid request",
"status": 400,
"code": "VALIDATION_FAILED",
"detail": "One or more fields are invalid",
"request_id": "50c20a47-bf9a-4dfa-98ae-54fd89a172e1",
"errors": [
{
"field": "socials",
"message": "Array must contain at least 1 element(s)"
}
]
}
```
| Field | Meaning |
| ------------ | ----------------------------------------- |
| `type` | Stable problem-type URL |
| `title` | Short category suitable for display |
| `status` | HTTP status code |
| `code` | Stable machine-readable error code |
| `detail` | Safe explanation of this failure |
| `request_id` | Identifier to retain for logs and support |
| `errors` | Optional field or row-level details |
## Common error codes
| HTTP | Code | Meaning | Action |
| ---: | -------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------ |
| 400 | `VALIDATION_FAILED` | A body, query, or field is invalid | Correct the fields listed in `errors` |
| 400 | `CSV_FILE_REQUIRED` | The multipart `file` field is missing | Attach one CSV file |
| 401 | `AUTHENTICATION_REQUIRED` | The Bearer credential is missing | Send a Public API key |
| 401 | `INVALID_API_KEY` | The key is malformed, incorrect, expired, or revoked | Replace or recreate the key |
| 403 | `PUBLIC_API_PLAN_REQUIRED` | The subject no longer has an eligible plan | Restore an eligible plan |
| 403 | `SCOPE_REQUIRED` | The key lacks the operation's scope | Use or create a least-privilege key with that scope |
| 403 | `SUBJECT_FORBIDDEN` | The account type cannot use this endpoint | Use an agency or creator endpoint appropriate to the subject |
| 403 | `LIMIT_EXCEEDED` | A current product-plan allowance has been reached | Review usage or change the plan before retrying |
| 404 | `NOT_FOUND` | The resource is absent or belongs to another tenant | Verify the opaque ID and authenticated subject |
| 409 | `CONFLICT` | The request conflicts with identity, capacity, or current state | Inspect the detail and do not retry unchanged |
| 413 | `REQUEST_TOO_LARGE` | A JSON body or CSV exceeds its size limit | Reduce the payload |
| 415 | `UNSUPPORTED_MEDIA_TYPE` | An import is not a CSV file | Submit `text/csv` multipart data |
| 429 | `RATE_LIMITED` | The active quota was exceeded | Wait for `Retry-After` |
| 503 | `PUBLIC_API_DISABLED` | Public API routing is not enabled in the environment | Do not retry continuously |
| 503 | `RATE_LIMIT_UNAVAILABLE` | Limits cannot be safely enforced | Retry later with backoff |
| 500 | `INTERNAL_ERROR` | An unexpected server error occurred | Retry safe reads; contact support if persistent |
## Tenant-safe not found responses
CreatorsJet returns `404` for resources that are absent or not owned by the authenticated subject, including creators, imports, media kits, decks, and campaigns. Do not use response differences to probe for resources owned by another account.
## Retry guidance
* Retry `429` after `Retry-After`.
* Retry temporary `503` and `500` responses with bounded exponential backoff for reads. After an ambiguous create failure, first check whether the resource was created.
* Do not retry validation, authentication, scope, not-found, or conflict errors without changing the request or account state.
* Log the error `code`, HTTP status, and `request_id`; never log the API key, CSV rows, or sensitive creator payloads.
---
# API setup for developers
> Create an API key and make a first request from secure server-side software.
>
> Canonical URL: https://docs.creatorsjet.com/api/getting-started
> **Info — Not a developer?:**
>
> Use the [API quick starts](/api/quick-starts) for simple read-only examples, or use [MCP](/mcp) to work in an AI assistant without writing code.
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.
```bash
curl https://api.creatorsjet.com/public/v1/me \
--header "Authorization: Bearer $CREATORSJET_API_KEY"
```
Agency response:
```json
{
"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.
```bash
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": "maria@example.com",
"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`:
```bash
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:
```json
{
"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.
---
# Creator CSV imports
> Format, submit, and monitor agency creator-roster imports through Public API V1.
>
> Canonical URL: https://docs.creatorsjet.com/api/imports
Agency keys with `roster:write` can queue a CSV roster import. The endpoint accepts one multipart field named `file`.
## Limits
* CSV only
* Maximum file size: 2 MB
* Maximum creator rows: 500
* One queued or processing Public API import per agency
* Agency roster-capacity rules apply before the job is queued
## CSV columns
| Column | Required | Notes |
| ------------------ | ----------: | -------------------------------------------------------------------- |
| `username` | Yes | 3–50 letters, numbers, or hyphens; a leading `@` is removed |
| `first_name` | Yes | Creator's first name |
| `last_name` | Yes | Creator's last name |
| `contact_email` | Yes | Valid email address |
| `bio` | No | Creator biography |
| `location` | No | City or free-form location |
| `country` | No | Country |
| `tags` | No | Separate values with semicolons or commas |
| `languages` | No | Separate values with semicolons or commas |
| `avatar_url` | No | Must be blank for Public API V1; remote avatar ingestion is disabled |
| `instagram_handle` | Conditional | Handle, `@handle`, or supported profile URL |
| `tiktok_handle` | Conditional | Handle, `@handle`, or supported profile URL |
| `youtube_handle` | Conditional | Handle, `@handle`, or supported profile URL |
| `facebook_url` | Conditional | Facebook profile URL or accepted identity |
| `linkedin_url` | Conditional | LinkedIn profile URL or accepted identity |
| `x_handle` | Conditional | X/Twitter handle, `@handle`, or profile URL |
Every row needs at least one social identity.
```csv
username,first_name,last_name,contact_email,bio,location,country,tags,languages,avatar_url,instagram_handle,tiktok_handle,youtube_handle,facebook_url,linkedin_url,x_handle
maria2,Maria,Lopez,maria@example.com,Lifestyle creator based in Paris,Paris,France,fashion; lifestyle,en; fr,,maria,,,,,
```
## Start an import
```bash
curl https://api.creatorsjet.com/public/v1/creator-imports \
--request POST \
--header "Authorization: Bearer $CREATORSJET_API_KEY" \
--form "file=@creators.csv;type=text/csv"
```
The API validates the file, queues accepted work, and returns `202`. Poll the returned import ID with `GET /creator-imports/{import_id}` using a key that has `roster:read`.
## Status and row results
Import status is one of:
* `queued`
* `running`
* `completed`
* `completed_with_errors`
* `failed`
Progress includes total, processed, created, attached-social, and failed counts. Each row may include a `creator_id`, automatically created agency `media_kit_id`, social IDs, and error messages.
Public imports do not silently attach a globally existing creator identity to another agency. An ambiguous external identity produces a row-level creator identity conflict. Fix the identity or resolve ownership in CreatorsJet before retrying that row.
## Sensitive data
CSV files contain creator contact information. Keep them out of logs and public support tickets, upload them only to the official API host, and retain them only as long as your workflow requires.
---
# Public API overview
> Connect CreatorsJet to your own software. Most people should use MCP instead.
>
> Canonical URL: https://docs.creatorsjet.com/api
The Public API connects CreatorsJet to your own software, website, or internal system. It is for developers and technical teams.
> **Info — Want to use an AI assistant instead?:**
>
> Use [CreatorsJet MCP](/mcp) and ask in plain language. You do not need an API key or code for that.
## Choose the easiest path
| You want to… | Best option |
| ------------------------------------------------------------------------- | ------------------------------------- |
| Ask an AI assistant to show your media kits, socials, decks, or campaigns | [MCP quick starts](/mcp/quick-starts) |
| Connect CreatorsJet to software you are building | Continue with the Public API |
| Try a few safe API requests | [API quick starts](/api/quick-starts) |
## What the API can do
| If you need to… | The API can… |
| --------------------- | ------------------------------------------------------------------------------ |
| Find media kits | List media kits you are allowed to see. |
| Check social accounts | List connected social accounts safely, without passwords or OAuth credentials. |
| Review campaigns | List, create, and update campaigns you own. |
| Work with decks | List, create, and update agency pitch decks. |
| Import creators | Add a creator or upload a CSV roster as an agency. |
## Who can use it
| Account | Plan needed | What they can do |
| ------- | -------------------------------- | ------------------------------------------------------------------------------------- |
| Creator | Active Pro | Work with their own media kits, socials, link-in-bio page, and campaigns. |
| Agency | Active Pro, Scale, or Enterprise | Work with roster creators, their media kits and socials, agency decks, and campaigns. |
Only agency owners can create agency keys. API keys are private secrets and must stay on a secure server, never in a browser or public file.
## Full developer details
> **Info — Technical section:**
>
> The rest of this page is for developers. If you only want to try the API, use the [quick starts](/api/quick-starts).
| Domain | Implemented V1 behavior |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Creator profiles | Retrieve identity, public social accounts, summary metrics, data status, and freshness timestamps. Creator keys can retrieve only their own profile. |
| Agency rosters | Add one creator or list an agency roster with opaque cursor pagination. |
| CSV imports | Queue an import of up to 500 creator rows and retrieve row-level progress and results. |
| Media kits | Ensure, list, and retrieve the default media kit visible to a creator or agency subject. |
| Social accounts | List connected social accounts for the creator represented by a creator key or an agency roster creator. Responses never include OAuth credentials. |
| Link in bio | Creator keys can create, retrieve, or edit their single page, social profile links, and safe link, title, or text blocks. |
| Pitch decks | Agency keys can list, retrieve, create, or edit agency-owned decks using creators already in the agency roster. |
| Campaigns | Creator and agency keys can list, retrieve, create, or edit owned campaign metadata, schedules, tracking state, CPM values, and EMV override. |
| Page-view analytics | Retrieve page views, unique visitors, and a time series for owned media kits, link-in-bio pages, public rosters, decks, or campaign reports. |
| Sponsorship discovery | Not included in V1. No sponsorship endpoint is published. |
V1 intentionally excludes creator-profile mutation, social OAuth and synchronization controls, full media-kit editing, link-in-bio block deletion, campaign participants and content, campaign report configuration and lifecycle actions, deck, link-in-bio, or campaign deletion, media uploads, custom domains, the full link-in-bio designer, creator invitations, webhooks, SDKs, GraphQL, XLSX, Google Sheets imports, and remote avatar ingestion.
## Full endpoint list
| Method | Endpoint | Account | Required scope |
| ------- | ------------------------------ | ------------------------ | ------------------------------- |
| `GET` | `/me` | Creator or agency | Any valid key |
| `POST` | `/creators` | Agency | `roster:write` |
| `GET` | `/creators` | Agency | `roster:read` |
| `GET` | `/creators/{creator_id}` | Agency or creator self | `roster:read` or `profile:read` |
| `POST` | `/creator-imports` | Agency | `roster:write` |
| `GET` | `/creator-imports/{import_id}` | Agency | `roster:read` |
| `POST` | `/media-kits` | Creator or agency | `media_kits:write` |
| `GET` | `/media-kits` | Creator or agency | `media_kits:read` |
| `GET` | `/media-kits/{media_kit_id}` | Creator or agency | `media_kits:read` |
| `GET` | `/socials` | Creator or agency roster | `profile:read` or `roster:read` |
| `GET` | `/link-in-bio` | Creator | `link_in_bio:read` |
| `POST` | `/link-in-bio` | Creator | `link_in_bio:write` |
| `PATCH` | `/link-in-bio` | Creator | `link_in_bio:write` |
| `GET` | `/decks` | Agency | `decks:read` |
| `POST` | `/decks` | Agency | `decks:write` |
| `GET` | `/decks/{deck_id}` | Agency | `decks:read` |
| `PATCH` | `/decks/{deck_id}` | Agency | `decks:write` |
| `GET` | `/campaigns` | Creator or agency | `campaigns:read` |
| `POST` | `/campaigns` | Creator or agency | `campaigns:write` |
| `GET` | `/campaigns/{campaign_id}` | Creator or agency | `campaigns:read` |
| `PATCH` | `/campaigns/{campaign_id}` | Creator or agency | `campaigns:write` |
| `GET` | `/analytics/views` | Creator or agency | `analytics:read` |
Cross-account resources return `404` rather than revealing that another tenant owns the requested ID.
## Next steps
* [Try simple API examples](/api/quick-starts)
* [Set up an API key (developers)](/api/getting-started)
* [Browse the developer reference](/api/reference)
---
# Subjects and resource ownership
> Understand creator and agency API subjects, ownership boundaries, and tenant-safe resource access.
>
> Canonical URL: https://docs.creatorsjet.com/api/ownership
Every Public API key acts as one subject: a creator or an agency. The subject is fixed when the key is created and is returned by `GET /me`.
```json
{
"data": {
"subject_type": "creator",
"subject_id": "66b0f51d46071dc43b2db101",
"user_id": "66b0f51d46071dc43b2db102",
"scopes": ["profile:read", "campaigns:read"],
"entitlement": "active"
},
"request_id": "50c20a47-bf9a-4dfa-98ae-54fd89a172e1"
}
```
Do not treat `user_id` and `subject_id` as interchangeable. Creator resources are owned by the creator record identified by `subject_id`; agency resources are owned by the agency identified by `subject_id`.
## Ownership matrix
| Resource | Creator key | Agency key |
| --------------- | --------------------------------------------------- | ------------------------------------------------------------ |
| Creator profile | The creator subject only | Creators currently in the agency roster |
| Creator import | Not available | Imports started by the agency |
| Media kit | Personal kits without an agency owner | Kits owned by the agency for its roster creators |
| Link in bio | The creator subject's single page | Not available |
| Pitch deck | Not available | Decks owned by the agency |
| Campaign | Campaigns owned by the creator | Campaigns owned by the agency |
| Analytics | Owned media kits, link in bio, and campaign reports | Owned media kits, public roster, decks, and campaign reports |
For agency media-kit operations, `creator_id` selects a creator already in the agency roster. It does not transfer ownership of another agency's kit or create a cross-agency relationship.
For creator media-kit operations, omit `creator_id`. The API infers the creator from the key and rejects attempts to select a different creator.
## Tenant-safe lookups
Ownership is part of the database query for resource reads and writes. A resource that does not exist and a resource owned by another subject both return `404 NOT_FOUND`.
This behavior applies to opaque resource IDs. It prevents callers from using response differences to discover whether another account owns a creator, import, media kit, deck, or campaign.
## Integration guidance
* Persist the `subject_id` alongside the API-key configuration in your system.
* Do not accept arbitrary resource IDs from an untrusted client and pass them to the API without authorization in your own application.
* Store IDs as opaque strings; do not derive ownership or resource type from their format.
* Use separate keys when one integration needs agency access and another needs creator access.
* Re-run `GET /me` after rotating credentials or changing the connected CreatorsJet account.
> **Info — A scope does not change ownership:**
>
> A write scope permits an operation only within the key's subject. It never grants access to another creator or agency.
---
# Quick starts
> Copy-and-paste Public API V1 examples for finding media kits, social accounts, decks, and campaigns.
>
> Canonical URL: https://docs.creatorsjet.com/api/quick-starts
These examples are read-only: they do not change your CreatorsJet account. They are a good first test after you create an API key.
> **Info — No code? Use MCP instead:**
>
> If you are working in an AI assistant, use the [MCP quick starts](/mcp/quick-starts). This page is only for people using a terminal or building software.
## Before you start
If a developer has given you an API key, set it once in the terminal they told you to use:
```bash
export CREATORSJET_API_KEY="paste-your-api-key-here"
```
Replace sample IDs with IDs returned by CreatorsJet. Keep the API key private; never paste it into a website, spreadsheet, or chat message.
## List your media kits
Creator keys return the creator's visible media kits. Agency keys return kits owned by the agency.
```bash
curl "https://api.creatorsjet.com/public/v1/media-kits?limit=10" \
--header "Authorization: Bearer $CREATORSJET_API_KEY"
```
An agency can limit the result to one roster creator:
```bash
curl "https://api.creatorsjet.com/public/v1/media-kits?creator_id=66b0f51d46071dc43b2db103&limit=10" \
--header "Authorization: Bearer $CREATORSJET_API_KEY"
```
This needs the `media_kits:read` scope.
## List connected social accounts
A creator key lists the connected social accounts for the creator represented by the key:
```bash
curl "https://api.creatorsjet.com/public/v1/socials?limit=10" \
--header "Authorization: Bearer $CREATORSJET_API_KEY"
```
An agency key must specify a creator already in its roster. This example returns only that creator's Instagram accounts:
```bash
curl "https://api.creatorsjet.com/public/v1/socials?creator_id=66b0f51d46071dc43b2db103&platform=instagram&limit=10" \
--header "Authorization: Bearer $CREATORSJET_API_KEY"
```
Creator keys need `profile:read`; agency keys need `roster:read`. Results include a platform, username, profile URL, and connection status—never OAuth credentials.
## List agency pitch decks
Pitch decks belong to agencies:
```bash
curl "https://api.creatorsjet.com/public/v1/decks?limit=10" \
--header "Authorization: Bearer $CREATORSJET_API_KEY"
```
This needs `decks:read`.
## List active campaigns
Creator and agency keys can list their own campaigns:
```bash
curl "https://api.creatorsjet.com/public/v1/campaigns?status=active&limit=10" \
--header "Authorization: Bearer $CREATORSJET_API_KEY"
```
Remove `status=active` to return all campaigns. This needs `campaigns:read`.
## Read the result and get the next page
Every list returns a `data` array. When there are more results, the response also includes `meta.next_cursor`. Copy that value unchanged into the next request:
```bash
curl "https://api.creatorsjet.com/public/v1/campaigns?limit=10&cursor=PASTE_NEXT_CURSOR_HERE" \
--header "Authorization: Bearer $CREATORSJET_API_KEY"
```
If a request returns `403`, check that the API key has the listed scope. A `404` for a resource means it is not visible to that key.
---
# Rate limits
> Understand Public API V1 quotas, headers, and safe retry behavior.
>
> Canonical URL: https://docs.creatorsjet.com/api/rate-limits
Rate limits protect CreatorsJet and apply after a request is authenticated.
| Request category | Limit | Window |
| ---------------- | -----------------------: | -------- |
| Reads | 120 requests per API key | 1 minute |
| Ordinary writes | 30 requests per API key | 1 minute |
| Import starts | 5 requests per API key | 1 hour |
Only one Public API creator import may be queued or processing for an agency at a time.
## Response headers
Authenticated requests include:
| Header | Meaning |
| --------------------- | -------------------------------------------------------- |
| `RateLimit-Limit` | Maximum requests in the current window |
| `RateLimit-Remaining` | Requests left in the current window |
| `RateLimit-Reset` | Unix timestamp when the current window resets |
| `Retry-After` | Seconds to wait; included when a request is rate limited |
## Rate-limit responses
A request above its limit returns HTTP `429` and code `RATE_LIMITED`.
```json
{
"type": "https://api.creatorsjet.com/problems/rate-limited",
"title": "Rate limit exceeded",
"status": 429,
"code": "RATE_LIMITED",
"detail": "Too many requests",
"request_id": "50c20a47-bf9a-4dfa-98ae-54fd89a172e1"
}
```
Wait for `Retry-After` before retrying. Add bounded exponential backoff and jitter if multiple workers share a key.
## Rate-limit availability
CreatorsJet fails closed when Redis cannot safely enforce a limit. The API returns `503 RATE_LIMIT_UNAVAILABLE`; do not bypass this response with aggressive retries. Retry after a delay.
---
# Changelog
> Notable updates to CreatorsJet documentation and published integration contracts.
>
> Canonical URL: https://docs.creatorsjet.com/docs/reference/changelog
## 2026-08-15
* Published CreatorsJet Public API V1 for eligible creator and agency accounts at `https://api.creatorsjet.com/public/v1`.
* Published the CreatorsJet remote MCP server at `https://api.creatorsjet.com/mcp` with OAuth authorization and PKCE.
* Promoted the implemented Public API endpoint reference and MCP tool catalog to the production documentation contract.
* Documented uniform MCP plan eligibility checks and role-specific upgrade actions.
## 2026-08-14
* Created the initial CreatorsJet documentation foundation.
* Documented the implemented CreatorsJet Public API V1 contract for agency and creator accounts.
* Documented API-key authentication, account eligibility, scopes, rate limits, errors, CSV imports, pagination, and tenant-safe `404` behavior.
* Added the 21-operation generated endpoint reference and bundled `/openapi.json` contract.
* Added creator-owned link-in-bio retrieval, creation, and editing for page copy, social profile links, and safe link, title, or text blocks.
* Added agency-owned pitch-deck listing, retrieval, creation, and editing with roster ownership and plan-capacity enforcement.
* Added creator- and agency-owned campaign listing, retrieval, creation, and base metadata editing through the existing campaign service and plan allowance.
* Added tenant-safe page-view analytics for media kits, link-in-bio pages, public rosters, decks, and campaign reports.
* Documented the MCP tool catalog, role scopes, write-safety rules, and plan actions.
* Added official Fumadocs LLM outputs, per-page Markdown alternates, and semantic custom-component exports.
Future entries will record meaningful documentation changes and released integration contract updates. This changelog is not a product release log unless an entry explicitly says so.
---
# Endpoint reference
> Exact Public API V1 operations generated from the CreatorsJet OpenAPI 3.1 contract.
>
> Canonical URL: https://docs.creatorsjet.com/api/reference
This reference is generated from the checked-in CreatorsJet Public API V1 OpenAPI contract. Use it for exact parameters, request bodies, response schemas, status codes, and security declarations.
## Identity
* [`GET /me`](/api/reference/identity/getCurrentSubject) — retrieve the authenticated creator or agency subject, granted scopes, and entitlement state.
## Creators
* [`POST /creators`](/api/reference/creators/createCreator) — add one creator to an agency roster.
* [`GET /creators`](/api/reference/creators/listCreators) — list an agency roster with cursor pagination.
* [`GET /creators/{creator_id}`](/api/reference/creators/getCreator) — retrieve one roster creator or the authenticated creator's own profile.
## Creator imports
* [`POST /creator-imports`](/api/reference/imports/createCreatorImport) — validate and queue an agency CSV import.
* [`GET /creator-imports/{import_id}`](/api/reference/imports/getCreatorImport) — retrieve progress and row-level results.
## Media kits
* [`POST /media-kits`](/api/reference/media-kits/ensureMediaKit) — find or create the visible default media kit.
* [`GET /media-kits`](/api/reference/media-kits/listMediaKits) — list visible owned media kits.
* [`GET /media-kits/{media_kit_id}`](/api/reference/media-kits/getMediaKit) — retrieve one strictly owned media kit.
## Link in bio
* [`GET /link-in-bio`](/api/reference/link-in-bio/getLinkInBio) — retrieve the creator subject's page.
* [`POST /link-in-bio`](/api/reference/link-in-bio/createLinkInBio) — create the creator subject's page.
* [`PATCH /link-in-bio`](/api/reference/link-in-bio/updateLinkInBio) — edit supported page fields and blocks.
## Pitch decks
* [`GET /decks`](/api/reference/decks/listDecks) — list agency-owned decks.
* [`POST /decks`](/api/reference/decks/createDeck) — create a deck from agency-roster creators.
* [`GET /decks/{deck_id}`](/api/reference/decks/getDeck) — retrieve one agency-owned deck.
* [`PATCH /decks/{deck_id}`](/api/reference/decks/updateDeck) — edit supported deck fields.
## Campaigns
* [`GET /campaigns`](/api/reference/campaigns/listCampaigns) — list creator- or agency-owned campaigns.
* [`POST /campaigns`](/api/reference/campaigns/createCampaign) — create an owned campaign.
* [`GET /campaigns/{campaign_id}`](/api/reference/campaigns/getCampaign) — retrieve one owned campaign.
* [`PATCH /campaigns/{campaign_id}`](/api/reference/campaigns/updateCampaign) — edit supported campaign metadata and tracking settings.
## Analytics
* [`GET /analytics/views`](/api/reference/analytics/getViewAnalytics) — retrieve page views for an owned resource.
The bundled machine-readable schema is also available at [`/openapi.json`](/openapi.json).
---
# Create a campaign
> undefined
>
> Canonical URL: https://docs.creatorsjet.com/api/reference/campaigns/createCampaign
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Retrieve one owned campaign
> undefined
>
> Canonical URL: https://docs.creatorsjet.com/api/reference/campaigns/getCampaign
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# List owned campaigns
> undefined
>
> Canonical URL: https://docs.creatorsjet.com/api/reference/campaigns/listCampaigns
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Update an owned campaign
> undefined
>
> Canonical URL: https://docs.creatorsjet.com/api/reference/campaigns/updateCampaign
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Add one creator to an agency roster
> undefined
>
> Canonical URL: https://docs.creatorsjet.com/api/reference/creators/createCreator
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Retrieve creator profile and summary metrics
> undefined
>
> Canonical URL: https://docs.creatorsjet.com/api/reference/creators/getCreator
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# List an agency roster
> undefined
>
> Canonical URL: https://docs.creatorsjet.com/api/reference/creators/listCreators
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Retrieve page-view analytics
> undefined
>
> Canonical URL: https://docs.creatorsjet.com/api/reference/analytics/getViewAnalytics
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Create an agency pitch deck
> undefined
>
> Canonical URL: https://docs.creatorsjet.com/api/reference/decks/createDeck
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Retrieve one agency pitch deck
> undefined
>
> Canonical URL: https://docs.creatorsjet.com/api/reference/decks/getDeck
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# List agency pitch decks
> undefined
>
> Canonical URL: https://docs.creatorsjet.com/api/reference/decks/listDecks
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Update an agency pitch deck
> undefined
>
> Canonical URL: https://docs.creatorsjet.com/api/reference/decks/updateDeck
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Retrieve the authenticated API subject
> undefined
>
> Canonical URL: https://docs.creatorsjet.com/api/reference/identity/getCurrentSubject
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Queue a creator roster CSV import
> undefined
>
> Canonical URL: https://docs.creatorsjet.com/api/reference/imports/createCreatorImport
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Retrieve an import and its row results
> undefined
>
> Canonical URL: https://docs.creatorsjet.com/api/reference/imports/getCreatorImport
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Create the creator's link-in-bio page
> undefined
>
> Canonical URL: https://docs.creatorsjet.com/api/reference/link-in-bio/createLinkInBio
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Retrieve the creator's link-in-bio page
> undefined
>
> Canonical URL: https://docs.creatorsjet.com/api/reference/link-in-bio/getLinkInBio
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Update the creator's link-in-bio page
> undefined
>
> Canonical URL: https://docs.creatorsjet.com/api/reference/link-in-bio/updateLinkInBio
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Ensure a default media kit exists
> undefined
>
> Canonical URL: https://docs.creatorsjet.com/api/reference/media-kits/ensureMediaKit
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# Retrieve one owned media kit
> undefined
>
> Canonical URL: https://docs.creatorsjet.com/api/reference/media-kits/getMediaKit
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
---
# List visible media kits
> undefined
>
> Canonical URL: https://docs.creatorsjet.com/api/reference/media-kits/listMediaKits
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}