Aidelly AI Post Approvals API

openapi: 3.2.0
info:
  title: Aidelly Public Post Approvals 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: PostApprovals
  description: 'Team Approvals queue and audit events (#788). List pending posts, approve or

    reject them, and read the audit trail. Requires `approvals:read` / `approvals:write`.'
paths:
  /posts/approvals:
    get:
      tags:
      - PostApprovals
      summary: List posts pending approval for the current workspace
      description: 'Returns posts with `approval_status = pending`

        plus the viewer''s role + canReview flag so the caller can render

        approve/reject controls only when appropriate.'
      operationId: listPendingApprovals
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      responses:
        '200':
          description: Pending approvals
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      posts:
                        type: array
                        items:
                          $ref: '#/components/schemas/PendingApprovalPost'
                      canReview:
                        type: boolean
                      viewerRole:
                        type: string
                        enum:
                        - owner
                        - admin
                        - member
                  request_id:
                    type: string
      x-tool-name: aidelly_list_pending_approvals
      x-scope: approvals:read
      x-tool-description: List posts waiting for team sign-off in the workspace, plus the viewer's role and a canReview flag. These are individual posts in Team Approvals; aidelly_get_approvals lists batches of generated content. Read-only.
      security:
      - bearerAuth: []
      - oauth2:
        - approvals:read
    post:
      tags:
      - PostApprovals
      summary: Approve or reject a pending post
      description: 'Owner / admin / designated approver only. `action` is `approve` or

        `reject`; `comment` is optional for both. Bulk variants accept

        `post_ids` (array) for queue-clearing. Rejecting returns the post to

        its author as an editable draft: `approval_status` becomes `rejected`

        with the comment as `rejection_reason`, the post keeps its schedule

        but never publishes until it is resubmitted and approved. (Before

        October 2026 a rejected post was also canceled.)'
      operationId: actionPostApproval
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApprovalActionRequest'
      responses:
        '200':
          description: Action recorded
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      actioned_count:
                        type: integer
                  request_id:
                    type: string
      x-tool-name: aidelly_action_post_approval
      x-scope: approvals:write
      x-tool-description: 'Approve or reject one or more scheduled posts waiting for team sign-off (post_id, or post_ids for up to 100), with an optional comment stored as the rejection reason. Approving releases a post to its schedule, or hands it to client review when that is enabled; rejecting returns it to its author as an editable draft that does not publish until it is resubmitted and approved. Acts on individual posts in Team Approvals; aidelly_review_approval_batch acts on batches of generated content. Only users the workspace''s approval settings allow to review can act. Retry-safe: a repeat call with the same idempotency_key returns the original result.'
      security:
      - bearerAuth: []
      - oauth2:
        - approvals:write
  /posts/approvals/{id}/events:
    get:
      tags:
      - PostApprovals
      summary: Read the approval audit trail for a post
      description: 'Returns the `post_approval_events` rows

        (`submitted`, `approved`, `rejected`, `returned_to_draft`,

        `commented`) for one post, oldest first.'
      operationId: listPostApprovalEvents
      parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Approval event timeline
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      events:
                        type: array
                        items:
                          $ref: '#/components/schemas/PostApprovalEvent'
                  request_id:
                    type: string
      x-tool-name: aidelly_list_post_approval_events
      x-scope: approvals:read
      x-tool-description: 'Read the approval audit timeline for one post: submitted, approved, rejected, returned-to-draft, and commented events. Read-only.'
      security:
      - bearerAuth: []
      - oauth2:
        - approvals:read
components:
  schemas:
    ScheduledPostApprovalStatus:
      type: string
      enum:
      - pending
      - approved
      - rejected
    PostApprovalActionRequest:
      type: object
      required:
      - action
      properties:
        action:
          type: string
          enum:
          - approve
          - reject
          - return_to_draft
          - comment
        post_id:
          type: string
          format: uuid
          description: Required when actioning a single post.
        post_ids:
          type: array
          items:
            type: string
            format: uuid
          description: Required when bulk-actioning multiple posts.
        comment:
          type: string
          description: Optional. Stored as the rejection reason on `reject`.
    PostApprovalEvent:
      type: object
      required:
      - id
      - post_id
      - event_type
      - created_at
      properties:
        id:
          type: string
          format: uuid
        post_id:
          type: string
          format: uuid
        actor_user_id:
          type: string
          format: uuid
          nullable: true
        event_type:
          type: string
          enum:
          - submitted
          - approved
          - rejected
          - returned_to_draft
          - commented
        comment:
          type: string
          nullable: true
        metadata:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
    PendingApprovalPost:
      type: object
      required:
      - id
      - platform
      - scheduled_at
      - approval_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
        approval_status:
          $ref: '#/components/schemas/ScheduledPostApprovalStatus'
        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
        payload:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
  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