# Agents (/docs/agents)
Nimply **agents** are AI helpers you hire from a gallery: a LinkedIn Ghostwriter, a Carousel
Designer, a Trend Scout, a Customer Support agent and more. Each one does one job for your
workspace, on the channels you give it.
With the API you can do what the **Agents** page in the app does:
* browse the gallery and hire an agent,
* change its settings, pause, resume or remove it,
* run it now and follow the run,
* approve what it made.
Agents never publish on their own. What a content agent makes lands as **posts waiting for
approval**. Nothing goes out until someone approves it.
**Scopes:** `agents:read` to read, `agents:write` to hire, change and remove, `agents:run` to
start and cancel runs. All three are opt-in.
## Two kinds of agent [#two-kinds-of-agent]
Every template has a `kind`:
* **`content`** agents make posts, designs or idea cards when they run, by hand or on a
schedule. Their output waits for approval.
* **`inbox`** agents answer conversations as messages arrive (for example Customer Support or
Sales & Lead). You can hire, set up, pause and remove them through the API, but you can't
run them by hand. **The API never reads or sends inbox messages.**
## Endpoints [#endpoints]
| Method | Path | Scope | What it does |
| -------- | -------------------------------- | -------------- | --------------------------------------------------- |
| `GET` | `/v1/agent-templates` | `agents:read` | The agents you can hire, with the settings to fill |
| `GET` | `/v1/agent-templates/{id}` | `agents:read` | One template |
| `GET` | `/v1/agents` | `agents:read` | Your agents (`status`, `templateId` filters) |
| `POST` | `/v1/agents` | `agents:write` | Hire an agent |
| `GET` | `/v1/agents/{id}` | `agents:read` | One agent: settings, channels, status, schedule |
| `PATCH` | `/v1/agents/{id}` | `agents:write` | Rename, change settings or channels, pause / resume |
| `DELETE` | `/v1/agents/{id}` | `agents:write` | Remove an agent |
| `POST` | `/v1/agents/{id}/runs` | `agents:run` | Run it now (uses AI credits) |
| `GET` | `/v1/agents/{id}/runs` | `agents:read` | Recent runs, newest first (`limit` up to 50) |
| `GET` | `/v1/agent-runs/{id}?wait=0..25` | `agents:read` | One run (long-poll with `wait`) |
| `POST` | `/v1/agent-runs/{id}/cancel` | `agents:run` | Stop a run |
Starting runs is limited to 10 requests per minute per key, on top of the
[general rate limit](/docs/errors#rate-limits).
## Browse the gallery [#browse-the-gallery]
```bash
curl "https://api.nimply.io/v1/agent-templates" \
-H "Authorization: Bearer $NIMPLY_API_KEY"
```
Each template lists the settings (`fields`) it needs. This one is trimmed to three fields:
```json
{
"data": [
{
"id": "linkedin-ghostwriter",
"name": "LinkedIn Ghostwriter",
"description": "Builds your personal brand on LinkedIn — posts written in your voice from your notes, wins, and expertise, scheduled as drafts for your approval.",
"category": "LinkedIn",
"kind": "content",
"channelTypes": ["LINKEDIN_PROFILE", "LINKEDIN_PAGE"],
"multiChannel": false,
"presets": [],
"fields": [
{
"key": "voice",
"label": "Who are you on LinkedIn?",
"type": "text",
"required": true,
"askable": true,
"setupInApp": false
},
{
"key": "cadence",
"label": "Writing schedule",
"type": "choice",
"required": true,
"askable": true,
"setupInApp": false,
"options": [
{ "value": "weekly_monday", "label": "Weekly — Mondays 9:00 UTC" },
{ "value": "three_per_week", "label": "Mon / Wed / Fri — 9:00 UTC" },
{ "value": "weekdays", "label": "Every weekday — 9:00 UTC" },
{ "value": "manual", "label": "Only when I press Run" }
]
},
{
"key": "postCount",
"label": "Drafts per run",
"type": "choice",
"required": true,
"askable": true,
"setupInApp": false,
"options": [
{ "value": "1", "label": "1 post" },
{ "value": "2", "label": "2 posts" },
{ "value": "3", "label": "3 posts" }
]
}
],
"creditsPerRun": { "min": 2, "max": 12 }
}
]
}
```
How to read a field:
| Property | Meaning |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `channel` (channel ids), `choice` (one of `options`, or a list when `multiple`), `on/off` (true/false), `text`, `datetime` (ISO 8601), or `setup-page-only` |
| `askable` | `true`: you can set it through the API |
| `setupInApp` | `true`: only the agent's setup page in the Nimply app can set it |
| `appOnlyValues` | Option values you can only pick in the app (see [Settings that stay in the app](#settings-that-stay-in-the-app)) |
| `onlyWhen` | The field is used only while another field holds one of these values |
`channelTypes` lists the channels the agent works on (empty means any). `presets` are
ready-made versions of a template, such as the Designer's "Carousel Designer"; pass the
preset `key` when you hire. `creditsPerRun` is what one run usually uses.
## Hire an agent [#hire-an-agent]
Send the template, the channel, and the settings you know. Channels go in `channelIds`, every
other setting goes in `config`.
```bash
curl -X POST "https://api.nimply.io/v1/agents" \
-H "Authorization: Bearer $NIMPLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"templateId": "linkedin-ghostwriter",
"channelIds": ["5b8f1e2a-3c4d-4e6f-8a9b-0c1d2e3f4a5b"],
"config": {
"voice": "Founder of a specialty coffee roaster. Practical, warm, first person.",
"topics": "Sourcing stories, brewing tips, running a small business"
}
}'
```
`channelIds` takes one channel, unless the template is `multiChannel`. `name` is optional
(it defaults to the template name and the channel), and so are `preset` and `tags`.
### When settings are missing [#when-settings-are-missing]
If a required setting is missing, nothing is created. You get `422` with code
`MISSING_FIELDS` and a `missingFields` list. Ask the user for just those, then send the
same request again with them added.
```json
{
"type": "https://developer.nimply.io/docs/errors#unprocessable-entity",
"title": "Unprocessable Entity",
"status": 422,
"detail": "LinkedIn Ghostwriter still needs: cadence (\"Writing schedule\", choice: weekly_monday | three_per_week | weekdays | manual); postCount (\"Drafts per run\", choice: 1 | 2 | 3). Ask the user for these and send them again (channels go in channelIds, everything else in config).",
"code": "MISSING_FIELDS",
"missingFields": [
{
"key": "cadence",
"label": "Writing schedule",
"type": "choice",
"options": [
{ "value": "weekly_monday", "label": "Weekly — Mondays 9:00 UTC" },
{ "value": "three_per_week", "label": "Mon / Wed / Fri — 9:00 UTC" },
{ "value": "weekdays", "label": "Every weekday — 9:00 UTC" },
{ "value": "manual", "label": "Only when I press Run" }
]
},
{
"key": "postCount",
"label": "Drafts per run",
"type": "choice",
"options": [
{ "value": "1", "label": "1 post" },
{ "value": "2", "label": "2 posts" },
{ "value": "3", "label": "3 posts" }
]
}
],
"instance": "/v1/agents"
}
```
Once everything is there, you get `201` with the agent:
```json
{
"id": "0d7c9e4b-2f1a-4b3c-9d8e-7f6a5b4c3d2e",
"name": "LinkedIn Ghostwriter — Brewhaus",
"templateId": "linkedin-ghostwriter",
"templateName": "LinkedIn Ghostwriter",
"kind": "content",
"status": "ACTIVE",
"pausedReason": null,
"channelIds": ["5b8f1e2a-3c4d-4e6f-8a9b-0c1d2e3f4a5b"],
"preset": null,
"config": {
"voice": "Founder of a specialty coffee roaster. Practical, warm, first person.",
"topics": "Sourcing stories, brewing tips, running a small business",
"cadence": "weekly_monday",
"postCount": "2"
},
"setInApp": [],
"schedule": { "cadence": "weekly_monday", "label": "Weekly — Mondays 9:00 UTC" },
"tags": [],
"createdAt": "2026-10-29T10:00:00.000Z",
"updatedAt": "2026-10-29T10:00:00.000Z",
"appUrl": "https://app.nimply.io/workspace/…/agents?instance=0d7c9e4b-…"
}
```
* `schedule` says how often the agent runs on its own. It is `null` when it only runs when
asked. A scheduled run still sends its posts for approval.
* `setInApp` lists settings that are set but can only be seen and changed in the app. Their
values are not returned.
* `appUrl` opens the agent in the Nimply app (sign-in required).
## Settings that stay in the app [#settings-that-stay-in-the-app]
Some settings let an agent act **without a person checking first**. You can only switch those
on in the Nimply app, where the person can see what they agree to:
| Setting | Value only the app can pick | What it would do |
| --------------- | --------------------------- | ---------------------------------------------------- |
| `replyMode` | `auto` | An inbox agent sends replies itself |
| `operatingMode` | `hybrid`, `autopilot` | The Restaurant Concierge answers on its own |
| `mcpWriteMode` | `allow_changes` | The agent changes data in your connected tools |
| `delivery` | `schedule` | Posts are scheduled straight away, skipping approval |
Fields with `setupInApp: true` also stay in the app: uploads, connected tools, Google Sheets
and other custom editors.
Sending one of these returns `422` with code `SET_IN_APP`. The problem body names the
settings in `fields` and gives `appUrl`, the link to the agent's setup page. Show that link
to the user so they can finish there.
```json
{
"type": "https://developer.nimply.io/docs/errors#unprocessable-entity",
"title": "Unprocessable Entity",
"status": 422,
"detail": "These settings can only be chosen in the Nimply app: Reply mode. Open https://app.nimply.io/workspace/…/agents/setup/customer-support to set them there.",
"code": "SET_IN_APP",
"fields": ["Reply mode"],
"appUrl": "https://app.nimply.io/workspace/…/agents/setup/customer-support",
"instance": "/v1/agents"
}
```
## Change, pause, resume, remove [#change-pause-resume-remove]
`PATCH /v1/agents/{id}` changes only what you send:
* `config` is **merged** into the current settings. `null` clears one setting. Settings you
don't send are kept, including ones set in the app.
* `channelIds` replaces the agent's channels. `name` and `tags` replace theirs.
* `status` pauses (`PAUSED`) or resumes (`ACTIVE`) the agent.
```bash
curl -X PATCH "https://api.nimply.io/v1/agents/0d7c9e4b-2f1a-4b3c-9d8e-7f6a5b4c3d2e" \
-H "Authorization: Bearer $NIMPLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "config": { "postCount": "3" }, "status": "PAUSED" }'
```
Pausing an agent also pauses the automations that work with it. **Resuming does not switch
those automations back on**: turn them on again with
[`POST /v1/automations/{id}/activate`](/docs/automations#draft-test-switch-on).
`DELETE /v1/agents/{id}` removes the agent. Posts it already made are kept. Automations that
worked with it are kept and paused.
`pausedReason` tells you when Nimply paused an agent itself, for example `CHANNEL_REMOVED`
after its channel was disconnected.
## Run an agent [#run-an-agent]
```bash
curl -X POST "https://api.nimply.io/v1/agents/0d7c9e4b-2f1a-4b3c-9d8e-7f6a5b4c3d2e/runs" \
-H "Authorization: Bearer $NIMPLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
```
Some templates take an optional `input`, such as a topic or a source link:
`{ "input": { "topic": "Our new single-origin from Ethiopia" } }`.
**Plans and credits:** running agents needs a paid plan or an active trial. A run uses AI
credits from your workspace. When it starts, Nimply holds the most it is expected to use
(`creditsLocked`). When it ends, you pay only what it used (`creditsUsed`). If the workspace
is short of credits, the run is refused with `402` and code `INSUFFICIENT_CREDITS`. Your plan
also sets how many runs you get each month.
The answer is `202` with the run. Runs are asynchronous: poll
`GET /v1/agent-runs/{id}?wait=25`. With `wait`, the request is held for up to 25 seconds and
returns as soon as the run changes.
```json
{
"id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"agentId": "0d7c9e4b-2f1a-4b3c-9d8e-7f6a5b4c3d2e",
"status": "COMPLETED",
"trigger": "MANUAL",
"creditsLocked": 12,
"creditsUsed": 6,
"error": null,
"startedAt": "2026-10-29T10:05:02.000Z",
"completedAt": "2026-10-29T10:05:48.000Z",
"createdAt": "2026-10-29T10:05:00.000Z",
"outputs": {
"postIds": ["c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f", "d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f7a"]
}
}
```
`status` moves from `PENDING` to `PROCESSING`, then ends as `COMPLETED`, `FAILED` or
`CANCELLED`. `outputs` lists what the run made: `postIds`, and when there are any, `designIds`
and `ideaIds` (idea cards).
`POST /v1/agent-runs/{id}/cancel` stops a run. A queued run stops at once and its held
credits are given back. A running one stops at its next checkpoint, and the work already done
is charged. A finished run is returned unchanged.
## Approve what the agent made [#approve-what-the-agent-made]
The posts in `outputs.postIds` wait in the Planner with status `PENDING_APPROVAL`. Look at them
with [`GET /v1/posts/{id}`](/docs/api-reference), then approve or reject:
```bash
curl -X POST "https://api.nimply.io/v1/posts/c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f/approve" \
-H "Authorization: Bearer $NIMPLY_API_KEY"
```
Approving needs the `posts:write` and `posts:publish` scopes. An approved post with a future
publish time goes back on the schedule; one without becomes a draft. Use
`POST /v1/posts/{id}/reject` to send it back. Your team also sees these posts in the app and
can approve them there.
## Who can do what [#who-can-do-what]
Keys act for a person: the user who approved the connection (OAuth), or the person who made
the API key. That person's workspace role decides what the call may do:
| Action | Roles |
| ---------------------------------------------- | -------------------- |
| Read templates, agents and runs | Any member |
| Hire, change, pause, resume, run, cancel a run | Owner, admin, editor |
| Remove an agent | Owner, admin |
Otherwise the call fails with `403` and code `INSUFFICIENT_ROLE`.
## Errors [#errors]
| Status | `code` | Meaning |
| ------ | -------------------------- | ---------------------------------------------------------------------------------------------- |
| `400` | `INVALID_CONFIG` | An unknown setting or preset, a value the field doesn't take, or a channel the agent can't use |
| `402` | `INSUFFICIENT_CREDITS` | Not enough AI credits to start the run; the body has `needed` and `available` |
| `403` | `AGENT_QUOTA_EXCEEDED` | Your plan allows no more agents |
| `403` | `AGENT_RUN_QUOTA_EXCEEDED` | This month's agent runs are used up |
| `403` | `PAID_PLAN_REQUIRED` | Running agents needs a paid plan or an active trial |
| `403` | `INSUFFICIENT_ROLE` | The person the key acts for needs a higher workspace role |
| `403` | — | The key or connection is missing an `agents:*` scope |
| `409` | `AGENT_PAUSED` | Resume the agent before running it |
| `422` | `MISSING_FIELDS` | Required settings are missing; see `missingFields` |
| `422` | `SET_IN_APP` | A setting only the Nimply app can choose; see `fields` and `appUrl` |
| `422` | `AGENT_RUNS_FROM_INBOX` | Inbox agents answer messages as they arrive and can't be run by hand |
| `429` | — | Too many requests, or too many runs at once; retry after `Retry-After` seconds |
## From ChatGPT, Claude and other assistants [#from-chatgpt-claude-and-other-assistants]
The [MCP server](/docs/mcp) (version 0.7.0 and later) has matching tools: `list_agent_templates`,
`list_agents`, `get_agent`, `hire_agent`, `update_agent`, `set_agent_status`, `remove_agent`,
`run_agent`, `get_agent_run` and `cancel_agent_run`. Ask things like:
* *"Hire a LinkedIn ghostwriter for my page."* The assistant asks only for the settings
Nimply still needs.
* *"Pause my Trend Scout."*
* *"Run my ghostwriter now and show me the drafts."* The assistant shows the posts and
approves them only when you say so.
Connections made before these tools existed don't have agent access yet. Reconnect Nimply in
your assistant and approve the agent permissions.
# Authentication (/docs/authentication)
The Nimply API uses **API keys** to authenticate requests. Every key is scoped to a single
workspace: a key can only see and act on the channels, posts, and media of the workspace it
was created in.
## Creating an API key [#creating-an-api-key]
1. Open the Nimply app and pick the workspace you want to integrate with.
2. Go to **Settings → Developers**.
3. Click **Create API key**, name it, and select the scopes it needs.
4. Copy the key — it is shown **only once**. Store it in a secret manager or environment variable.
Live keys look like this:
```txt
nim_live_4f8a2c…
```
## Using your key [#using-your-key]
Send the key as a Bearer token in the `Authorization` header of every request:
```bash
curl https://api.nimply.io/v1/workspace \
-H "Authorization: Bearer nim_live_4f8a2c…"
```
`GET /v1/workspace` is a handy connectivity check — it returns the workspace the key belongs to.
API keys carry full access to their scopes. Never embed them in client-side code, mobile
apps, or public repositories. Rotate a key immediately if it leaks.
## Scopes [#scopes]
Scopes limit what a key is allowed to do. New keys are **read-only by default** — grant write
scopes explicitly when you need them.
| Scope | Grants |
| ------------------- | ------------------------------------------------------------------------------- |
| `workspace:read` | Read the workspace the key belongs to |
| `channels:read` | List and inspect connected social channels and their posting schedules |
| `posts:read` | List and read posts |
| `posts:write` | Create, update, and delete draft posts |
| `posts:publish` | Schedule posts and publish immediately (`schedule` values other than `"draft"`) |
| `media:read` | List and read media assets |
| `media:write` | Upload and delete media assets |
| `analytics:read` | Read profile and post metrics |
| `webhooks:manage` | Create, update, and delete webhook subscriptions |
| `links:read` | List link pages (nimply.link) and read their blocks and analytics |
| `links:write` | Add, update, and remove link-page blocks; publish pages |
| `designs:read` | List designs and brand kits, poll design jobs, get cost estimates |
| `designs:write` | Start design jobs (generate, image to layers) and cancel them — uses AI credits |
| `agents:read` | List agent templates and your agents, read agent runs |
| `agents:write` | Hire, change, pause, resume, and remove agents |
| `agents:run` | Run agents now and cancel runs — uses AI credits |
| `automations:read` | List step types, recipes, automations, and their runs |
| `automations:write` | Create, change, test, switch on or off, run, and delete automations |
Requests made without the required scope fail with `403 Forbidden` and a
[problem details](/docs/errors) body naming the missing scope.
The `agents:*` and `automations:*` scopes are opt-in. Some agent and automation actions also
need a workspace role (for example, only owners and admins can switch automations on): see
[Agents](/docs/agents#who-can-do-what) and [Automations](/docs/automations#who-can-do-what).
## Next steps [#next-steps]
# Automations (/docs/automations)
An **automation** does something for you when a trigger fires: "when a post fails, alert me",
"every morning, have my Trend Scout find a topic and my Designer make a carousel". They are
the same automations you see on the **Automations** page in the app, and you can open and
edit any of them there.
With the API you can:
* list the building blocks (step types) and ready-made recipes,
* create an automation from a recipe, from a list of steps, or from a full graph,
* test it, switch it on or off, run it now, and see its runs,
* change or delete it.
**Scopes:** `automations:read` to read, `automations:write` for everything that creates,
changes, tests or runs. Both are opt-in.
## The safe order: draft → test → switch on [#the-safe-order-draft--test--switch-on]
Every automation you create through the API starts as a **draft**. A draft never runs on
its own.
1. Create it (`POST /v1/automations` or `POST /v1/automations/from-recipe`).
2. Test it (`POST /v1/automations/{id}/test`). Steps that would change something are only
previewed.
3. Show the user what it will do, and switch it on (`POST /v1/automations/{id}/activate`)
only when they agree.
## Endpoints [#endpoints]
| Method | Path | Scope | What it does |
| -------- | ------------------------------- | ------------------- | -------------------------------------------------------------------------- |
| `GET` | `/v1/automation-step-types` | `automations:read` | Triggers, actions and logic you can use, with their settings |
| `GET` | `/v1/automation-recipes` | `automations:read` | Ready-made automations and the blanks to fill |
| `GET` | `/v1/automations` | `automations:read` | Your automations (`status` filter; up to 100, most recently changed first) |
| `POST` | `/v1/automations` | `automations:write` | Create a draft from `steps` or `graph` |
| `POST` | `/v1/automations/from-recipe` | `automations:write` | Create a draft from a recipe |
| `GET` | `/v1/automations/{id}` | `automations:read` | One automation, in plain words and as a graph |
| `PATCH` | `/v1/automations/{id}` | `automations:write` | Change name, description or steps |
| `DELETE` | `/v1/automations/{id}` | `automations:write` | Delete it and its run history |
| `POST` | `/v1/automations/{id}/activate` | `automations:write` | Switch it on |
| `POST` | `/v1/automations/{id}/pause` | `automations:write` | Switch it off |
| `POST` | `/v1/automations/{id}/test` | `automations:write` | Test run with sample data |
| `POST` | `/v1/automations/{id}/run` | `automations:write` | Run it once for real |
| `GET` | `/v1/automations/{id}/runs` | `automations:read` | Recent runs (`limit` up to 100) |
| `GET` | `/v1/automation-runs/{id}` | `automations:read` | One run, step by step |
Tests are limited to 20 requests per minute per key and live runs to 10 per minute, on top of
the [general rate limit](/docs/errors#rate-limits).
## Step types [#step-types]
`GET /v1/automation-step-types` lists every building block you can use through the API:
* **Triggers** start an automation: a schedule, a button press (`trigger.manual`), a workspace
event such as "Post failed", a new article in a feed, a new comment, and more.
* **Actions** do something: run an agent, create a draft post, make a design, send a
notification, tag a person, and more.
* **Logic**: `logic.if` (branch on a value) and `logic.delay` (wait).
Here is the If step from that list:
```json
{
"data": [
{
"key": "logic.if",
"kind": "logic",
"name": "If condition",
"description": "Branches the workflow: continues on the true or false path.",
"fields": [
{ "key": "left", "type": "text", "label": "Value", "required": true, "multiple": false },
{
"key": "operator",
"type": "select",
"label": "Operator",
"required": true,
"multiple": false,
"options": [
{ "value": "equals", "label": "equals" },
{ "value": "not_equals", "label": "does not equal" },
{ "value": "contains", "label": "contains" },
{ "value": "gt", "label": "greater than" },
{ "value": "lt", "label": "less than" },
{ "value": "exists", "label": "exists" },
{ "value": "not_exists", "label": "does not exist" }
]
},
{ "key": "right", "type": "text", "label": "Compare to", "required": false, "multiple": false }
],
"outputs": ["true", "false"],
"costsCredits": false,
"activateInApp": false
}
]
}
```
* `fields` are the step's settings. Put them in the step's `params`. Text settings can use
values from earlier steps: `{{trigger.…}}` and `{{nodes..…}}`.
* `costsCredits: true` means the step uses AI credits when it runs (running an agent, making a
design, sorting inbox messages).
* `activateInApp: true` marks a step that messages customers with no human check. See
[What stays in the app](#what-stays-in-the-app).
## Recipes [#recipes]
Recipes are the quickest start. `GET /v1/automation-recipes` lists them with their `blanks`:
the things you choose, usually which agent to run.
```bash
curl -X POST "https://api.nimply.io/v1/automations/from-recipe" \
-H "Authorization: Bearer $NIMPLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"recipeId": "daily-trend-carousel",
"values": {
"scoutInstanceId": "3f0c2a5e-1b7d-4c8e-9a6f-2d4b8e1c7a90",
"designerInstanceId": "8e1c7a90-2d4b-4c8e-9a6f-3f0c2a5e1b7d"
}
}'
```
Agent blanks take an agent id from [`GET /v1/agents`](/docs/agents). The agent must be made
from one of the blank's `templateIds`. Blanks you leave out stay empty: the draft is created,
but it can't be switched on until they are filled (with `PATCH` or in the app).
## Build from steps [#build-from-steps]
For your own automation, send a list of `steps`: the trigger first, then the actions. Without
`edges`, the steps run one after another in the order you send them.
```bash
curl -X POST "https://api.nimply.io/v1/automations" \
-H "Authorization: Bearer $NIMPLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Monday planning reminder",
"steps": [
{ "type": "trigger.schedule", "name": "Every Monday at 9", "params": { "cron": "0 9 * * 1" } },
{ "type": "action.notify", "params": { "target": "inapp", "message": "Time to plan the week" } }
]
}'
```
Schedules use five-field cron, in UTC.
### Branch with If [#branch-with-if]
To branch, give the steps your own `id`s and add `edges`. Each edge out of an If step needs a
`sourceHandle` of `"true"` or `"false"`:
```json
{
"name": "Failure triage",
"steps": [
{ "id": "trigger", "type": "trigger.event", "params": { "event": "post.failed" } },
{
"id": "check",
"type": "logic.if",
"name": "Auth error?",
"params": { "left": "{{trigger.error}}", "operator": "contains", "right": "token" }
},
{
"id": "reconnect",
"type": "action.notify",
"params": { "target": "inapp", "message": "{{trigger.channel.name}} needs reconnecting." }
},
{
"id": "generic",
"type": "action.notify",
"params": { "target": "inapp", "message": "Post failed on {{trigger.channel.name}}: {{trigger.error}}" }
}
],
"edges": [
{ "source": "trigger", "target": "check" },
{ "source": "check", "target": "reconnect", "sourceHandle": "true" },
{ "source": "check", "target": "generic", "sourceHandle": "false" }
]
}
```
### Or send the full graph [#or-send-the-full-graph]
If a list can't express your layout, send `graph` instead of `steps`: `{ "nodes": [...],
"edges": [...] }`, the same shape `GET /v1/automations/{id}` returns. Each node needs an `id`
and a `type`; `name`, `params` and a canvas `position` are optional. Send `steps` or `graph`,
not both.
### The automation [#the-automation]
Both ways return `201` with the draft:
```json
{
"id": "9d2f4b1a-6c3e-4f8a-b5d7-1e0a2c4b6d8f",
"name": "Monday planning reminder",
"description": null,
"status": "DRAFT",
"pausedReason": null,
"managedBy": null,
"trigger": { "type": "trigger.schedule", "summary": "On a schedule (0 9 * * 1 UTC)" },
"steps": [
{
"id": "n2",
"type": "action.notify",
"name": "Send notification",
"summary": "target: inapp · message: Time to plan the week"
}
],
"graph": {
"nodes": [
{
"id": "n1",
"type": "trigger.schedule",
"name": "Every Monday at 9",
"position": { "x": 80, "y": 200 },
"params": { "cron": "0 9 * * 1" }
},
{
"id": "n2",
"type": "action.notify",
"position": { "x": 420, "y": 200 },
"params": { "target": "inapp", "message": "Time to plan the week" }
}
],
"edges": [{ "id": "e1", "source": "n1", "target": "n2", "sourceHandle": "main" }]
},
"tags": [],
"version": 1,
"activateInApp": false,
"lastRunAt": null,
"nextRunAt": null,
"createdAt": "2026-10-29T09:00:00.000Z",
"updatedAt": "2026-10-29T09:00:00.000Z",
"appUrl": "https://app.nimply.io/workspace/…/automations/9d2f4b1a-…"
}
```
`trigger.summary` and each step's `summary` describe the automation in plain words. Show them
to the user before you switch it on.
## Everywhere: copy new videos to other channels [#everywhere-copy-new-videos-to-other-channels]
Everywhere watches one channel for videos posted outside Nimply (in the Instagram app, for
example) and copies each new one to the other channels you name. Every copy is a post awaiting
approval. Start from the `everywhere` recipe, or send the two steps yourself:
```json
{
"name": "Everywhere: Instagram",
"steps": [
{ "type": "trigger.channel_post", "params": { "channelIds": [""] } },
{
"type": "action.everywhere_repost",
"params": {
"destinationChannelIds": ["", ""],
"caption": "original",
"delivery": "approval"
}
}
]
}
```
* **The channel to watch** is one Instagram, Facebook Page or Threads channel. Switching the
automation on also turns on "posts made outside Nimply" for that channel.
* **What starts it:** a video posted on that channel after the automation was switched on.
Photos, shares of someone else's video and anything Nimply published never start it. New
videos are usually noticed within an hour.
* **`caption`:** `original` keeps the caption (shortened only if it is too long for a channel);
`ai` adapts it per platform and uses about 1 AI credit per channel.
* **Never twice:** a video is copied to a channel once. A video that is too long or too large
for a channel, or whose file the platform does not share (Instagram withholds videos with
licensed music), is skipped for that channel and the workspace is told why.
* **YouTube** destinations always wait for approval.
* Everywhere needs a paid plan or trial. Switching it on from a free plan returns
`403 EVERYWHERE_UPGRADE_REQUIRED`.
Picking older videos by hand is done in the Nimply app.
## Draft, test, switch on [#draft-test-switch-on]
**Test** runs the automation once with sample data, or with your own `triggerData`
(available to the steps as `{{trigger.…}}`):
```bash
curl -X POST "https://api.nimply.io/v1/automations/9d2f4b1a-6c3e-4f8a-b5d7-1e0a2c4b6d8f/test" \
-H "Authorization: Bearer $NIMPLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
```
Steps that would change something (create a post, send a message, notify) are only previewed.
Steps that use AI can still use credits. The answer is `200` with the finished test run.
**Switch on** with `POST /v1/automations/{id}/activate`. Nimply checks everything first: one
trigger, every step connected, required settings filled, a valid schedule. If something is
wrong you get `422 INVALID_GRAPH`, with one problem per entry in `errors`, so you can fix them
all at once:
```json
{
"type": "https://developer.nimply.io/docs/errors#unprocessable-entity",
"title": "Unprocessable Entity",
"status": 422,
"detail": "Step \"n2\" (Send notification): missing required field \"Message\" (message)",
"code": "INVALID_GRAPH",
"errors": ["Step \"n2\" (Send notification): missing required field \"Message\" (message)"],
"instance": "/v1/automations/9d2f4b1a-6c3e-4f8a-b5d7-1e0a2c4b6d8f/activate"
}
```
Once on, it runs by itself every time its trigger fires. Switching on an automation that starts
on a new comment also turns on the Inbox for the channels it watches.
**Switch off** with `POST /v1/automations/{id}/pause`.
**Run now** with `POST /v1/automations/{id}/run`. This is a real run, not a test, whether or
not the automation is switched on. It works only for automations started by hand or on a
schedule; one that starts on an event returns `422 RUN_NEEDS_EVENT` (test it instead). The
answer is `202` with the run; read it with `GET /v1/automation-runs/{id}`. Live runs count
toward your plan's monthly runs.
## Change an automation [#change-an-automation]
`PATCH /v1/automations/{id}` changes `name`, `description` (`null` clears it), or what it does
(`steps` + `edges`, or `graph`). New steps replace all the old ones.
Every automation has a `version` that goes up each time its steps change. Send the `version`
you read (or an `If-Match: "3"` header). If someone changed it in the meantime, nothing is
saved and you get `409 VERSION_CONFLICT`: read it again, then retry.
```bash
curl -X PATCH "https://api.nimply.io/v1/automations/9d2f4b1a-6c3e-4f8a-b5d7-1e0a2c4b6d8f" \
-H "Authorization: Bearer $NIMPLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "Monday planning nudge", "version": 1 }'
```
An automation that is switched on must stay ready to run, so a change to its steps is checked
the same way as switching on.
## Managed automations are read-only [#managed-automations-are-read-only]
Some automations belong to something else. Their `managedBy` tells you:
* **`agent`**: it follows an agent, for example the schedule of a LinkedIn Ghostwriter. Change,
pause or remove the [agent](/docs/agents) instead.
* **`nimply`**: Nimply runs it for a feature you switch on in the app (Smart inbox triage).
You can read them, but changing, testing, running or deleting one returns
`409 MANAGED_AUTOMATION`.
## What stays in the app [#what-stays-in-the-app]
Some things can't be done through the API at all:
* **Web requests** to outside addresses (`action.http_request`).
* **Stored secrets** (`{{secret:…}}`).
* **Webhook triggers** (`trigger.webhook`), whose secret URL starts the automation.
These step types aren't listed, and sending one returns `422 STEP_NOT_ALLOWED`. You can add
them yourself on the Automations page. An automation that already has one (built in the app)
can still be read, but testing, running or switching it on through the API returns
`422 SET_IN_APP`.
**Posting automatically.** An Everywhere automation (`action.everywhere_repost`) can be set to
post its copies with no approval step, but only in the app. Through the API, `"delivery"` is
always `"approval"`; sending `"publish"` returns `422 SET_IN_APP`. An automation set to post
automatically in the app has `activateInApp: true` and is switched on and run there.
Two steps message customers **with no human check**: **Reply in inbox** (`action.inbox_reply`)
and **Reply & DM by keyword** (`action.comment_dm`, comment-to-DM). You can build and test
automations with them through the API. Switching them on, or running them live, happens only in
the Nimply app, where the person sees what they agree to. Such automations have
`activateInApp: true`. Trying returns `422 SET_IN_APP` with `appUrl`, the link to the
automation in the app.
## Runs [#runs]
```json
{
"id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
"automationId": "9d2f4b1a-6c3e-4f8a-b5d7-1e0a2c4b6d8f",
"mode": "TEST",
"status": "SUCCEEDED",
"triggerType": "manual",
"creditsUsed": 0,
"error": null,
"startedAt": "2026-10-29T09:00:00.000Z",
"finishedAt": "2026-10-29T09:00:01.000Z",
"steps": [
{ "nodeId": "n1", "type": "trigger.schedule", "status": "SUCCEEDED", "error": null },
{ "nodeId": "n2", "type": "action.notify", "status": "SUCCEEDED", "error": null }
]
}
```
* `mode` is `TEST` or `LIVE`. `status` is `RUNNING`, `WAITING` (at a delay step), `SUCCEEDED`,
`FAILED`, `CANCELED` or `SKIPPED`.
* Each step reports only its `status` and `error`. **What a step received or produced is never
returned**, because it can hold customer messages and other private data. Open the run in the
app to see more.
## Limits [#limits]
* At most **30 steps** (and 40 connections) per automation.
* At most **20 automations switched on** per workspace (`403 ACTIVE_AUTOMATION_LIMIT`).
* Your plan sets how many automations you can have (`403 AUTOMATION_QUOTA_EXCEEDED`) and how
many live runs you get each month.
* Live runs are also capped at 60 an hour and 5 at once per workspace (`429`).
## Who can do what [#who-can-do-what]
Keys act for a person: the user who approved the connection (OAuth), or the person who made
the API key. That person's workspace role decides what the call may do:
| Action | Roles |
| ---------------------------------------------- | -------------------- |
| Read step types, recipes, automations and runs | Any member |
| Create, change, test | Owner, admin, editor |
| Switch on, switch off, run now, delete | Owner, admin |
Otherwise the call fails with `403` and code `INSUFFICIENT_ROLE`.
## Errors [#errors]
| Status | `code` | Meaning |
| ------ | ----------------------------- | ------------------------------------------------------------------------------------------ |
| `403` | `INSUFFICIENT_ROLE` | The person the key acts for needs a higher workspace role |
| `403` | `AUTOMATION_QUOTA_EXCEEDED` | Your plan allows no more automations |
| `403` | `ACTIVE_AUTOMATION_LIMIT` | 20 automations are already switched on; pause one first |
| `403` | `EVERYWHERE_UPGRADE_REQUIRED` | Everywhere needs a paid plan or trial |
| `403` | — | The key or connection is missing an `automations:*` scope |
| `404` | `RECIPE_NOT_FOUND` | No recipe with that id |
| `409` | `VERSION_CONFLICT` | It changed since you read it; read it again, then retry |
| `409` | `MANAGED_AUTOMATION` | It belongs to an agent or a Nimply feature and is read-only |
| `422` | `STEP_NOT_ALLOWED` | A step type or stored secret the API can't add |
| `422` | `INVALID_GRAPH` | Not ready (or not valid); `errors` lists every problem |
| `422` | `INVALID_INPUT` | Send `steps` or `graph`, not both; `edges` only with `steps` |
| `422` | `INVALID_VALUES` | An unknown recipe blank, or an agent that isn't in this workspace or doesn't fit the blank |
| `422` | `SET_IN_APP` | Only the Nimply app can switch this on or run it; see `appUrl` |
| `422` | `RUN_NEEDS_EVENT` | It starts on an event, so it can't be run by hand; test it instead |
| `429` | — | Too many requests, or the hourly / at-once run caps; retry after `Retry-After` seconds |
## From ChatGPT, Claude and other assistants [#from-chatgpt-claude-and-other-assistants]
The [MCP server](/docs/mcp) (version 0.7.0 and later) has matching tools:
`list_automation_step_types`, `list_automation_recipes`, `list_automations`, `get_automation`,
`create_automation`, `create_automation_from_recipe`, `update_automation`,
`set_automation_status`, `test_automation`, `run_automation`, `get_automation_run` and
`delete_automation`. Ask things like:
* *"Every Monday, make a trend carousel with my Trend Scout and Designer."*
* *"Alert me in Slack when a post fails."*
* *"Pause my planning reminder."*
The assistant creates a draft, tests it, and switches it on only after you confirm.
Connections made before these tools existed don't have automation access yet. Reconnect Nimply
in your assistant and approve the automation permissions.
# Set up a brand kit and teach it your look (/docs/brand-kits)
A **brand kit** holds your brand's name, colours, fonts, voice and logo. Every
[design](/docs/designs) Nimply makes uses one. A kit can also **learn your look** from your
own designs: the layouts, type, colour use and photo style you use. After that, every new
design for that kit follows it.
**Scopes:** `designs:read` for reads, `designs:write` for changes. **Plans and credits:**
creating and editing kits is free (your plan sets how many kits you can have). Learning a
look and reading a brand from a website or [several sources](#create-a-kit-from-several-sources) use AI
credits, on paid plans and during a trial.
## Endpoints [#endpoints]
| Method | Path | Scope | What it does |
| -------- | ------------------------------------------------ | --------------- | ----------------------------------------------------------------- |
| `GET` | `/v1/brand-kits` | `designs:read` | List your kits |
| `POST` | `/v1/brand-kits` | `designs:write` | Create a kit |
| `POST` | `/v1/brand-kits/import` | `designs:write` | Read a brand from its website (nothing is saved) |
| `POST` | `/v1/brand-kits/imports/estimate` | `designs:write` | Price a several-source import (free) |
| `POST` | `/v1/brand-kits/imports` | `designs:write` | Read a brand from several sources (async, AI credits) |
| `GET` | `/v1/brand-kits/imports/{id}` | `designs:read` | Progress and the draft kit |
| `POST` | `/v1/brand-kits/imports/{id}/save` | `designs:write` | Create the kit from the draft |
| `GET` | `/v1/brand-kits/{id}` | `designs:read` | One kit |
| `PATCH` | `/v1/brand-kits/{id}` | `designs:write` | Change a kit |
| `GET` | `/v1/brand-kits/{id}/style` | `designs:read` | The learned look, its rules and examples, and what learning costs |
| `GET` | `/v1/brand-kits/{id}/style/post-candidates` | `designs:read` | Published posts with an image, to learn from |
| `POST` | `/v1/brand-kits/{id}/style/examples` | `designs:write` | Add examples |
| `DELETE` | `/v1/brand-kits/{id}/style/examples/{exampleId}` | `designs:write` | Remove an example |
| `POST` | `/v1/brand-kits/{id}/style/learn` | `designs:write` | Learn the look (async, AI credits) |
| `PUT` | `/v1/brand-kits/{id}/style/rules` | `designs:write` | Your own rules, and which learned rules are on |
## 1. Create the kit [#1-create-the-kit]
Every workspace already has a **main kit** (`isMain: true` in `GET /v1/brand-kits`). Change
it with `PATCH`, or create another kit for a second brand:
```bash
curl -X POST https://api.nimply.io/v1/brand-kits \
-H "Authorization: Bearer $NIMPLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Brewhaus",
"colors": ["#F0530F", "#1B1815", "#FFF7EE"],
"fonts": { "heading": { "family": "Anton" }, "body": { "family": "Inter", "weight": 400 } },
"voice": "Warm, plain-spoken and a little playful."
}'
```
* `colors` are hex codes, most important first: the first is your main colour.
* Fonts are Google Fonts families or fonts uploaded in Nimply.
* For a logo, import the image with [`POST /v1/media`](/docs/api-reference/media) and pass
its id as `logoMediaId`.
* On `PATCH`, only the fields you send change. `colors` and `fonts` replace the whole list;
`null` clears a field.
**Fill it from your website.** `POST /v1/brand-kits/import` with `{ "website": "brewhaus.coffee" }`
reads the site and suggests a name, colours, fonts and logos. It saves nothing: send what
you want to keep to `POST` or `PATCH`. It uses your connected Brandfetch account when you
have one (no credits), otherwise AI (a few credits; `creditsCharged` says how many).
## Create a kit from several sources [#create-a-kit-from-several-sources]
Read your brand from up to **6 sources at once** and get one draft kit to review. Each value
in the draft says which source it came from, and where two sources disagree you choose.
| `kind` | Field | What is read |
| --------- | ----------- | ----------------------------------------------------------------------------------------- |
| `website` | `website` | Your site: name, colours, fonts, logos |
| `text` | `text` | Brand notes, guidelines or tone (20–20,000 characters). Only what the text states |
| `pdf` | `mediaId` | A brand book PDF (up to 25 MB; the first 20 pages are read) |
| `channel` | `channelId` | One of your **connected** channels: its name and picture, recent image posts and captions |
| `images` | `mediaIds` | Up to 20 of your images: logos, photos, finished designs |
**Upload files first.** PDFs and images are passed as media ids. Upload a local file with
[`POST /v1/media/uploads`](/docs/api-reference/media) (`contentType: "application/pdf"` for a
PDF), `PUT` the bytes, then complete it; or import a public link with `POST /v1/media`.
### 1. Check the cost (optional, free) [#1-check-the-cost-optional-free]
`POST /v1/brand-kits/imports/estimate` with the same body as below returns `creditsMax` per
source and in total, plus `creditsAvailable`. An import usually uses about 20–80 credits.
### 2. Start reading [#2-start-reading]
```bash
curl -X POST https://api.nimply.io/v1/brand-kits/imports \
-H "Authorization: Bearer $NIMPLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sources": [
{ "kind": "website", "website": "brewhaus.coffee" },
{ "kind": "pdf", "mediaId": "…" },
{ "kind": "text", "text": "Brewhaus is a neighbourhood coffee roaster. Primary colour #5F8EFD. Never use script fonts." },
{ "kind": "channel", "channelId": "…" }
]
}'
```
It returns `202` with the import `id`, `status: "queued"`, one entry per source in `sources`,
and the `estimate`. Nimply holds up to `estimate.creditsMax` credits and charges only what it
really uses. A source that can't be used is a `400` with `sourceIndex` (0-based) saying which.
### 3. Poll until ready [#3-poll-until-ready]
Reading takes about a minute. Read `GET /v1/brand-kits/imports/{id}` every 10–20 seconds
until `status` is `ready` (or `failed`: nothing could be read, no credits used). Each source
shows `waiting`, `reading`, `done` or `failed` with an `error`; one failed source doesn't stop
the others.
When `ready`, `draft` holds the kit: `name`, `colors` (with roles, primary first), `fonts`,
`logos`, `voice`, `voiceSamples`, `guidelines`, `doNots`, `examples` (with `examplesCount`),
`fontUploads` (fonts that are not Google Fonts: upload them in Nimply) and `warnings`. Every
value has `sources`: the source's `index`, `kind`, `label` and, where known, a `detail`
(for example `p.3`).
### 4. Review disagreements [#4-review-disagreements]
`draft.colorConflicts` lists each colour role where two sources state different colours,
for example the PDF says `#5F8EFD` and the website `#515DEF`. The first option is the
default (a brand book or your text beats the website, which beats colours measured on
posts). `name`, `voice` and each font also have `options` when sources differ.
### 5. Save [#5-save]
```bash
curl -X POST https://api.nimply.io/v1/brand-kits/imports/$IMPORT_ID/save \
-H "Authorization: Bearer $NIMPLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "picks": { "colors": { "primary": "#515DEF" } }, "logo": 0, "learn": true }'
```
* `picks`: your choices for `name`, `colors` (per role), `fonts` (per role, a family) and
`voice`. Leave them out to keep the defaults.
* `logo`: which of `draft.logos` to use, by position (default `0`; `-1` for none).
* `learn: true` also starts [learning the look](#3-learn-the-look) from the examples found
(at least 3; uses AI credits).
It returns `brandKitId`, how many `examples` were added, `learningStarted`,
`creditsReserved` for learning, and `notes` about anything that didn't apply. Your don'ts
become [rules](#4-add-your-own-rules) of the new kit. A ready draft is kept for 7 days.
### Add a brand book to a kit you already have [#add-a-brand-book-to-a-kit-you-already-have]
Pass `brandKitId` when you start, with the new sources (usually one `pdf`):
```bash
curl -X POST https://api.nimply.io/v1/brand-kits/imports \
-H "Authorization: Bearer $NIMPLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "brandKitId": "…", "sources": [{ "kind": "pdf", "mediaId": "…" }] }'
```
The import has `targetBrandKitId`, and once `ready` a `target` that compares the draft with
the kit. It lists only what differs: `colors` (with the `added` colours the kit doesn't have),
`fonts` per role, `voice` and `guidelines`, each with the kit's value (`kit`) and the one
found (`found`). `target.brandBooks` lists the kit's current brand book PDFs.
Save works as above but **updates the kit**. The kit's own values win by default; empty
fields are filled (`target.defaults` shows what save will do). To choose, send `apply`:
```bash
curl -X POST https://api.nimply.io/v1/brand-kits/imports/$IMPORT_ID/save \
-H "Authorization: Bearer $NIMPLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "apply": { "colors": "add", "fonts": { "heading": "found" } }, "replaceBrandBook": true, "learn": true }'
```
* `apply.colors`: `kit` (keep), `found` (use the colours found) or `add` (keep the kit's and
add the new ones). `apply.guidelines` takes the same values; `apply.voice` and each
`apply.fonts` role take `kit` or `found`.
* The kit keeps its logo unless you send `logo`. The don'ts found are added to its rules and
the brand book's pages are added as examples.
* `replaceBrandBook: true` replaces the kit's current brand book: its pages leave the learned
look and its files leave the kit's Brand assets folder (you can delete them then). Learn the
look again (`learn: true`) so it reflects the new book.
The result also has `updated: true`, the kit fields that `changed` and `replacedBrandBooks`.
## 2. Add examples [#2-add-examples]
The look is learned from **your own** designs: at least 3, up to 50. Between 8 and 20 varied
examples work best. Two kinds of example:
* **Images** from your media library: `mediaIds`.
* **Published posts** with an image: `postIds`. List them with
`GET /v1/brand-kits/{id}/style/post-candidates` (24 per page, `cursor` for more, optional
`channelId`).
```bash
curl -X POST https://api.nimply.io/v1/brand-kits/$KIT_ID/style/examples \
-H "Authorization: Bearer $NIMPLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "postIds": ["…", "…"], "mediaIds": ["…"] }'
```
Adding examples is free; duplicates are skipped. The response is the kit's style (below).
## 3. Learn the look [#3-learn-the-look]
First check the cost: `GET /v1/brand-kits/{id}/style` returns `learnEstimate.creditsMax`
(the most it can use) and `creditsAvailable`. Then start learning:
```bash
curl -X POST https://api.nimply.io/v1/brand-kits/$KIT_ID/style/learn \
-H "Authorization: Bearer $NIMPLY_API_KEY"
```
It returns `202` with `status: "learning"` and `creditsReserved`. Nimply holds that many
credits and charges only what it really uses. Learning takes a few minutes: read
`GET /v1/brand-kits/{id}/style` about once a minute until `status` is `ready` or `failed`.
When it is `ready`, the style has a plain-words `summary`, a `palette`, `fonts`, `doNots`,
`recipes` (the kinds of posts you make) and learned `rules`. New designs for this kit
follow it automatically (see [Learned brand look](/docs/designs#learned-brand-look)).
Learning again later learns only the new examples. Pass `{ "relearnAll": true }` to learn
everything again.
## 4. Add your own rules [#4-add-your-own-rules]
Rules are short instructions every design for the kit follows, yours first. Send your whole
list to `PUT /v1/brand-kits/{id}/style/rules`:
```json
{
"rules": [
{ "text": "Never use script fonts." },
{ "text": "Leave space for the logo in the top right." },
{ "id": "learned:2", "text": "Headlines in all caps.", "enabled": false }
]
}
```
* A rule without an `id` is new. Your rules left out of the list are deleted.
* Learned rules have ids `learned:`. Switch one off with `enabled: false`, or change its
text to save your own version. A learned rule you leave out keeps its state.
* Your rules stay when the look is learned again.
## Errors [#errors]
| Status | `code` | Meaning |
| ------ | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | `STYLE_TOO_FEW_EXAMPLES` | Add at least 3 examples before learning |
| `400` | `STYLE_NOTHING_NEW` | Every example is already learned; add new ones or pass `relearnAll` |
| `400` | `STYLE_EXAMPLE_INVALID` | An id is not in this workspace, or has no image |
| `400` | `BRAND_KIT_INVALID_COLOR` / `BRAND_KIT_UNKNOWN_FONT` | A colour isn't a hex code, or a font isn't a Google font or one you uploaded |
| `400` | `BRAND_SOURCE_NOT_AVAILABLE` and other source codes | A source can't be used; `sourceIndex` says which |
| `400` | `BRAND_IMPORT_NOT_READY` / `BRAND_IMPORT_EXPIRED` | Still reading, or the draft is older than 7 days |
| `402` | `INSUFFICIENT_CREDITS` | Not enough AI credits; the body has `needed` and `available` |
| `403` | `PAID_PLAN_REQUIRED` | Learning and several-source imports need a paid plan or a trial; website import needs a paid plan (or Brandfetch connected in Nimply) |
| `403` | `BRAND_KIT_QUOTA_EXCEEDED` | Your plan's kit limit is reached |
| `409` | `STYLE_LEARNING` | The look is being learned right now; try again when it finishes |
| `409` | `BRAND_IMPORT_SAVED` | This import was already saved |
## From ChatGPT, Claude and other assistants [#from-chatgpt-claude-and-other-assistants]
The [MCP server](/docs/mcp) has a tool for each step: `create_brand_kit`,
`import_brand_from_website`, `import_brand_from_sources`, `get_brand_import`,
`save_brand_import`, `get_brand_kit`, `update_brand_kit`,
`list_style_post_candidates`, `add_style_examples`, `remove_style_example`,
`learn_brand_style`, `get_brand_style` and `set_brand_style_rules`. Ask things like:
* *"Set up a brand kit for brewhaus.coffee."*
* *"Make a brand kit from our website, this brand book PDF and our Instagram."*
* *"Learn our look from our 10 best Instagram posts."*
* *"Add a rule: never use script fonts."*
The assistant tells you the credit cost before it starts learning, and checks back until the
look is ready. Connections made before these tools existed need to be reconnected to see them.
# Data model (/docs/data-model)
Four resources cover almost everything the API does. Get these straight and every
endpoint becomes predictable.
```txt
Workspace ─ the tenant your API key belongs to
├── Channels ─ connected social accounts (Instagram, LinkedIn, …)
├── Posts ─ content, each targeting exactly ONE channel
├── Media ─ imported images/videos, attachable to posts
└── Webhooks ─ endpoints that receive events about the above
```
## Workspace — the boundary of everything [#workspace--the-boundary-of-everything]
Every credential is bound to **one workspace**: an API key (`nim_live_...`) is created
inside a workspace, and an OAuth access token (`nim_oat_...`) is issued for the workspace
the user picked during consent. There is no cross-workspace access — a key can only see
the channels, posts, and media of its own workspace, and resources from other workspaces
return `404`, not `403`.
`GET /v1/workspace` tells you which workspace you're in and which scopes your credential
has (`grantedScopes`).
## Channels — where posts go [#channels--where-posts-go]
A **channel** is one connected social account. The `type` field has 13 values across 9 platforms:
| Platform | Channel types |
| --------------- | ---------------------------------------------- |
| Facebook | `FACEBOOK_PAGE`, `FACEBOOK_GROUP` |
| Instagram | `INSTAGRAM_PROFESSIONAL`, `INSTAGRAM_PERSONAL` |
| Twitter/X | `TWITTER` |
| LinkedIn | `LINKEDIN_PROFILE`, `LINKEDIN_PAGE` |
| TikTok | `TIKTOK_PERSONAL`, `TIKTOK_BUSINESS` |
| YouTube | `YOUTUBE` |
| Pinterest | `PINTEREST` |
| Google Business | `GOOGLE_BUSINESS` |
| Threads | `THREADS` |
Channels are connected in the Nimply app (the API can't connect them — that requires the
platform's own OAuth dance). Before publishing, check that `isConnected` is `true` and
`tokenStatus` is not `NEEDS_RECONNECT`. Each channel also has a `timezone` and a
**posting schedule** (`GET /v1/channels/{id}/schedule`) — the weekday time slots used by
`"next_slot"` scheduling.
## Posts — one post, one channel [#posts--one-post-one-channel]
A post targets **exactly one channel**. When you call `POST /v1/posts` with several
`channelIds`, Nimply creates one post *per channel* and returns them all — each with its
own `id`, status, and lifecycle. Keep this in mind when you later schedule, poll, or
delete: you operate on individual per-channel posts.
### Status lifecycle [#status-lifecycle]
```txt
request-approval
┌─────────────────────────────────────┐
│ ▼
DRAFT ◄───────── reject ─────── PENDING_APPROVAL
│ ▲ │
│ └── approve (no publish time) ──────┤
│ │ approve (has a
│ schedule / publish now / next_slot │ future publish time)
▼ │
SCHEDULED ◄──────────────────────────────┘
│
│ publish time reached
├──────────────► PUBLISHED (live on the platform)
└──────────────► FAILED (the platform rejected it)
ARCHIVED — archived in the Nimply app; find with ?status=ARCHIVED
```
* **DRAFT** — created, nothing will happen until you act (`"schedule": "draft"` is the default).
* **PENDING\_APPROVAL** — a draft sent for review via `POST /v1/posts/{id}/request-approval`. Approving returns it to `SCHEDULED` (if it has a future publish time) or `DRAFT`; rejecting returns it to `DRAFT`.
* **SCHEDULED** — queued for a publish time. Note that "publish now" is also asynchronous: the post briefly sits in `SCHEDULED` while the queue processes it.
* **PUBLISHED** — successfully live. Published posts can't be edited or deleted via the API.
* **FAILED** — publishing was attempted and rejected by the platform.
* **ARCHIVED** — archived in the Nimply app; excluded from your normal workflow but still readable.
### Content types [#content-types]
The `contentType` field selects the *format* on the platform:
| Value | Meaning |
| ------- | ------------------------------------------------------------------------------------------------------------ |
| `POST` | A standard feed post (default). **Multiple media on a `POST` become a carousel** — order follows `mediaIds`. |
| `REEL` | A short-form vertical video (Reels-style surface). |
| `STORY` | An ephemeral story. |
| `VIDEO` | A regular video post (e.g. a YouTube upload — use `title` too). |
### Posts made outside Nimply [#posts-made-outside-nimply]
A customer can let Nimply show posts they published on the platform itself (for example straight from the Instagram app). These carry `source: "external"`; posts created in Nimply carry `source: "nimply"`.
* `GET /v1/posts` returns only `nimply` posts unless you pass `source=external` or `source=all`.
* An `external` post is always `PUBLISHED`, has no `mediaIds`, and is read-only: changing, scheduling, publishing or deleting it returns `409 EXTERNAL_POST_READ_ONLY`.
* Platforms are being switched on one at a time, starting with Instagram. The customer turns this on or off per channel in the Nimply app.
### Platform-specific options [#platform-specific-options]
`POST /v1/posts` covers the fields every platform understands: `content`, `title`,
`contentType`, `mediaIds`, `schedule`. Four platforms support more than that, and each has
a **dedicated create endpoint** that accepts its full option set and validates
platform-required fields at request time:
| Platform | Endpoint | Notable options |
| --------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| YouTube | [`POST /v1/posts/youtube`](/docs/api-reference/posts/createYouTubeVideo) | `title` (required), `videoType` (`video`/`short`), `category`, `tags`, `visibility`, `license`, `notifySubscribers`, `allowEmbedding`, `madeForKids` |
| TikTok | [`POST /v1/posts/tiktok`](/docs/api-reference/posts/createTikTokPost) | `privacyLevel` (required), `allowComments`, `allowDuet`, `allowStitch`, `brandContent`, `brandOrganic` |
| Pinterest | [`POST /v1/posts/pinterest`](/docs/api-reference/posts/createPinterestPin) | `boardId` (required), `link`, `altText` |
| LinkedIn | [`POST /v1/posts/linkedin`](/docs/api-reference/posts/createLinkedInPost) | `visibility` (`PUBLIC`/`CONNECTIONS`) |
Two helper endpoints supply the values these options need:
[`GET /v1/channels/{id}/pinterest/boards`](/docs/api-reference/channels/getPinterestBoards)
lists a channel's boards, and
[`GET /v1/channels/{id}/tiktok/creator-info`](/docs/api-reference/channels/getTikTokCreatorInfo)
returns the privacy levels a TikTok account allows (plus Duet/Stitch availability and the
max video duration).
Rule of thumb: use the **generic endpoint** for simple cross-platform posting, and the
**platform endpoint** whenever you need platform features. Facebook, Instagram, Twitter/X,
and Threads have no extra options — the generic endpoint is all they need.
### Video thumbnails and covers [#video-thumbnails-and-covers]
A video post can carry a custom cover, set in one of two ways:
* `thumbnailMediaId`: the id of an **image** media asset to use as the thumbnail. Upload it
with `POST /v1/media` like any other file.
* `coverTimestampMs`: a frame of the video to use as the cover, in milliseconds from the
start.
Both are optional, and both work on `POST /v1/posts` and `PATCH /v1/posts/{id}` (pass
`null` to remove one). The platform endpoints accept the ones their platform supports.
| Platform | Custom image (`thumbnailMediaId`) | Frame (`coverTimestampMs`) |
| ------------------------- | --------------------------------- | ------------------------------- |
| YouTube | Yes, on verified channels | No |
| Instagram Reels | Yes | Yes |
| Facebook videos and Reels | Yes | No |
| LinkedIn videos | Yes | No |
| TikTok videos | Yes | Yes |
| Pinterest video pins | Yes | Yes, rounded down to the second |
* When both are set, the custom image wins.
* Platforms that are not in the table, and posts without a video, ignore both fields.
* A thumbnail that is not an image returns `400`; an id from another workspace returns `404`.
* The cover is applied when the post publishes. If a platform rejects the image, the
video still publishes without it.
* Post responses return `thumbnailMediaId` and `coverTimestampMs` (`null` when unset).
## Media — upload once, attach anywhere [#media--upload-once-attach-anywhere]
Media assets are imported by URL (`POST /v1/media` with a publicly reachable `url`) into
workspace storage, then referenced by id in a post's `mediaIds` array — in display order.
Assets are workspace-level, not post-level: one uploaded image can be attached to many
posts. Types are `IMAGE`, `VIDEO`, `GIF`, and `DOCUMENT`. The `url` returned on a media
asset is a signed delivery URL that expires after 24 hours — re-fetch the asset for a
fresh one, and don't store it.
## Webhooks — events about posts and channels [#webhooks--events-about-posts-and-channels]
[Webhooks](/docs/webhooks) are registered per workspace and fire for **post events**
(`post.created`, `post.updated`, `post.published`, `post.failed`, `post.deleted`, and the
approval trio `post.approval_requested` / `post.approved` / `post.rejected`) and
**channel events** (`channel.disconnected`). Every delivery envelope carries the
`workspaceId` plus the affected `postId`/`channelId`, and is signed with your endpoint's
secret.
## Next steps [#next-steps]
# Designs (/docs/designs)
Nimply can make **real, editable designs** for you: social posts, carousels, ads and
thumbnails, built in your brand kit and opened in the Nimply design editor. Two jobs are
available:
* **Generate** — give a brief ("an Instagram post announcing our summer sale, 20% off,
shop now") and Nimply's design composer builds a finished design.
* **Layers** — give an image (for example one ChatGPT just made) and Nimply splits it into
editable text, objects and a clean background, so you can change the words, move things
around and reuse it.
Each job leaves a design in your workspace. You get back an **edit link** that opens it
in the editor, and **preview images** (PNG) of the result.
**Scopes:** `designs:read` for reads and polling, `designs:write` to start or cancel a
job. Both are opt-in.
**Plans and credits:** designs are available on paid plans and during a trial. Each job
uses AI credits from your workspace. Nimply reserves the maximum up front and charges
only what the job actually used. Ask for an estimate first with
[`GET /v1/designs/estimate`](#estimate-the-cost). If the workspace is short of credits the
job is refused with `402` and code `INSUFFICIENT_CREDITS`.
## How jobs work [#how-jobs-work]
Both kinds of job are asynchronous. A design takes about 1–3 minutes per size; layering an
image takes about 30–60 seconds.
1. Start the job: `POST /v1/designs/generate` or `POST /v1/designs/from-image` → `202` with a
**design job**.
2. Poll `GET /v1/design-jobs/{id}?wait=25`. With `wait`, the request is held for up to 25
seconds and returns as soon as something changes, so a few calls cover a whole job.
3. When `status` is `done`, each item in `designs` has its `editUrl` and `previewUrls`.
`status` moves through `queued` → `running` → `rendering` (the preview PNGs are being made)
→ `done`. It can also end as `failed` (unused credits are released) or `cancelled`.
## Endpoints [#endpoints]
| Method | Path | Scope | What it does |
| ------ | --------------------------------- | --------------- | -------------------------------------------------------------------------------------------------- |
| `POST` | `/v1/designs/generate` | `designs:write` | Start a design from a prompt |
| `POST` | `/v1/designs/from-image` | `designs:write` | Turn an image into an editable, layered design |
| `GET` | `/v1/design-jobs/{id}?wait=0..25` | `designs:read` | Job status and result (long-poll with `wait`) |
| `POST` | `/v1/design-jobs/{id}/cancel` | `designs:write` | Stop a job; unused credits are released |
| `GET` | `/v1/designs` | `designs:read` | List designs (`limit`, `cursor`) |
| `GET` | `/v1/designs/{id}` | `designs:read` | One design with fresh preview links |
| `GET` | `/v1/designs/estimate` | `designs:read` | Credit estimate for a job, plus credits available |
| `GET` | `/v1/brand-kits` | `designs:read` | Your brand kits, to pick one for a design (create and change them: [Brand kits](/docs/brand-kits)) |
| `GET` | `/v1/design-sizes` | `designs:read` | Size ids you can ask for (Instagram post, story, LinkedIn, …) |
Both start endpoints are limited to 10 requests per minute per key, on top of the
[general rate limit](/docs/errors).
## Generate a design [#generate-a-design]
```bash
curl -X POST "https://api.nimply.io/v1/designs/generate" \
-H "Authorization: Bearer $NIMPLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Instagram post announcing our summer sale: 20% off all cold brew this weekend. Friendly, bright, for coffee lovers in Dubai.",
"sizes": ["ig-post-45"],
"cta": "Shop the sale",
"maxCredits": 300
}'
```
| Field | Type | Notes |
| ----------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `prompt` | string, required | The brief. Say who it's for, the offer or message, and the call to action. |
| `sizes` | string\[] | Up to 3 ids from `GET /v1/design-sizes`; default `ig-post-45` (Instagram 4:5). Each size becomes its own design. |
| `format` | `single` \| `carousel` | Default `single`. |
| `pages` | 1–10 | Carousel page count (default 5). A carousel has at most 7 slides: a higher value makes 7. |
| `brandKitId` | string | From `GET /v1/brand-kits`. Default: your main kit. |
| `channelId` | string | Use the brand kit linked to this channel. |
| `cta` | string | Call-to-action text (≤120 chars). |
| `styleHint` | string | A look to aim for, e.g. "minimal, lots of white space" (≤300 chars). |
| `locale` | string | Language for the design text, e.g. `de`. |
| `photoMediaIds` | string\[] | Up to 4 of your own photos (e.g. a product shot) from the media library. |
| `maxCredits` | integer | Refuse the job (`422 OVER_MAX_CREDITS`) if it could cost more than this. |
| `useLearnedStyle` | boolean | Default `true`: apply the brand kit's [learned look](#learned-brand-look) when the kit has one. `false` uses only its colours, fonts and logo. |
## Learned brand look [#learned-brand-look]
In Nimply, a brand kit can **learn your look** from your own posts: its layouts, type,
colour use and the kinds of posts you make. When the kit you design with (`brandKitId`,
the channel's kit, or your main kit) has learned a look, every generated design follows it
automatically. Teach a kit its look in the app's brand kit editor, or through the API and
MCP: see [Set up a brand kit and teach it your look](/docs/brand-kits).
* Turn it off for one job with `"useLearnedStyle": false`.
* The learned look adds a little to the cost. `GET /v1/designs/estimate` and `maxCredits`
already include it.
* Designs in a finished job carry `brandMatch`: how closely the design matches the kit's
own posts, 0–100. They also carry `styleVersion`, the version of the learned look that was
used. Both are `null` when no learned look was applied.
## Turn an image into layers [#turn-an-image-into-layers]
Send exactly one of `mediaId` (an image already in your media library) or `imageUrl` (a
public image URL; Nimply imports it first).
```bash
curl -X POST "https://api.nimply.io/v1/designs/from-image" \
-H "Authorization: Bearer $NIMPLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "imageUrl": "https://example.com/poster.png", "mode": "everything" }'
```
`mode` chooses what becomes editable: `text` (just the words, the cheapest), `objects`, or
`everything` (the default).
## The design job [#the-design-job]
```json
{
"id": "6f0c1d1e-2a9b-4f57-9d3c-0b6c3b2c9a11",
"kind": "generate",
"status": "done",
"progress": 100,
"stage": "Ready",
"creditsReserved": 251,
"creditsCharged": 132,
"estimatedSeconds": null,
"designs": [
{
"id": "b1d0c7e2-5c1a-4a43-8f53-3d0f6f9d7e20",
"name": "Summer sale — Instagram portrait",
"width": 1080,
"height": 1350,
"pageCount": 1,
"sizePreset": "ig-post-45",
"editUrl": "https://app.nimply.io/workspace/…/studio/design/b1d0c7e2-…",
"previewUrls": ["https://cdn.nimply.io/…/page-1.png?…"],
"thumbnailUrl": "https://cdn.nimply.io/…/thumb.jpg?…",
"createdAt": "2026-10-21T10:02:11.000Z",
"brandMatch": 82,
"styleVersion": 3
}
],
"error": null,
"createdAt": "2026-10-21T10:00:40.000Z",
"finishedAt": "2026-10-21T10:02:30.000Z"
}
```
* `editUrl` opens the design in the Nimply editor. It needs a Nimply login with access to
the workspace.
* `previewUrls` are signed links to full-size PNGs, one per page. They expire after 7 days.
`GET /v1/designs/{id}` always returns fresh ones.
* New designs also show up in the app under Design, and the person who started the job gets
a "ready" notification.
## Estimate the cost [#estimate-the-cost]
For `kind=generate`, pass the same `brandKitId` / `channelId` you will generate with (and
`useLearnedStyle=false` if you'll turn the learned look off) to price exactly that run.
```bash
curl "https://api.nimply.io/v1/designs/estimate?kind=generate&sizes=ig-post-45,ig-story" \
-H "Authorization: Bearer $NIMPLY_API_KEY"
```
```json
{
"kind": "generate",
"creditsMin": 133,
"creditsMax": 478,
"estimatedSeconds": { "min": 120, "max": 360 },
"creditsAvailable": 1840
}
```
## Errors [#errors]
| Status | `code` | Meaning |
| ------ | ---------------------- | -------------------------------------------------------------------------------- |
| `402` | `INSUFFICIENT_CREDITS` | Not enough AI credits; the body has `needed` and `available` |
| `403` | `PAID_PLAN_REQUIRED` | Designs need a paid plan or an active trial |
| `403` | — | The key or connection is missing `designs:read` / `designs:write` |
| `422` | `OVER_MAX_CREDITS` | The job could cost more than your `maxCredits` |
| `422` | `INVALID_SIZE` | An id in `sizes` isn't in `GET /v1/design-sizes` |
| `422` | `IMAGE_IMPORT_FAILED` | Nimply couldn't download the `imageUrl` (not public, too large, or not an image) |
| `429` | — | Too many jobs; retry after `Retry-After` seconds |
A job that fails after it started ends with `status: "failed"` and an `error` with a `code` and a readable `message`. Unused credits are released.
## From ChatGPT, Claude and other assistants [#from-chatgpt-claude-and-other-assistants]
The [MCP server](/docs/mcp) exposes the same jobs as tools: `create_design`,
`layer_image`, `get_design_job`, `get_design`, `list_designs`, `list_brand_kits`,
`list_design_sizes`, `estimate_design_cost` and `cancel_design_job` (plus the
[brand kit tools](/docs/brand-kits#from-chatgpt-claude-and-other-assistants)). Ask things like:
* *"Make an Instagram post for our weekend cold brew sale in our brand kit."*
* *"Turn this image into an editable design."* — in ChatGPT, attach the image or ask
ChatGPT to make one first. Other clients can pass a public image URL.
The assistant shows a preview in the chat and gives you the link to open the design in
Nimply.
Connections made before these tools existed don't have design access yet. Reconnect
Nimply in your assistant and approve the design permissions.
# Errors (/docs/errors)
The Nimply API reports failures using **problem details** as defined by
[RFC 9457](https://www.rfc-editor.org/rfc/rfc9457). Error responses have the
`Content-Type: application/problem+json` header and a consistent body shape.
## Problem details format [#problem-details-format]
```http
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json
{
"type": "https://developer.nimply.io/docs/errors#unprocessable-entity",
"title": "Unprocessable Entity",
"status": 422,
"detail": "scheduledAt must be an ISO 8601 datetime in the future.",
"instance": "/v1/posts/9f2b1c3d/schedule",
"errors": [
"scheduledAt must be an ISO 8601 datetime in the future."
]
}
```
| Field | Meaning |
| ---------- | -------------------------------------------------------------------------------------- |
| `type` | A URI identifying the error category |
| `title` | Short, human-readable summary of the error category |
| `status` | The HTTP status code, repeated in the body |
| `detail` | Human-readable explanation specific to this occurrence |
| `instance` | The request path that produced the error |
| `errors` | (Some errors only) the individual problems — see below |
| `code` | (When present) a stable, machine-readable error code — branch on this, not on `detail` |
Some errors add more members you can act on without reading `detail`:
| Member | When | Meaning |
| --------------------- | --------------------------- | --------------------------------------------------------------------------------------------- |
| `errors` | Validation, `INVALID_GRAPH` | Every problem as its own string, so you can fix them all at once |
| `missingFields` | `MISSING_FIELDS` | The settings still needed: `key`, `label`, `type`, and `options` / `multiple` when they apply |
| `fields` | `SET_IN_APP` | The names of the settings only the Nimply app can choose |
| `appUrl` | `SET_IN_APP` | Link to the place in the Nimply app where the user can finish |
| `needed`, `available` | `INSUFFICIENT_CREDITS` | AI credits the job could use, and credits the workspace has |
## Status codes [#status-codes]
| Status | Meaning |
| ------ | ------------------------------------------------------------------------ |
| `400` | Malformed request (invalid JSON, wrong types) |
| `401` | Missing or invalid API key |
| `403` | Key is valid but lacks the required [scope](/docs/authentication#scopes) |
| `404` | Resource does not exist or belongs to another workspace |
| `409` | Conflict (e.g. replayed `Idempotency-Key` with a different body) |
| `422` | Request understood but failed validation |
| `429` | Rate limit exceeded — see below |
| `5xx` | Something went wrong on Nimply's side; safe to retry with backoff |
## Agent and automation error codes [#agent-and-automation-error-codes]
The [Agents](/docs/agents#errors) and [Automations](/docs/automations#errors) guides explain
each code. In short:
| Status | `code` | Meaning |
| ------ | ------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `400` | `INVALID_CONFIG` | An agent setting, preset or channel the agent can't use |
| `402` | `INSUFFICIENT_CREDITS` | Not enough AI credits to start the run |
| `403` | `INSUFFICIENT_ROLE` | The person the key acts for needs a higher workspace role |
| `403` | `PAID_PLAN_REQUIRED` | Needs a paid plan or an active trial |
| `403` | `AGENT_QUOTA_EXCEEDED` / `AGENT_RUN_QUOTA_EXCEEDED` | The plan's agent or monthly run limit is reached |
| `403` | `AUTOMATION_QUOTA_EXCEEDED` / `ACTIVE_AUTOMATION_LIMIT` | The plan's automation limit, or 20 switched on, is reached |
| `404` | `RECIPE_NOT_FOUND` | No automation recipe with that id |
| `409` | `AGENT_PAUSED` | Resume the agent before running it |
| `409` | `VERSION_CONFLICT` | The automation changed since you read it |
| `409` | `MANAGED_AUTOMATION` | The automation belongs to an agent or a Nimply feature and is read-only |
| `422` | `MISSING_FIELDS` | Required agent settings are missing (`missingFields`) |
| `422` | `SET_IN_APP` | Only the Nimply app can do this (`fields`, `appUrl`) |
| `422` | `AGENT_RUNS_FROM_INBOX` | Inbox agents can't be run by hand |
| `422` | `STEP_NOT_ALLOWED` | A step type or stored secret the API can't add |
| `422` | `INVALID_GRAPH` | The automation isn't ready or valid (`errors`) |
| `422` | `INVALID_INPUT` / `INVALID_VALUES` | Wrong mix of `steps` / `graph` / `edges`, or a recipe blank that doesn't fit |
| `422` | `RUN_NEEDS_EVENT` | The automation starts on an event and can't be run by hand |
## Rate limits [#rate-limits]
Rate limits are applied per API key. Every response includes headers describing your
current allowance:
| Header | Meaning |
| ----------------------- | ----------------------------------------------- |
| `X-RateLimit-Limit` | Requests allowed in the current window |
| `X-RateLimit-Remaining` | Requests left in the current window |
| `Retry-After` | (On `429` only) seconds to wait before retrying |
When you exceed the limit, the API responds with `429 Too Many Requests`:
```http
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
Retry-After: 27
{
"type": "https://developers.nimply.io/errors/rate-limited",
"title": "Too many requests",
"status": 429,
"detail": "Rate limit exceeded. Retry after 27 seconds."
}
```
Honor `Retry-After` and use exponential backoff with jitter for `5xx` responses. Combine
retries with an [`Idempotency-Key`](/docs/quickstart#3-create-a-draft-post) on `POST`
requests so retried writes never create duplicates.
# Nimply API (/docs)
The Nimply API lets you automate everything you can do in the Nimply app: connect to your
workspace, browse connected social channels, upload media, and create, schedule, and publish
posts across Facebook, Instagram, Twitter/X, LinkedIn, TikTok, YouTube, Pinterest, and more.
## Base URL [#base-url]
All API requests are made to:
```txt
https://api.nimply.io
```
Every endpoint in the current version is prefixed with `/v1`.
## Typical workflow [#typical-workflow]
1. **Authenticate** with a workspace API key (`nim_live_...`) in the `Authorization` header.
2. **List channels** with `GET /v1/channels` to find the ids of the social accounts you want to post to.
3. **Upload media** (optional) with `POST /v1/media` by giving Nimply a public URL to import.
4. **Create a post** with `POST /v1/posts` — as a draft, at an ISO 8601 time, in the next free queue slot, or immediately.
## Get started [#get-started]
# Link pages (/docs/link-pages)
A **link page** is the public page Nimply hosts for a workspace at
`https://nimply.link/` (the "link in bio"). It is built from **blocks**
— link buttons, text, latest posts, forms, countdowns, products and so on —
and has a **draft** that goes live only when you publish.
The API lets you manage the parts of a page that automations care about:
add a link when something happens, swap a countdown, hide a block after a
campaign, and publish. Page design (looks, themes) and blocks that carry
uploaded media stay in the Nimply app.
**Scopes:** `links:read` for reads, `links:write` for changes and publishing.
Both are opt-in — tick them when you create the key.
## Endpoints [#endpoints]
| Method | Path | Scope | What it does |
| -------- | -------------------------------------------------- | ------------- | --------------------------------------------------------------------- |
| `GET` | `/v1/link-pages` | `links:read` | List pages `{ data: LinkPage[] }` |
| `GET` | `/v1/link-pages/{id}` | `links:read` | One page with its `blocks` in display order |
| `PATCH` | `/v1/link-pages/{id}` | `links:write` | Update `title`, `bio`, `seoTitle`, `seoDescription`, `noindex` |
| `POST` | `/v1/link-pages/{id}/publish` | `links:write` | Publish the draft → `{ publishedVersion, url }` |
| `GET` | `/v1/link-pages/{id}/blocks` | `links:read` | Blocks only |
| `POST` | `/v1/link-pages/{id}/blocks` | `links:write` | Add a block (types below) |
| `PATCH` | `/v1/link-pages/{id}/blocks/{blockId}` | `links:write` | Change `config`, `isActive`, `scheduledStartAt`, `scheduledEndAt` |
| `DELETE` | `/v1/link-pages/{id}/blocks/{blockId}` | `links:write` | Remove a block |
| `GET` | `/v1/link-pages/{id}/analytics?range=7d\|28d\|12m` | `links:read` | Views, clicks, CTR and per-block clicks (paid plans; `403` otherwise) |
Every write lands in the page **draft**. Nothing changes for visitors until
you call `publish`, which returns the new `publishedVersion`; the public URL
updates within about a minute.
## Objects [#objects]
### LinkPage [#linkpage]
```json
{
"id": "8097029e-5895-4a48-b03c-2d7263c2d891",
"handle": "brewhaus.coffee",
"url": "https://nimply.link/brewhaus.coffee",
"title": "Brewhaus Coffee",
"bio": "Specialty coffee in Al Quoz. Open daily.",
"status": "PUBLISHED",
"publishedVersion": 4,
"publishedAt": "2026-09-26T16:43:48.221Z",
"seo": { "title": "Brewhaus Coffee", "description": null, "noindex": false },
"blocksCount": 7,
"createdAt": "2026-09-26T16:37:10.000Z",
"updatedAt": "2026-09-27T08:02:11.000Z"
}
```
`status` is `DRAFT` (never published), `PUBLISHED`, or `SUSPENDED` (paused by
Nimply Trust & Safety — writes still work, publishing is refused).
### LinkBlock [#linkblock]
```json
{
"id": "5d1f8f4a-6d2e-4a4e-9c0f-2b7e2c0d9a11",
"type": "LINK",
"position": 2,
"isActive": true,
"config": {
"title": "Watch my latest video",
"url": "https://youtube.com/watch?v=abc123",
"subtitle": null,
"style": "solid"
},
"scheduledStartAt": null,
"scheduledEndAt": null,
"createdAt": "2026-09-26T16:37:12.000Z",
"updatedAt": "2026-09-26T16:37:12.000Z"
}
```
`position` is 0-based in display order. `isActive: false` hides a block
without deleting it. A schedule window (`scheduledStartAt` / `scheduledEndAt`,
ISO 8601) shows the block only inside that window — evaluated live on every
visit, so a countdown or offer can appear and disappear without a republish.
## Block types you can create [#block-types-you-can-create]
Other block types (profile header, social icons, galleries, videos, forms,
latest posts, menus, events, …) are created in the Nimply app; the API can
still read them and toggle `isActive` on them.
| `type` | `config` |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `LINK` | `{ "title", "url", "subtitle"?, "thumbnailUrl"?, "icon"?, "style"?: "solid" \| "outline" \| "card" \| "featured", "pinned"?, "utm"? }` |
| `TEXT` | `{ "content", "align"?: "left" \| "center", "size"?: "sm" \| "md" \| "lg" }` — `content` is restricted markdown (`##`, `###`, `**bold**`, `*italic*`, `[text](https://url)`, `- lists`) |
| `SECTION` | `{ "label"?, "style"?: "header" \| "divider" \| "spacer" }` |
| `POST_CARD` | `{ "url", "title"?, "caption"?, "thumbnailUrl"?, "platform"?: "instagram" \| "tiktok" \| "youtube" \| … }` — a card that links to a post by URL |
| `PRODUCT` | `{ "items": [{ "id", "title", "buyUrl", "price"?, "compareAtPrice"?, "currency"?: "USD", "imageUrl"?, "badge"?, "retailer"?, "affiliate"?: false }], "layout"?: "grid" \| "list", "columns"?: 1‑3, "buttonLabel"? }` — `affiliate: true` adds the required "Paid link" disclosure |
| `COUPON` | `{ "code", "headline"?, "description"?, "expiresAt"?, "terms"?, "url"?, "buttonLabel"? }` |
| `COUNTDOWN` | `{ "targetAt", "label"?, "timezone"?, "expired"?: { "behaviour": "hide" \| "text" \| "cta", "text"?, "ctaLabel"?, "ctaUrl"? } }` |
| `NOTICE_BAR` | `{ "text", "tone"?: "info" \| "warning" \| "success", "dismissible"?: true, "url"? }` |
| `FAQ` | `{ "title"?, "items": [{ "q", "a" }] }` |
| `TESTIMONIAL` | `{ "items": [{ "id", "quote", "author", "role"?, "avatarUrl"?, "rating"?: 1‑5, "source"?: "google" \| "yelp" \| "trustpilot" \| "instagram" \| "tiktok" \| "manual", "sourceUrl"? }], "layout"?: "cards" \| "carousel" \| "quote" }` |
Any other `type` is rejected with `400` and a message naming the allowed
types. Every URL is checked against Google Safe Browsing at publish time; a
flagged URL blocks the publish with the offending block id in the error.
## Examples [#examples]
Add a link button and publish:
```bash
curl -X POST "https://api.nimply.io/v1/link-pages/$PAGE_ID/blocks" \
-H "Authorization: Bearer $NIMPLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "LINK",
"position": 0,
"config": { "title": "New episode is out", "url": "https://youtu.be/abc123", "style": "featured" }
}'
curl -X POST "https://api.nimply.io/v1/link-pages/$PAGE_ID/publish" \
-H "Authorization: Bearer $NIMPLY_API_KEY"
```
A countdown that shows itself only this week and disappears afterwards:
```bash
curl -X POST "https://api.nimply.io/v1/link-pages/$PAGE_ID/blocks" \
-H "Authorization: Bearer $NIMPLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "COUNTDOWN",
"config": { "label": "Drop goes live in", "targetAt": "2026-10-03T18:00:00Z", "expired": { "behaviour": "hide" } },
"scheduledStartAt": "2026-09-28T00:00:00Z",
"scheduledEndAt": "2026-10-03T18:00:00Z"
}'
```
Hide a block after a campaign without deleting it:
```bash
curl -X PATCH "https://api.nimply.io/v1/link-pages/$PAGE_ID/blocks/$BLOCK_ID" \
-H "Authorization: Bearer $NIMPLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "isActive": false }'
```
Analytics for the last 28 days:
```json
{
"range": "28d",
"totals": { "views": 4210, "clicks": 1188, "ctr": 0.282, "forms": 31 },
"series": [{ "date": "2026-09-01", "views": 140, "clicks": 41 }],
"blocks": [{ "blockId": "5d1f…", "type": "LINK", "title": "Watch my latest video", "clicks": 612 }]
}
```
## Also available in [#also-available-in]
* **MCP** — `list_link_pages`, `get_link_page`, `add_link_block`, `update_link_block`, `publish_link_page` ([MCP server](/docs/mcp)).
* **Zapier** — *Add Link Block* action and *Find Link Page* search ([Zapier](/docs/integrations/zapier)).
* **Make** — *Add Link Block* and *Publish Link Page* modules ([Make](/docs/integrations/make)).
* **n8n** — the *Link Page* resource on the Nimply node ([n8n](/docs/integrations/n8n)).
Recipe: [Add a link to your page when a video goes live](/docs/examples/add-link-when-video-goes-live).
# MCP Server (/docs/mcp)
Nimply ships a remote [MCP](https://modelcontextprotocol.io) (Model Context Protocol) server, so any MCP-capable AI agent can plan, create, schedule, and measure your social content conversationally.
* **Endpoint:** `https://mcp.nimply.io/mcp` (Streamable HTTP)
* **Auth — two options:**
1. **OAuth (recommended):** in clients with connector support (claude.ai, ChatGPT, Claude Desktop), just add the server URL — you'll be redirected to Nimply to log in, pick a workspace, and approve the permissions. No keys to copy.
2. **API key header:** `Authorization: Bearer nim_live_...` ([create one](/docs/authentication)) for clients that use config files.
Either way, the agent acts with exactly the permissions you granted: read-only lets it analyze but not post; `posts:write` + `posts:publish` let it schedule and publish. Revoke access anytime (delete the key, or revoke the app from workspace settings).
## Tools [#tools]
| Tool | What it does |
| ------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_channels` | Connected accounts, ids, and connection health |
| `get_posting_schedule` | A channel's posting time slots per weekday |
| `create_post` | Create posts (draft / next free slot / now / at a time) |
| `create_youtube_video` / `create_tiktok_post` / `create_pinterest_pin` / `create_linkedin_post` | Platform-specific posting with the full option set (YouTube visibility/category/tags, TikTok privacy and disclosure, Pinterest board/link/alt text, LinkedIn visibility). These and `create_post` also take a custom video thumbnail (`thumbnailMediaId`) or cover frame (`coverTimestampMs`) |
| `get_pinterest_boards` / `get_tiktok_creator_info` | Board list and TikTok posting constraints that feed the platform tools |
| `list_posts` / `get_post` | Browse and inspect posts, filter by status/channel |
| `update_post` / `schedule_post` / `unschedule_post` / `publish_post` / `delete_post` | Manage drafts and scheduled posts |
| `upload_media` | Import an image/video from a public URL |
| `create_media_upload` / `complete_media_upload` | Direct binary upload via presigned URL — for agents that can run an HTTP PUT (CLIs, IDEs) |
| `get_analytics` | Workspace, channel, or post performance metrics |
| `request_approval` / `approve_post` / `reject_post` | Client sign-off workflow for agencies |
| `list_link_pages` / `get_link_page` | Your nimply.link pages and their blocks |
| `add_link_block` / `update_link_block` / `publish_link_page` | Add or change link-page blocks, then put the page live |
| `create_design` / `layer_image` | Make an editable design from a prompt, or turn an image into editable layers ([Designs](/docs/designs)). Uses AI credits |
| `get_design_job` / `cancel_design_job` | Follow a design job until it's ready, or stop it |
| `list_designs` / `get_design` / `list_brand_kits` / `list_design_sizes` / `estimate_design_cost` | Browse designs and brand kits, check the credit cost first |
| `create_brand_kit` / `import_brand_from_website` / `get_brand_kit` / `update_brand_kit` | Set up a brand kit, or fill one from the brand's website ([Brand kits](/docs/brand-kits)) |
| `import_brand_from_sources` / `get_brand_import` / `save_brand_import` | Make a brand kit from several sources at once: website, text, a PDF brand book, a connected channel, images. Uses AI credits |
| `list_style_post_candidates` / `add_style_examples` / `remove_style_example` / `learn_brand_style` / `get_brand_style` / `set_brand_style_rules` | Teach a brand kit your look from your own posts and images, and set your own design rules. Learning uses AI credits |
| `list_agent_templates` / `list_agents` / `get_agent` | Browse the agent gallery and your agents ([Agents](/docs/agents)). MCP server 0.7.0 |
| `hire_agent` / `update_agent` / `set_agent_status` / `remove_agent` | Hire an agent (the assistant asks only for missing settings), change it, pause or resume it, remove it. MCP server 0.7.0 |
| `run_agent` / `get_agent_run` / `cancel_agent_run` | Run an agent now and follow the run. Uses AI credits; what it makes waits for approval. MCP server 0.7.0 |
| `list_automation_step_types` / `list_automation_recipes` / `list_automations` / `get_automation` | Browse building blocks, recipes and your automations ([Automations](/docs/automations)). MCP server 0.7.0 |
| `create_automation` / `create_automation_from_recipe` / `update_automation` / `delete_automation` | Build an automation as a draft, change it, or delete it. MCP server 0.7.0 |
| `test_automation` / `set_automation_status` / `run_automation` / `get_automation_run` | Test with sample data, switch on or off, run once, and check a run. MCP server 0.7.0 |
## Connect your client [#connect-your-client]
Every supported platform has a dedicated step-by-step guide with the exact config for that client:
| | | |
| ------------------------------------------- | --------------------------------------------------- | --------------------------------------------------- |
| [claude.ai](/docs/integrations/claude-ai) | [Claude Desktop](/docs/integrations/claude-desktop) | [Claude Code](/docs/integrations/claude-code) |
| [ChatGPT](/docs/integrations/chatgpt) | [Cursor](/docs/integrations/cursor) | [VS Code](/docs/integrations/vs-code) |
| [Windsurf](/docs/integrations/windsurf) | [Codex CLI](/docs/integrations/codex-cli) | [Gemini CLI](/docs/integrations/gemini-cli) |
| [Perplexity](/docs/integrations/perplexity) | [Raycast](/docs/integrations/raycast) | [Any MCP client](/docs/integrations/any-mcp-client) |
The 30-second version for OAuth-capable clients (claude.ai, ChatGPT, Claude Desktop): add a custom connector with URL `https://mcp.nimply.io/mcp`, log in to Nimply, choose a workspace, approve — done. Config-file clients use the same URL plus an `Authorization: Bearer nim_live_...` header.
Browse [all integrations](/docs/integrations) — including [Zapier](/docs/integrations/zapier), [Make](/docs/integrations/make), and [n8n](/docs/integrations/n8n) for no-code automation.
## Try it [#try-it]
Once connected, ask your agent things like:
* *"What channels do I have connected, and are any unhealthy?"*
* *"Draft a week of posts about our product launch and schedule them into the next free slots."*
* *"Which of my posts performed best last month?"*
* *"Make an Instagram post for our weekend sale in our brand colours."*
* *"Turn this image into an editable design."*
* *"Learn our brand look from our best Instagram posts."*
* *"Hire a LinkedIn ghostwriter for my page, then run it and show me the drafts."*
* *"Every morning, have my Trend Scout find a topic and my Designer make a carousel."*
## Notes [#notes]
* Rate limits and plan quotas apply exactly as for direct API use — the MCP server is a thin wrapper over the [REST API](/docs/api-reference).
* Designs are asynchronous too: the agent polls `get_design_job` until it is `done`, then shows you the preview and the edit link.
* Agents never publish: what `run_agent` makes waits for approval, and the assistant approves a post only when you say so. Automations are created as drafts; the assistant tests them and switches them on only after you confirm. Nothing in the MCP server reads or sends inbox messages.
* Publishing is asynchronous: after "publish now" the post is `SCHEDULED`; the agent should poll `get_post` for `PUBLISHED` or `FAILED`.
* Treat your API key like a password. Use a dedicated key per agent so you can revoke one without breaking others.
# Quickstart (/docs/quickstart)
This walkthrough takes you from an empty terminal to a scheduled post in four requests.
You need an [API key](/docs/authentication) with the `channels:read`, `media:write`,
`posts:write`, and `posts:publish` scopes.
Export your key once so the examples stay short:
```bash
export NIMPLY_API_KEY="nim_live_4f8a2c…"
```
## 1. Find your channels [#1-find-your-channels]
Posts are published to **channels** — the social accounts connected to your workspace.
List them to get their ids:
```bash
curl https://api.nimply.io/v1/channels \
-H "Authorization: Bearer $NIMPLY_API_KEY"
```
```json
{
"data": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Acme Corp",
"type": "INSTAGRAM_PROFESSIONAL",
"username": "acmecorp",
"isConnected": true,
"tokenStatus": "HEALTHY",
"timezone": "Europe/Berlin"
}
]
}
```
Pick the `id` of the channel you want to post to. Make sure `isConnected` is `true` and
`tokenStatus` is not `NEEDS_RECONNECT`.
## 2. Upload media [#2-upload-media]
Give Nimply a publicly reachable URL and it downloads and stores the file, returning a
media id you can attach to posts:
```bash
curl -X POST https://api.nimply.io/v1/media \
-H "Authorization: Bearer $NIMPLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/images/launch-banner.png",
"name": "launch-banner.png"
}'
```
```json
{
"id": "9f2b1c3d-5a6e-4f70-8b91-2c3d4e5f6a70",
"name": "launch-banner.png",
"type": "IMAGE"
}
```
## 3. Create a draft post [#3-create-a-draft-post]
Create the post as a **draft** first (`"schedule": "draft"`), so you can review it in the
Nimply app before anything goes live:
```bash
curl -X POST https://api.nimply.io/v1/posts \
-H "Authorization: Bearer $NIMPLY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 4b1f2b6e-launch-post-001" \
-d '{
"channelIds": ["123e4567-e89b-12d3-a456-426614174000"],
"content": "Launching something new today 🚀",
"mediaIds": ["9f2b1c3d-5a6e-4f70-8b91-2c3d4e5f6a70"],
"schedule": "draft"
}'
```
One post is created per channel id. The response includes the post `id` you need in the next step.
Send an `Idempotency-Key` header (any unique string per logical operation) on `POST`
requests. If a request times out or your retry logic fires twice, Nimply returns the
original result instead of creating a duplicate post.
## 4. Schedule it [#4-schedule-it]
When you are happy with the draft, schedule it for a specific ISO 8601 time:
```bash
curl -X POST https://api.nimply.io/v1/posts/{postId}/schedule \
-H "Authorization: Bearer $NIMPLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "scheduledAt": "2026-08-01T09:00:00.000Z" }'
```
The post status moves to `SCHEDULED` and Nimply publishes it at that time.
Prefer to skip the draft step? Set `schedule` directly when creating the post:
`"next_slot"` uses the channel's next free posting-schedule slot, `"now"` publishes
immediately, and an ISO 8601 datetime schedules it — all of these require the
`posts:publish` scope.
## Next steps [#next-steps]
# Roadmap (/docs/roadmap)
The short version of where the Nimply developer platform is heading. Released means live
today; everything else is directional and unscheduled — we build in the order developers
ask for things.
## Released [#released]
All shipped **July 2026**:
* **API v1** — REST API for workspace, channels, posts, and media, with workspace-scoped API keys and per-key [scopes](/docs/authentication#scopes).
* **OAuth 2.1** — authorization-code flow with PKCE and dynamic client registration, powering connector-style sign-in for MCP clients and integrations.
* **MCP server** — `https://mcp.nimply.io/mcp` with 16 tools covering channels, posts, media, analytics, and approvals. [Guide](/docs/mcp).
* **Signed webhooks** — HMAC-signed event delivery with retries and a test endpoint. [Guide](/docs/webhooks).
* **Analytics endpoints** — workspace, channel, and post metrics over the API.
* **Approval workflow** — request-approval / approve / reject endpoints with recorded decisions and comments.
* **Bulk post creation** — up to 50 posts per request with per-item results.
## In progress [#in-progress]
* **Zapier directory listing** — the Zapier integration is built; public directory listing is underway.
* **Make directory listing** — same for Make (Custom App today, public listing next).
* **n8n community node** — `@nimply/n8n-nodes-nimply` is built and headed for the community package registry.
## Exploring [#exploring]
No commitments or dates — these are on our radar, roughly ordered by how often they come up:
* **Org-level agency keys** — one credential spanning multiple workspaces for agencies.
* **Third-party app directory** — a public directory of OAuth apps built on Nimply.
* **CSV report exports** — downloadable analytics reports (the JSON [analytics endpoints](/docs/api-reference) already expose the data).
* **Docs in additional languages** — localized versions of this documentation.
* **Inbox API** — programmatic access to the unified inbox.
## Tell us what to build [#tell-us-what-to-build]
The fastest way to move something up this list is to ask for it: reach us at
[nimply.io/contact](https://nimply.io/contact) with what you're building and what's
missing.
# Webhooks (/docs/webhooks)
Webhooks push events to your server the moment they happen — no polling. Register an HTTPS endpoint and Nimply will POST a JSON envelope for every subscribed event.
Requires the `webhooks:manage` scope. Manage endpoints via the [API reference](/docs/api-reference).
## Events [#events]
| Event | Fired when |
| ------------------------- | -------------------------------------------------------------- |
| `post.created` | A post is created (app or API) |
| `post.updated` | A post's content is edited via the API |
| `post.published` | A scheduled post was successfully published |
| `post.failed` | Publishing was attempted and rejected by the platform |
| `post.deleted` | A post is deleted via the API |
| `post.approval_requested` | A draft is sent for approval |
| `post.approved` | An approver accepts a pending post |
| `post.rejected` | An approver rejects a pending post |
| `channel.connected` | A channel is connected to the workspace |
| `channel.disconnected` | A channel is removed from the workspace |
| `lead.created` | A lead is captured (inbox agent, browser extension or by hand) |
| `lead.stage_changed` | A lead moves to another pipeline stage |
| `webhook.test` | You call the test endpoint |
## Payload [#payload]
Every delivery is a POST with this envelope:
```json
{
"id": "evt_56e4a1cc-e2c5-459f-b039-445dfef46796",
"type": "post.published",
"createdAt": "2026-07-05T13:55:31.246Z",
"workspaceId": "d8380224-...",
"data": {
"postId": "7a245d46-...",
"channelId": "3e0b9311-...",
"status": "PUBLISHED",
"publishedAt": "2026-07-05T13:55:31.000Z",
"postUrl": "https://...",
"error": null
}
}
```
Headers: `X-Nimply-Event` (event type), `X-Nimply-Delivery` (event id, stable across retries), `X-Nimply-Signature`.
## Verifying signatures [#verifying-signatures]
Each webhook has a secret (`whsec_...`, returned when you create it). The signature header is:
```
X-Nimply-Signature: t=1783259731,v1=71bead50ec1d78af...
```
`v1` is the hex HMAC-SHA256 of `"{t}.{rawBody}"` using your secret. Verify with a constant-time comparison, and reject timestamps older than a few minutes to prevent replays:
```js
import { createHmac, timingSafeEqual } from "node:crypto";
function verify(rawBody, header, secret) {
const [t, v1] = header.split(",").map((p) => p.split("=")[1]);
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}
```
Compute the HMAC over the **raw request body** — parsing and re-serializing the JSON can change key order and break the signature.
## Delivery & retries [#delivery--retries]
* Respond with any `2xx` within 15 seconds to acknowledge.
* Failed deliveries are retried **5 times with exponential backoff** (\~1 hour total).
* After **10 consecutive failed deliveries**, the endpoint is auto-disabled (`isActive: false`). Fix your endpoint, then re-enable it with `PATCH /v1/webhooks/{id}` — that also resets the failure counter.
* Deliveries can arrive out of order and (rarely) more than once — deduplicate by the envelope `id`.
## Testing [#testing]
`POST /v1/webhooks/{id}/test` sends a `webhook.test` event so you can verify connectivity and your signature check before going live.
# API Reference (/docs/api-reference)
The Nimply API is organized around REST. All endpoints live under
`https://api.nimply.io/v1` and are authenticated with a workspace
[API key](/docs/authentication) sent as a Bearer token.
# Add a link to your page when a video goes live (/docs/examples/add-link-when-video-goes-live)
**Scopes:** `links:read`, `links:write` (plus `webhooks:manage` if you use the
`post.published` webhook instead of a YouTube trigger).
The pattern: something publishes a video → add a **featured link block** at the
top of your link page → **publish** the page. Optionally retire the previous
"latest video" link so the page never grows.
## With the API (Node) [#with-the-api-node]
Triggered by your own code, or by the Nimply [`post.published`](/docs/webhooks)
webhook when the video was scheduled through Nimply:
```js
const API = "https://api.nimply.io";
const headers = {
Authorization: `Bearer ${process.env.NIMPLY_API_KEY}`,
"Content-Type": "application/json",
};
// 1. Find the page (most workspaces have one).
const { data: pages } = await (await fetch(`${API}/v1/link-pages`, { headers })).json();
const page = pages.find((p) => p.status !== "SUSPENDED");
// 2. Retire the previous "latest video" link (tagged by our own convention: icon "youtube").
const full = await (await fetch(`${API}/v1/link-pages/${page.id}`, { headers })).json();
for (const b of full.blocks) {
if (b.type === "LINK" && b.config.icon === "youtube" && b.isActive) {
await fetch(`${API}/v1/link-pages/${page.id}/blocks/${b.id}`, {
method: "PATCH",
headers,
body: JSON.stringify({ isActive: false }),
});
}
}
// 3. Add the new one at the top.
await fetch(`${API}/v1/link-pages/${page.id}/blocks`, {
method: "POST",
headers,
body: JSON.stringify({
type: "LINK",
position: 1, // 0 is usually the social icons row; adjust to taste
config: {
title: "New video: " + video.title,
url: video.url,
icon: "youtube",
style: "featured",
thumbnailUrl: video.thumbnailUrl,
},
}),
});
// 4. Publish — live at nimply.link/ within about a minute.
await fetch(`${API}/v1/link-pages/${page.id}/publish`, { method: "POST", headers });
```
`video` comes from wherever your trigger fires: the `post.published` webhook
payload (`postUrl`), the YouTube Data API, or an RSS feed of the channel.
## With Zapier [#with-zapier]
1. **Trigger:** *YouTube → New Video in Channel* (or *Nimply → Post Published*
filtered to your YouTube channel).
2. **Action:** *Nimply → Add Link Block*. Pick the page, set **Block type** to
`Link`, **Title** to `New video: {{Title}}`, **URL** to the video URL,
**Style** to `featured`, **Position** to `1`, and turn **Publish after
adding** on.
That is the whole Zap. To retire the previous link automatically, add a
*Nimply → Find Link Page* search first and a *Code* step that PATCHes the old
block as in the API example — or simply keep a fixed "Latest video" block and
update it: *Add Link Block* with **Replace block ID** set to that block id
replaces its title and URL instead of adding a new block.
## With n8n [#with-n8n]
* **YouTube Trigger** (or **Nimply Trigger → post.published**) →
**Nimply → Link Page → Add Block** (`type: LINK`, config from the trigger,
`Publish after adding: true`).
To keep one rolling "latest video" block, use **Link Page → Update Block**
with the stored block id instead of Add Block.
## Notes [#notes]
* Position `0` inserts at the very top, above whatever is there; most pages
keep the social-icons row first, so `1` is a good default.
* Every URL is Safe-Browsing checked at publish. A flagged URL blocks the
publish with the block id in the error body.
* Publishing is idempotent: re-running the Zap after a partial failure just
publishes the current draft again.
# Bulk-create posts from a CSV (/docs/examples/bulk-from-csv)
**Scopes:** `posts:write`, plus `posts:publish` if any row schedules.
`POST /v1/posts/bulk` accepts 1–50 items, each shaped exactly like a single
`createPost` body. Items are processed **in order**, and a failing item does **not**
abort the batch — you get a per-item result to check.
## The CSV [#the-csv]
```csv
channelId,content,schedule
123e4567-e89b-12d3-a456-426614174000,Monday motivation 💪,2026-08-03T09:00:00.000Z
123e4567-e89b-12d3-a456-426614174000,Midweek tips 🛠️,2026-08-05T09:00:00.000Z
123e4567-e89b-12d3-a456-426614174000,Friday recap 📋,2026-08-07T09:00:00.000Z
```
## Convert and send (Node) [#convert-and-send-node]
```js
import { readFileSync } from "node:fs";
const rows = readFileSync("calendar.csv", "utf8")
.trim()
.split("\n")
.slice(1) // skip header
.map((line) => {
const [channelId, content, schedule] = line.split(",");
return { channelIds: [channelId], content, schedule };
});
const results = await (
await fetch("https://api.nimply.io/v1/posts/bulk", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.NIMPLY_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": "calendar-import-2026-08-w1",
},
body: JSON.stringify({ posts: rows }),
})
).json();
for (const r of results) {
if (r.success) {
console.log(`row ${r.index}: created ${r.posts.map((p) => p.id).join(", ")}`);
} else {
console.error(`row ${r.index}: FAILED — ${r.error}`);
}
}
```
Or the equivalent curl with an inline body:
```bash
curl -X POST https://api.nimply.io/v1/posts/bulk \
-H "Authorization: Bearer $NIMPLY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: calendar-import-2026-08-w1" \
-d '{
"posts": [
{ "channelIds": ["123e4567-e89b-12d3-a456-426614174000"], "content": "Monday motivation 💪", "schedule": "2026-08-03T09:00:00.000Z" },
{ "channelIds": ["123e4567-e89b-12d3-a456-426614174000"], "content": "Midweek tips 🛠️", "schedule": "2026-08-05T09:00:00.000Z" }
]
}'
```
## The response — check every item [#the-response--check-every-item]
Results come back **in input order**, one per item:
```json
[
{ "index": 0, "success": true, "posts": [{ "id": "7a245d46-…", "status": "SCHEDULED" }] },
{ "index": 1, "success": false, "error": "scheduledAt must be in the future" },
{ "index": 2, "success": true, "posts": [{ "id": "8b356e57-…", "status": "SCHEDULED" }] }
]
```
## Gotchas [#gotchas]
* **A 201 does not mean everything succeeded.** Item 1 above failed while the batch as a whole returned normally — always iterate the results and handle `success: false`.
* Each item can target multiple channels, so `posts` inside a result is an array (one post per channel id).
* Maximum **50 items** per request; split larger calendars into multiple batches.
* Scheduling rules and scopes are identical to single-post creation: `"draft"` is the default, anything else needs `posts:publish`.
* Naive `line.split(",")` breaks on captions containing commas — use a real CSV parser for production imports.
# Carousel post (/docs/examples/carousel-post)
**Scopes:** `media:write`, `posts:write`, `posts:publish`.
There is no separate carousel content type: **multiple media on a `POST` become a
carousel**, and the slides appear in the order of the `mediaIds` array.
## 1. Import each image [#1-import-each-image]
Repeat `POST /v1/media` once per slide and collect the ids:
```bash
for url in \
"https://example.com/images/slide-1.png" \
"https://example.com/images/slide-2.png" \
"https://example.com/images/slide-3.png"; do
curl -s -X POST https://api.nimply.io/v1/media \
-H "Authorization: Bearer $NIMPLY_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"url\": \"$url\"}"
echo
done
```
Each call returns a media object — note down the three `id` values in the order you want
the slides shown.
## 2. Create the post with ordered `mediaIds` [#2-create-the-post-with-ordered-mediaids]
```bash
curl -X POST https://api.nimply.io/v1/posts \
-H "Authorization: Bearer $NIMPLY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: feature-carousel-001" \
-d '{
"channelIds": ["123e4567-e89b-12d3-a456-426614174000"],
"content": "Swipe through the highlights 👉",
"contentType": "POST",
"mediaIds": [
"9f2b1c3d-5a6e-4f70-8b91-2c3d4e5f6a70",
"1b2c3d4e-5f60-4a7b-8c9d-0e1f2a3b4c5d",
"aa11bb22-cc33-4d44-8e55-ff6677889900"
],
"schedule": "2026-08-01T09:00:00.000Z"
}'
```
The returned post echoes `mediaIds` in the same order — that is the slide order.
## Gotchas [#gotchas]
* **Order matters**: `mediaIds` is defined as "media asset ids in display order". Reorder the array to reorder the slides.
* `contentType` stays `"POST"` (it's also the default) — the multiple media are what make it a carousel.
* Media assets are reusable: the same media id can appear in many posts, so you don't need to re-import shared brand assets per post.
# Client approval flow (/docs/examples/client-approval-flow)
**Scopes:** `posts:read`, `posts:write` (plus `posts:publish` if creation also schedules).
Agencies typically split this across two credentials: the **content tool** creates drafts
and requests approval; the **review tool** lists pending posts and records decisions.
Both keys belong to the same workspace.
## 1. Create a draft and request approval [#1-create-a-draft-and-request-approval]
```bash
# Create the draft (schedule can also be set now — it's kept through approval)
curl -X POST https://api.nimply.io/v1/posts \
-H "Authorization: Bearer $NIMPLY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: client-acme-aug-01" \
-d '{
"channelIds": ["123e4567-e89b-12d3-a456-426614174000"],
"content": "Acme summer sale starts Monday ☀️",
"schedule": "2026-08-01T09:00:00.000Z"
}'
# Send it for review
curl -X POST https://api.nimply.io/v1/posts/7a245d46-…/request-approval \
-H "Authorization: Bearer $NIMPLY_API_KEY"
```
The post moves to `PENDING_APPROVAL` and the `post.approval_requested`
[webhook](/docs/webhooks) fires — a good trigger for notifying the reviewer.
## 2. List posts awaiting review [#2-list-posts-awaiting-review]
```bash
curl "https://api.nimply.io/v1/posts?status=PENDING_APPROVAL" \
-H "Authorization: Bearer $NIMPLY_API_KEY"
```
```json
{
"data": [
{
"id": "7a245d46-…",
"channelId": "123e4567-e89b-12d3-a456-426614174000",
"content": "Acme summer sale starts Monday ☀️",
"status": "PENDING_APPROVAL",
"scheduledAt": "2026-08-01T09:00:00.000Z"
}
],
"nextCursor": null
}
```
The list is cursor-paginated — keep passing `?cursor={nextCursor}` until `nextCursor` is `null`.
## 3. Approve — or reject with feedback [#3-approve--or-reject-with-feedback]
```bash
# Approve
curl -X POST https://api.nimply.io/v1/posts/7a245d46-…/approve \
-H "Authorization: Bearer $NIMPLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "comment": "Looks great, ship it" }'
```
```bash
# ...or reject
curl -X POST https://api.nimply.io/v1/posts/7a245d46-…/reject \
-H "Authorization: Bearer $NIMPLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "comment": "Swap the hero image for the blue variant, please" }'
```
* **Approve** → the post returns to `SCHEDULED` if it has a future publish time, otherwise `DRAFT`. Fires `post.approved`.
* **Reject** → the post returns to `DRAFT`. Fires `post.rejected`.
The decision and comment are recorded either way (`comment` is optional).
## Gotchas [#gotchas]
* The state machine is strict: `request-approval` only works on a `DRAFT` (`409` otherwise), and `approve`/`reject` only work on `PENDING_APPROVAL` (`409` otherwise). Handle `409` as "someone else already acted on it".
* Set the publish time **before** requesting approval — an approved post with a future `scheduledAt` goes straight back to `SCHEDULED` and needs no second touch.
* A rejected post lands back in `DRAFT`: fix it with `PATCH /v1/posts/{id}`, then request approval again.
* To drive reviewer notifications, subscribe to `post.approval_requested`, `post.approved`, and `post.rejected` webhook events.
# Create a Reel (/docs/examples/create-a-reel)
**Scopes:** `media:write`, `posts:write`, `posts:publish`.
Setting `"contentType": "REEL"` publishes the post to the platform's short-form video
surface instead of the regular feed.
## 1. Import the video [#1-import-the-video]
```bash
curl -X POST https://api.nimply.io/v1/media \
-H "Authorization: Bearer $NIMPLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/videos/behind-the-scenes.mp4",
"name": "behind-the-scenes.mp4"
}'
```
```json
{
"id": "c4d5e6f7-1a2b-4c3d-9e8f-0a1b2c3d4e5f",
"name": "behind-the-scenes.mp4",
"type": "VIDEO",
"url": "https://…signed…",
"thumbnailUrl": null,
"size": 18874368,
"createdAt": "2026-07-09T10:00:00.000Z"
}
```
Confirm `type` is `VIDEO`. `thumbnailUrl` may still be `null` right after upload —
thumbnails are generated asynchronously.
## 2. Create the post with `contentType: REEL` [#2-create-the-post-with-contenttype-reel]
```bash
curl -X POST https://api.nimply.io/v1/posts \
-H "Authorization: Bearer $NIMPLY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: bts-reel-001" \
-d '{
"channelIds": ["123e4567-e89b-12d3-a456-426614174000"],
"content": "Behind the scenes of our launch 🎬",
"contentType": "REEL",
"mediaIds": ["c4d5e6f7-1a2b-4c3d-9e8f-0a1b2c3d4e5f"],
"schedule": "next_slot"
}'
```
```json
[
{
"id": "7a245d46-…",
"channelId": "123e4567-e89b-12d3-a456-426614174000",
"contentType": "REEL",
"status": "SCHEDULED",
"scheduledAt": "2026-07-09T18:00:00.000Z",
"mediaIds": ["c4d5e6f7-1a2b-4c3d-9e8f-0a1b2c3d4e5f"]
}
]
```
## Gotchas [#gotchas]
* A Reel needs a **video** media asset — attach the `VIDEO` media id, not an image.
* Media import happens by URL: the video must be publicly reachable over http(s). Plan quotas (file size, storage, monthly uploads) apply — an oversized file returns `400`.
* Target a channel type that has a Reels-style format; check your channel's `type` from `GET /v1/channels`.
* Video publishing takes longer than images — watch for `post.published` / `post.failed` [webhooks](/docs/webhooks) rather than assuming success.
# Examples (/docs/examples)
Each recipe is a complete, runnable walkthrough of one task: the exact requests, the
responses you should expect, and the gotchas. They all assume an exported key:
```bash
export NIMPLY_API_KEY="nim_live_4f8a2c…"
```
## Publishing [#publishing]
## Monitoring & workflows [#monitoring--workflows]
## Link pages [#link-pages]
# Pin to a Pinterest board (/docs/examples/pin-to-a-pinterest-board)
**Scopes:** `channels:read`, `media:write`, `posts:write`, `posts:publish`.
Pinterest requires every pin to target a **board**, so pin creation is a two-step flow:
fetch the channel's boards, then create the pin with `POST /v1/posts/pinterest`.
## 1. List the channel's boards [#1-list-the-channels-boards]
```bash
curl https://api.nimply.io/v1/channels/223e4567-e89b-12d3-a456-426614174001/pinterest/boards \
-H "Authorization: Bearer $NIMPLY_API_KEY"
```
```json
[
{ "id": "1022106146619699999", "name": "Product inspiration", "privacy": "PUBLIC", "pinCount": 42 },
{ "id": "1022106146619700123", "name": "Launch assets", "privacy": "SECRET", "pinCount": 7 }
]
```
The channel must be a `PINTEREST` channel (from `GET /v1/channels`); any other type
returns `400`.
## 2. Create the pin [#2-create-the-pin]
```bash
curl -X POST https://api.nimply.io/v1/posts/pinterest \
-H "Authorization: Bearer $NIMPLY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: pin-workspace-inspo-001" \
-d '{
"channelId": "223e4567-e89b-12d3-a456-426614174001",
"boardId": "1022106146619699999",
"mediaIds": ["c4d5e6f7-1a2b-4c3d-9e8f-0a1b2c3d4e5f"],
"title": "Workspace inspiration",
"content": "Our favorite desk setups this year.",
"link": "https://example.com/blog/desk-setups",
"altText": "A tidy desk with a laptop, plant, and warm lamp",
"schedule": "next_slot"
}'
```
```json
{
"id": "7a245d46-…",
"channelId": "223e4567-e89b-12d3-a456-426614174001",
"title": "Workspace inspiration",
"contentType": "POST",
"status": "SCHEDULED",
"scheduledAt": "2026-07-17T09:00:00.000Z",
"mediaIds": ["c4d5e6f7-1a2b-4c3d-9e8f-0a1b2c3d4e5f"]
}
```
## Gotchas [#gotchas]
* `boardId` is **required** — a pin without a board cannot publish, so the API rejects it at request time.
* Up to **5 images** (a carousel) or **1 video** per pin; media must be uploaded first via `POST /v1/media`.
* `link` is where the pin sends people who click through (max 2048 characters); `altText` (max 500) is read by screen readers — both optional but strongly recommended.
* Board ids are stable — cache them if you pin frequently, and re-fetch when the user adds boards in Pinterest.
# Poll until published (/docs/examples/poll-until-published)
**Scopes:** `posts:write`, `posts:publish`, `posts:read`.
"Publish now" is **asynchronous**: the post is queued, so the create response shows it as
`SCHEDULED`, not `PUBLISHED`. To know it actually went live, watch for the terminal
status — `PUBLISHED` or `FAILED`.
Polling works, but subscribing to `post.published` and `post.failed`
[webhooks](/docs/webhooks) tells you the moment it happens, with no request budget
spent. Use polling for scripts and one-offs; use webhooks for anything long-running.
## 1. Create with `"schedule": "now"` [#1-create-with-schedule-now]
```bash
curl -X POST https://api.nimply.io/v1/posts \
-H "Authorization: Bearer $NIMPLY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: hotfix-announcement-001" \
-d '{
"channelIds": ["123e4567-e89b-12d3-a456-426614174000"],
"content": "We just shipped a fix — safe to update now.",
"schedule": "now"
}'
```
```json
[
{ "id": "7a245d46-…", "status": "SCHEDULED", "publishedAt": null }
]
```
## 2. Poll `GET /v1/posts/{id}` [#2-poll-get-v1postsid]
```js
const API = "https://api.nimply.io/v1";
const headers = { Authorization: `Bearer ${process.env.NIMPLY_API_KEY}` };
async function waitForPublish(postId, { intervalMs = 5000, maxAttempts = 24 } = {}) {
for (let i = 0; i < maxAttempts; i++) {
const post = await (await fetch(`${API}/posts/${postId}`, { headers })).json();
if (post.status === "PUBLISHED") return post;
if (post.status === "FAILED") throw new Error(`Publishing failed for ${postId}`);
await new Promise((r) => setTimeout(r, intervalMs));
}
throw new Error(`Timed out waiting for ${postId}`);
}
const post = await waitForPublish("7a245d46-…");
console.log("Live at", post.publishedAt);
```
The same check with curl:
```bash
curl https://api.nimply.io/v1/posts/7a245d46-… \
-H "Authorization: Bearer $NIMPLY_API_KEY"
```
```json
{ "id": "7a245d46-…", "status": "PUBLISHED", "publishedAt": "2026-07-09T13:55:31.000Z" }
```
## Gotchas [#gotchas]
* Poll politely: a few seconds between requests. Rate limits are per key, and every poll counts against them (watch `X-RateLimit-Remaining`).
* With multiple channel ids you get multiple posts — poll **each** post id; one channel can publish while another fails.
* The same pattern applies to `POST /v1/posts/{id}/publish` on an existing draft — its response also returns the post as `SCHEDULED`.
* Cap your attempts. Video posts in particular can take a while to process on the platform side.
# Post to all channels in the next slot (/docs/examples/post-to-all-channels-next-slot)
**Scopes:** `channels:read`, `posts:write`, `posts:publish`.
Each channel in Nimply has a posting schedule (weekday time slots). `"schedule": "next_slot"`
drops the post into the **next free slot of each channel independently** — so one request can
queue Instagram for 13:30 and LinkedIn for 18:00.
## 1. List channels and pick the healthy ones [#1-list-channels-and-pick-the-healthy-ones]
```bash
curl https://api.nimply.io/v1/channels \
-H "Authorization: Bearer $NIMPLY_API_KEY"
```
Keep only channels where `isConnected` is `true` and `tokenStatus` is not
`NEEDS_RECONNECT`. Skip channels with `isQueuePaused: true` too — their scheduled posts
won't go out until the queue is resumed.
## 2. Create one post per channel with `next_slot` [#2-create-one-post-per-channel-with-next_slot]
```bash
curl -X POST https://api.nimply.io/v1/posts \
-H "Authorization: Bearer $NIMPLY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: weekly-update-2026-w28" \
-d '{
"channelIds": [
"123e4567-e89b-12d3-a456-426614174000",
"3e0b9311-aaaa-4bbb-8ccc-000000000001"
],
"content": "Our weekly update is out — highlights inside.",
"schedule": "next_slot"
}'
```
## Both steps in JavaScript [#both-steps-in-javascript]
```js
const API = "https://api.nimply.io/v1";
const headers = {
Authorization: `Bearer ${process.env.NIMPLY_API_KEY}`,
"Content-Type": "application/json",
};
const { data: channels } = await (await fetch(`${API}/channels`, { headers })).json();
const healthy = channels.filter(
(c) => c.isConnected && c.tokenStatus !== "NEEDS_RECONNECT" && !c.isQueuePaused
);
const posts = await (
await fetch(`${API}/posts`, {
method: "POST",
headers: { ...headers, "Idempotency-Key": "weekly-update-2026-w28" },
body: JSON.stringify({
channelIds: healthy.map((c) => c.id),
content: "Our weekly update is out — highlights inside.",
schedule: "next_slot",
}),
})
).json();
for (const p of posts) console.log(p.channelId, p.status, p.scheduledAt);
```
Each returned post is `SCHEDULED` with its own `scheduledAt` — the slot Nimply picked for
that channel.
## Gotchas [#gotchas]
* Slots are configured per channel in the channel's own `timezone`. Inspect them with `GET /v1/channels/{id}/schedule`.
* One post is created **per channel** — you get back an array of independent posts, each with its own id and lifecycle.
* `"next_slot"` requires the `posts:publish` scope, like every `schedule` value other than `"draft"`.
# Post to LinkedIn (/docs/examples/post-to-linkedin)
**Scopes:** `channels:read`, `posts:write`, `posts:publish` (plus `media:write` if you attach media).
LinkedIn posts go through the dedicated `POST /v1/posts/linkedin` endpoint, which adds one
platform option on top of the generic post flow: `visibility`.
## 1. Find your LinkedIn channel [#1-find-your-linkedin-channel]
```bash
curl https://api.nimply.io/v1/channels \
-H "Authorization: Bearer $NIMPLY_API_KEY"
```
```json
[
{
"id": "323e4567-e89b-12d3-a456-426614174002",
"name": "Acme Corp",
"type": "LINKEDIN_PROFILE",
"isConnected": true,
"tokenStatus": "HEALTHY"
}
]
```
Use any channel whose `type` starts with `LINKEDIN`; the endpoint accepts them all.
Any other channel type returns `400`.
## 2. Create the post [#2-create-the-post]
```bash
curl -X POST https://api.nimply.io/v1/posts/linkedin \
-H "Authorization: Bearer $NIMPLY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: li-product-update-001" \
-d '{
"channelId": "323e4567-e89b-12d3-a456-426614174002",
"content": "We just shipped scheduled carousels. Here is what changed and why it took three rewrites.",
"mediaIds": ["c4d5e6f7-1a2b-4c3d-9e8f-0a1b2c3d4e5f"],
"visibility": "PUBLIC",
"schedule": "next_slot"
}'
```
```json
{
"id": "9b356e57-…",
"channelId": "323e4567-e89b-12d3-a456-426614174002",
"contentType": "POST",
"status": "SCHEDULED",
"scheduledAt": "2026-07-23T09:00:00.000Z",
"mediaIds": ["c4d5e6f7-1a2b-4c3d-9e8f-0a1b2c3d4e5f"]
}
```
## Gotchas [#gotchas]
* `content` is capped at **3000 characters** — LinkedIn's own post limit. The API rejects longer text at request time.
* Up to **20 images** or **1 video** per post; media must be uploaded first via `POST /v1/media`. Text-only posts are fine — just omit `mediaIds`.
* `visibility` defaults to `PUBLIC`. `CONNECTIONS` restricts the post to the account's 1st-degree connections and only applies to personal accounts.
* `schedule` works like `createPost` (`next_slot`, an ISO timestamp, or omit to create a draft), and an `Idempotency-Key` header makes retries safe.
# Post to TikTok (/docs/examples/post-to-tiktok)
**Scopes:** `channels:read`, `media:write`, `posts:write`, `posts:publish`.
TikTok requires every post to declare a **privacy level** the account is actually allowed to
use, so posting is a two-step flow: fetch the channel's creator info, then create the post
with `POST /v1/posts/tiktok`.
## 1. Check the channel's creator info [#1-check-the-channels-creator-info]
```bash
curl https://api.nimply.io/v1/channels/423e4567-e89b-12d3-a456-426614174003/tiktok/creator-info \
-H "Authorization: Bearer $NIMPLY_API_KEY"
```
```json
{
"nickname": "nimply.io",
"avatarUrl": "https://…",
"privacyLevelOptions": ["PUBLIC_TO_EVERYONE", "MUTUAL_FOLLOW_FRIENDS", "SELF_ONLY"],
"commentDisabled": false,
"duetDisabled": false,
"stitchDisabled": true,
"maxVideoDurationSec": 600
}
```
The channel must be a TikTok channel (from `GET /v1/channels`); any other type returns `400`.
## 2. Create the post [#2-create-the-post]
```bash
curl -X POST https://api.nimply.io/v1/posts/tiktok \
-H "Authorization: Bearer $NIMPLY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: tt-launch-video-001" \
-d '{
"channelId": "423e4567-e89b-12d3-a456-426614174003",
"mediaIds": ["d5e6f7a8-2b3c-4d5e-af90-1b2c3d4e5f6a"],
"privacyLevel": "PUBLIC_TO_EVERYONE",
"title": "Three rewrites later…",
"content": "How we shipped scheduled carousels #buildinpublic",
"allowComments": true,
"allowDuet": true,
"schedule": "next_slot"
}'
```
```json
{
"id": "8c467f68-…",
"channelId": "423e4567-e89b-12d3-a456-426614174003",
"title": "Three rewrites later…",
"contentType": "POST",
"status": "SCHEDULED",
"scheduledAt": "2026-07-23T09:00:00.000Z",
"mediaIds": ["d5e6f7a8-2b3c-4d5e-af90-1b2c3d4e5f6a"]
}
```
## Gotchas [#gotchas]
* `mediaIds` is **required** — TikTok has no text-only posts. Send **1 video** or up to **35 photos** (a photo-mode post), uploaded first via `POST /v1/media`. Videos must fit within the account's `maxVideoDurationSec`.
* `privacyLevel` is **required** and must be one of the account's `privacyLevelOptions` from step 1 — sending a level the account can't use fails at publish time.
* Comments, Duet, and Stitch are **off by default**; opt in with `allowComments` / `allowDuet` / `allowStitch`. If creator info reports one as disabled for the account (like `stitchDisabled` above), enabling it has no effect. Duet and Stitch apply to video posts only.
* Disclosure toggles: `brandContent` marks a paid third-party partnership, `brandOrganic` marks self-promotion. `brandContent` cannot be combined with `privacyLevel: "SELF_ONLY"` — the API rejects it at request time.
* `title` is capped at 100 characters, the `content` caption at 2200. `schedule` works like `createPost`, and an `Idempotency-Key` header makes retries safe.
# Schedule an image post (/docs/examples/schedule-image-post)
**Scopes:** `media:write`, `posts:write`, `posts:publish` (needed for any `schedule` value other than `"draft"`).
## 1. Import the image [#1-import-the-image]
Give Nimply a publicly reachable URL; it downloads and stores the file:
```bash
curl -X POST https://api.nimply.io/v1/media \
-H "Authorization: Bearer $NIMPLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/images/launch-banner.png",
"name": "launch-banner.png"
}'
```
```json
{
"id": "9f2b1c3d-5a6e-4f70-8b91-2c3d4e5f6a70",
"name": "launch-banner.png",
"type": "IMAGE",
"url": "https://…signed…",
"thumbnailUrl": null,
"size": 245760,
"createdAt": "2026-07-09T10:00:00.000Z"
}
```
## 2. Create the post with an ISO 8601 schedule [#2-create-the-post-with-an-iso-8601-schedule]
Passing a datetime as `schedule` creates *and* schedules in one call:
```bash
curl -X POST https://api.nimply.io/v1/posts \
-H "Authorization: Bearer $NIMPLY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: launch-banner-2026-08-01" \
-d '{
"channelIds": ["123e4567-e89b-12d3-a456-426614174000"],
"content": "Launching something new today 🚀",
"mediaIds": ["9f2b1c3d-5a6e-4f70-8b91-2c3d4e5f6a70"],
"schedule": "2026-08-01T09:00:00.000Z"
}'
```
The response is an **array** — one post per channel id:
```json
[
{
"id": "7a245d46-…",
"channelId": "123e4567-e89b-12d3-a456-426614174000",
"content": "Launching something new today 🚀",
"contentType": "POST",
"status": "SCHEDULED",
"scheduledAt": "2026-08-01T09:00:00.000Z",
"publishedAt": null,
"mediaIds": ["9f2b1c3d-5a6e-4f70-8b91-2c3d4e5f6a70"]
}
]
```
## Gotchas [#gotchas]
* The schedule time must be **in the future**; a past datetime fails validation (`422`).
* The response is always an array, even with a single channel id.
* Always send an `Idempotency-Key` on `POST` — a timed-out retry then returns the original result instead of scheduling a duplicate.
* To confirm it went live, subscribe to `post.published` / `post.failed` [webhooks](/docs/webhooks) or [poll the post](/docs/examples/poll-until-published).
# Upload a YouTube video (/docs/examples/upload-a-youtube-video)
**Scopes:** `media:write`, `posts:write`, `posts:publish`.
`POST /v1/posts/youtube` is the platform-specific create endpoint for YouTube: it accepts
every video option the Nimply app exposes and rejects bad requests up front (missing
title, non-video media, or a channel that isn't a YouTube channel).
## 1. Import the video [#1-import-the-video]
```bash
curl -X POST https://api.nimply.io/v1/media \
-H "Authorization: Bearer $NIMPLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/videos/launch-recap.mp4",
"name": "launch-recap.mp4"
}'
```
Confirm the returned `type` is `VIDEO` — the YouTube endpoint requires a video asset and
returns `400` otherwise.
## 2. Create the video post [#2-create-the-video-post]
```bash
curl -X POST https://api.nimply.io/v1/posts/youtube \
-H "Authorization: Bearer $NIMPLY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: yt-launch-recap-001" \
-d '{
"channelId": "123e4567-e89b-12d3-a456-426614174000",
"title": "How we built our launch in 7 days",
"description": "A behind-the-scenes look at the sprint.",
"mediaId": "c4d5e6f7-1a2b-4c3d-9e8f-0a1b2c3d4e5f",
"videoType": "video",
"category": "28",
"tags": ["launch", "product demo"],
"visibility": "unlisted",
"notifySubscribers": false,
"thumbnailMediaId": "9b8a7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"schedule": "2026-08-01T15:00:00.000Z"
}'
```
`thumbnailMediaId` is optional: it is the id of an image you imported with `POST /v1/media`,
the same way as the video in step 1.
```json
{
"id": "7a245d46-…",
"channelId": "123e4567-e89b-12d3-a456-426614174000",
"title": "How we built our launch in 7 days",
"contentType": "VIDEO",
"status": "SCHEDULED",
"scheduledAt": "2026-08-01T15:00:00.000Z",
"mediaIds": ["c4d5e6f7-1a2b-4c3d-9e8f-0a1b2c3d4e5f"],
"thumbnailMediaId": "9b8a7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"coverTimestampMs": null
}
```
Unlike the generic `POST /v1/posts` (which returns an array — one post per channel), the
platform endpoints target one channel and return a single post object.
## Options reference [#options-reference]
| Field | Values | Default |
| ------------------- | ----------------------------------------------------------------------- | ---------------------------- |
| `videoType` | `video`, `short` | `video` |
| `category` | YouTube category id (`1`, `2`, `10`, `15`, `17`, `19`, `20`, `22`–`28`) | `22` (People & Blogs) |
| `tags` | list of keywords, up to 500 characters together | none |
| `visibility` | `public`, `unlisted`, `private` | `public` |
| `license` | `youtube` (standard), `creativeCommon` | `youtube` |
| `notifySubscribers` | boolean | `true` |
| `allowEmbedding` | boolean | `true` |
| `madeForKids` | boolean (COPPA self-declaration) | `false` |
| `thumbnailMediaId` | id of an image media asset | none (YouTube picks a frame) |
## Gotchas [#gotchas]
* `title` is **required** — YouTube refuses untitled uploads, so the API refuses them too (max 100 characters).
* Use `"videoType": "short"` to publish a Short; the same options apply.
* `madeForKids` is a legal declaration (COPPA) — set it deliberately, not by default.
* A custom thumbnail is set right after the video publishes. YouTube only accepts custom thumbnails on verified channels; if it refuses the image, the video still publishes with YouTube's own frame.
* Video publishing takes longer than images — watch for `post.published` / `post.failed` [webhooks](/docs/webhooks) rather than assuming success.
# Upload a file as raw bytes (/docs/examples/upload-binary-file)
When your file isn't hosted at a public URL (or it's a large video), upload the bytes directly. Three steps: get a presigned URL, PUT the bytes, complete.
Requires the `media:write` scope.
## 1. Start the upload [#1-start-the-upload]
Declare the name, MIME type, and size — quotas are checked now, before any bytes move:
```bash
curl -X POST https://api.nimply.io/v1/media/uploads \
-H "Authorization: Bearer nim_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"fileName": "launch-video.mp4",
"contentType": "video/mp4",
"sizeBytes": 10485760
}'
```
```json
{
"mediaId": "5c4d37cf-…",
"uploadUrl": "https://…r2.cloudflarestorage.com/…?X-Amz-Signature=…",
"method": "PUT",
"headers": { "Content-Type": "video/mp4" },
"expiresInSeconds": 3600
}
```
## 2. PUT the bytes [#2-put-the-bytes]
Send the raw file to `uploadUrl` with **exactly** the Content-Type you declared — it's part of the URL's signature:
```bash
curl -X PUT "" \
-H "Content-Type: video/mp4" \
--data-binary @launch-video.mp4
```
No `Authorization` header here — the URL itself is the credential. It expires after an hour.
## 3. Complete [#3-complete]
```bash
curl -X POST https://api.nimply.io/v1/media/uploads//complete \
-H "Authorization: Bearer nim_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{ "sizeBytes": 10485760, "width": 1920, "height": 1080 }'
```
The response is the finished media asset — use its `id` in a post's `mediaIds`. Thumbnails generate in the background.
## All together in JavaScript [#all-together-in-javascript]
```js
const API = "https://api.nimply.io";
const KEY = process.env.NIMPLY_API_KEY;
async function uploadFile(bytes, fileName, contentType) {
const ticket = await fetch(`${API}/v1/media/uploads`, {
method: "POST",
headers: { Authorization: `Bearer ${KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({ fileName, contentType, sizeBytes: bytes.byteLength }),
}).then((r) => r.json());
await fetch(ticket.uploadUrl, {
method: "PUT",
headers: ticket.headers,
body: bytes,
});
return fetch(`${API}/v1/media/uploads/${ticket.mediaId}/complete`, {
method: "POST",
headers: { Authorization: `Bearer ${KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({ sizeBytes: bytes.byteLength }),
}).then((r) => r.json());
}
```
## Gotchas [#gotchas]
* **Don't skip complete** — until then the asset has a placeholder size, consumes no quota, and shouldn't be attached to posts.
* A mismatched `Content-Type` on the PUT gets a `403 SignatureDoesNotMatch` from storage.
* Already have the file at a public URL? [`POST /v1/media`](/docs/examples/schedule-image-post) is one call instead of three.
# Webhook receiver (/docs/examples/webhook-receiver)
**Scopes:** `webhooks:manage` (to register the endpoint).
This recipe builds the smallest correct receiver: raw-body capture, `X-Nimply-Signature`
verification, fast `2xx` acknowledgement, and deduplication. The full event catalogue and
retry behavior live in the [webhooks guide](/docs/webhooks).
## 1. The server [#1-the-server]
```js
import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";
const app = express();
const SECRET = process.env.NIMPLY_WEBHOOK_SECRET; // whsec_..., returned on webhook creation
function verify(rawBody, header, secret) {
const [t, v1] = header.split(",").map((p) => p.split("=")[1]);
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}
const seen = new Set(); // use a persistent store in production
app.post("/hooks/nimply", express.raw({ type: "application/json" }), (req, res) => {
const signature = req.get("X-Nimply-Signature");
if (!signature || !verify(req.body, signature, SECRET)) {
return res.status(401).send("invalid signature");
}
const event = JSON.parse(req.body);
// Deliveries can repeat — dedupe by the envelope id
if (seen.has(event.id)) return res.sendStatus(200);
seen.add(event.id);
// Acknowledge fast, process after
res.sendStatus(200);
switch (event.type) {
case "post.published":
console.log("live:", event.data.postId, event.data.postUrl);
break;
case "post.failed":
console.error("failed:", event.data.postId, event.data.error);
break;
default:
console.log("event:", event.type);
}
});
app.listen(3000);
```
Two details are load-bearing:
* **`express.raw`, not `express.json`** — the `v1` value is the hex HMAC-SHA256 of `"{t}.{rawBody}"` using your secret. Parsing and re-serializing the JSON can change key order and break the signature, so the HMAC must be computed over the raw bytes.
* **Timestamp check** — rejecting `t` older than \~5 minutes prevents replay of captured deliveries. Compare with `timingSafeEqual`, never `===`.
## 2. Register the endpoint [#2-register-the-endpoint]
```bash
curl -X POST https://api.nimply.io/v1/webhooks \
-H "Authorization: Bearer $NIMPLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Publishing monitor",
"url": "https://example.com/hooks/nimply",
"events": ["post.published", "post.failed"]
}'
```
The response includes the signing `secret` (`whsec_...`) — store it as
`NIMPLY_WEBHOOK_SECRET`. It is per-webhook, not per-workspace.
## 3. Test it [#3-test-it]
```bash
curl -X POST https://api.nimply.io/v1/webhooks/{webhookId}/test \
-H "Authorization: Bearer $NIMPLY_API_KEY"
```
Your server should log a `webhook.test` event and return `200`. If it logs
"invalid signature" instead, the usual culprit is a JSON body parser mounted before the
raw handler.
## Gotchas [#gotchas]
* Respond `2xx` **within 15 seconds** — do slow work after acknowledging, not before.
* Failed deliveries are retried 5 times with exponential backoff; after 10 consecutive failures the endpoint is auto-disabled (`isActive: false`). Re-enable with `PATCH /v1/webhooks/{id}` once fixed.
* Deliveries can arrive **out of order and more than once** — the `X-Nimply-Delivery` header (the event id) is stable across retries, so dedupe on it or on the envelope `id`.
# Any MCP client (/docs/integrations/any-mcp-client)
Nimply's MCP server is a standard remote server. Any client that implements the MCP spec can connect — including ones that don't exist yet.
## The three connection shapes [#the-three-connection-shapes]
**1. OAuth-capable clients** (connector-style UIs): just give them the URL —
```
https://mcp.nimply.io/mcp
```
The server advertises its authorization server via RFC 9728 protected-resource metadata; the client discovers it, registers itself, and walks you through Nimply's consent screen. Nothing to copy.
**2. Header-capable clients** (config-file tools): same URL plus one header —
```
Authorization: Bearer nim_live_YOUR_KEY
```
Create the key in Nimply → **Settings → Developers**.
**3. Stdio-only clients** (no remote support): bridge with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote):
```bash
npx -y mcp-remote https://mcp.nimply.io/mcp \
--header "Authorization: Bearer nim_live_YOUR_KEY"
```
Configure that command wherever the client expects a local MCP server. Without the `--header`, `mcp-remote` runs Nimply's OAuth flow in your browser instead.
## Verify from the terminal [#verify-from-the-terminal]
```bash
curl -s https://mcp.nimply.io/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "Authorization: Bearer nim_live_YOUR_KEY" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```
A tool list means auth and transport are fine — any remaining trouble is client configuration.
## Details [#details]
* Transport: Streamable HTTP (MCP spec 2025-06-18); no SSE-only legacy endpoint.
* Tools: listed in the [MCP overview](/docs/mcp).
* Rate limits and permissions are those of the credential — see [Authentication](/docs/authentication).
# Browser extension (/docs/integrations/browser-extension)
Nimply Sidekick is Nimply's own browser extension. It puts a side panel next to
the page you are reading so you can keep a post, write a post from it, or get a
reply drafted, without leaving the tab.
It runs on Chrome, Edge, Opera, Brave, Vivaldi and Arc from one build, plus
Firefox and Safari.
## What it does [#what-it-does]
| Action | What happens |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Keep this post | Saves the post, comment or article to an Ideas board with its author, text, images, link and the engagement it had at that moment |
| Write a post from this | Sends the page or your selected text to the Content Repurposer or LinkedIn Ghostwriter, then opens the result in your composer as a draft |
| Help me reply | Reads the comment thread you are looking at and suggests three replies in your brand voice, which you copy and send yourself |
| Save image | Imports an image into your media library with the page it came from recorded |
| Save as lead | Records a commenter's name, profile link and comment as a lead for the Sales and Lead agent |
## What it will not do [#what-it-will-not-do]
Sidekick never acts on a social platform. It does not like, comment, follow,
connect, or send messages, and it never types into a page on your behalf.
Drafted replies go to your clipboard.
It also never reads a page in the background. A capture only happens when you
click the Nimply icon, use the right-click menu, or press the keyboard
shortcut, and it reads one post at a time rather than a feed.
The panel is a browser side panel. Sidekick adds nothing to the pages you
visit, which is what most platform terms prohibit.
## How it reaches your workspace [#how-it-reaches-your-workspace]
Sidekick signs in with OAuth 2.1 and PKCE against your Nimply account, the same
authorization server the MCP server and other connectors use. The token is
bound to one workspace, chosen on the consent screen. Connecting a second
workspace is a second authorization; both stay signed in and you switch between
them in the panel.
Requested scopes:
```text
workspace:read channels:read posts:write media:write
ideas:read ideas:write ext:draft ext:reply leads:write
```
Sidekick never requests `posts:publish`. Anything it creates is a draft that
goes through your normal approval and scheduling flow.
You can see and revoke the connection at any time under
**Settings → Developers → Connected apps**, the same place other OAuth
connections live.
## Credits [#credits]
Saving a post, importing an image and saving a lead do not cost AI credits.
Drafting a post and suggesting replies use the same AI credits as the studio
and the inbox. The panel shows the cost before it runs and your remaining
balance after.
## Ideas cards from a capture [#ideas-cards-from-a-capture]
A saved post becomes a card on an Ideas board with a link attachment holding
the source URL, platform, author name and profile link, the post text, media
URLs and the engagement snapshot. Trend Scout and the Content Repurposer read
those cards, so anything you keep is available to your agents.
The `ideas:read` and `ideas:write` scopes are part of the public API. The
`ext:*` scopes are first-party only and are not available to third-party
OAuth clients or API keys.
## Privacy [#privacy]
The extension reads the post under your click and nothing else. It does not
touch cookies or your session, does not track browsing, and stores only your
sign-in token and preferences on your device. Full detail, including how
someone whose public post you saved can ask for removal, is in the
[browser extension privacy policy](https://nimply.io/legal/browser-extension).
# Canva (/docs/integrations/canva)
## What it does [#what-it-does]
Link your Canva account and you can browse, search, and import your designs from inside Nimply - each import lands in the media library as a ready-to-post image. Imported assets remember where they came from, so you can jump back to Canva to edit and pull the new version with one click.
## Connect [#connect]
The connection is **personal**: each team member links their own Canva account and sees their own designs.
1. Go to **Settings → Integrations → Canva** and click **Connect Canva** (any role except viewer).
2. Approve on Canva's consent screen — Nimply requests **read-only** access (list designs, export them). Your designs are never modified.
3. Done — Canva now appears as a source in the media import button.
## Import a design [#import-a-design]
1. In the media library, the `/media` page, or the post composer, open the **import-source button** and pick **Canva**.
2. Search or browse your designs and click one — Nimply exports it as **PNG** and imports it.
3. **Multi-page designs become one image per page** (up to 10 pages per import) — handy for carousels.
## Edit in Canva & re-import [#edit-in-canva--re-import]
On an imported asset's page you'll find two extra actions:
* **Edit in Canva** — opens the original design in Canva's editor. When you're done, Canva's **"Return to Nimply"** button brings you straight back to the asset.
* **Re-import latest** — pulls the design's current version as a **new** asset. The original is untouched, so posts already using it keep rendering exactly what was approved; swap the new version in wherever you want it.
## Troubleshooting [#troubleshooting]
* **"Your Canva connection expired"** — reconnect from Settings → Integrations → Canva. This happens if access was revoked on Canva's side or the connection sat unused past its refresh window.
* **Export fails for a design** — very large or unusual designs can time out; try again, or export manually from Canva and upload.
* **Disconnecting** — removes Nimply's access to your Canva account; already-imported assets stay in the media library.
# ChatGPT (/docs/integrations/chatgpt)
Draft, schedule, and analyze your social content from a ChatGPT conversation.
## Connect [#connect]
Custom connectors require a plan with connector support and **developer mode** enabled (Settings → Connectors → Advanced).
1. Open **Settings → Connectors → Create** (or **Add custom connector**).
2. Enter the MCP server URL:
```
https://mcp.nimply.io/mcp
```
3. Choose **OAuth** when asked about authentication. ChatGPT discovers Nimply's authorization server automatically.
4. Log in to Nimply, pick the workspace, review permissions, and click **Allow access**.
5. Enable the connector in a chat (some plans require picking it under Tools).
## Try it [#try-it]
* *"Plan a 5-post content series about our product launch and save them as drafts in Nimply."*
* *"What's my total follower count across channels, and how did engagement trend this month?"*
## Troubleshooting [#troubleshooting]
* **Connector option missing** — developer mode isn't enabled, or your plan doesn't include custom connectors.
* **Authorization loop** — make sure third-party cookies aren't blocked for the login window, then reconnect.
* **Tool calls denied** — the approved permission set doesn't cover the action; remove the connector and reconnect approving the fuller set.
# claude.ai (/docs/integrations/claude-ai)
Manage your social media by chatting with Claude on the web: draft a week of posts, schedule them into your best time slots, check what performed.
## Connect [#connect]
1. In claude.ai, open **Settings → Connectors** and choose **Add custom connector**.
2. Enter the server URL:
```
https://mcp.nimply.io/mcp
```
3. Claude opens Nimply's authorization page. Log in, **choose the workspace** the connector may use, review the permissions, and click **Allow access**.
4. Back in claude.ai, enable the Nimply connector for your chat.
No API key is involved — the OAuth flow issues a scoped token that you can revoke at any time.
## Try it [#try-it]
* *"What channels do I have connected in Nimply, and are any of them unhealthy?"*
* *"Draft five posts about our summer sale and schedule them into the next free slots."*
* *"Which of my posts got the most engagement in the last 30 days?"*
## Troubleshooting [#troubleshooting]
* **The authorization page never appears** — your browser may be blocking the popup; allow popups for claude.ai and retry.
* **"You need OWNER or ADMIN role"** — only workspace owners/admins can authorize apps. Ask an admin to connect, or have your role upgraded.
* **Claude says a tool call was denied** — the granted permissions don't cover that action (for example, publishing needs the publish permission). Reconnect and approve the fuller permission set.
All available tools are listed in the [MCP overview](/docs/mcp).
# Claude Code (/docs/integrations/claude-code)
Let Claude Code schedule your release announcements, post changelogs, or pull engagement numbers — right from the terminal.
## Connect [#connect]
With an API key (create one in Nimply → **Settings → Developers**):
```bash
claude mcp add --transport http nimply https://mcp.nimply.io/mcp \
--header "Authorization: Bearer nim_live_YOUR_KEY"
```
Or without a key, using OAuth — add the server and authenticate when prompted:
```bash
claude mcp add --transport http nimply https://mcp.nimply.io/mcp
# then inside Claude Code:
/mcp # → select nimply → Authenticate
```
Use `--scope project` to share the server (without the key) via `.mcp.json` in your repo, or `--scope user` to have it in every project.
## Try it [#try-it]
* *"Ship notes for v2.3 are in CHANGELOG.md — draft a launch post from them and schedule it for tomorrow 10am on LinkedIn."*
* *"Check nimply for any FAILED posts this week and tell me the errors."*
## Troubleshooting [#troubleshooting]
* **`/mcp` shows the server as failed** — check the URL and header spelling; run `claude mcp get nimply` to inspect the config.
* **403 with a scope name in the message** — your key lacks that permission; create a key with the needed scopes and re-add.
# Claude Desktop (/docs/integrations/claude-desktop)
Everything the claude.ai connector does, on your desktop.
## Option A — Connector (OAuth, recommended) [#option-a--connector-oauth-recommended]
1. Open **Settings → Connectors → Add custom connector**.
2. Enter `https://mcp.nimply.io/mcp`.
3. Log in to Nimply in the browser window that opens, pick a workspace, and click **Allow access**.
## Option B — Config file (API key) [#option-b--config-file-api-key]
If you prefer file-based configuration, add Nimply to `claude_desktop_config.json` (**Settings → Developer → Edit Config**):
```json
{
"mcpServers": {
"nimply": {
"type": "http",
"url": "https://mcp.nimply.io/mcp",
"headers": {
"Authorization": "Bearer nim_live_YOUR_KEY"
}
}
}
}
```
Create the key in Nimply under **Settings → Developers** ([scopes explained here](/docs/authentication)), then restart Claude Desktop.
## Try it [#try-it]
* *"Upload this image URL to Nimply and schedule it as an Instagram post for Friday 9am."*
* *"List everything scheduled this week and move Thursday's post to Saturday."*
## Troubleshooting [#troubleshooting]
* **Tools don't appear after editing the config** — fully quit and reopen Claude Desktop; config is read at startup.
* **401 errors** — the key was revoked, expired, or mistyped. Keys always start with `nim_live_`.
# Codex CLI (/docs/integrations/codex-cli)
## Connect [#connect]
Codex CLI configures MCP servers in `~/.codex/config.toml`. The most reliable way to attach a remote HTTP server with an auth header is the standard `mcp-remote` bridge:
```toml
[mcp_servers.nimply]
command = "npx"
args = [
"-y", "mcp-remote",
"https://mcp.nimply.io/mcp",
"--header", "Authorization: Bearer nim_live_YOUR_KEY"
]
```
Create the key in Nimply → **Settings → Developers**. Restart Codex; the Nimply tools appear in the session's tool list.
If your Codex version supports native remote MCP servers (`url` field), you can skip the bridge:
```toml
[mcp_servers.nimply]
url = "https://mcp.nimply.io/mcp"
http_headers = { "Authorization" = "Bearer nim_live_YOUR_KEY" }
```
## Try it [#try-it]
* *"Use nimply to draft a post about this repo's new release and save it as a draft."*
## Troubleshooting [#troubleshooting]
* **Bridge fails to start** — `npx mcp-remote` needs Node 18+; run the command manually to see the error.
* **Tools not listed** — check `codex mcp list` (or the equivalent in your version) for the server status.
# Cursor (/docs/integrations/cursor)
Give Cursor's agent access to your posting queue — useful for shipping release posts alongside code, or wiring Nimply calls while you build against the API.
## Connect [#connect]
1. Create an API key in Nimply → **Settings → Developers**.
2. Open **Cursor Settings → MCP → Add new MCP server**, or edit the config file directly — `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` globally):
```json
{
"mcpServers": {
"nimply": {
"url": "https://mcp.nimply.io/mcp",
"headers": {
"Authorization": "Bearer nim_live_YOUR_KEY"
}
}
}
}
```
3. Nimply appears in the MCP list with a green dot and its tools listed.
Don't commit a config containing your key — use the global file, or keep the project file untracked.
## Try it [#try-it]
* *"Use nimply to list my connected channels."*
* *"Draft a post announcing the feature in this PR and schedule it for the next free slot."*
## Troubleshooting [#troubleshooting]
* **Red dot / no tools** — usually a typo in the URL or header. Toggle the server off/on after fixing.
* **401** — key revoked or mis-pasted; it must start with `nim_live_`.
# Gemini CLI (/docs/integrations/gemini-cli)
## Connect [#connect]
1. Create an API key in Nimply → **Settings → Developers**.
2. Add Nimply to `~/.gemini/settings.json` (or the project's `.gemini/settings.json`):
```json
{
"mcpServers": {
"nimply": {
"httpUrl": "https://mcp.nimply.io/mcp",
"headers": {
"Authorization": "Bearer nim_live_YOUR_KEY"
}
}
}
}
```
3. Restart the CLI and run `/mcp` to confirm the server is connected and its tools are listed.
## Try it [#try-it]
* *"Use nimply to list my channels and this month's workspace analytics."*
## Troubleshooting [#troubleshooting]
* **Server shows disconnected** — verify the URL uses `httpUrl` (not `url`, which older versions treat as SSE).
* **401** — the key was revoked or mistyped; keys start with `nim_live_`.
# Grok (/docs/integrations/grok)
## Connect [#connect]
Grok supports custom MCP connectors, and Nimply's MCP server works with them out of the box:
1. Go to [grok.com/connectors](https://grok.com/connectors).
2. Click **New Connector** → **Custom**.
3. Enter the server URL:
```
https://mcp.nimply.io/mcp
```
4. Complete the authentication step — you'll be redirected to Nimply to log in, pick a workspace, and approve permissions (standard OAuth, nothing to copy).
Once connected, the Nimply tools are available in your Grok conversations alongside the built-in connectors.
For **Grok Business and Enterprise**, a team admin must provision the connector first before members can use it.
## Grok Build plugin [#grok-build-plugin]
For the Grok Build CLI there is an official Nimply plugin ([github.com/nimply/grok-plugin](https://github.com/nimply/grok-plugin)) that bundles the MCP server with a skill teaching Grok the Nimply workflow. It is submitted to the [xAI plugin marketplace](https://github.com/xai-org/plugin-marketplace); once listed, install it with:
```bash
grok plugin install nimply --trust
```
Until then, clone the repo and load it directly:
```bash
git clone https://github.com/nimply/grok-plugin.git
grok --plugin-dir ./grok-plugin
```
On first use Grok opens Nimply's authorization page (or press `i` on the server in the `/mcps` modal). Sign in, choose a workspace, approve the permissions.
## Grok API & Grok Build (manual) [#grok-api--grok-build-manual]
xAI also supports remote MCP tools in its API (native SDK, OpenAI-compatible Responses API, and the Voice Agent API) and in the Grok Build CLI. Point them at the same server URL with an API-key header (`Authorization: Bearer nim_live_...`, created in Nimply → **Settings → Developers**) — the pattern in [Any MCP client](/docs/integrations/any-mcp-client) applies unchanged.
## Try it [#try-it]
* *"List my Nimply channels and draft a post announcing tomorrow's livestream for each."*
* *"How did last week's posts perform? Queue a follow-up on the best one."*
## Troubleshooting [#troubleshooting]
* **Connector fails to add** — the server must be reachable from the internet; `https://mcp.nimply.io/mcp` is public, so double-check the URL was entered exactly (including the `/mcp` path).
* **Authentication loop** — make sure you complete the workspace selection step in the Nimply consent screen; the connector is scoped to that one workspace.
* **Tools missing on a team plan** — Business/Enterprise workspaces need an admin to provision the connector before it appears for members.
# Integrations (/docs/integrations)
Nimply connects to anything that speaks [MCP](/docs/mcp) — plus the major no-code platforms via our API and webhooks. Pick your tool for a step-by-step guide:
## AI assistants [#ai-assistants]
| Platform | Auth | Guide |
| --------------- | ----------------------------------- | ----------------------------------------------------------- |
| claude.ai (web) | OAuth — click and approve | [Connect claude.ai](/docs/integrations/claude-ai) |
| Claude Desktop | OAuth or API key | [Connect Claude Desktop](/docs/integrations/claude-desktop) |
| ChatGPT | OAuth — connectors / developer mode | [Connect ChatGPT](/docs/integrations/chatgpt) |
| Grok | OAuth — custom connector | [Connect Grok](/docs/integrations/grok) |
| Perplexity | API key | [Connect Perplexity](/docs/integrations/perplexity) |
## IDEs & CLIs [#ides--clis]
| Tool | Auth | Guide |
| ----------------- | -------------------- | ----------------------------------------------------- |
| Claude Code | OAuth or API key | [Connect Claude Code](/docs/integrations/claude-code) |
| Cursor | API key | [Connect Cursor](/docs/integrations/cursor) |
| VS Code (Copilot) | API key | [Connect VS Code](/docs/integrations/vs-code) |
| Windsurf | API key | [Connect Windsurf](/docs/integrations/windsurf) |
| Codex CLI | API key (via bridge) | [Connect Codex CLI](/docs/integrations/codex-cli) |
| Gemini CLI | API key | [Connect Gemini CLI](/docs/integrations/gemini-cli) |
| OpenClaw | API key | [Connect OpenClaw](/docs/integrations/openclaw) |
| Raycast | API key | [Connect Raycast](/docs/integrations/raycast) |
| Anything else | Either | [Any MCP client](/docs/integrations/any-mcp-client) |
## No-code platforms [#no-code-platforms]
| Platform | How it connects | Guide |
| ------------------------------------------------------------------------------------ | -------------------------------------- | --------------------------------------------------- |
|
Zapier | OAuth app — triggers & actions | [Use Nimply with Zapier](/docs/integrations/zapier) |
|
Make | OAuth app — instant triggers & modules | [Use Nimply with Make](/docs/integrations/make) |
|
n8n | Community node or HTTP nodes — API key | [Use Nimply with n8n](/docs/integrations/n8n) |
## Workspace integrations [#workspace-integrations]
Built into the Nimply app — connected from **Settings → Integrations**, no credentials to manage:
| Integration | What it does | Guide |
| ------------------------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------- |
| Slack | Publish/failure alerts + approvals with buttons | [Slack](/docs/integrations/slack) |
| Telegram | Alerts, one-tap approvals, interactive bot & drafts | [Telegram](/docs/integrations/telegram) |
| WhatsApp Business | Customer chats in the unified inbox, agents reply inside the 24-hour window (inbox only) | [WhatsApp](/docs/integrations/whatsapp) |
| Canva | Import designs; edit-and-reimport round trip | [Canva](/docs/integrations/canva) |
| Drive, OneDrive, Dropbox, Google Photos, Unsplash | Import media straight into the library | [Media imports](/docs/integrations/media-imports) |
## The two credentials [#the-two-credentials]
* **OAuth** — you click Connect, log in to Nimply, pick a workspace, approve permissions. Best for consumer apps; nothing to copy.
* **API key** — created in Nimply under **Settings → Developers**, pasted into a config file as `Authorization: Bearer nim_live_...`. Best for tools configured by file. See [Authentication](/docs/authentication) for scopes.
Either way, the connected tool can only do what the granted permissions allow, in the one workspace the credential belongs to — and you can revoke it at any time.
# Make (/docs/integrations/make)
The Nimply app for Make (formerly Integromat) brings your queue into visual scenarios.
> **Availability:** the app is going through Make's review process. Until it's listed, you can use Make's generic **HTTP** module with an [API key](/docs/authentication) and **Custom webhook** module with [Nimply webhooks](/docs/webhooks) — everything on this page is possible that way too.
## Modules [#modules]
* **Watch Events** (instant trigger) — fires on post published/failed/created/updated/deleted, approvals, and channel events; registers a Nimply webhook automatically.
* **Create a Post** — channels picked from a live dropdown; draft / next slot / now / at a time.
* **Create a YouTube Video / TikTok Post / Pinterest Pin / LinkedIn Post** — platform-specific modules with the full option set: YouTube category/visibility/license, TikTok privacy level (loaded from the account) and disclosure toggles, Pinterest board dropdown with link and alt text, LinkedIn visibility.
* **Update a Post / Schedule a Post** — edit content/title, or set/change the publish time.
* **Unschedule a Post** — moves a scheduled post back to draft and clears its publish time.
* **Upload Media from URL** — returns a media ID to attach to posts.
* **Upload Media (Binary)** — uploads file data from a previous module via a presigned URL.
* **List Channels** — for routing and filters.
* **Add Link Block / Publish Link Page** — put a link, product, coupon, countdown or FAQ on your nimply.link page and publish it; **List Link Pages** powers the page dropdown.
Files from other Make modules usually arrive as URLs, which **Upload Media from URL** accepts directly. For true binary data, the app includes **Upload Media (Binary)** — map the file data, name, and MIME type and it handles the presigned flow internally.
## Connect [#connect]
1. Add any Nimply module to a scenario and click **Create a connection**.
2. Log in to Nimply, pick the workspace, and click **Allow access**.
## Starter blueprint [#starter-blueprint]
A minimal scenario with the HTTP module pre-configured for creating a draft post — works today, no waiting for the directory listing:
## Scenario ideas [#scenario-ideas]
* Airtable content calendar → **Create a Post** at each row's publish date.
* **Watch Events: post.failed** → email the account manager with the error and post link.
* Form submission → **Upload Media** → **Create a Post** as a draft for review.
## Troubleshooting [#troubleshooting]
* **Webhook trigger shows no data** — run the scenario once with "Run once" and fire a [test delivery](/docs/webhooks#testing) to give Make a sample payload.
* **Connection fails** — the OWNER or ADMIN role is required to authorize apps.
# Media imports (/docs/integrations/media-imports)
Nimply's media library, `/media` page, and post composer share an **import-source button**: pick a source once and it stays your default; the dropdown switches between sources. All of them respect your plan's storage and upload quotas, and none of them require setup in Nimply's settings — you authorize each pick directly with the provider.
## Google Drive [#google-drive]
Click **Import from Google Drive**, sign in with Google, and pick images or videos in the Drive window (multi-select supported). Nimply can only read the specific files you pick — never your whole Drive (Google's `drive.file` scope). Transfers run **directly from your browser to Nimply's storage**; file contents never pass through our servers.
## OneDrive [#onedrive]
Same flow with Microsoft's file picker — sign in with a Microsoft account, pick photos/videos, and they upload straight from your browser. Only the files you pick are ever accessible; no account connection is stored.
## Dropbox [#dropbox]
Dropbox's Chooser popup: pick images or videos and they import via time-limited download links, browser-to-storage. Nothing is stored about your Dropbox account.
## Google Photos [#google-photos]
Picking opens a **Google Photos tab** (Google's Picker — the only access Google permits third parties): select photos or videos there, click **Done**, and back in Nimply your picks import automatically. Nimply can only ever see the items you picked in that session — never your photo library.
## Unsplash [#unsplash]
Built-in stock photo search — no account needed. Search millions of free photos, click one to import. Photos are provided under the [Unsplash License](https://unsplash.com/license?utm_source=nimply\&utm_medium=referral) (free for commercial use); each imported photo keeps its photographer credit on the asset page.
## Notes [#notes]
* **Who can import**: any workspace member except viewers.
* **Where files go**: imports become normal media assets — tag them, attach them to posts, track usage, exactly like uploads.
* **Originals are never modified** in the source service; Nimply only reads what you pick.
# n8n (/docs/integrations/n8n)
Two ways to use Nimply from n8n workflows: the dedicated **community node** (nicest experience, self-hosted n8n only) or n8n's built-in **HTTP Request + Webhook nodes** (works everywhere, including n8n Cloud).
Both use an API key from Nimply → **Settings → Developers** ([scopes explained here](/docs/authentication)).
The `@nimply/n8n-nodes-nimply` package gives you typed operations for agents, automations, designs and brand kits, plus posts (including bulk and approvals), channels, media, link pages and analytics, and a trigger node with verified webhook deliveries. Platform-specific operations (**Create YouTube Video**, **Create TikTok Post**, **Create Pinterest Pin**, **Create LinkedIn Post**) expose each platform's full option set, with live dropdowns for Pinterest boards.
## Install [#install]
**Settings → Community nodes → Install** → enter `@nimply/n8n-nodes-nimply`. (Community nodes require self-hosted n8n.)
## Credentials [#credentials]
Create a **Nimply API** credential with your API key. The built-in credential test calls `GET /v1/workspace`, so a green check means you're fully connected.
## Nodes [#nodes]
* **Nimply**:
* **Agent**: templates, hire, get, update (pause/resume), remove, run (optionally waits for the result), runs.
* **Automation**: recipes, step types, create (from a recipe or steps), get, update, delete, test, switch on, pause, run, runs.
* **Design**: create from a prompt (optionally waits for the result), create from an image (editable layers), estimate credits, get, jobs, sizes.
* **Brand Kit**: get, create, update, import from a website or several sources, learn the look, look rules.
* **Post**: create, create bulk, platform-specific create, get, get many, update, delete, request approval, approve, reject, schedule, unschedule, publish.
* **Channel** (get, get many, get schedule), **Media** (upload from URL or binary, get, get many, delete), **Analytics** (workspace, channel, post), **Link Page** (get many, get, add/update/delete block, analytics, publish), **Workspace** (get).
* **Nimply Trigger** — subscribes to any of the 12 webhook events (posts, channels and leads) and **verifies the HMAC signature** of each delivery before your workflow runs; forged or replayed calls are rejected with 401.
Agent runs and design jobs use AI credits. Agents never publish on their own: what they make lands as posts awaiting approval, which you can approve from the workflow with **Post → Approve**.
## Starter workflow [#starter-workflow]
Run an agent for every new Google Sheets row and tell your team in Slack when its drafts are ready for approval:
More ready-to-import workflows (new leads to your CRM, alerts for failed posts) are in the package's [`examples` folder](https://github.com/nimply/n8n-nodes-nimply/tree/main/examples).
## Workflow ideas [#workflow-ideas]
* Google Sheets (new row) → **Nimply: Agent → Run** with the row as input → Slack message with the drafts to approve.
* **Nimply Trigger: lead.created** → add the lead to your CRM.
* Cron → RSS Read → **Nimply: Create Post** (next free slot).
* **Nimply Trigger: post.failed** → Telegram alert with the error.
* Spreadsheet batch → **Nimply: Create Bulk** → filter failed items into a review list.
* YouTube Trigger → **Nimply: Link Page → Add Block** (featured link, publish after adding) — see the [recipe](/docs/examples/add-link-when-video-goes-live).
## Troubleshooting [#troubleshooting]
* **Trigger inactive** — the webhook is registered when the workflow is activated; make sure the workflow is ON.
* **Signature failures in logs** — the webhook secret rotated (toggle the workflow off/on to re-register) or something altered the request body in transit.
No installation needed — n8n's built-in nodes talk to the API directly. Works on n8n Cloud and self-hosted alike.
## Starter workflow — paste and go [#starter-workflow--paste-and-go]
A complete flow — list channels → upload media from a URL → create a draft post — with the node wiring and expressions already done:
## Credential (reusable) [#credential-reusable]
Create a **Header Auth** credential once and attach it to every Nimply HTTP Request node:
* **Name:** `Authorization`
* **Value:** `Bearer nim_live_YOUR_KEY`
## Actions with the HTTP Request node [#actions-with-the-http-request-node]
Create a post:
* **Method:** `POST` · **URL:** `https://api.nimply.io/v1/posts`
* **Authentication:** Generic → Header Auth (the credential above)
* **Body (JSON):**
```json
{
"channelIds": ["{{ $json.channelId }}"],
"content": "{{ $json.caption }}",
"schedule": "next_slot"
}
```
Other useful calls, same pattern: `GET /v1/channels` (find channel ids), `POST /v1/media` with `{"url": "..."}` (import media, use the returned `id` in `mediaIds`), `POST /v1/posts/bulk` (up to 50 with per-item results). Full list in the [API reference](/docs/api-reference).
Tip: set a unique `Idempotency-Key` header (e.g. `{{ $execution.id }}`) on create calls so n8n retries can't double-post.
## Triggers with the Webhook node [#triggers-with-the-webhook-node]
1. Add a **Webhook** node (method POST) and copy its production URL.
2. Register it with Nimply once (from any terminal):
```bash
curl -X POST https://api.nimply.io/v1/webhooks \
-H "Authorization: Bearer nim_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "n8n workflow", "url": "", "events": ["post.published", "post.failed"]}'
```
3. Save the returned `secret` if you want to verify signatures (recommended — see the [webhook receiver recipe](/docs/examples/webhook-receiver) for the exact HMAC check, which you can run in a Code node).
4. Each delivery arrives as `{ id, type, createdAt, workspaceId, data }` — branch on `{{ $json.body.type }}`.
Test the wiring anytime with `POST /v1/webhooks/{id}/test`.
## Troubleshooting [#troubleshooting-1]
* **401 from the API** — the header value must be the full string `Bearer nim_live_...`.
* **Webhook node receives nothing** — the workflow must be **active** for the production URL to listen; the test URL only listens while you're executing manually.
# OpenClaw (/docs/integrations/openclaw)
## Connect [#connect]
OpenClaw configures MCP servers in `~/.openclaw/openclaw.json`. Add Nimply as a remote streamable-HTTP server with your API key:
```json
{
"mcp": {
"servers": {
"nimply": {
"url": "https://mcp.nimply.io/mcp",
"transport": "streamable-http",
"headers": {
"Authorization": "Bearer nim_live_YOUR_KEY"
}
}
}
}
}
```
Or from the CLI:
```bash
openclaw mcp set nimply '{
"url": "https://mcp.nimply.io/mcp",
"transport": "streamable-http",
"headers": {"Authorization": "Bearer nim_live_YOUR_KEY"}
}'
```
Create the key in Nimply → **Settings → Developers**. Verify the connection:
```bash
openclaw mcp doctor nimply --probe
openclaw mcp status --verbose
```
## Uploading generated media [#uploading-generated-media]
OpenClaw can execute shell commands, so it can push locally generated files (e.g. AI-generated images) straight into your media library without hosting them anywhere: it calls `create_media_upload`, PUTs the raw bytes to the returned presigned URL, then calls `complete_media_upload`. Just ask it to upload the file — no public URL needed.
## Try it [#try-it]
* *"Use nimply to list my channels and queue this image as an Instagram post in the next free slot."*
* *"Every Monday, draft a week of posts from my notes and send them for approval in nimply."*
## Troubleshooting [#troubleshooting]
* **401 Unauthorized** — the header must be exactly `Bearer nim_live_...`; regenerate the key in **Settings → Developers** if it was revoked.
* **Server not listed** — run `openclaw mcp doctor nimply --probe` and check the gateway logs; older OpenClaw versions need an update for streamable-HTTP support.
* **Key in a committed config** — `openclaw.json` is plain text; keep it out of dotfile repos, or store the token in an environment variable if your OpenClaw version supports header expansion.
# Perplexity (/docs/integrations/perplexity)
## Connect [#connect]
Perplexity supports MCP connectors in its desktop apps and the Comet browser.
1. Create an API key in Nimply → **Settings → Developers**.
2. Open **Settings → Connectors** in the Perplexity app and add a connector.
3. Choose the remote/HTTP server type and enter:
* **URL:** `https://mcp.nimply.io/mcp`
* **Header:** `Authorization: Bearer nim_live_YOUR_KEY`
4. Save — the Nimply tools become available to Perplexity's assistant.
If your Perplexity version only supports local (command-based) connectors, use the [mcp-remote bridge](/docs/integrations/any-mcp-client) as the command.
## Try it [#try-it]
* *"What did my audience engage with most last month in Nimply?"*
* *"Research trending topics in my niche and draft three posts as Nimply drafts."*
## Troubleshooting [#troubleshooting]
* **Connector not calling tools** — connectors may need to be toggled on per-thread; check the tools menu in the composer.
* **401** — recheck the header value; the whole string is `Bearer nim_live_...`.
# Raycast (/docs/integrations/raycast)
## Connect [#connect]
1. Create an API key in Nimply → **Settings → Developers**.
2. In Raycast, run **Manage MCP Servers → Add Server** (Raycast Pro with AI).
3. Add Nimply as an HTTP server — URL `https://mcp.nimply.io/mcp` with header `Authorization: Bearer nim_live_YOUR_KEY`. If your Raycast version only accepts command-based servers, use the bridge:
```json
{
"mcpServers": {
"nimply": {
"command": "npx",
"args": [
"-y", "mcp-remote",
"https://mcp.nimply.io/mcp",
"--header", "Authorization: Bearer nim_live_YOUR_KEY"
]
}
}
}
```
4. Mention `@nimply` in Raycast AI chat to bring its tools into the conversation.
## Try it [#try-it]
* *"@nimply what's scheduled for this week?"*
* *"@nimply schedule a post: 'We're hiring!' on LinkedIn, next free slot."*
## Troubleshooting [#troubleshooting]
* **Server not responding** — the bridge needs Node 18+ available on your PATH.
* **Tools denied** — the key's permissions don't cover the action; create a key with broader scopes.
# Slack (/docs/integrations/slack)
## What it does [#what-it-does]
Once connected, Nimply posts to a Slack channel of your choice when:
* a post **publishes** (with a link to the live post)
* a post **fails** (with the error, so you can fix it before a client notices)
* a **social account disconnects** and needs reconnecting
* a post is **submitted for approval** — the message carries **Approve / Reject buttons**, so admins can decide without opening Nimply
You choose which of these events are sent, per workspace.
## Connect [#connect]
1. In Nimply, go to **Settings → Integrations → Slack** and click **Add to Slack**.
2. Slack asks you to pick your Slack workspace and approve — you need the OWNER or ADMIN role in the Nimply workspace.
3. Back in Nimply, choose the **channel** alerts go to and toggle the **events** you want. Nothing is sent until a channel is chosen.
The bot can post to any public channel. To use a private channel, invite the bot to it in Slack first.
## Approvals from Slack [#approvals-from-slack]
Approval-request messages include **Approve** and **Reject** buttons. When someone clicks one, Nimply matches their **Slack profile email** to a Nimply account:
* The email must belong to a Nimply user who is an **OWNER or ADMIN** of the workspace — the same rule as approving in the app.
* Anyone else gets a private explanation and the post is untouched.
* The decision is recorded in Nimply's normal approval history ("Approved from Slack"), and the Slack message updates to show who decided.
## Troubleshooting [#troubleshooting]
* **No messages arriving** — check a channel is selected and the event is toggled on under Settings → Integrations → Slack; then confirm the bot wasn't removed from the channel.
* **Approve button says my email doesn't match** — your Slack profile email must equal your Nimply login email, and your role must be OWNER or ADMIN.
* **Disconnecting** — Settings → Integrations → Slack → Disconnect. Access is revoked immediately; reconnect any time.
# Telegram channels & groups (/docs/integrations/telegram-channels)
## What it does [#what-it-does]
Telegram is a full channel in Nimply, not just a notification target:
* **Publish** to a channel or group from the planner — text, photos, videos, GIFs, documents, albums of up to 10 items, polls — with URL buttons under the post, silent delivery, protected content, link-preview control, pin-after-publish and an auto-delete timer.
* **Edit or remove a post after it is live** (Telegram is the only platform where this works through the API).
* **Inbox**: comments under your posts (through the channel's discussion group), group messages and reactions land in the unified inbox; reply, delete, mute a member for 24 hours, or ban them.
* **Personal DMs** (Telegram Business, needs Telegram Premium on the account): route the chats you choose from your own Telegram account to the inbox and let agents draft or answer as you.
* **Agents & automations**: the Community Moderator, the DM agents (Customer Support, Sales Lead, Personal DM) and the Telegram Channel Editor bind to Telegram; automations get join-request, member-joined/left triggers and approve/decline, mute/ban and send-message actions.
* **Analytics** show members, joins and leaves by invite link, reactions and comments per post. Views and reach are not exposed by Telegram's Bot API — they stay in Telegram's built-in statistics.
## Connect a channel or group [#connect-a-channel-or-group]
You need the OWNER or ADMIN role in the workspace and admin rights on the Telegram chat. No bot creation, no tokens.
1. In Nimply, go to **Channels → Connect → Telegram → Telegram Channel or Group** and click **Open Telegram**.
2. Press **Start** in the chat with the Nimply bot. It replies with **Add to a channel** and **Add to a group** buttons.
3. Pick the chat. Telegram asks which admin rights to grant — keep the pre-selected ones (post, edit, delete, pin, invite users).
4. Back in Nimply the chat appears with a rights checklist. Click **Connect**.
If Nimply doesn't detect the chat within a minute, post `/connect CODE` (the code shown in Nimply) in the chat.
**Comments:** if the channel has a discussion group, add the bot to that group too (Nimply shows an **Add bot to comments group** link on the channel page). Comments arrive in the inbox only from groups the bot is in.
## Connect your personal DMs (Telegram Business) [#connect-your-personal-dms-telegram-business]
1. **Channels → Connect → Telegram → Telegram Business** and press **Start** in the bot chat.
2. In Telegram: **Settings → Telegram Business → Chatbots** (this needs Telegram Premium on your account; Telegram is gradually rolling out a free **Settings → Chat Automation** entry that does the same), choose the Nimply bot, and select which chats it may handle. We recommend *New chats only* and *Exclude contacts*.
3. Telegram confirms the connection to Nimply automatically; click **Connect my DMs**.
Replies go out from your own account and only in chats active within the last 24 hours. The first automatic reply an agent sends in a conversation tells the person they are talking to an assistant.
## Post options [#post-options]
| Option | Effect |
| -------------------- | -------------------------------------------------- |
| Buttons | Up to 3 rows of URL buttons under the post |
| Silent | Delivered without a notification sound |
| Protect content | Subscribers cannot forward or save the post |
| Link preview | Show or hide the preview card |
| Spoiler media | Photos/videos blurred until tapped |
| Pin after publishing | Pins the post (needs the bot's edit/pin right) |
| Auto-delete | Removes the post after 24h / 48h / 3 days / 7 days |
Limits: 4,096 characters for a text post, 1,024 for a media caption (longer text is sent as a message right after the media), albums of 2–10 photos/videos, files up to 50 MB.
## Troubleshooting [#troubleshooting]
* **"The Nimply bot is no longer an administrator"** — someone removed the bot or its post right. Add it back as an admin; the channel reconnects automatically.
* **Comments don't show up** — the bot is not in the discussion group. Use the link on the channel page.
* **"Telegram no longer lets the connected bot reply"** — the 24-hour window since the person's last message has passed, or the chat is outside the scope you chose in Telegram Business. Reply from your Telegram app, or wait for them to write again.
* **Pin failed** — grant the bot the *Edit messages* (channels) or *Pin messages* (groups) right.
# Telegram (/docs/integrations/telegram)
## What it does [#what-it-does]
Link a private chat (or a team group) to your workspace and the Nimply bot:
* sends **alerts** — post published, post failed, channel disconnected
* delivers **approval requests** with ✅ Approve / ❌ Reject buttons
* answers **commands** about your workspace
* turns **text you send it into drafts** (private chats)
## Connect [#connect]
1. In Nimply, go to **Settings → Integrations → Telegram** and click **Connect Telegram** (OWNER or ADMIN role required).
2. Choose **Open my private chat** for personal alerts, or **Add to a group** for a team channel. The link is valid for 10 minutes.
3. Press **Start** in Telegram. The chat is now linked — pick which events are sent from the same settings page.
One chat per workspace. To switch chats, disconnect and connect again with a fresh link.
## Bot commands [#bot-commands]
| Command | What it does |
| --------------- | ------------------------------------------------------------ |
| `/status` | Workspace overview — channels, queue size, pending approvals |
| `/queue` | The next scheduled posts with times and excerpts |
| `/pending` | Posts awaiting approval, each with Approve/Reject buttons |
| `/channels` | Connected social accounts with a 🟢/🟡/🔴 health dot |
| `/draft ` | Save a draft — the bot asks which channel it's for |
| `/cancel` | Abandon the current action |
| `/help` | Command reference |
In a **private chat**, you can skip `/draft` entirely: send the bot any text and it offers to draft it, with a channel picker. In **groups**, the bot only reacts to commands so it never spams the conversation.
## Who can act [#who-can-act]
* **Approvals and drafts** are restricted to the Telegram account that linked the chat, and that person's Nimply role is re-checked on every action (OWNER/ADMIN for approvals; any non-viewer role for drafts).
* Read commands (`/status`, `/queue`, …) work for anyone in the linked chat — they only show information about the workspace the chat is linked to.
## Troubleshooting [#troubleshooting]
* **"This chat isn't connected"** — the link expired before you pressed Start, or the chat was disconnected. Generate a fresh link from Settings → Integrations → Telegram.
* **Buttons say only the linked account can decide** — by design; the person who connected the chat is the only one who can approve from Telegram. Others can review in Nimply.
* **No alerts** — check the event toggles on the Telegram settings page.
# VS Code (/docs/integrations/vs-code)
## Connect [#connect]
1. Create an API key in Nimply → **Settings → Developers**.
2. Run **MCP: Add Server** from the Command Palette, or create `.vscode/mcp.json` in your workspace:
```json
{
"servers": {
"nimply": {
"type": "http",
"url": "https://mcp.nimply.io/mcp",
"headers": {
"Authorization": "Bearer nim_live_YOUR_KEY"
}
}
}
}
```
To avoid committing the key, use an input placeholder instead:
```json
{
"inputs": [
{ "id": "nimply-key", "type": "promptString", "password": true, "description": "Nimply API key" }
],
"servers": {
"nimply": {
"type": "http",
"url": "https://mcp.nimply.io/mcp",
"headers": { "Authorization": "Bearer ${input:nimply-key}" }
}
}
}
```
3. Open Copilot Chat in **agent mode** — the Nimply tools are available under the tools picker.
## Try it [#try-it]
* *"List my Nimply channels and tell me which need reconnecting."*
## Troubleshooting [#troubleshooting]
* **Server won't start** — run **MCP: List Servers → nimply → Show Output** for the error detail.
* **Tools missing in chat** — agent mode only; ask mode doesn't call tools.
# WhatsApp Business (/docs/integrations/whatsapp)
## What it does [#what-it-does]
WhatsApp is an **inbox-only** channel in Nimply, connected through the WhatsApp Business Platform (Meta's Cloud API):
* **Inbox**: every customer chat becomes a thread. Text, photos, videos, voice notes, documents and stickers arrive as sent; reactions attach to the message they refer to; replies you send show delivered and read status. Assignment, internal notes, saved replies, tags, SLA policies and AI triage work as on every other channel.
* **Replies** support text plus one attachment (image, video, document or audio). WhatsApp allows free-form replies only within **24 hours of the customer's last message**; the composer shows the remaining window and tells you in plain language when it has closed.
* **Agents & automations**: the Customer Support, Sales Lead and Personal DM agents bind to a WhatsApp channel (draft-first by default, auto mode per agent); inbox-triggered automations run on WhatsApp conversations.
* **Identity**: threads are keyed on Meta's business-scoped user ID, so a customer stays one conversation whether they show a phone number or a WhatsApp username.
Not available, by platform design: publishing or scheduling (WhatsApp Status and Channels have no official API — channels report `capabilities.publish: false` and are rejected by the post endpoints with `CHANNEL_NOT_PUBLISHABLE`), template or broadcast messages, messaging people who never wrote to you, and WhatsApp analytics.
## Requirements [#requirements]
* OWNER or ADMIN role in the workspace, and a paid plan (Creator: 1 number, Growth: 3, Agency: 10).
* A Facebook account that manages, or can create, your Meta business portfolio.
* A phone number that can receive an SMS or voice call. A number already in the **WhatsApp Business app** can stay there and connect too — see [Keep using the WhatsApp Business app](#keep-using-the-whatsapp-business-app-coexistence). A number in the consumer WhatsApp app must be moved to WhatsApp Business first.
Nimply is a **Tech Provider** on Meta's platform: your WhatsApp Business Account and phone number stay in your own business portfolio, Meta bills your account directly for delivery, and you can revoke Nimply's access from Meta Business settings at any time.
## Connect a number [#connect-a-number]
1. In Nimply go to **Channels → Connect → WhatsApp Business** and click **Connect**.
2. Meta's Embedded Signup opens in a popup. Sign in with the Facebook account that manages your business.
3. Choose or create your **business portfolio** and **WhatsApp Business Account**, then either add a new phone number and verify it with the SMS or voice code, or choose **connect your existing WhatsApp Business app** and paste the code Meta sends to the app.
4. Confirm the permissions Meta shows (`whatsapp_business_messaging` and `whatsapp_business_management`, both reviewed and approved for Nimply).
5. Back in Nimply the number appears as a channel with its inbox switched on. Nimply registers the number with the Cloud API and subscribes to message webhooks for you.
Send yourself a message from any phone to see the first thread. If the channel shows *Number not registered with WhatsApp yet*, reconnect it once — registration can lag Meta's own setup by a minute.
## Keep using the WhatsApp Business app (Coexistence) [#keep-using-the-whatsapp-business-app-coexistence]
If the number already lives in the WhatsApp Business app on your phone, the signup offers to connect it in place. Meta calls this *Coexistence*: the phone app keeps working, and Nimply and the app share the same number.
Requirements: WhatsApp Business app **2.24.17 or newer**. During signup Meta sends a verification code to the app; tap **Connect to the Business Platform**, confirm whether to share chat history, and paste the code.
What happens after connecting:
* Nimply asks Meta for your **contacts** and the **last 180 days of chats**. Keep the app open for a few minutes; the import runs in the background and imported chats never trigger agents, automations or notifications.
* Replies you send **from the phone** appear in the inbox as your own messages; replies sent from Nimply appear in the app.
* The number is already registered, so no PIN or registration step runs.
What changes in the app for that number: broadcast lists, disappearing messages, view-once messages, live location and voice/video calls are switched off, and group chats stay in the app only. Linked companion devices are unlinked once and can be linked again. Messages sent from Nimply follow Cloud API pricing; messages sent from the app stay free.
To disconnect, use the app: **Settings → Account → Business Platform → Disconnect Account**. Nimply marks the channel disconnected when Meta reports it.
## Costs [#costs]
Nimply adds **no per-message charge** for WhatsApp. Conversations are part of your plan, and agent runs use AI credits exactly as on every other channel.
Meta bills delivery separately, to the payment method on your own WhatsApp Business Account:
| What | Meta's charge |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Messages customers send you | Free |
| Your replies inside the 24-hour window ("service messages") | Free until **1 October 2026**. From then, per delivered reply at Meta's published rate for the customer's country, after **1,000 free replies a month per phone number** |
| Utility template messages (renewal reminders and similar) | Per delivered message at Meta's published rate; from 1 October 2026 this applies inside the 24-hour window too |
Rates depend on the customer's phone number country, not on where your business is. Meta stops delivering replies on 1 October 2026 for accounts with no payment method on file, so add one in WhatsApp Manager → Billing before then. Meta's rate cards: [Pricing on the WhatsApp Business Platform](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing).
## Troubleshooting [#troubleshooting]
* **"It's been more than 24 hours since this customer's last message"** — WhatsApp's customer service window has closed. The customer's next message reopens it; Nimply does not send template messages to reopen conversations.
* **"WhatsApp rejected the recipient: a test number can only message phone numbers on its allowed list"** — you connected a Meta *test* number. Add the recipient in Meta's API Setup, or connect a real business number.
* **"Your WhatsApp connection has expired or lost access"** — the token was revoked or the permissions changed. Reconnect the number from Channels.
* **"Your WhatsApp Business Account is restricted or disabled by Meta"** — check WhatsApp Manager; Nimply cannot lift Meta restrictions.
* **Messages don't arrive** — the channel page shows an inbox webhook error if Meta's subscription failed; reconnecting re-subscribes.
# Windsurf (/docs/integrations/windsurf)
## Connect [#connect]
1. Create an API key in Nimply → **Settings → Developers**.
2. Open Windsurf's MCP settings (**Cascade → MCP servers → Manage**) or edit `~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"nimply": {
"serverUrl": "https://mcp.nimply.io/mcp",
"headers": {
"Authorization": "Bearer nim_live_YOUR_KEY"
}
}
}
}
```
3. Refresh the MCP server list; Nimply's tools become available to Cascade.
If your Windsurf version doesn't support remote servers with headers, use the [mcp-remote bridge](/docs/integrations/any-mcp-client) instead.
## Try it [#try-it]
* *"Schedule a LinkedIn post about today's release for tomorrow morning via nimply."*
## Troubleshooting [#troubleshooting]
* **Server listed but no tools** — hit refresh in the MCP panel after saving the config.
* **401** — check the key; it must start with `nim_live_` and be active in Settings → Developers.
# Zapier (/docs/integrations/zapier)
The Nimply app for Zapier connects your posting queue to everything else you use — no code.
> **Availability:** the app is being submitted to Zapier's public directory; directory review takes a few weeks. If you don't find "Nimply" in the Zap editor yet, check back soon — or use [webhooks](/docs/webhooks) with Zapier's generic *Webhooks by Zapier* app in the meantime.
## What it does [#what-it-does]
**Triggers** (instant, webhook-powered — no polling):
| Trigger | Fires when |
| ------------------ | --------------------------------------------------------------------- |
| Post Published | a scheduled post goes live |
| Post Failed | a platform rejects a post — alert your team before the client notices |
| Approval Requested | a draft is sent for sign-off |
**Actions:** Create Post (draft / next slot / now / at a time, with media), platform-specific creates — Create YouTube Video, Create TikTok Post, Create Pinterest Pin, Create LinkedIn Post — with each platform's full option set (live dropdowns for Pinterest boards and TikTok privacy levels), Upload Media from URL, plus the full post lifecycle — Update, Schedule, Unschedule (back to draft), Publish, Delete, and the approval workflow (Request Approval, Approve, Reject).
File fields from other apps (Drive, Gmail, Dropbox…) work automatically — Zapier passes files as URLs, which the upload action accepts directly.
**Search:** Find Channel by name.
## Connect [#connect]
1. In the Zap editor, add a Nimply trigger or action and click **Sign in to Nimply**.
2. Log in, choose the workspace, and click **Allow access** — the standard Nimply OAuth consent.
3. Build your Zap as usual.
## Zap ideas [#zap-ideas]
* New RSS item → **Create Post** (next free slot) on all channels.
* **Post Failed** → Slack message to #marketing with the error.
* New row in Google Sheets → **Upload Media** → **Create Post** scheduled at the row's date.
* **Post Published** → log the post URL to Airtable for client reporting.
* New YouTube video → **Add Link Block** on your nimply.link page (featured, at the top) — see the [recipe](/docs/examples/add-link-when-video-goes-live).
## Why no copy-paste workflow here? [#why-no-copy-paste-workflow-here]
Unlike [n8n](/docs/integrations/n8n) and [Make](/docs/integrations/make), Zapier doesn't support importing workflow JSON — Zaps can only be shared as templates from a published app. Once the Nimply app is listed we'll publish Zap templates for the common flows; until then, build from the trigger/action list above.
## Troubleshooting [#troubleshooting]
* **Connection fails at consent** — you need the OWNER or ADMIN role in the workspace.
* **Trigger never fires** — the Zap must be turned ON (Zapier registers the webhook at that moment); check Settings → Developers → the webhook list shows a "Zapier: …" entry.
# Cancel an agent run (/docs/api-reference/agent-runs/cancelAgentRun)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Get an agent run (/docs/api-reference/agent-runs/getAgentRun)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Get an agent template (/docs/api-reference/agent-templates/getAgentTemplate)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# List agent templates (/docs/api-reference/agent-templates/listAgentTemplates)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Get an agent (/docs/api-reference/agents/getAgent)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Hire an agent (/docs/api-reference/agents/hireAgent)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# List an agent's recent runs (/docs/api-reference/agents/listAgentRuns)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# List agents (/docs/api-reference/agents/listAgents)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Remove an agent (/docs/api-reference/agents/removeAgent)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Run an agent now (/docs/api-reference/agents/runAgent)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Change an agent (/docs/api-reference/agents/updateAgent)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Channel analytics (/docs/api-reference/analytics/getChannelAnalytics)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Post analytics (/docs/api-reference/analytics/getPostAnalytics)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Workspace analytics summary (/docs/api-reference/analytics/getWorkspaceAnalytics)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# List automation recipes (/docs/api-reference/automation-recipes/listAutomationRecipes)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Get an automation run (/docs/api-reference/automation-runs/getAutomationRun)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# List automation step types (/docs/api-reference/automation-step-types/listAutomationStepTypes)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Switch an automation on (/docs/api-reference/automations/activateAutomation)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Create an automation (/docs/api-reference/automations/createAutomation)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Create an automation from a recipe (/docs/api-reference/automations/createAutomationFromRecipe)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Delete an automation (/docs/api-reference/automations/deleteAutomation)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Get an automation (/docs/api-reference/automations/getAutomation)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# List runs of an automation (/docs/api-reference/automations/listAutomationRuns)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# List automations (/docs/api-reference/automations/listAutomations)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Pause an automation (/docs/api-reference/automations/pauseAutomation)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Run an automation now (/docs/api-reference/automations/runAutomation)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Test an automation (/docs/api-reference/automations/testAutomation)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Update an automation (/docs/api-reference/automations/updateAutomation)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Add examples to learn the look from (/docs/api-reference/brand-kits/addBrandKitStyleExamples)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Create a brand kit (/docs/api-reference/brand-kits/createBrandKit)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Create a brand kit from several sources (/docs/api-reference/brand-kits/createBrandKitImport)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Price a brand import (/docs/api-reference/brand-kits/estimateBrandKitImport)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Get a brand kit (/docs/api-reference/brand-kits/getBrandKit)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Get a brand import (/docs/api-reference/brand-kits/getBrandKitImport)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Get a brand kit's learned look (/docs/api-reference/brand-kits/getBrandKitStyle)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Read a brand from its website (/docs/api-reference/brand-kits/importBrandKit)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Learn the look from the examples (/docs/api-reference/brand-kits/learnBrandKitStyle)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# List published posts to learn from (/docs/api-reference/brand-kits/listBrandKitStylePostCandidates)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# List brand kits (/docs/api-reference/brand-kits/listBrandKits)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Remove an example (/docs/api-reference/brand-kits/removeBrandKitStyleExample)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Save a brand import as a brand kit (/docs/api-reference/brand-kits/saveBrandKitImport)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Set the look's rules (/docs/api-reference/brand-kits/setBrandKitStyleRules)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Update a brand kit (/docs/api-reference/brand-kits/updateBrandKit)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Get a channel (/docs/api-reference/channels/getChannel)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Get a channel's posting schedule (/docs/api-reference/channels/getChannelSchedule)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# List a Pinterest channel's boards (/docs/api-reference/channels/getPinterestBoards)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Get a TikTok channel's creator info (/docs/api-reference/channels/getTikTokCreatorInfo)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# List connected channels (/docs/api-reference/channels/listChannels)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Cancel a design job (/docs/api-reference/design-jobs/cancelDesignJob)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Get a design job (/docs/api-reference/design-jobs/getDesignJob)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# List design sizes (/docs/api-reference/design-sizes/listDesignSizes)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Turn an image into an editable, layered design (/docs/api-reference/designs/createDesignFromImage)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Estimate the credits a design run can use (/docs/api-reference/designs/estimateDesignCost)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Create a design from a prompt (/docs/api-reference/designs/generateDesign)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Get a design (/docs/api-reference/designs/getDesign)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# List designs (/docs/api-reference/designs/listDesigns)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Add a block to a link page (/docs/api-reference/link-pages/createLinkPageBlock)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Delete a block (/docs/api-reference/link-pages/deleteLinkPageBlock)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Get a link page with its blocks (/docs/api-reference/link-pages/getLinkPage)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Link page analytics (/docs/api-reference/link-pages/getLinkPageAnalytics)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# List the blocks of a link page (/docs/api-reference/link-pages/listLinkPageBlocks)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# List link pages (/docs/api-reference/link-pages/listLinkPages)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Publish a link page (/docs/api-reference/link-pages/publishLinkPage)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Update a link page (title, bio, SEO) (/docs/api-reference/link-pages/updateLinkPage)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Update a block (/docs/api-reference/link-pages/updateLinkPageBlock)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Complete a direct binary upload (/docs/api-reference/media/completeMediaUpload)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Start a direct binary upload (/docs/api-reference/media/createMediaUpload)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Delete a media asset (/docs/api-reference/media/deleteMedia)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Get a media asset (/docs/api-reference/media/getMedia)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# List media assets (/docs/api-reference/media/listMedia)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Import media from a URL (/docs/api-reference/media/uploadMedia)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Approve a post (/docs/api-reference/posts/approvePost)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Post to LinkedIn (/docs/api-reference/posts/createLinkedInPost)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Create a Pinterest pin (/docs/api-reference/posts/createPinterestPin)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Create a post (/docs/api-reference/posts/createPost)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Create posts in bulk (/docs/api-reference/posts/createPostsBulk)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Post to TikTok (/docs/api-reference/posts/createTikTokPost)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Post a YouTube video (/docs/api-reference/posts/createYouTubeVideo)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Delete a post (/docs/api-reference/posts/deletePost)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Get a post (/docs/api-reference/posts/getPost)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# List posts (/docs/api-reference/posts/listPosts)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Publish a post now (/docs/api-reference/posts/publishPost)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Reject a post (/docs/api-reference/posts/rejectPost)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Request approval for a post (/docs/api-reference/posts/requestPostApproval)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Schedule a post (/docs/api-reference/posts/schedulePost)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Unschedule a post (/docs/api-reference/posts/unschedulePost)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Update a post (/docs/api-reference/posts/updatePost)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Create a webhook (/docs/api-reference/webhooks/createWebhook)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Delete a webhook (/docs/api-reference/webhooks/deleteWebhook)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Get a webhook (/docs/api-reference/webhooks/getWebhook)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# List webhooks (/docs/api-reference/webhooks/listWebhooks)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Send a test event (/docs/api-reference/webhooks/testWebhook)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Update a webhook (/docs/api-reference/webhooks/updateWebhook)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
# Get the current workspace (/docs/api-reference/workspace/getWorkspace)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}