> ## Documentation Index > Fetch the complete documentation index at: https://docs.social-api.ai/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Base URL: https://api.social-api.ai/v1. Send your API key in the Authorization header: Authorization: Bearer . > Every error response from /v1 is JSON: { "error": { "code", "message", "meta" (optional) }, "request_id" }. Branch on error.code; use error.message only for logs. > A 429 response carries a Retry-After header, in seconds, when the limit has a known wait. > Paginated list endpoints return next_cursor, at the top level or inside pagination (see /guides/pagination). Pass it as the cursor query parameter to get the next page. An absent or empty next_cursor means you have the last page. > Treat every ID as an opaque string: do not parse it or assume a format. > Support differs by platform and by operation. Check /platforms/overview before assuming an operation works on a platform. An unsupported operation returns 501 with error.code resource.not_supported. # Create an Automation > Creates an Automation on an Instagram or Facebook account. When a comment or DM on the account matches its filters, its actions are carried out within seconds, with no code on your side. Each action costs what the same API call costs: reply_comment and send_dm cost 1 credit, private_reply and hide_comment are free. The first step's actions depend on the trigger: a comment trigger allows hide_comment, reply_comment and private_reply; a dm trigger allows send_dm. Steps after start run when the person taps one of your postback buttons, and may only send DMs. An account holds at most 50 Automations. Comments and messages sent by the account itself never trigger it; on Facebook that is the Page, so a Page admin commenting from their personal profile does trigger it. A dm Automation answers the same person at most 5 times an hour. Besides automations:write, a scoped key needs the scope each action's own API call needs: inbox:write for hide_comment, reply_comment and private_reply, dms:send for send_dm. Send follow_gate instead of steps to build a Follow gate: the commenter gets a private reply with a button, and a tap sends the link if they follow the account, otherwise a follow-first message with a button to try again. Instagram only. ## OpenAPI ````yaml /api-reference/openapi.json post /automations openapi: 3.0.0 info: description: >- Unified social media inbox API. Read and respond to comments, DMs, reviews, and mentions across Instagram, Facebook, Threads, Google Business Profile, TikTok, LinkedIn, and YouTube through a single REST API. X/Twitter and Trustpilot coming soon. title: SocialAPI.AI contact: name: SocialAPI.AI Support email: support@social-api.ai license: name: MIT version: '1.0' servers: - url: https://api.social-api.ai/v1 security: [] paths: /automations: post: tags: - Automations summary: Create an Automation description: >- Creates an Automation on an Instagram or Facebook account. When a comment or DM on the account matches its filters, its actions are carried out within seconds, with no code on your side. Each action costs what the same API call costs: reply_comment and send_dm cost 1 credit, private_reply and hide_comment are free. The first step's actions depend on the trigger: a comment trigger allows hide_comment, reply_comment and private_reply; a dm trigger allows send_dm. Steps after start run when the person taps one of your postback buttons, and may only send DMs. An account holds at most 50 Automations. Comments and messages sent by the account itself never trigger it; on Facebook that is the Page, so a Page admin commenting from their personal profile does trigger it. A dm Automation answers the same person at most 5 times an hour. Besides automations:write, a scoped key needs the scope each action's own API call needs: inbox:write for hide_comment, reply_comment and private_reply, dms:send for send_dm. Send follow_gate instead of steps to build a Follow gate: the commenter gets a private reply with a button, and a tap sends the link if they follow the account, otherwise a follow-first message with a button to try again. Instagram only. requestBody: content: application/json: schema: $ref: >- #/components/schemas/social-api_ai_core_api_service.CreateAutomationParams description: Automation definition required: true responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/social-api_ai_core_api_service.Automation' '400': description: >- Invalid definition (validation.*), or a trigger or action needs a permission the account does not have (validation.permission_missing) content: application/json: schema: $ref: '#/components/schemas/api_endpoints.ErrorResponse' '401': description: Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/api_endpoints.ErrorResponse' '403': description: >- The key's scopes do not include automations:write or the scope an action needs content: application/json: schema: $ref: '#/components/schemas/api_endpoints.ErrorResponse' '404': description: Account not found content: application/json: schema: $ref: '#/components/schemas/api_endpoints.ErrorResponse' '409': description: The account already has 50 Automations (automation.limit_reached) content: application/json: schema: $ref: '#/components/schemas/api_endpoints.ErrorResponse' '422': description: >- The account is not on Instagram or Facebook (automation.platform_unsupported) content: application/json: schema: $ref: '#/components/schemas/api_endpoints.ErrorResponse' security: - BearerAuth: [] components: schemas: social-api_ai_core_api_service.CreateAutomationParams: type: object properties: account_id: type: string example: acc_01HZ9X3Q4R5M6N7P8V2K0W1J follow_gate: description: >- Builds the three-step Follow gate. Instagram, comment trigger only. Send instead of steps allOf: - $ref: '#/components/schemas/social-api_ai_core_api_service.FollowGate' name: description: 1 to 100 characters type: string example: Send the link once_per_person: description: >- Reach each person at most once. A run in which every action failed does not count. Defaults to false type: boolean post_ids: description: >- Up to 100 platform post ids, each 1 to 100 characters, a comment must be on. Omitted means every post. Comment trigger only type: array items: type: string steps: type: array items: $ref: '#/components/schemas/social-api_ai_core_api_service.Step' trigger: type: string enum: - comment - dm example: comment social-api_ai_core_api_service.Automation: type: object properties: account_id: type: string example: acc_01HZ9X3Q4R5M6N7P8V2K0W1J created_at: type: string failed_count: description: Actions that failed type: integer fired_count: description: Events the Automation ran against type: integer id: type: string example: aut_01J9Z8Y7X6W5V4T3S2R1Q0P9N8 name: type: string example: Send the link once_per_person: description: >- Reach each person at most once. A run in which every action failed does not count type: boolean post_ids: description: >- Up to 100 platform post ids, each 1 to 100 characters, a comment must be on. Omitted means every post. Comment trigger only type: array items: type: string sent_count: description: Actions carried out successfully type: integer status: type: string enum: - active - paused example: active steps: description: Up to 10 Steps forming a graph. One must have the key "start" type: array items: $ref: '#/components/schemas/social-api_ai_core_api_service.Step' trigger: description: The kind of inbound event that fires the Automation type: string enum: - comment - dm example: comment updated_at: type: string api_endpoints.ErrorResponse: type: object properties: error: $ref: '#/components/schemas/api_endpoints.ErrorBody' social-api_ai_core_api_service.FollowGate: type: object properties: button_title: description: Up to 20 characters type: string example: Get the link keywords: description: Comment keywords that open the gate type: array items: type: string example: - link link_texts: description: Sent once the person follows type: array items: type: string example: - 'Here you go: https://example.com' not_following_texts: description: Sent when the person does not follow the account yet type: array items: type: string example: - Follow us first and tap again opening_texts: description: Private reply sent to the commenter type: array items: type: string example: - Tap below to get the link retry_button_title: description: Up to 20 characters type: string example: I followed social-api_ai_core_api_service.Step: type: object properties: actions: description: At most one of each type type: array items: $ref: '#/components/schemas/social-api_ai_core_api_service.Action' buttons: description: >- Up to 3, shown under the private_reply or send_dm message. With buttons, each of that message's texts is at most 640 characters type: array items: $ref: '#/components/schemas/social-api_ai_core_api_service.StepButton' fallthrough_step: description: >- Key of the Step to run when this Step's filters fail. Not allowed on start type: string filters: description: Up to 10. All must pass. None means every event passes type: array items: $ref: '#/components/schemas/social-api_ai_core_api_service.Filter' key: description: Unique within the Automation. The entry step is "start" type: string example: start api_endpoints.ErrorBody: type: object properties: code: type: string example: resource.not_found message: type: string example: Account not found meta: type: object additionalProperties: {} social-api_ai_core_api_service.Action: type: object properties: private_reply: description: DM to the comment's author. Free allOf: - $ref: '#/components/schemas/social-api_ai_core_api_service.TextAction' reply_comment: description: Public reply to the comment. Costs 1 credit allOf: - $ref: '#/components/schemas/social-api_ai_core_api_service.TextAction' send_dm: description: DM in the conversation. Costs 1 credit allOf: - $ref: '#/components/schemas/social-api_ai_core_api_service.TextAction' type: type: string enum: - hide_comment - reply_comment - private_reply - send_dm example: private_reply social-api_ai_core_api_service.StepButton: type: object properties: next_step: description: >- Key of the Step to run when this button is tapped. Required when type is postback type: string example: check title: description: Up to 20 characters type: string example: Open type: type: string enum: - url - postback example: url url: description: An http or https URL. Required when type is url type: string example: https://example.com social-api_ai_core_api_service.Filter: type: object properties: keyword: description: Required when type is keyword allOf: - $ref: >- #/components/schemas/social-api_ai_core_api_service.KeywordFilter type: description: >- follows_account is available on Instagram only and not on the start step type: string enum: - keyword - follows_account example: keyword social-api_ai_core_api_service.TextAction: type: object properties: texts: description: >- 1 to 10 variants, each 1 to 1000 characters, or at most 640 for a private_reply or send_dm whose step has buttons; one is picked at random each time type: array items: type: string example: - 'Here is the link: https://example.com' social-api_ai_core_api_service.KeywordFilter: type: object properties: keywords: description: 1 to 50, each 1 to 100 characters type: array items: type: string example: - link - price match: description: >- contains: a keyword appears as a whole word or phrase. exact: the whole text equals a keyword type: string enum: - contains - exact example: contains securitySchemes: BearerAuth: description: >- Prefix your API key with "Bearer ". Example: `Authorization: Bearer sapi_key_...` type: apiKey name: Authorization in: header ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.