REST API v1 & MCP Protocol • 2026 Standard

REST API v1 & Model Context Protocol (MCP) Documentation

Manage brands, generate AI content, schedule cross-platform posts across 15 networks, and integrate OperPilot into Claude Desktop, Cursor AI, Make.com, or your backend.

Production API Base URL:

https://app.operpilot.com/api/v1

Authentication (API Key)

All HTTP requests require a secret API key passed in the Authorization header as a Bearer token. Generate keys inside your account dashboard.

Rate Limits

Default rate limit is 60 requests per minute per API key. Exceeding limits triggers an HTTP 429 Too Many Requests response with a Retry-After header.

MCP Protocol

Model Context Protocol (MCP)

Connect OperPilot directly to Claude Desktop, Cursor AI, or any MCP-compatible agent. The AI automatically gains access to 12 publishing tools.

Claude Desktop Configuration

claude_desktop_config.json

{
  "mcpServers": {
    "operpilot": {
      "command": "node",
      "args": ["-e", "fetch('https://app.operpilot.com/operpilot-mcp.mjs').then(r=>r.text()).then(eval)"],
      "env": {
        "OPERPILOT_API_KEY": "op_live_YOUR_API_KEY"
      }
    }
  }
}

Cursor AI Configuration (.cursor/mcp.json)

.cursor/mcp.json

{
  "mcpServers": {
    "operpilot": {
      "command": "node",
      "args": ["-e", "fetch('https://app.operpilot.com/operpilot-mcp.mjs').then(r=>r.text()).then(eval)"],
      "env": {
        "OPERPILOT_API_KEY": "op_live_YOUR_API_KEY"
      }
    }
  }
}

OperPilot 12 MCP Tools

When connected, your AI assistant receives immediate access to these 12 tools via natural language instructions.

get_profile

MCP Tool

Brand DNA: business profile, industry, target customer persona, Brand Voice, visual guidelines and color palette — AI context.

Example prompt in Claude / Cursor:

“Fetch my brand profile and tell me what tone of voice I should use for posts.”

Returns: Object: { name, description, industry, targetAudience, brandVoice, visualGuidelines, primaryColors, website }

connected_accounts

MCP Tool

Active publishing channels: complete list of connected social profiles (across 15 platforms) ready for immediate or scheduled delivery.

Example prompt in Claude / Cursor:

“Which social media accounts are currently connected in my OperPilot?”

Returns: Array of { id, platform, name, accountType, isConnected, avatarUrl }

generate_post

MCP Tool

AI Copywriter: generates engaging post copy with hashtags in 7 languages (PL, EN, DE, ES, FR, IT, UK) matched to brand voice and channel.

Example prompt in Claude / Cursor:

“Write a LinkedIn post about the benefits of automated social media publishing.”

Parameter	Type	Required	Description
topic	string	Required	Post topic, goal, or promotional message.
language	string	Optional	Language code ('pl', 'en', 'de', 'es', 'fr', 'it', 'uk'). Default 'pl'.
platform	string	Optional	Target social network (e.g. 'facebook', 'instagram', 'linkedin').
tone	string	Optional	Tone override (e.g. 'expert', 'casual', 'storytelling').

Returns: Object: { content, hashtags, suggestedPlatform, charCount }

generate_ideas

MCP Tool

Strategic ideas generator: delivers a batch of fresh post concepts and angles tailored to your industry and audience.

Example prompt in Claude / Cursor:

“Suggest 5 educational post ideas for my industry for the coming week.”

Parameter	Type	Required	Description
topic	string	Optional	Optional topic area (e.g. 'autumn sale', 'product launch').
locale	string	Optional	Language of the generated ideas (default 'pl').

Returns: Object: { ideas: Array<{ title, angle, targetFormat, hook }> }

translate_post

MCP Tool

Multilingual localisation: translates and adapts posts for 7 European markets preserving tone and natural native phrasing.

Example prompt in Claude / Cursor:

“Translate this post into German keeping a friendly, engaging tone.”

Parameter	Type	Required	Description
text	string	Required	Original post text to translate.
target_language	string	Required	Target language code ('pl', 'en', 'de', 'es', 'fr', 'it', 'uk').

Returns: Object: { translatedText, targetLanguage, notes }

create_post

MCP Tool

Post creator: creates a post in OperPilot, attaches channels, and optionally schedules for automatic broadcast or publishes immediately.

Example prompt in Claude / Cursor:

“Create a post titled 'New Release' and schedule it for tomorrow at 10:00 AM on Facebook and LinkedIn.”

Parameter	Type	Required	Description
title	string	Required	Draft title or headline.
content	string	Required	Full post body text with hashtags.
platforms	array	Optional	Target platforms list (e.g. ['facebook', 'linkedin']).
scheduled_at	string	Optional	ISO publication timestamp. Omit for draft.
publish_now	boolean	Optional	Set to true to publish immediately to all assigned channels.

