# Getting started

> Prepare a CreatorsJet API key and first authenticated Public API V1 request after access is enabled.
>
> Canonical URL: https://docs.creatorsjet.com/api/getting-started

> **Warn — Access must be enabled first:**
>
> Public API V1 is release gated. The key-management controls and production endpoints are available only after CreatorsJet enables access for the target account and environment.

## 1. Confirm account eligibility

When Public API access is enabled, 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. Make your first request

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 keys with `roster:write` can add one creator. An idempotency key is required for this write.

```bash
curl https://api.creatorsjet.com/public/v1/creators \
  --request POST \
  --header "Authorization: Bearer $CREATORSJET_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: creator-add-2026-08-14-001" \
  --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`.

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.

## Response conventions

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 integration 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.
* Use a unique idempotency key for every supported write operation.
* Follow `Retry-After` for `429` responses and use bounded backoff for temporary failures.
* Store opaque IDs and cursors as strings without deriving meaning from their format.