> For the complete documentation index, see [llms.txt](https://help.blotato.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.blotato.com/start-with-an-ai-agent/llm/overview.md).

# Connection and endpoint index

Choose MCP or REST, verify authentication with a read-only request, and find the supported operations.

Compact reference for agents making REST requests. All endpoint paths below are relative to `https://backend.blotato.com/v2`. For task instructions, read the [workflow guide](/start-with-an-ai-agent/agents.md). For tool calls, use the [MCP reference](/start-with-an-ai-agent/mcp/tools.md).

## Connection

Reuse an authorized connection when available. Verify with `blotato_get_user` or REST `GET /v2/users/me`, then list accounts before selecting a publishing destination. Authentication success is not publication readiness. Keep API keys in credential storage, not in chat or committed files. Follow [authentication and trial requirements](/api-and-mcp-concepts/authentication.md) before creating a key.

```
BLOTATO API REFERENCE
=====================

IMPORTANT: CHECK HOW YOU ARE CONNECTED
- If you have blotato_create_post, blotato_list_accounts, etc. as MCP tools:
  You are connected via MCP. Call those tools directly. You do NOT need HTTP
  endpoints, base URLs, or auth headers. See tool descriptions for parameters.
- If you are making HTTP requests directly (no MCP tools available):
  Use the REST API reference below.

REST API:
Base URL: https://backend.blotato.com/v2
Auth Header: blotato-api-key: YOUR_API_KEY
Content-Type: application/json

API KEY FORMAT: Your key sometimes ends with one or more "=" characters (base64
padding). The "=" is part of the key. Send it exactly. Do not strip, trim, or
URL-encode it. In shells, .env files, and scripts, wrap the key in single quotes
(for example 'abc123=='), to preserve the value.
For a 401, verify the complete key and authentication method. Verify with GET /users/me.

Posts, sources, visuals, comments, and messages use asynchronous completion.
Use each operation's status rules. Presigned upload is a separate request/PUT/URL flow.

```

Continue with the [REST quickstart](/start-with-an-ai-agent/start.md), [OpenAPI reference](/rest-api-reference/openapi-reference.md), or [error reference](/support/errors.md).

## Mcp tool → rest api mapping (for reference only)

This table maps operations, not interchangeable payloads. MCP uses tool arguments and transforms some responses. REST uses its own request wrappers and response shapes. Read [REST versus MCP](/api-and-mcp-concepts/rest-vs-mcp.md) before translating a call.

```
blotato_get_user                    → GET  /users/me
blotato_list_accounts               → GET  /users/me/accounts
blotato_get_credits                 → GET  /credits
blotato_create_post                 → POST /posts
blotato_get_post_status             → GET  /posts/:postSubmissionId
blotato_list_posts                  → GET  /posts
blotato_list_top_posts              → GET  /analytics
blotato_get_post_analytics          → GET  /posts/:id/analytics
blotato_list_comments               → GET  /comments
blotato_get_comment                 → GET  /comments/:commentId
blotato_post_comment                → POST /comments
blotato_list_conversations          → GET  /conversations
blotato_get_conversation            → GET  /conversations/:conversationId
blotato_list_messages               → GET  /messages
blotato_get_message                 → GET  /messages/:messageId
blotato_send_message                → POST /messages
blotato_list_automations            → GET  /dm-automations
blotato_create_automation           → POST /dm-automations
blotato_update_automation           → PATCH /dm-automations/:id
blotato_update_automation_trigger   → PATCH /dm-automations/:flowId/triggers/:triggerId
blotato_delete_automation           → DELETE /dm-automations/:id
blotato_list_automation_runs        → GET  /dm-automations/:id/runs
blotato_list_automation_logs        → GET  /dm-automations/:id/logs
blotato_get_automation_analytics    → GET  /dm-automations/:id/analytics
blotato_create_source               → POST /source-resolutions-v3 (polls internally)
blotato_get_source_status           → GET  /source-resolutions-v3/:id
blotato_list_design_templates       → GET  /videos/templates
blotato_create_design               → POST /videos/from-templates
blotato_get_design_status           → GET  /videos/creations/:id
blotato_list_schedules              → GET  /schedules
blotato_get_schedule                → GET  /schedules/:id
blotato_update_schedule             → PATCH /schedules/:id
blotato_delete_schedule             → DELETE /schedules/:id
blotato_list_pinterest_boards        → GET  /social/pinterest/boards
blotato_create_presigned_upload_url → POST /media/uploads
```

## Rest api endpoints

```
USER INFO & CONNECTED ACCOUNTS
  GET  /users/me              - Verify API key, get user info
  GET  /users/me/usage        - Get connected-account usage, active-contact usage, and active-contact limit
  GET  /users/me/accounts     - List connected social accounts (get accountId)
  GET  /users/me/accounts/:accountId/subaccounts - Get Facebook/LinkedIn Page IDs or YouTube playlist IDs
  GET  /social/pinterest/boards?accountId=ID - List Pinterest boards (get boardId)

CREDITS (billing)
  GET  /credits               - Get credit balance, account email, and pricing (price per 1,000 credits, min/max purchase quantity)
  POST /credits               - Create a Stripe Checkout link to buy credits (quantity 1000-10000). Returns checkoutUrl. Creating the link does NOT charge; a human completes payment in the browser. Confirm the account email first (credits are non-transferable). 10 req/hour

PUBLISHING
  POST /posts                 - Create/publish a post (30 req/min)
  GET  /posts                 - List posts: scheduled/published/failed, cursor-paginated (60 req/min)
  GET  /posts/:postSubmissionId - Poll post status (60 req/min)

TIKTOK STARTER POSTING-DESTINATION LIMIT
  The 3-unique-accounts-per-24-hours error is about accounts POSTED TO, not
  accounts connected. Count distinct TikTok accountId values with successful
  Blotato posts during the rolling previous 24 hours. Posting again to an account
  already in that set does not use another destination slot. A post to a 4th
  accountId fails until one of the prior 3 leaves the window. Connection date is
  irrelevant. Creator and Agency have no 3-destination limit.

ANALYTICS (Published Post Metrics)
  Collected for twitter/instagram/facebook/threads/bluesky/tiktok/youtube/pinterest. LinkedIn returns no metrics yet.
  GET  /analytics              - Top performing published posts (sortBy likes_count/comments_count/views_count/reach_count, default views_count; since/until/platform/limit; Twitter/X comments ranking falls back to replies_count, views ranking falls back to impressions_count)
  GET  /posts/:id/analytics    - Latest metrics + snapshot history for one published post (id = published post id, not postSubmissionId)
  GET  /published-posts        - Search published posts (query/platform) with latest analytics snapshot attached
  Metrics: every field is optional; counts are strings, rates are numbers, breakdowns are objects.

COMMENTS (Instagram, Facebook)
  GET  /comments               - List comments on your Instagram and Facebook posts, cursor-paginated (60 req/min). Filters: postId, parentCommentId, accountId, platform, since, until
  GET  /comments/:commentId    - Get a single comment (60 req/min). Poll to check comment status
  POST /comments               - Post a top-level comment, or a reply when parentCommentId is set, on a published Instagram or Facebook post (30 req/min)

MESSAGING (Instagram, Facebook)
  GET  /conversations          - List direct-message conversations, cursor-paginated (60 req/min)
  GET  /conversations/:conversationId - Get a single conversation (60 req/min)
  GET  /messages               - List messages, cursor-paginated (60 req/min)
  GET  /messages/:messageId    - Get a single message (60 req/min). Poll to check send status
  POST /messages               - Send a direct message or a private reply to a comment, optionally with buttons or quick replies; async, poll GET /messages/:messageId until sent|failed (30 req/min)

DM AUTOMATIONS (Instagram, Facebook)
  PLATFORM BOUNDARY: TikTok publishing, scheduling, and repurposing automation do not provide TikTok DM automation. TikTok DM automations are not supported. DM automations support Instagram and Facebook only.
  TESTING: Own comments never trigger an automation. Test comment-received from a different Instagram or Facebook account.
  GET  /dm-automations         - List DM automations, cursor-paginated (60 req/min)
  GET  /dm-automations/:id     - Get a single DM automation (60 req/min)
  POST /dm-automations         - Create a DM automation (30 req/min)
  PATCH /dm-automations/:id    - Update a DM automation; body is { "patch": { ... } } (30 req/min)
  PATCH /dm-automations/:flowId/triggers/:triggerId - Update a single trigger; body is { "patch": { "isActive": true|false } } (30 req/min)
  DELETE /dm-automations/:id   - Archive a DM automation; returns 200 with the archived flow (30 req/min)
  GET  /dm-automations/:id/runs      - List execution runs, cursor-paginated (60 req/min)
  GET  /dm-automations/:id/logs      - List execution logs, cursor-paginated; filter with flowRunId (60 req/min)
  GET  /dm-automations/:id/analytics - All-time run totals (60 req/min)

VISUALS
  POST /videos/from-templates - Create visual from template (30 req/min)
  GET  /videos/creations/:id  - Poll visual status
  GET  /videos/templates      - List available templates
  DELETE /videos/:id          - Delete a video

SOURCES (Content Extraction)
  POST /source-resolutions-v3 - Extract content from URL/text (30 req/min)
  GET  /source-resolutions-v3/:id - Poll source status (60 req/min)

SCHEDULES (Content Calendar)
  GET  /schedules              - List future scheduled posts (cursor-paginated)
  GET  /schedules/:id          - Get a single scheduled post
  PATCH /schedules/:id         - Update scheduled post (content and/or time)
  DELETE /schedules/:id        - Delete scheduled post and cancel publishing job

SCHEDULE SLOTS (Recurring Time Windows)
  GET  /schedule/slots         - List all scheduling slots
  POST /schedule/slots         - Create one or more slots
  PATCH /schedule/slots/:id    - Update slot targets (platforms/accounts)
  DELETE /schedules/slots/:id  - Delete a slot
  POST /schedule/slots/next-available - Find next open slot for a platform/account

MEDIA
  POST /media                 - Upload media from URL (30 req/min, optional)
  POST /media/uploads          - Get presigned upload URL for local files (120 req/min)
```

For metric names and availability, use [Analytics metrics](/rest-api-reference/analytics/analytics-metrics.md). For ID selection and optional playlists, use [Accounts and identifiers](/api-and-mcp-concepts/accounts-and-identifiers.md).

Return to the [agent reference index](/start-with-an-ai-agent/llm.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.blotato.com/start-with-an-ai-agent/llm/overview.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.