Returns: Object: { id, title, status, scheduledAt, platforms }

list_posts

MCP Tool

Posts schedule & registry: browse posts filtered by status: draft, scheduled, published, failed.

Example prompt in Claude / Cursor:

“Show me the next 5 scheduled posts in my calendar.”

Parameter	Type	Required	Description
status	string	Optional	Status filter ('draft', 'scheduled', 'published', 'failed').
limit	number	Optional	Max posts count (default 20, max 50).

Returns: Array of { id, title, content, status, scheduledAt, platforms, createdAt }

schedule_post

MCP Tool

Calendar scheduler: reschedules or assigns a publication date and time for an existing post.

Example prompt in Claude / Cursor:

“Reschedule post ID 8f7e... to next Friday at 6:00 PM.”

Parameter	Type	Required	Description
post_id	string	Required	Post identifier (UUID).
scheduled_at	string	Required	New emission timestamp in ISO format.

Returns: Object: { id, status: 'scheduled', scheduledAt }

publish_post

MCP Tool

Instant broadcast: sends an existing post for concurrent immediate delivery across all assigned channels.

Example prompt in Claude / Cursor:

“Publish this post right now to all connected profiles.”

Parameter	Type	Required	Description
post_id	string	Required	Post identifier (UUID) to publish.

Returns: Object: { id, status: 'published', publishedAt, results }

delete_post

MCP Tool

Post removal: permanently deletes a post and cancels its queued delivery jobs.

Example prompt in Claude / Cursor:

“Delete draft post with ID b4c1...”

Parameter	Type	Required	Description
post_id	string	Required	Post identifier (UUID) to delete.

Returns: Object: { success: true, deletedId }

analytics

MCP Tool

Analytics centre: aggregated metrics of impressions, reach, reactions, and comments broken down by platform.

Example prompt in Claude / Cursor:

“What are our publication metrics and reach over the past 30 days?”

Returns: Object: { summary: { totalImpressions, totalEngagements, totalLikes }, platforms: { ... } }

list_brands

MCP Tool

Brand manager: list all brands/clients within the workspace (available in Pro and Business tiers).

Example prompt in Claude / Cursor:

“List all brands configured under my OperPilot account.”

Returns: Array of { id, name, industry, isDefault }

REST API

REST API v1 Reference

For direct HTTP integrations with custom applications, backend architectures, cron jobs, or no-code engines (Make.com, n8n, Zapier).

Base URL:https://app.operpilot.com/api/v1

GET

/profile

Get Brand Profile & Voice

Returns full brand profile guidelines: name, industry, description, target audience, brand voice, and color palette.

curl -X GET "https://app.operpilot.com/api/v1/profile" \
  -H "Authorization: Bearer op_live_YOUR_API_KEY" \
  -H "Accept: application/json"

Sample Response (HTTP 200 OK):

200 OK • JSON

{
  "profile": {
    "name": "Acme Software",
    "description": "Platforma automatyzacji AI dla e-commerce i marketingu B2B.",
    "industry": "Software / B2B SaaS",
    "targetAudience": "Właściciele sklepów internetowych, menedżerowie marketingu",
    "brandVoice": "Profesjonalny, oparty na faktach, technologiczny",
    "website": "https://example.com"
  }
}

GET

/channels

List Connected Social Channels

Returns connected accounts across 15 supported platforms ready for post dispatch.

curl -X GET "https://app.operpilot.com/api/v1/channels" \
  -H "Authorization: Bearer op_live_YOUR_API_KEY" \
  -H "Accept: application/json"

Sample Response (HTTP 200 OK):

200 OK • JSON

{
  "channels": [
    {
      "id": "conn_91f8a2b3",
      "platform": "facebook",
      "name": "Acme Fanpage",
      "isConnected": true
    },
    {
      "id": "conn_44c21e7d",
      "platform": "linkedin",
      "name": "Acme Corporate",
      "isConnected": true
    }
  ]
}

GET

/posts

List Posts & Schedule

Fetches paginated posts with optional status filtering.

Parameter	Type	Required	Description
status	string (query)	Optional	Filter by status: 'draft', 'scheduled', 'published', 'failed'.
limit	number (query)	Optional	Max items (default 20, max 50).

curl -X GET "https://app.operpilot.com/api/v1/posts" \
  -H "Authorization: Bearer op_live_YOUR_API_KEY" \
  -H "Accept: application/json"

Sample Response (HTTP 200 OK):

200 OK • JSON

