Aidelly AI Automations API

openapi: 3.2.0
info:
  title: Aidelly Public Automations API
  version: 1.1.0
  x-versioning-policy: https://www.aidelly.ai/developers/api/deprecation
  description: 'Customer-facing API for publishing and scheduling social posts through Aidelly.

    All responses use `{ success, data | error, request_id }`.


    This API is optimized for single-user project integrations and AI agents:

    - deterministic error codes

    - required idempotency on writes

    - plan-aware rate-limit headers on authenticated responses'
servers:
- url: https://app.aidelly.ai/api/public/v1
security:
- bearerAuth: []
tags:
- name: Automations
paths:
  /content-automations:
    get:
      tags:
      - Automations
      summary: List content automations
      operationId: listContentAutomations
      responses:
        '200':
          $ref: '#/components/responses/UsageEnvelopeResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '429':
          $ref: '#/components/responses/RateLimitedResponse'
        '500':
          $ref: '#/components/responses/InternalErrorResponse'
      x-tool-name: aidelly_get_content_automations
      x-scope: automations:read
      x-tool-description: List saved content automation rules for the selected workspace. Returns rule configuration and activity state; follow next_cursor for additional pages. Does not run or change rules.
      parameters:
      - in: query
        name: cursor
        description: Opaque cursor from a previous response's `next_cursor`. Treat it as opaque; its encoding is not part of the contract. Omit to start at the first page. When both `cursor` and offset-style parameters are sent, the cursor wins.
        schema:
          type: string
          maxLength: 512
      security:
      - bearerAuth: []
      - oauth2:
        - automations:read
      description: List saved content automation rules for the selected workspace. Returns rule configuration and activity state; follow next_cursor for additional pages. Does not run or change rules.
    post:
      tags:
      - Automations
      summary: Create content automation
      operationId: createContentAutomation
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        description: 'Content automation rule. `trigger_type` defaults to `schedule`. Set it to `youtube_repurpose` to create a standing repurposing rule (#1891): put the whole definition in `source_config` as `{ source: { platform: "youtube", connectionId, channelId }, destinations: [{ platform, accountId }], skipHashtags: [], autoPublish: bool, aiOptimize: bool, includeImages: bool }`. `platforms`, `platform_account_ids`, `auto_approve` and `include_media` are then derived from `source_config` and any values sent for them are ignored.'
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          $ref: '#/components/responses/UsageEnvelopeResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '409':
          $ref: '#/components/responses/ConflictResponse'
        '429':
          $ref: '#/components/responses/RateLimitedResponse'
        '500':
          $ref: '#/components/responses/InternalErrorResponse'
      x-tool-name: aidelly_create_content_automation
      x-tool-aliases:
      - aidelly_post_content_automations
      x-scope: automations:write
      x-tool-description: 'Create a content automation rule from the configuration in body. Supports scheduled content generation and YouTube repurposing rules. Active rules generate content and can schedule or publish it according to their approval settings; returns the saved rule. Retry-safe: a repeat call with the same idempotency_key returns the original result.'
      security:
      - bearerAuth: []
      - oauth2:
        - automations:write
      description: 'Create a content automation rule from the configuration in body. Supports scheduled content generation and YouTube repurposing rules. Active rules generate content and can schedule or publish it according to their approval settings; returns the saved rule. Retry-safe: a repeat call with the same idempotency_key returns the original result.'
  /content-automations/{id}:
    get:
      tags:
      - Automations
      summary: Get content automation
      operationId: getContentAutomation
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          $ref: '#/components/responses/UsageEnvelopeResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '429':
          $ref: '#/components/responses/RateLimitedResponse'
        '500':
          $ref: '#/components/responses/InternalErrorResponse'
      x-tool-name: aidelly_get_content_automation
      x-tool-aliases:
      - aidelly_get_content_automations_id
      x-scope: automations:read
      x-tool-description: Read one saved content automation rule by id, including its configuration. Read-only. It does not run the automation.
      security:
      - bearerAuth: []
      - oauth2:
        - automations:read
      description: Read one saved content automation rule by id, including its configuration. Read-only. It does not run the automation.
    put:
      tags:
      - Automations
      summary: Update content automation
      operationId: updateContentAutomation
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        description: 'Content automation rule. `trigger_type` defaults to `schedule`. Set it to `youtube_repurpose` to create a standing repurposing rule (#1891): put the whole definition in `source_config` as `{ source: { platform: "youtube", connectionId, channelId }, destinations: [{ platform, accountId }], skipHashtags: [], autoPublish: bool, aiOptimize: bool, includeImages: bool }`. `platforms`, `platform_account_ids`, `auto_approve` and `include_media` are then derived from `source_config` and any values sent for them are ignored.'
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          $ref: '#/components/responses/UsageEnvelopeResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '409':
          $ref: '#/components/responses/ConflictResponse'
        '429':
          $ref: '#/components/responses/RateLimitedResponse'
        '500':
          $ref: '#/components/responses/InternalErrorResponse'
      x-tool-name: aidelly_update_content_automation
      x-tool-aliases:
      - aidelly_put_content_automations_id
      x-scope: automations:write
      x-tool-description: 'Update the saved content automation rule identified by id using the configuration in body. Overwrites the settings that control future generation, destinations, and approval behavior; active rules can schedule or publish content according to those settings. Returns the updated rule. Retry-safe: a repeat call with the same idempotency_key returns the original result.'
      security:
      - bearerAuth: []
      - oauth2:
        - automations:write
      description: 'Update the saved content automation rule identified by id using the configuration in body. Overwrites the settings that control future generation, destinations, and approval behavior; active rules can schedule or publish content according to those settings. Returns the updated rule. Retry-safe: a repeat call with the same idempotency_key returns the original result.'
    delete:
      tags:
      - Automations
      summary: Delete content automation
      operationId: deleteContentAutomation
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200':
          $ref: '#/components/responses/UsageEnvelopeResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '429':
          $ref: '#/components/responses/RateLimitedResponse'
        '500':
          $ref: '#/components/responses/InternalErrorResponse'
      x-tool-name: aidelly_delete_content_automation
      x-tool-aliases:
      - aidelly_delete_content_automations_id
      x-scope: automations:write
      x-tool-description: 'Delete a content automation rule by id. Removes the saved rule so it no longer runs on future triggers; returns the deletion result. Retry-safe: a repeat call with the same idempotency_key returns the original result.'
      security:
      - bearerAuth: []
      - oauth2:
        - automations:write
      description: 'Delete a content automation rule by id. Removes the saved rule so it no longer runs on future triggers; returns the deletion result. Retry-safe: a repeat call with the same idempotency_key returns the original result.'
  /content-automations/{id}/trigger:
    post:
      tags:
      - Automations
      summary: Trigger content automation
      operationId: triggerContentAutomation
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          $ref: '#/components/responses/UsageEnvelopeResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '409':
          $ref: '#/components/responses/ConflictResponse'
        '429':
          $ref: '#/components/responses/RateLimitedResponse'
        '500':
          $ref: '#/components/responses/InternalErrorResponse'
      x-tool-name: aidelly_trigger_content_automation
      x-tool-aliases:
      - aidelly_post_content_automations_id_trigger
      x-scope: automations:write
      x-tool-description: 'Run a saved content automation rule by id on demand. Starts content generation with the rule''s configuration, and the results can be scheduled or published according to its approval settings. Returns the trigger result. Retry-safe: a repeat call with the same idempotency_key returns the original result.'
      security:
      - bearerAuth: []
      - oauth2:
        - automations:write
      description: 'Run a saved content automation rule by id on demand. Starts content generation with the rule''s configuration, and the results can be scheduled or published according to its approval settings. Returns the trigger result. Retry-safe: a repeat call with the same idempotency_key returns the original result.'
