Postiv Public API

Use the Public API to connect trusted agents and automations to a Postiv workspace. The API can add knowledge, create document post drafts, schedule text or image posts, list LinkedIn profiles, and read cached analytics.

Authentication

Send the organization API key with either x-api-key or an Authorization bearer token.

curl https://postiv.ai/api/public/workspace \
  -H "Authorization: Bearer pk_postiv_..."

Scopes

Existing knowledge-base keys remain limited to knowledge:write. New keys generated from Settings receive the full set of scopes listed above; use "Regenerate Key (adds new scopes)" in Settings, under Integrations, to explicitly replace a legacy key.

Endpoints

Post Workflow

1. 1. Call GET /api/public/linkedin-profiles and choose an id.
2. 2. Read that profile's writing style and search the knowledge base before drafting original content. Optionally search templates or select a Bob plan item.
3. 3. Call POST /api/public/posts to create a document draft. Pass templateId or planItemId when applicable so attribution stays linked.
4. 4. Optionally patch the draft content or profile assignment.
5. 5. Call POST /api/public/posts/:id/schedule with an ISO scheduled time.

Content is stored verbatim by default. Pass "humanize": true on create to run Postiv's humanizer over the content before saving (the same anti-AI-pattern pass the in-app assistant uses); updates are always verbatim. Scheduling never publishes immediately: scheduledTime must be at least 2 minutes in the future, and if the target profile has approvers configured the post waits for their approval (check requiresApproval in the response). If the post has an image attached in Postiv and you omit mediaType/mediaUrls, the image is included automatically.

Analytics Workflow

Public analytics endpoints are read-only and return cached/imported analytics from Postiv tables. They do not force LinkedIn refreshes. accountId is required: use an account id from GET /api/public/analytics/accounts (each maps to one LinkedIn profile) for per-profile numbers, or accountId=all for an explicit workspace-wide aggregate.

Hosted MCP

The hosted MCP server exposes the same workspace automation surface as the Public API. It uses the same organization API key, the same scopes, and the same server-side services behind the public endpoints. The endpoint is https://postiv.ai/mcp (https://postiv.ai/api/mcp/mcp also works).

In hosts that support MCP Apps, such as claude.ai, tools render interactive widgets instead of plain text: a post editor card, an image preview, a carousel pager, and inspiration cards.

claude.ai (custom connector)

claude.ai custom connectors can only take a URL, they cannot send a header, so the API key goes in the path instead of an Authorization header. Treat this URL as a secret, the same as the key itself.

https://postiv.ai/mcp/pk_postiv_...

1. 1. In claude.ai, go to Settings, then Connectors.
2. 2. Click "Add custom connector".
3. 3. Paste the URL above with your own key in it.

Claude Code

claude mcp add --transport http postiv https://postiv.ai/mcp \
  --header "Authorization: Bearer pk_postiv_..."

Generic Streamable HTTP Client

{
  "postiv": {
    "url": "https://postiv.ai/mcp",
    "headers": {
      "Authorization": "Bearer pk_postiv_..."
    }
  }
}

Claude Desktop With mcp-remote

{
  "mcpServers": {
    "postiv": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://postiv.ai/mcp",
        "--header",
        "Authorization: Bearer pk_postiv_..."
      ]
    }
  }
}