{
  "posts": [
    {
      "id": "c7a84e12-4215-4ff1-a8bc-19b841e42109",
      "title": "Nowości w ofercie",
      "status": "scheduled",
      "scheduledAt": "2026-10-25T14:00:00.000Z",
      "platforms": ["facebook", "linkedin"]
    }
  ]
}

POST

/posts

Create Post (Draft, Schedule, or Instant Publish)

Creates a post record, attaches target platforms, and optionally schedules emission or broadcasts immediately.

Parameter	Type	Required	Description
title	string	Required	Title of the post.
content	string	Required	Full body copy text including hashtags.
platforms	array	Optional	Array of platform slugs (e.g. ['facebook', 'linkedin']).
scheduled_at	string	Optional	ISO date for scheduled broadcast. Omit for draft.
publish_now	boolean	Optional	Set true to broadcast concurrently right away.

curl -X POST "https://app.operpilot.com/api/v1/posts" \
  -H "Authorization: Bearer op_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Nowy post z API",
    "content": "Właśnie publikujemy ten wpis automatycznie przez OperPilot REST API v1 🚀",
    "platforms": ["facebook", "linkedin"],
    "publish_now": true
  }'

Sample Response (HTTP 200 OK):

200 OK • JSON

{
  "success": true,
  "post": {
    "id": "c7a84e12-4215-4ff1-a8bc-19b841e42109",
    "title": "Nowy post z API",
    "status": "scheduled",
    "scheduledAt": "2026-10-25T14:00:00.000Z",
    "platforms": ["facebook", "linkedin"]
  }
}

GET

/posts/:id

Get Post Details & Dispatch Status

Fetches a single post including target-specific delivery logs and remote platform post IDs.

Parameter	Type	Required	Description
id	string (path)	Required	Post identifier (UUID).

curl -X GET "https://app.operpilot.com/api/v1/posts/c7a84e12-4215-4ff1-a8bc-19b841e42109" \
  -H "Authorization: Bearer op_live_YOUR_API_KEY" \
  -H "Accept: application/json"

Sample Response (HTTP 200 OK):

200 OK • JSON

{
  "post": {
    "id": "c7a84e12-4215-4ff1-a8bc-19b841e42109",
    "title": "Jak automatyzacja oszczędza czas?",
    "status": "published",
    "targets": [
      { "platform": "facebook", "status": "published", "remotePostId": "fb_123456" },
      { "platform": "linkedin", "status": "published", "remotePostId": "urn:li:share:789" }
    ]
  }
}

PATCH

/posts/:id

Update or Reschedule Post

Allows modifying post content, title, or updating scheduled publication timestamp.

Parameter	Type	Required	Description
id	string (path)	Required	Post identifier (UUID).
title	string	Optional	Updated title.
content	string	Optional	Updated content.
scheduled_at	string	Optional	New emission timestamp in ISO format.

curl -X PATCH "https://app.operpilot.com/api/v1/posts/c7a84e12-4215-4ff1-a8bc-19b841e42109" \
  -H "Authorization: Bearer op_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scheduled_at": "2026-10-25T16:00:00.000Z"
  }'

Sample Response (HTTP 200 OK):

200 OK • JSON

{
  "success": true,
  "post": {
    "id": "c7a84e12-4215-4ff1-a8bc-19b841e42109",
    "status": "scheduled",
    "scheduledAt": "2026-10-25T16:00:00.000Z"
  }
}

DELETE

/posts/:id

Delete Post

Permanently deletes a post and cancels its queued emission tasks.

Parameter	Type	Required	Description
id	string (path)	Required	Post identifier (UUID).

curl -X DELETE "https://app.operpilot.com/api/v1/posts/c7a84e12-4215-4ff1-a8bc-19b841e42109" \
  -H "Authorization: Bearer op_live_YOUR_API_KEY"

Sample Response (HTTP 200 OK):

200 OK • JSON

{
  "success": true,
  "message": "Post został pomyślnie usunięty."
}

GET

/analytics

Publication Metrics & Analytics

Returns aggregated metrics for impressions, engagement, likes, and comments across platforms.

curl -X GET "https://app.operpilot.com/api/v1/analytics" \
  -H "Authorization: Bearer op_live_YOUR_API_KEY" \
  -H "Accept: application/json"

Sample Response (HTTP 200 OK):

200 OK • JSON

{
  "analytics": {
    "totalImpressions": 24500,
    "totalEngagements": 1820,
    "totalLikes": 1240,
    "totalComments": 185,
    "totalShares": 95,
    "byPlatform": {
      "facebook": { "impressions": 12000, "engagements": 920 },
      "linkedin": { "impressions": 8500, "engagements": 650 },
      "instagram": { "impressions": 4000, "engagements": 250 }
    }
  }
}

GET

/brands

List Workspace Brands

