# Getting started

> Create an API key, verify it with your first request, and learn the response format.
>
> Canonical URL: https://docs.creatorsjet.com/api/getting-started

This guide takes you from no key to a working, authenticated request. It is for developers building or maintaining software.

> **Info — Not a developer?:**
>
> Try the read-only [example requests](/api/quick-starts), or use [CreatorsJet MCP](/mcp) to work in an AI assistant without writing code.

### Check your plan

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.

### Create an API key

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

1. Give the key a recognizable name.
2. Select only the [scopes](/api/authentication#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 a protected server environment variable.

> **Security — The key is shown once:**
>
> CreatorsJet stores only a digest of the secret and cannot display it again. If you lose it, revoke it and create a new one.

### Verify the key

Send the key as a Bearer credential. `GET /me` confirms the key, its subject, granted scopes, and current API entitlement.

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

A successful agency response looks like this:

```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"
}
```

### Make a real request

**Agency key**

Agency keys with `roster:write` can add one creator to the roster:

```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 platforms 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 roster, the API returns that creator with `created: false` instead of creating a duplicate.

**Creator key**

With a creator key, a good 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 requires `profile:read`. Creator keys cannot retrieve a different creator ID.

## Response format

Successful responses share one shape:

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

* `meta` appears when the endpoint has pagination or other response metadata.
* Errors use `application/problem+json`. See [errors](/api/errors).
* Keep `request_id` when reporting an issue to support.

### Pagination

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` on `429` responses. After an ambiguous connection failure on a create request, check whether the resource exists before retrying.
* Store opaque IDs and cursors as strings without deriving meaning from their format.

## Next steps

* [Authentication](/api/authentication): scopes, key lifecycle, and secret handling.
* [Subjects and ownership](/api/ownership): what each key can see and change.
* [Endpoint reference](/api/reference): exact request and response schemas.