components:
  headers:
    XRateLimitLimit:
      description: Maximum requests allowed in the current window.
      schema:
        type: integer
        example: 120
    XRateLimitPlan:
      description: Resolved plan tier for rate limiting.
      schema:
        type: string
        enum:
        - launch
        - scale
        - agency
        - fallback
        example: scale
    XRateLimitResetEpoch:
      description: Unix epoch seconds for current window reset.
      schema:
        type: integer
        example: 1771353600
    RateLimitLimit:
      description: RFC 9333 maximum requests allowed in the current window.
      schema:
        type: integer
        minimum: 0
        example: 120
    XRateLimitWindowSeconds:
      description: Rate limit window duration in seconds.
      schema:
        type: integer
        example: 60
    RateLimitPolicy:
      description: Quota policy extension using limit and window parameters.
      schema:
        type: string
        example: 120;w=60
    RateLimitRemaining:
      description: RFC 9333 requests remaining in the current window.
      schema:
        type: integer
        minimum: 0
        example: 118
    XRateLimitReset:
      description: ISO timestamp for current window reset.
      schema:
        type: string
        format: date-time
        example: 2026-02-17 18:40:00+00:00
    XRateLimitRemaining:
      description: Remaining requests available in the current window.
      schema:
        type: integer
        example: 118
    RateLimitReset:
      description: RFC 9333 seconds until the current window resets.
      schema:
        type: integer
        minimum: 1
        example: 42
    RetryAfter:
      description: Seconds to wait before retrying after a `429`.
      schema:
        type: integer
        minimum: 1
        example: 17
  schemas:
    EnvelopeBase:
      type: object
      required:
      - success
      - request_id
      properties:
        success:
          type: boolean
        request_id:
          type: string
          format: uuid
    UsageEnvelope:
      allOf:
      - $ref: '#/components/schemas/EnvelopeBase'
      - type: object
        properties:
          success:
            const: true
          data:
            type: object
            additionalProperties: true
    PlanLimitErrorDetails:
      type: object
      additionalProperties: false
      required:
      - limit_key
      - plan_tier
      - current_usage
      - limit
      - reset_at
      - recommended_plan
      - upgrade_url
      properties:
        limit_key:
          type: string
          example: automations.active
        plan_tier:
          type: string
          example: launch
        current_usage:
          type: integer
          nullable: true
          example: 5
        limit:
          type: integer
          nullable: true
          example: 5
        reset_at:
          type: string
          format: date-time
          nullable: true
          example: 2026-03-31 23:59:59+00:00
        recommended_plan:
          type: string
          nullable: true
          example: scale
        upgrade_url:
          type: string
          format: uri
          example: https://app.aidelly.ai/account/billing
    ErrorEnvelope:
      allOf:
      - $ref: '#/components/schemas/EnvelopeBase'
      - type: object
        required:
        - error
        properties:
          success:
            const: false
          error:
            type: object
            required:
            - code
            - message
            properties:
              code:
                type: string
              message:
                type: string
              details:
                description: Machine-readable error details object. Plan/feature gates use PlanLimitErrorDetails.
                oneOf:
                - $ref: '#/components/schemas/PlanLimitErrorDetails'
                - type: object
                  additionalProperties: true
  responses:
    NotFoundResponse:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              code: PUBLIC_API_POST_NOT_FOUND
              message: Post not found.
            request_id: e2f4f215-183a-47f7-bd4f-29a9380d9528
    UnauthorizedResponse:
      description: API key missing, invalid, or expired
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              code: PUBLIC_API_AUTH_REQUIRED
              message: A Bearer API key is required.
            request_id: e2f4f215-183a-47f7-bd4f-29a9380d9528
    ForbiddenResponse:
      description: API key scope or context restriction failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              code: PUBLIC_API_SCOPE_FORBIDDEN
              message: The API key does not include required scopes.
              details:
                missing_scopes:
                - posts:write
            request_id: e2f4f215-183a-47f7-bd4f-29a9380d9528
    ConflictResponse:
      description: Idempotency conflict or state conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              code: PUBLIC_API_IDEMPOTENCY_CONFLICT
              message: Idempotency-Key was already used with a different request body.
            request_id: e2f4f215-183a-47f7-bd4f-29a9380d9528
    InternalErrorResponse:
      description: Unexpected server-side failure
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              code: PUBLIC_API_POST_CREATE_FAILED
              message: Unable to create scheduled post.
            request_id: e2f4f215-183a-47f7-bd4f-29a9380d9528
    BadRequestResponse:
      description: Request validation failed (body, missing Idempotency-Key, or invalid Idempotency-Key)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          examples:
            bodyInvalid:
              value:
                success: false
                error:
                  code: PUBLIC_API_BODY_INVALID
                  message: Invalid request body.
                request_id: e2f4f215-183a-47f7-bd4f-29a9380d9528
            idempotencyKeyInvalid:
              value:
                success: false
                error:
                  code: PUBLIC_API_IDEMPOTENCY_KEY_INVALID
                  message: 'Idempotency-Key must be 1-255 printable ASCII characters with no spaces (letters, digits, and punctuation such as - _ : . are allowed).'
                request_id: e2f4f215-183a-47f7-bd4f-29a9380d9528
    UsageEnvelopeResponse:
      description: Generic successful response envelope
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/XRateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/XRateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/XRateLimitReset'
        X-RateLimit-Reset-Epoch:
          $ref: '#/components/headers/XRateLimitResetEpoch'
        X-RateLimit-Window-Seconds:
          $ref: '#/components/headers/XRateLimitWindowSeconds'
        X-RateLimit-Plan:
          $ref: '#/components/headers/XRateLimitPlan'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UsageEnvelope'
    RateLimitedResponse:
      description: API key exceeded allowed request throughput
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        X-RateLimit-Limit:
          $ref: '#/components/headers/XRateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/XRateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/XRateLimitReset'
        X-RateLimit-Reset-Epoch:
          $ref: '#/components/headers/XRateLimitResetEpoch'
        X-RateLimit-Window-Seconds:
          $ref: '#/components/headers/XRateLimitWindowSeconds'
        X-RateLimit-Plan:
          $ref: '#/components/headers/XRateLimitPlan'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              code: PUBLIC_API_RATE_LIMITED
              message: Rate limit exceeded.
            request_id: e2f4f215-183a-47f7-bd4f-29a9380d9528
  parameters:
    IdempotencyKey:
      in: header
      name: Idempotency-Key
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 255
        pattern: ^[\x21-\x7E]{1,255}$
        example: order-123:create-post:v1
      description: 'Required on all write endpoints. 1-255 printable ASCII characters (0x21-0x7E): letters, digits, and punctuation such as `-`, `_`, `.`, and `:` are allowed; spaces, control characters, and non-ASCII are not. Leading and trailing whitespace is trimmed. An invalid key returns 400 `PUBLIC_API_IDEMPOTENCY_KEY_INVALID`; a missing key returns 400 `PUBLIC_API_IDEMPOTENCY_REQUIRED`. Keys are scoped to the API key, method, and path.'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://app.aidelly.ai/api/mcp/oauth/authorize
          tokenUrl: https://app.aidelly.ai/api/mcp/oauth/token
          refreshUrl: https://app.aidelly.ai/api/mcp/oauth/token
          scopes:
            posts:write: Create and modify posts
            posts:read: Read access to posts
            photos:write: Create and modify photos
            media:write: Create and modify media
            connections:read: Read access to connections
            webhooks:manage: Manage webhooks
            approvals:read: Read access to approvals
            approvals:write: Create and modify approvals
            inbox:read: Read access to inbox
            inbox:write: Create and modify inbox
            automations:read: Read access to automations
            automations:write: Create and modify automations
            queues:read: Read access to queues
            queues:write: Create and modify queues
            destination-presets:read: Read access to destination-presets
            destination-presets:write: Create and modify destination-presets
            calendar:read: Read access to calendar
            calendar:write: Create and modify calendar
            analytics:read: Read access to analytics
            analytics:write: Create and modify analytics
            brand:read: Read access to brand
            brand:write: Create and modify brand
            workspaces:read: Read access to workspaces
            workspaces:write: Create and modify workspaces
            team:read: Read access to team
            team:write: Create and modify team
            repurpose:read: Read access to repurpose
            repurpose:write: Create and modify repurpose
            ideas:read: Read access to ideas
            ideas:write: Create and modify ideas
            links:read: Read access to links
            links:write: Create and modify links
            connect_links:read: Read access to connect_links
            connect_links:write: Create and modify connect_links
            bio:read: Read access to bio
            bio:write: Create and modify bio
            image_editor:read: Read access to image_editor
            image_editor:write: Create and modify image_editor
            viral_trends:read: Read access to viral_trends
            creators:read: Read access to creators
            creators:write: Create and modify creators
            competitors:read: Read access to competitors
            competitors:write: Create and modify competitors
            reports:read: Read access to reports
            reports:write: Create and modify reports
            tasks:read: Read access to tasks
            tasks:write: Create and modify tasks
            white-label:read: Read access to white-label
            white-label:write: Create and modify white-label
            drafts:read: Read access to drafts
            drafts:write: Create and modify drafts
            activity:read: Read access to activity
            credits:read: Read access to credits
            comments:read: Read access to comments
            comments:write: Create and modify comments
            prompts:read: Read access to prompts
            prompts:write: Create and modify prompts
externalDocs:
  description: Aidelly developer documentation and API lifecycle policy
  url: https://www.aidelly.ai/docs