Returns all configured brands/clients associated with your workspace account (Pro & Business plans).

curl -X GET "https://app.operpilot.com/api/v1/brands" \
  -H "Authorization: Bearer op_live_YOUR_API_KEY" \
  -H "Accept: application/json"

Sample Response (HTTP 200 OK):

200 OK • JSON

{
  "brands": [
    {
      "id": "brand_01a",
      "name": "Acme Software",
      "industry": "IT & Automation",
      "isDefault": true
    }
  ]
}

AI Engine

AI Engine in 7 Languages (Generation, Ideas, Translation)

Native AI endpoints optimized for multi-platform copywriting and cultural localization across 15 networks respecting your Brand Voice.

POST

/ai/generate

AI Post Generation (7 Languages)

Generates tailored post copy in any of 7 languages adhering to Brand Voice with hashtags and tips.

Parameter	Type	Required	Description
topic	string	Required	Topic, campaign goal or key message.
language	string	Optional	Language code ('pl', 'en', 'de', 'es', 'fr', 'it', 'uk'). Default 'pl'.
platform	string	Optional	Target platform.
tone	string	Optional	Tone of voice override.

curl -X POST "https://app.operpilot.com/api/v1/ai/generate" \
  -H "Authorization: Bearer op_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "Wprowadzenie automatyzacji social media w firmie",
    "language": "en",
    "platform": "linkedin",
    "tone": "expert"
  }'

Sample Response (HTTP 200 OK):

200 OK • JSON

{
  "content": "Czy wiesz, że regularność w publikacji to klucz do algorytmów social media? 🚀\n\nOto 3 kroki, jak zautomatyzować publikacje bez utraty jakości...",
  "hashtags": ["#marketing", "#automatyzacja", "#socialmedia", "#productivity"],
  "language": "pl",
  "characterCount": 420
}

POST

/ai/ideas

Strategic Ideas & Concepts Generator

Delivers a structured set of post ideas, hooks, and content angles tailored to your brand niche.

Parameter	Type	Required	Description
topic	string	Optional	Optional topic or campaign focus.
locale	string	Optional	Language of the generated ideas.

curl -X POST "https://app.operpilot.com/api/v1/ai/ideas" \
  -H "Authorization: Bearer op_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "Marketing tips",
    "locale": "en"
  }'

Sample Response (HTTP 200 OK):

200 OK • JSON

{
  "ideas": [
    {
      "title": "5 błędów w planowaniu postów, które obcinają zasięg",
      "angle": "Post edukacyjny / checklista",
      "targetFormat": "Karuzela lub wątek",
      "hook": "Robisz to co tydzień? Algorytmy tego nie lubią..."
    }
  ]
}

POST

/ai/translate

Post Translation & Cultural Localisation

Translates and culturally adapts post copy into 7 European languages maintaining brand voice nuances.

Parameter	Type	Required	Description
text	string	Required	Post text to translate.
target_language	string	Required	Target language ('pl', 'en', 'de', 'es', 'fr', 'it', 'uk').

curl -X POST "https://app.operpilot.com/api/v1/ai/translate" \
  -H "Authorization: Bearer op_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Nasz nowy produkt jest już dostępny w sprzedaży!",
    "target_language": "de"
  }'

Sample Response (HTTP 200 OK):

200 OK • JSON

{
  "translatedText": "Did you know that consistency is the #1 factor in social media reach? 🚀\n\nHere are 3 ways to automate your schedule while keeping human touch...",
  "targetLanguage": "en"
}

Error Codes & Rate Limits

OperPilot API adheres to standard HTTP status codes. All 4xx and 5xx responses deliver a structured JSON payload with error details.

HTTP Code	Name	Meaning & Resolution
200 OK	Success	Request succeeded.
201 Created	Created	Resource (e.g. post) successfully created.
400 Bad Request	Invalid Request	Missing or invalid payload fields.
401 Unauthorized	Unauthorized	Missing or invalid API key in Authorization header.
403 Forbidden	Forbidden	Key is revoked or lacks required scopes.
404 Not Found	Not Found	Specified post or resource not found.
429 Too Many Requests	Rate Limited	Rate limit exceeded (60 req/min). Please back off.
500 Internal Error	Server Error	Internal error. Contact support at kontakt@operpilot.com.

No-Code Automation (Make.com, Zapier, n8n)

Easily integrate OperPilot into Make.com, Zapier, or n8n workflows using standard HTTP request modules:

Configuration steps in Make.com:

Add an HTTP -> Make a request module.
Set URL: https://app.operpilot.com/api/v1/posts and Method: POST.
Add Headers: Authorization = Bearer op_live_YOUR_KEY and Content-Type = application/json.
Select Raw -> JSON Body and provide title, content, platforms, and publish_now parameters.