Skip to content
Join the waitlist
Developers

REST API reference

Everything under /public/v1, generated from the routes the server really has. JSON in, JSON out.

Base address

Send every request to this address. A self-hosted PostNimbo uses its own backend address instead.

https://postnimbo.com/api/public/v1

Authentication

Put the credential in the Authorization header as it is, without a Bearer prefix. Two kinds work:

  • An API key, from Settings > Agents / Dev. It acts as the whole workspace and reaches every route below.
  • An OAuth access token (it starts with pos_), from an OAuth app. It acts as the member who approved it, sees only their brands and channels, and is limited to the scopes they approved.
curl https://postnimbo.com/api/public/v1/me \
  -H "Authorization: <api key or pos_ token>"

A missing or wrong credential answers 401. A route a token was not approved for answers 403. Errors carry a msg or message field.

Rate limits

  • 120 requests a minute for each API key or token, across every route.
  • Creating posts is also limited per workspace each hour (90 by default).
  • Over a limit the answer is 429 with a Retry-After header in seconds. Wait that long before trying again.

Self-hosted servers set their own limits with PUBLIC_API_RATE_LIMIT, PUBLIC_API_RATE_TTL and API_LIMIT.

Endpoints

The scope column is what an OAuth token needs. An API key reaches every route.

Account

  • GET/public/v1/me

    The workspace the credential belongs to, and for an OAuth token the member who approved it.

    ScopeAny token
  • GET/public/v1/is-connected

    Check that the credential works.

    ScopeAny token
  • GET/public/v1/groups

    The brands (customers) the credential can see.

    ScopeAny token
  • GET/public/v1/counts

    Posts waiting for approval and unread open inbox conversations.

    Scopeposts:readinbox:readInputquery: brandId?

Channels

  • GET/public/v1/integrations

    The connected channels, with their ids and networks.

    Scopeposts:readInputquery: group? (a brand id)
  • GET/public/v1/integration-settings/:id

    The rules of a channel: character limits, media rules and the settings a post needs.

    ScopeAPI key or full-access token
  • GET/public/v1/find-slot/:id

    The next free posting slot of a channel.

    Scopeposts:read
  • GET/public/v1/social/:integration

    The sign-in link that connects a new channel of a network (for example linkedin).

    ScopeAPI key or full-access tokenInputquery: refresh? (a channel id to reconnect)
  • DELETE/public/v1/integrations/:id

    Disconnect a channel.

    ScopeAPI key or full-access token
  • POST/public/v1/integration-trigger/:id

    Run a lookup a network offers (for example the boards of a Pinterest account).

    ScopeAPI key or full-access tokenInputbody: { methodName, data }

Posts

  • GET/public/v1/posts

    The posts between two dates.

    Scopeposts:readInputquery: startDate, endDate (ISO 8601), customer?
  • POST/public/v1/posts

    Create a draft, schedule a post or publish now, on one or more channels.

    Scopeposts:scheduleInputbody: { type: draft|schedule|now, date, shortLink, tags, posts: [{ integration: { id }, value: [{ content, image? }], settings? }] }
  • PUT/public/v1/posts/:id/settings

    Change the network settings of a post.

    ScopeAPI key or full-access tokenInputbody: { settings }
  • PUT/public/v1/posts/:id/status

    Move a post between draft and scheduled.

    ScopeAPI key or full-access tokenInputbody: { status: draft|schedule }
  • GET/public/v1/posts/:id/missing

    For a post the network accepted without returning its id: the recent posts of the channel to pick it from.

    ScopeAPI key or full-access token
  • PUT/public/v1/posts/:id/release-id

    Link a post to the network post it became.

    ScopeAPI key or full-access tokenInputbody: { releaseId }
  • DELETE/public/v1/posts/:id

    Delete a post.

    ScopeAPI key or full-access token
  • DELETE/public/v1/posts/group/:group

    Delete every post of a group (one post sent to several channels).

    ScopeAPI key or full-access token

Media

  • POST/public/v1/upload

    Upload a file to the media library.

    Scopemedia:writeInputmultipart: file, adjust?
  • POST/public/v1/upload-from-url

    Add a file from a public https address.

    Scopemedia:writeInputbody: { url, adjust? }
  • GET/public/v1/media

    The media library, a page at a time.

    ScopeAPI key or full-access tokenInputquery: page?, search?, folder?
  • GET/public/v1/media/:id/status

    Whether an uploaded video finished processing.

    ScopeAPI key or full-access token

Ideas

  • POST/public/v1/ideas

    Save an idea to the Ideas board.

    Scopeideas:writeInputbody: { title, content? }
  • DELETE/public/v1/ideas/:id

    Remove an idea the credential saved.

    Scopeideas:write

Analytics

  • GET/public/v1/performance

    A summary of the last 7 days: posts, reach and engagement.

    Scopeanalytics:readInputquery: brandId?, tz?
  • GET/public/v1/best-times/next

    The next best times to post, from your own results.

    Scopeposts:readInputquery: integrationId?, brandId?, tz?, goal?: engagement|reach|views, count? (1-20)
  • GET/public/v1/analytics/:integration

    The analytics of a channel.

    ScopeAPI key or full-access tokenInputquery: date (days back)
  • GET/public/v1/analytics/post/:postId

    The analytics of one published post.

    ScopeAPI key or full-access tokenInputquery: date (days back)

AI

  • POST/public/v1/ai/draft

    Draft a post about a web page with PostNimbo AI.

    Scopeai:useInputbody: { url, title?, selection?, mode: summary|captions }
  • POST/public/v1/ai/reply

    Draft a reply to a comment or message.

    Scopeai:useInputbody: { text, url? }

Link in bio

  • GET/public/v1/link-in-bio

    The link-in-bio pages of the workspace.

    Scopelink-in-bio:write
  • POST/public/v1/link-in-bio/:id/links

    Add a link to a link-in-bio page.

    Scopelink-in-bio:writeInputbody: { label, url }

Video and clipping

  • POST/public/v1/generate-video

    Generate a video with one of the AI video tools.

    ScopeAPI key or full-access token
  • POST/public/v1/video/function

    Load the options of a video tool (voices, avatars).

    ScopeAPI key or full-access token
  • POST/public/v1/clipping

    Cut a long video into short clips.

    ScopeAPI key or full-access token
  • GET/public/v1/clipping

    The clipping jobs, a page at a time.

    ScopeAPI key or full-access tokenInputquery: page
  • GET/public/v1/clipping/:id

    One clipping job and its clips.

    ScopeAPI key or full-access token

Notifications

  • GET/public/v1/notifications

    The workspace notifications, a page at a time.

    ScopeAPI key or full-access tokenInputquery: page?

Webhooks

  • GET/public/v1/webhooks/events

    The events a webhook is sent, with a sample payload of each.

    ScopeAny token
  • GET/public/v1/webhooks

    The webhooks of the workspace, without their addresses; ?url= finds the webhooks of one address.

    Scopewebhooks:writeInputquery: url?
  • POST/public/v1/webhooks

    Subscribe an address to events (how Zapier, Make and n8n triggers switch on).

    Scopewebhooks:writeInputbody: { url, events?, integrations? (channel ids), name? }
  • DELETE/public/v1/webhooks/:id

    Remove a webhook (how a trigger switches off).

    Scopewebhooks:write

Building something with PostNimbo?

Tell us what you are making. We help with the API, review apps for the directory and add the endpoints integrations need.

Email the teamGet an API key