Pipeline - ContentHero

Base URL https://app.contenthero.ai/api/v1. All endpoints take a bearer API key. Reads need no scope; writes need the scope listed.

Spaces and stages

A space is a board; each space has its own stages, in order.

Method	Path	Scope	Purpose
`GET`	`/spaces`	read	List your spaces.
`POST`	`/spaces`	`planner:write`	Create a space.
`GET`	`/spaces/{id}`	read	Get one space.
`PATCH`	`/spaces/{id}`	`planner:write`	Update a space.
`DELETE`	`/spaces/{id}`	`planner:write`	Delete a space.
`GET`	`/stages`	read	List a space’s stages, in order.
`POST`	`/stages`	`planner:write`	Create a stage.
`PATCH`	`/stages/{id}`	`planner:write`	Update a stage.
`DELETE`	`/stages/{id}`	`planner:write`	Delete a stage.

Cards

A card is the unit of work: its title, notes and cover, the posts that publish it (one per platform), and what it holds (its assets).

Method	Path	Scope	Purpose
`GET`	`/cards`	read	List a space’s cards.
`POST`	`/cards`	`planner:write`	Create a card. Without a space it lands on your default board.
`GET`	`/cards/{id}`	read	Get a card with its posts and assets.
`PATCH`	`/cards/{id}`	`planner:write`	Update a card: its fields, its `posts`, its `assets` and its schedule.
`POST`	`/cards/{id}/publish`	`publish:write`	Publish now, to every post on the card or to one platform.

To archive a card, POST /archive with assetType: "card". Scheduling is the scheduledAt field on PATCH /cards/{id}: it sets the card and every post, and a post can carry its own to override it.

What a card can hold

posts and assets on PATCH /cards/{id} are declarative: send the whole list you want to end up with, because anything left out is removed. Read the card first, append, then send it all back. The order of assets is the carousel order, so reordering is sending the same ids in a new sequence. Each entry in assets either keeps one already on the card, { "id": "<asset id>" }, or adds one by exactly one reference:

To add	Entry	The id comes from
Media: a generation, an upload or an import	`{ "outputId": "<id>" }`, or `"<id>-2"` for variation 2	the generate call, `POST /media/uploads` then `POST /media/uploads/{outputId}/complete`, or `POST /media/imports`
A link	`{ "assetUrl": "https://..." }`	any web address; nothing is copied
An inspiration post (the card’s Inspiration tab)	`{ "contentId": "<id>" }`	`GET /content`, `GET /content/{id}`, or an inspiration asset’s `contentId` on `GET /cards/{id}`
An editor or canvas project	`{ "projectId": "<id>" }`	`GET /projects` for one that exists; a new one is linked in the same call by `cardId` on `POST /projects` or `POST /projects/import`

An entry naming two references, or none, is refused with a 400, and so is a list that names the same post, project, file or asset id twice. An inspiration post is attached by contentId, never by its permalink: assetType: "inspiration" with an assetUrl is refused with a 400 that names contentId. A post you cannot see, or a project that is not yours, answers 404.

PATCH /cards/{id}
{
  "assets": [
    { "id": "8f0c...e21" },
    { "contentId": "236e7611-4afe-4485-ba95-f86568a6bbd6" },
    { "projectId": "6a830d19-eb85-45b9-be59-ccbdfcfac101" }
  ]
}

Link a new project when you make it. POST /projects and POST /projects/import take an optional cardId: the project is linked to that card in the same call, and the reply carries linkedCardId. Linking writes to the card, so it also needs planner:write; a card that is not yours answers 404 before any project is made. GET /cards/{id} reads each kind back under the field that attached it: an inspiration asset carries contentId (with its creator, outlier score and views), and a linked project carries projectId. assetId is still returned as a deprecated alias.

Connected accounts

Method	Path	Scope	Purpose
`GET`	`/connected-accounts`	read	List your connected social accounts (safe projection; no credentials).
`GET`	`/connected-accounts/{id}`	read	Get one connected account with its enabled capabilities.

Encrypted credential fields on a connected account are never exposed through the API. A post names the connected account it publishes through.

See the Pipeline guide for the workflow end to end.

​Spaces and stages

​Cards

​What a card can hold

​Connected accounts

Spaces and stages

Cards

What a card can hold

Connected accounts