API Keys & REST API

The public REST API lets scripts, AI agents, n8n workflows, Make.com scenarios, and any HTTP client submit promotions and retrieve data without opening the web UI. API keys are scoped to a workspace and managed in SettingsAPI Keys.

Screenshot pending

/help/api-keys/open_api_keys_menu.png

Settings sidebar with API Keys sub-item highlighted

See docs/help-screenshot-manifest.md for capture instructions.

Screenshot pending

/help/api-keys/api_keys_list.png

API Keys page with a table of existing keys showing name, key prefix (masked), scopes, created date, last used, and per-row Rotate/Revoke actions

See docs/help-screenshot-manifest.md for capture instructions.

Creating an API key

Open API Keys settings

Navigate to SettingsAPI Keys. You need Admin or Owner role.

Click Create API key

Enter a name (e.g., "n8n workflow — launch") and select the scopes you need: read, write, or both.

Copy the key immediately

The full key (e.g., pk_live_abc123…) is shown only once. Copy it now and store it in your password manager or secret vault. The UI only ever shows the first 12 characters after this point.

Screenshot pending

/help/api-keys/create_key_dialog.png

Create API key dialog with Name input, scope checkboxes (Read, Write, Admin), and a Sandbox vs Live radio toggle

See docs/help-screenshot-manifest.md for capture instructions.

Screenshot pending

/help/api-keys/key_reveal_once.png

Post-create confirmation screen showing the full plaintext API key in a code block with a large Copy to clipboard button and a red warning that the key won't be shown again

See docs/help-screenshot-manifest.md for capture instructions.

Key types: live vs sandbox

Prefix	Behaviour
pk_live_…	Production key. Real posts go out. Your AI balance is charged for real generation costs.
pk_test_…	Sandbox key. The full pipeline runs (scheduling, targeting rules, variant generation) but connector calls return mock URLs — no real posts go out and your AI balance is not charged.

Always develop and test against a pk_test_ key. Switch to pk_live_ only when you are ready to post for real.

Using the API

Pass your API key in the X-API-Key header with every request:

curl -X POST https://boostpost.ubalitics.com/api/v1/agent/promote-now \
  -H "X-API-Key: pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_text": "Excited to announce our 10k GitHub stars milestone!",
    "audience_template_id": "tmpl_uuid_here"
  }'

The response includes a promotion_id you can poll for status.

Rate limits

Endpoint type	Default limit
Read endpoints (GET)	60 requests / minute per key
Write endpoints (POST)	20 requests / minute per key

When a limit is exceeded the API returns HTTP 429 with a Retry-After header specifying how many seconds to wait.

Idempotency

Add an Idempotency-Key header to any POST request. If you retry the same key within 24 hours (e.g., after a network timeout), the server returns the original response with the header X-Idempotent-Replayed: true — no duplicate promotion is created.

curl -X POST ... \
  -H "Idempotency-Key: $(uuidgen)" \
  ...

Rotating and revoking keys

On any API key row in SettingsAPI Keys:

Rotate — generates a new key and marks the old one as "rotating." The old key continues working for 30 days, giving you time to update it in your integrations. After 30 days it expires automatically.
Revoke — immediately invalidates the key. In-flight requests that have already started may complete, but no new requests are accepted.

Screenshot pending

/help/api-keys/key_row_actions.png

A single API key row with per-row action buttons visible: Rotate (with a small tooltip about 30-day grace), Revoke (in destructive red), and view usage

See docs/help-screenshot-manifest.md for capture instructions.

MCP Server

AI Boost Post exposes a native Model Context Protocol (MCP) server for MCP-compatible clients such as Claude Desktop, Claude Code, and Cursor. The MCP server offers the same 17 tools as the REST API but through the MCP protocol — no HTTP plumbing needed.

Connecting Claude Desktop or Claude Code

// Add to your claude_desktop_config.json or .claude/settings.json:
{
  "mcpServers": {
    "boostpost": {
      "type": "http",
      "url": "https://mcp.boostpost.ubalitics.com",
      "headers": {
        "X-API-Key": "pk_live_YOUR_KEY"
      }
    }
  }
}

Once connected, you can say things like "Promote my latest blog post to the Tech SaaS template" and the agent will call boostpost_promote on your behalf.

Full API documentation is available at docs.boostpost.ubalitics.com — interactive OpenAPI explorer, code samples in curl / Node.js / Python, and ready-to-paste Claude tool definitions.