# Aback Social full documentation for AI agents This document is the complete reference for the Aback Social agent surfaces. It covers the MCP server, the public REST API, the API key lifecycle and the scope model. ## 1. What Aback Social does Aback Social is an AI native social media workspace. A workspace connects social accounts, creates posts with per network text, threads and first comments, plans them on a calendar and in queues, routes them through an approval workflow bound to the exact version when the workspace requires approval, and publishes them through each network's official API. Every account, post, approval and metric is scoped to one workspace, and an API key acts only in its own workspace with its own scopes. ## 2. Authentication Send the API key as a bearer token in the Authorization header: Authorization: Bearer absk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx Keys are never accepted in the URL, because URLs end up in logs and browser history. An API key is a 32 character base62 secret behind the `absk_` prefix. The plaintext value is returned exactly once, when the key is created. Only a SHA-256 hash is stored, so a key cannot be recovered from the database and has to be rotated if it leaks. Failed authentication returns HTTP 401 with a JSON-RPC error whose code is `-32001`. ## 3. Scopes Every MCP tool declares exactly one required scope. A call whose key does not carry that scope is rejected with the JSON-RPC error code `-32002`. A key created without explicit scopes receives the read only default set. - posts:read: Read posts and drafts - posts:write: Create and edit posts - publish:write: Publish posts - accounts:read: Read connected accounts - accounts:write: Manage connected accounts - analytics:read: Read analytics - calendar:read: Read the content calendar - calendar:write: Write to the content calendar - approvals:read: Read the approval inbox - approvals:write: Submit posts for approval - billing:read: Read plan and quota usage - media:read: Read the media library - media:write: Upload and edit media - automation:read: Read queues, ideas, feeds and webhooks - automation:write: Manage queues, ideas, feeds and webhooks Read only default scopes: posts:read, accounts:read, analytics:read, calendar:read, approvals:read, billing:read. ## 4. The MCP server Endpoint: POST https://abacksocial.com/api/mcp Transport: Streamable HTTP. Every exchange is a JSON-RPC 2.0 message with the content type application/json. The deprecated HTTP plus SSE transport is not supported. A GET request is answered with HTTP 405. Supported methods: - initialize. Returns the protocol version, the server capabilities and the server info. - notifications/initialized. A notification. It never returns a body. - ping. Returns an empty result. - tools/list. Returns every tool with its JSON Schema. - tools/call. Runs a tool. Initialize result: { "protocolVersion": "2025-06-18", "capabilities": { "tools": { "listChanged": false } }, "serverInfo": { "name": "aback-social", "version": "1.0.0" } } Example request: curl -X POST https://abacksocial.com/api/mcp \ -H "Authorization: Bearer absk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' Tool results are returned as structured content. The payload is a JSON document in the text field. { "content": [ { "type": "text", "text": "{ \"posts\": [...] }" } ] } A domain failure, such as an unknown post or a missing approval, is reported as a result with `isError: true` and a message that explains what to do next. It is not a protocol error, so the agent can read the message and correct itself. Rate limiting: 120 calls per minute per API key. Exceeding the limit returns HTTP 429 with the JSON-RPC error code `-32003`. ## 5. MCP tools ### list_connected_accounts List the social accounts connected to the workspace, including platform, handle, follower count and connection health. Required scope: accounts:read Arguments: - platform (optional): string. Optional platform filter, for example instagram, linkedin, twitter, facebook, reddit, bluesky or google_business. - includeInactive (optional): boolean. Set to true to include disconnected accounts. Defaults to false. ### list_posts List the posts in the workspace with optional lifecycle status filtering. Drafts, scheduled posts, published posts and failed posts are all returned. Required scope: posts:read Arguments: - status (optional): string. Optional lifecycle status filter: draft, pending_approval, approved, scheduled, posted, failed or partial. - limit (optional): integer. Maximum number of posts to return. Defaults to 25. ### create_post Create a draft post for one or more connected accounts. Supply a scheduledFor timestamp to schedule it straight away, otherwise the post is saved as a draft. Required scope: posts:write Arguments: - content: string. The post body. Up to 5000 characters. - socialAccountIds (optional): array. Ids of the connected accounts to publish to. At least one is required. - scheduledFor (optional): string. Optional ISO 8601 timestamp. Must be in the future. The post is scheduled when it is supplied. - tone (optional): string. Optional tone label stored with the post, for example friendly or bold. - customHashtags (optional): array. Optional hashtags stored with the post. ### update_post Update the content of a post that has not been published yet. Editing a team post creates a new version that has to be approved again. Required scope: posts:write Arguments: - postId: string. The id of the post to update. - content: string. The new post body. Up to 5000 characters. - tone (optional): string. Optional tone label stored with the post. - customHashtags (optional): array. Optional hashtags stored with the post. ### schedule_post Set the publication time of a post. The timestamp must be in the future. Team workspaces with an approval policy require the post version to be approved first. Required scope: calendar:write Arguments: - postId: string. The id of the post to schedule. - scheduledFor: string. ISO 8601 timestamp for the publication time. ### publish_post Publish an approved or scheduled post. Use preflight to check that every target is ready before publishing, and execute_now to publish immediately. Required scope: publish:write Arguments: - postId: string. The id of the post to publish. - mode (optional): preflight | execute_now. preflight validates the post and its targets. execute_now publishes immediately. Defaults to preflight. ### get_post_analytics Read the performance of a published post, including impressions, reach, engagement and the latest snapshot per platform. Required scope: analytics:read Arguments: - postId: string. The id of the post to analyse. ### list_calendar_posts List the posts scheduled inside a date range. Both bounds are inclusive and are given as ISO 8601 timestamps. Required scope: calendar:read Arguments: - from: string. Start of the range as an ISO 8601 timestamp. - to: string. End of the range as an ISO 8601 timestamp. - limit (optional): integer. Maximum number of posts to return. Defaults to 100. ### submit_post_for_approval Send a draft post into the team approval workflow. Needs an API key created in the team workspace the post belongs to. Required scope: approvals:write Arguments: - postId: string. The id of the post to submit. - teamId (optional): string. Optional team id. Required when the API key is not scoped to a team and the post has no team. - note (optional): string. Optional note for the reviewers. ### list_pending_approvals List the posts that are waiting for approval in the API key's team workspace. Required scope: approvals:read Arguments: - teamId (optional): string. The team to read. Optional when the API key is already scoped to a team. - status (optional): string. Optional status filter: pending, approved, rejected, changes_requested or cancelled. Defaults to pending. - limit (optional): integer. Maximum number of requests to return. Defaults to 50. ### get_account_health Read the connection health of the connected social accounts. Accounts that need to be reconnected are reported with a reason. Required scope: accounts:read Arguments: - platform (optional): string. Optional platform filter. ### get_usage_and_quota Read the workspace's plan and its monthly usage (X posts, X posts with links, AI credits) against the plan's allowances. Required scope: billing:read Arguments: - no arguments ## 6. The public REST API All endpoints answer with the same envelope. Success: { "success": true, "data": { ... } } Failure: { "success": false, "error": "Human readable message", "code": "MACHINE_READABLE_CODE" } The session cookie API is used by the product UI. The endpoints below are the ones that are relevant to an agent and can be reached with an API key where an agent session is not required. ### GET /api/posts Lists the posts of the workspace. Query parameters: status, page, limit, and from and to (ISO dates) to select the posts scheduled or published in a time window, as the calendar does. ### POST /api/posts Creates a post. Body: content, socialAccountIds, scheduledFor, media, tone, customHashtags. ### GET /api/posts/{id} Reads a single post. ### PUT /api/posts/{id} Updates a post. Body: content, socialAccountIds, platforms, scheduledFor, media, tone, customHashtags, status. ### POST /api/posts/{id}/publish Runs a publish preflight or publishes immediately. Body: mode, where mode is preflight or execute_now. ### GET /api/social/accounts Lists the connected accounts of the caller. ### GET /api/analytics Aggregated analytics for the workspace, from the metrics each network's API provides. A metric a network does not report is missing, not zero. ### GET /api/analytics/{postId} Analytics for a single post, where the network's API provides them. ### GET /api/approvals/inbox The approval requests of the workspace the key belongs to. Query: view (pending, the default, oldest first; or history, newest first), cursor (the nextCursor of the previous page) and limit (1 to 100, default 25). Each item has the post preview, its accounts and time, the submitter, the decisions so far, approvals given and needed, and what the caller may do. A personal workspace answers available: false, because approvals are for team workspaces. ### GET /api/posts/{id}/approval The approval state of a post: whether its workspace's policy requires a review for its path (scheduled or publish now), the current request with its decisions, and whether the post changed after approval. ### POST /api/posts/{id}/approval/submit, /approve, /reject, /request-changes, /cancel Submit a post for review, decide on it, or withdraw it. Decisions take comment, requestId and expectedPostVersion. The workspace policy sets who may submit and review, how many different reviewers must approve (1 to 10) and whether the submitter may approve their own post. A change to the text, media, accounts or time after submission or approval invalidates it. ### POST /api/api-keys Creates an API key. Body: name, scopes, teamId, expiresAt. The response contains the plaintext key exactly once. ### GET /api/api-keys Lists the API keys of the caller. Key hashes are never returned. ### DELETE /api/api-keys/{id} Revokes an API key. Revocation is permanent. ## 7. Tenant isolation An API key belongs to exactly one user and, optionally, to exactly one team. - A key without a team only ever reads and writes the rows that its owner owns. - A key with a team additionally reaches the rows of that team, and only while the owner is an active member of the team. - A resource that belongs to another tenant is reported as missing, so ids cannot be probed. - Connected account tokens are never returned by any tool or endpoint. ## 8. Errors | Code | Meaning | | --- | --- | | -32700 | The request body is not valid JSON. | | -32600 | The message is not a valid JSON-RPC 2.0 request. | | -32601 | The method does not exist. | | -32602 | The parameters are invalid, for example an unknown tool. | | -32603 | The server failed to handle the request. | | -32001 | The API key is missing, unknown, revoked or expired. | | -32002 | The API key does not have the scope the tool requires. | | -32003 | The rate limit for the key is exhausted. | ## 9. Support Contact: support@abacksocial.com Security reports: support@abacksocial.com