Getting started
Authentication
Authenticate Public API and MCP requests with your organization API key and understand what each scope allows.
Every request is authenticated with an organization API key. Keys start with pk_postiv_ and are generated in Settings → Integrations inside Postiv. The key identifies your workspace, so requests never need an organization id.
Authenticated request
curl https://postiv.ai/api/public/workspace \
-H "Authorization: Bearer pk_postiv_..."Headers
Send the key with either header. If both are present, x-api-key wins:
| Header | Format |
|---|---|
| Authorization | Bearer pk_postiv_... |
| x-api-key | pk_postiv_... |
Scopes
Each key carries a set of scopes, and every endpoint requires one. GET /api/public/workspace returns the scopes your key actually has.
| Scope | Grants |
|---|---|
workspace:read | Read workspace identity and the scopes granted to the key. |
knowledge:read | Semantically search the workspace knowledge base. |
knowledge:write | Add items to the workspace knowledge base. |
posts:read | List and read posts, templates, carousels, and infographics. |
posts:write | Create and update drafts, carousels, infographics, and slide edits. |
posts:schedule | Schedule, reschedule, and unschedule posts; set Comment Plug defaults. |
images:write | Generate and edit branded post images. |
profiles:read | List LinkedIn profiles and read trained writing styles. |
analytics:read | Read cached analytics: accounts, KPIs, performance, and top posts. |
inspiration:read | Search the moderated LinkedIn inspiration library. |
plans:read | Read Bob content plans, plan items, and content pillars. |
scratchpad:read | List and read scratchpad items. |
scratchpad:write | Create, update, delete, and promote scratchpad items. |
Legacy knowledge-base keys are limited to
knowledge:write. New keys receive the full scope set; use Regenerate Key (adds new scopes) in Settings → Integrations to explicitly replace a legacy key. Regeneration invalidates the previous key.Auth errors
| Status | Meaning |
|---|---|
| 401 | The key is missing, malformed, or revoked. |
| 403 | The key is valid but does not carry the scope this endpoint requires. |
Treat the key like a password: it grants workspace automation access according to its scopes. Never commit it to version control, and regenerate it immediately if it leaks.