API reference

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.

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.