# API reference

Every endpoint of the CreatorHyve API, generated from the same description the server uses.


Base URL: `https://creatorhyve.com/api/v1/developer`. All endpoints need `Authorization: Bearer ch_live_...` and the scope shown for each. The same description is available as [OpenAPI 3.1](/api/v1/developer/openapi.json).

## Accounts

### GET /accounts

**List connected accounts.** Scope: `accounts:read`.

Responses:

- `200`: Connected accounts. Tokens are never returned.

## Media

### POST /media

**Add media to the library.** Scope: `media:write`. Supports the `Idempotency-Key` header.

Send `{ "url": "https://..." }` to import an image or short video (up to 25 MB), or use `{ "action": "init" }` then PUT the file then `{ "action": "complete" }` for large files. Use the returned `media.id` as `mediaId` when creating a post.

| Field | Type | Required | Description |
|---|---|---|---|
| `url` | string (uri) | no |  |
| `action` | string | no |  One of: `init`, `complete`. |
| `type` | string | no |  |
| `size` | integer | no |  |
| `key` | string | no |  |
| `filename` | string | no |  |

Responses:

- `200`: Upload URL (action init).
- `201`: Media added.

### GET /media/:id

**Get a media item.** Scope: `posts:read`.

| Parameter | In | Description |
|---|---|---|
| `id` | path | Identifier (UUID). |

Responses:

- `200`: The media item.

## Posts

### GET /posts

**List posts.** Scope: `posts:read`.

| Parameter | In | Description |
|---|---|---|
| `status` | query | draft, scheduled, published or failed (default scheduled). |
| `tag` | query | Only posts with this tag. |
| `limit` | query | 1 to 100 (default 50). |
| `offset` | query | Offset for paging. |

Responses:

- `200`: Posts.

### POST /posts

**Create or schedule a post.** Scope: `posts:write`. Supports the `Idempotency-Key` header.

With `scheduledDatetime` the post is scheduled to every listed platform (the most recently connected account of each platform unless `accountId` is given). Without it the post is saved as a draft. Send an `Idempotency-Key` header so retries cannot create duplicates.

| Field | Type | Required | Description |
|---|---|---|---|
| `caption` | string | yes | The post text. |
| `platforms` | array | yes | Platform names (`"x"`) or `{ "platform": "x", "accountId": "<uuid>" }`. Use GET /accounts for the ids. |
| `scheduledDatetime` | string (date-time) | no | ISO 8601, in the future. Omit to save a draft. |
| `mediaId` | string (uuid) | no | `media.id` from POST /media. |
| `tags` | array of strings | no | Up to 10 labels. |
| `timezone` | string | no | IANA time zone, default `UTC`. |
| `title` | string | no | Defaults to the first line of the caption. |
| `options` | object | no | Per-platform settings, see the platform options guide. |

Responses:

- `201`: Created.
- `403`: Plan or monthly schedule limit reached.

### GET /posts/:id

**Get a post.** Scope: `posts:read`.

| Parameter | In | Description |
|---|---|---|
| `id` | path | Identifier (UUID). |

Responses:

- `200`: The post.

### PATCH /posts/:id

**Edit a post.** Scope: `posts:write`.

Edit caption, title, tags or time of a draft or a scheduled post that is not about to publish. Sending `scheduledDatetime` for a draft schedules it.

| Parameter | In | Description |
|---|---|---|
| `id` | path | Identifier (UUID). |

| Field | Type | Required | Description |
|---|---|---|---|
| `caption` | string | no |  |
| `title` | string | no |  |
| `scheduledDatetime` | string (date-time) | no |  |
| `tags` | array | no |  |
| `platforms` | array | no |  |

Responses:

- `200`: The updated post.
- `409`: The post can no longer be edited.

### DELETE /posts/:id

**Delete a post.** Scope: `posts:write`.

Drafts and scheduled posts that have not started publishing.

| Parameter | In | Description |
|---|---|---|
| `id` | path | Identifier (UUID). |

Responses:

- `204`: Deleted.

### GET /posts/:id/results

**Per-platform results.** Scope: `posts:read`.

Status, link and a plain-language error for each platform of a post.

| Parameter | In | Description |
|---|---|---|
| `id` | path | Identifier (UUID). |

Responses:

- `200`: Results.

## Usage

### GET /usage

**Plan, credits and schedule limit.** Scope: `posts:read`.

Responses:

- `200`: Usage.

## Analytics

### GET /analytics

**Analytics summary.** Scope: `analytics:read`.

Totals, per-platform breakdown and top posts. Metrics are collected once a day.

| Parameter | In | Description |
|---|---|---|
| `period` | query | Days, 1 to 90 (default 30). |
| `platform` | query | Only this platform. |
| `limit` | query | Top posts, 1 to 100 (default 20). |

Responses:

- `200`: Summary.

## Webhooks

### GET /webhooks

**List webhook endpoints.** Scope: `webhooks:manage`.

Responses:

- `200`: Endpoints.

### POST /webhooks

**Create a webhook endpoint.** Scope: `webhooks:manage`.

Events: post.published, post.failed, account.needs_reconnect. The signing secret is returned once. Deliveries carry `X-CreatorHyve-Signature: t=<unix>,v1=<hmac_sha256(secret, "<t>.<body>")>`.

| Field | Type | Required | Description |
|---|---|---|---|
| `url` | string (uri) | yes |  |
| `events` | array | no |  |
| `description` | string | no |  |

Responses:

- `201`: Created. Includes `secret`.

### PATCH /webhooks/:id

**Update a webhook endpoint.** Scope: `webhooks:manage`.

| Parameter | In | Description |
|---|---|---|
| `id` | path | Identifier (UUID). |

| Field | Type | Required | Description |
|---|---|---|---|
| `events` | array | no |  |
| `is_active` | boolean | no |  |
| `description` | string | no |  |

Responses:

- `200`: Updated.

### DELETE /webhooks/:id

**Delete a webhook endpoint.** Scope: `webhooks:manage`.

| Parameter | In | Description |
|---|---|---|
| `id` | path | Identifier (UUID). |

Responses:

- `204`: Deleted.

### POST /webhooks/:id/test

**Send a test event.** Scope: `webhooks:manage`.

| Parameter | In | Description |
|---|---|---|
| `id` | path | Identifier (UUID). |

Responses:

- `200`: Queued and attempted.

## Short links

### GET /links

**List short links.** Scope: `links:manage`.

Responses:

- `200`: Short links with click counts.

### POST /links

**Create a short link.** Scope: `links:manage`.

| Field | Type | Required | Description |
|---|---|---|---|
| `url` | string (uri) | yes |  |

Responses:

- `201`: Created.

### DELETE /links/:code

**Disable a short link.** Scope: `links:manage`.

| Parameter | In | Description |
|---|---|---|
| `code` | path | Short code. |

Responses:

- `204`: Disabled.