Aidelly AI Scheduled Posts API

openapi: 3.2.0
info:
  title: Aidelly Public Scheduled Posts 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: ScheduledPosts
  description: 'Scheduled posts API, including compose-time auto-recycle (#847) and

    the self-healing publish audit trail (#852). Public API preview.'
paths:
  /scheduled-posts:
    get:
      tags:
      - ScheduledPosts
      summary: List scheduled posts for the workspace
      description: 'Public API preview. Surfaces every scheduled_post including

        compose-time recycle entries (#847) and approval state (#788).'
      operationId: listScheduledPosts
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - in: query
        name: from
        schema:
          type: string
          format: date-time
      - in: query
        name: to
        schema:
          type: string
          format: date-time
      - in: query
        name: status
        schema:
          type: string
          enum:
          - scheduled
          - pending
          - processing
          - retry
          - completed
          - failed
          - canceled
      - in: query
        name: platform
        schema:
          $ref: '#/components/schemas/Platform'
      - in: query
        name: limit
        description: Page size. Use `cursor` to page beyond this many results.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      - 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.
        schema:
          type: string
          maxLength: 512
      responses:
        '200':
          description: Scheduled post list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostListEnvelope'
      x-tool-name: aidelly_list_scheduled_posts
      x-scope: posts:read
      x-tool-description: List workspace scheduled posts with from/to timestamps, status, platform, and cursor pagination (maximum 100 per page). Returns items with scheduled_at and approval_status; an empty items array means no matching posts. Approval state is separate from publishing status.
      security:
      - bearerAuth: []
      - oauth2:
        - posts:read
    post:
      tags:
      - ScheduledPosts
      summary: Schedule a post with optional auto-recycle entries
      description: 'Public API preview. Accepts `recycle` array (up to 3 reposts and 3

        reshares) for compose-time auto-recycle (#847). When the workspace

        has Team Approvals on and the caller is a member, the post lands

        in `approval_status = pending` instead of publishing immediately.

        Bare media-library UUIDs in `payload.media` are resolved within the

        selected workspace before the post is stored.'
      operationId: createScheduledPost
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateScheduledPostRequest'
      responses:
        '201':
          description: Scheduled post created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/ScheduledPost'
                  request_id:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '422':
          $ref: '#/components/responses/UnprocessableResponse'
      x-tool-name: aidelly_create_scheduled_post
      x-scope: posts:write
      x-tool-description: 'Schedule a post for a future time, with optional auto-recycle entries (up to 3 reposts and 3 reshares). Scheduled posts publish automatically at their time; when Team Approvals is on, posts submitted by members are held as pending until approved. LinkedIn document posts attach one PDF (≤100 MB, ≤300 pages) as media[].type = "document"; documents are rejected on every other platform. Retry-safe: a repeat call with the same idempotency_key returns the original result.'
      security:
      - bearerAuth: []
      - oauth2:
        - posts:write
  /scheduled-posts/{id}:
    get:
      tags:
      - ScheduledPosts
      summary: Get one scheduled post
      operationId: getScheduledPost
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Scheduled post detail
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/ScheduledPost'
                  request_id:
                    type: string
        '404':
          $ref: '#/components/responses/NotFoundResponse'
      x-tool-name: aidelly_get_scheduled_post
      x-scope: posts:read
      x-tool-description: Read one scheduled post, including its recycle plan and approval state. Read-only.
      security:
      - bearerAuth: []
      - oauth2:
        - posts:read
      description: Read one scheduled post, including its recycle plan and approval state. Read-only.
    patch:
      tags:
      - ScheduledPosts
      summary: Update a scheduled post (caption, schedule, recycle plan)
      operationId: updateScheduledPost
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/IdempotencyKey'
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateScheduledPostRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/EnvelopeBase'
                - type: object
                  properties:
                    success:
                      const: true
                    data:
                      type: object
                      properties:
                        post:
                          $ref: '#/components/schemas/ScheduledPost'
      x-tool-name: aidelly_update_scheduled_post
      x-scope: posts:write
      x-tool-description: 'Update the caption, schedule, or recycle plan of a scheduled post. Overwrites the supplied fields; a new time changes when the post publishes. Retry-safe: a repeat call with the same idempotency_key returns the original result.'
      security:
      - bearerAuth: []
      - oauth2:
        - posts:write
      description: 'Update the caption, schedule, or recycle plan of a scheduled post. Overwrites the supplied fields; a new time changes when the post publishes. Retry-safe: a repeat call with the same idempotency_key returns the original result.'
    delete:
      tags:
      - ScheduledPosts
      summary: Cancel a scheduled post
      operationId: cancelScheduledPost
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/IdempotencyKey'
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Cancelled
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/EnvelopeBase'
                - type: object
                  properties:
                    success:
                      const: true
                    data:
                      $ref: '#/components/schemas/ScheduledPostDeleteResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
      x-tool-name: aidelly_cancel_scheduled_post
      x-scope: posts:write
      x-tool-description: 'Cancel a scheduled calendar post in the workspace and its pending auto-recycle entries (reposts and reshares waiting on it). Statuses become canceled and the records are kept. Requires a workspace-scoped key or workspace_id. aidelly_cancel_post cancels only the single post. Retry-safe: a repeat call with the same idempotency_key returns the original result.'
      security:
      - bearerAuth: []
      - oauth2:
        - posts:write
      description: 'Cancel a scheduled calendar post in the workspace and its pending auto-recycle entries (reposts and reshares waiting on it). Statuses become canceled and the records are kept. Requires a workspace-scoped key or workspace_id. aidelly_cancel_post cancels only the single post. Retry-safe: a repeat call with the same idempotency_key returns the original result.'
components:
  schemas:
    CreateScheduledPostRequest:
      type: object
      required:
      - platform
      - scheduled_at
      - payload
      properties:
        platform:
          type: string
        account_id:
          type: string
          description: A provider account ID from `/accounts`, or a social connection UUID selector.
        scheduled_at:
          type: string
          format: date-time
        timezone:
          type: string
          default: UTC
        payload:
          type: object
          description: 'Post content. `payload.media` accepts URL objects, objects with `media_id`, or bare media-library UUID strings owned by the selected workspace.

            `media[].type` accepts `image`, `video`, `gif`, or `document`, and is resolved from the media-library row when omitted (`application/pdf` → `document`).

            LinkedIn document posts attach one PDF (≤100 MB, ≤300 pages) as `media[].type = "document"`; documents on any other platform are rejected with `422`.

            '
          additionalProperties: true
        recycle:
          type: array
          maxItems: 6
          items:
            $ref: '#/components/schemas/RecycleEntry'
        content_campaign_id:
          type: string
          format: uuid
          nullable: true
    ScheduledPostDeleteResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
          - canceled
    PublicPost:
      type: object
      properties:
        id:
          type: string
          format: uuid
        platform:
          $ref: '#/components/schemas/Platform'
        account_id:
          type: string
          nullable: true
        status:
          $ref: '#/components/schemas/PostStatus'
        scheduled_at:
          type: string
          format: date-time
        timezone:
          type: string
        provider_post_id:
          type: string
          nullable: true
        error_code:
          type: string
          nullable: true
        error:
          type: string
          nullable: true
        approval_status:
          type: string
          enum:
          - pending
          - approved
          - rejected
          nullable: true
          description: Set when Team Approvals holds or records a decision on the post.
        submitted_by_user_id:
          type: string
          format: uuid
          nullable: true
        submitted_for_approval_at:
          type: string
          format: date-time
          nullable: true
        rejection_reason:
          type: string
          nullable: true
          description: The reviewer's reason when the post was rejected or sent back for changes. When the API key's user has the client role in the post's workspace, a reason written by a team reviewer (owner, admin or member) is returned as null; a reason from a client reviewer or a client review link is always returned.
        content:
          type: object
          additionalProperties: true
        metadata:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    ScheduledPostApprovalStatus:
      type: string
      enum:
      - pending
      - approved
      - rejected
    UpdateScheduledPostRequest:
      type: object
      properties:
        scheduled_at:
          type: string
          format: date-time
        timezone:
          type: string
        payload:
          type: object
          description: Replacement post content. `payload.media` accepts URL objects, objects with `media_id`, or bare media-library UUID strings owned by the selected workspace.
          additionalProperties: true
        recycle:
          type: array
          maxItems: 6
          items:
            $ref: '#/components/schemas/RecycleEntry'
    PostListEnvelope:
      allOf:
      - $ref: '#/components/schemas/EnvelopeBase'
      - type: object
        properties:
          success:
            const: true
          data:
            type: object
            properties:
              items:
                type: array
                items:
                  $ref: '#/components/schemas/PublicPost'
              count:
                type: integer
                description: Number of items on this page.
              has_more:
                type: boolean
                description: True when further pages are available.
              next_cursor:
                type: string
                nullable: true
                description: Pass as `cursor` to fetch the next page. Null on the last page.
    RecycleEntry:
      type: object
      required:
      - kind
      - offset_seconds
      properties:
        kind:
          type: string
          enum:
          - repost
          - reshare
        offset_seconds:
          type: integer
          minimum: 3600
          maximum: 31536000
          description: Seconds after the source publishes when this recycle fires.
    EnvelopeBase:
      type: object
      required:
      - success
      - request_id
      properties:
        success:
          type: boolean
        request_id:
          type: string
          format: uuid
    Platform:
      type: string
      enum:
      - facebook
      - instagram
      - linkedin
      - twitter
      - bluesky
      - threads
      - pinterest
      - youtube
      - tiktok
      - google_business
      - mastodon
      description: 'Supported platform identifier. `twitter` and `x` map to the same surface;

        responses always normalize to `twitter`. `google_business` posts target

        a single Google Business Profile location identified by

        `platform_specific.locationName`. `mastodon` accounts are per-instance —

        the connected account carries its own `instance_url`.

        '
      example: linkedin
    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
    PostStatus:
      type: string
      enum:
      - scheduled
      - pending
      - processing
      - retry
      - completed
      - failed
      - canceled
      example: scheduled
    ScheduledPost:
      type: object
      required:
      - id
      - platform
      - scheduled_at
      - timezone
      - status
      properties:
        id:
          type: string
          format: uuid
        platform:
          type: string
        account_id:
          type: string
          nullable: true
        scheduled_at:
          type: string
          format: date-time
        timezone:
          type: string
        status:
          type: string
          enum:
          - scheduled
          - publishing
          - published
          - failed
          - cancelled
          - pending_approval
        approval_status:
          $ref: '#/components/schemas/ScheduledPostApprovalStatus'
        source_post_id:
          type: string
          format: uuid
          nullable: true
          description: Set when this row is a recycle child of another post.
        recycle:
          type: array
          maxItems: 6
          items:
            $ref: '#/components/schemas/RecycleEntry'
        content_campaign_id:
          type: string
          format: uuid
          nullable: true
        payload:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
    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
  responses:
    UnprocessableResponse:
      description: Content validation or publishing failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          examples:
            contentValidation:
              value:
                success: false
                error:
                  code: CONTENT_VALIDATION_FAILED
                  message: Post exceeds Threads's 500-character limit.
                request_id: e2f4f215-183a-47f7-bd4f-29a9380d9528
            publishFailure:
              value:
                success: false
                error:
                  code: PUBLIC_API_PUBLISH_FAILED
                  message: Post publishing failed.
                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
    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
  parameters:
    WorkspaceId:
      in: header
      name: x-aidelly-workspace-id
      required: false
      schema:
        type: string
        format: uuid
        description: 'Workspace to operate in: the `id` of a workspace returned by aidelly_list_workspaces. Optional for read operations; required when creating content.'
      description: Optional workspace scope override for workspace-compatible API keys.
    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