Aidelly AI Accounts API

openapi: 3.2.0
info:
  title: Aidelly Public Accounts 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: Accounts
paths:
  /accounts:
    get:
      tags:
      - Accounts
      summary: List postable accounts
      description: 'Returns a flat list of every postable account the authenticated user has connected,

        including sub-accounts such as Facebook Pages, Instagram Business accounts, and

        LinkedIn company pages.


        Use the `id` field from each account as the `account_id` when creating a post to

        target that specific account. If `account_id` is omitted from a post request, the

        default account for that platform is used.


        **Account types returned per platform:**

        - **facebook** — one entry per Facebook Page (`account_type: page`)

        - **instagram** — one entry per Instagram Business account (`account_type: business`)

        - **linkedin** — one entry for the personal profile (`account_type: personal`) + one per company page (`account_type: company`)

        - **google_business** — one entry per Google Business Profile location (`account_type: location`); the `id` is the full `accounts/{accountId}/locations/{locationId}` resource name

        - **bluesky / threads / pinterest / tiktok / twitter / youtube / mastodon** — one entry per connection (`account_type: personal`). For `mastodon`, `instance_url` identifies the federated instance the account lives on.'
      operationId: listAccounts
      parameters:
      - in: header
        name: x-aidelly-workspace-id
        required: true
        schema:
          type: string
          format: uuid
        description: Workspace ID (required for listing postable accounts).
      - $ref: '#/components/parameters/BrandId'
      responses:
        '200':
          description: Accounts list
          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/AccountsEnvelope'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '429':
          $ref: '#/components/responses/RateLimitedResponse'
        '500':
          $ref: '#/components/responses/InternalErrorResponse'
      x-tool-name: aidelly_list_accounts
      x-scope: connections:read
      x-tool-description: List every postable account in a workspace as a flat list, including sub-accounts such as Facebook Pages, Instagram Business accounts, and LinkedIn company pages. Requires workspace_id. Each account's id is the account_id that aidelly_create_post takes. Read-only.
      security:
      - bearerAuth: []
      - oauth2:
        - connections:read
  /accounts/pinterest/boards:
    get:
      tags:
      - Accounts
      summary: List Pinterest boards
      description: 'Returns sanitized boards from the active Pinterest connection. Use a returned

        board `id` as `content.platform_specific.board_id` when creating a Pinterest post.

        When `board_id` is omitted on create, Aidelly may also use a board saved on the

        connected account or workspace/user posting defaults (see Pinterest `platform_specific`).'
      operationId: listPinterestBoards
      parameters:
      - in: header
        name: x-aidelly-workspace-id
        required: true
        schema:
          type: string
          format: uuid
        description: Workspace ID (required for listing Pinterest boards).
      - $ref: '#/components/parameters/BrandId'
      - in: query
        name: page_size
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
      - in: query
        name: bookmark
        schema:
          type: string
      responses:
        '200':
          description: Pinterest board list
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/EnvelopeBase'
                - type: object
                  properties:
                    data:
                      type: object
                      properties:
                        boards:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                              name:
                                type: string
                              privacy:
                                type: string
                        bookmark:
                          type: string
                          nullable: true
                        connection_id:
                          type: string
                          format: uuid
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '429':
          $ref: '#/components/responses/RateLimitedResponse'
        '500':
          $ref: '#/components/responses/InternalErrorResponse'
      x-tool-name: aidelly_list_pinterest_boards
      x-scope: connections:read
      x-tool-description: List the Pinterest boards available in a workspace. A Pinterest post created with aidelly_create_post takes one of these board ids as content.platform_specific.board_id. Read-only.
      security:
      - bearerAuth: []
      - oauth2:
        - connections:read
  /connection-attempts:
    get:
      tags:
      - Accounts
      summary: List social-connect attempts
      description: 'Returns recent social-connect (OAuth) attempts recorded for the workspace,

        newest first — including the ones that FAILED. Use it to see why a client''s

        "Connect account" flow did not produce a connection.


        Each attempt records the platform, who initiated it, whether it succeeded,

        and the provider or Aidelly error code when it did not.


        **Visibility:** a key belonging to the workspace''s billing owner sees every

        attempt in the workspace. Any other member''s key sees only the attempts

        that member initiated.


        Attempts are best-effort telemetry: they are recorded outside the connect

        flow and are never used to decide whether a connection exists. Query

        `/accounts` for the authoritative list of connected accounts.'
      operationId: listConnectionAttempts
      parameters:
      - in: header
        name: x-aidelly-workspace-id
        required: true
        schema:
          type: string
          format: uuid
        description: Workspace ID (required for listing connection attempts).
      - $ref: '#/components/parameters/BrandId'
      - in: query
        name: limit
        description: Maximum attempts to return (newest first).
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
      - in: query
        name: outcome
        description: Return only attempts with this outcome.
        schema:
          type: string
          enum:
          - success
          - error
      - 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
      responses:
        '200':
          description: Connection attempt list
          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:
                allOf:
                - $ref: '#/components/schemas/EnvelopeBase'
                - type: object
                  properties:
                    data:
                      type: object
                      properties:
                        attempts:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                                format: uuid
                              workspace_id:
                                type: string
                                format: uuid
                                nullable: true
                              platform:
                                type: string
                              initiated_by_user_id:
                                type: string
                                format: uuid
                                nullable: true
                              outcome:
                                type: string
                                enum:
                                - success
                                - error
                              error_code:
                                type: string
                                nullable: true
                              created_at:
                                type: string
                                format: date-time
                        count:
                          type: integer
                        has_more:
                          type: boolean
                          description: Whether another page exists after this one.
                        next_cursor:
                          type:
                          - string
                          - 'null'
                          description: Opaque cursor for the next page; null on the last page.
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '429':
          $ref: '#/components/responses/RateLimitedResponse'
        '500':
          $ref: '#/components/responses/InternalErrorResponse'
      x-tool-name: aidelly_list_connection_attempts
      x-scope: connections:read
      x-tool-description: List recent social-connect (OAuth) attempts in a workspace, including failed ones, with the platform, initiator, outcome, and error code. Requires workspace_id. Useful for diagnosing why a client could not connect an account; aidelly_list_accounts lists the accounts that did connect. Read-only.
      security:
      - bearerAuth: []
      - oauth2:
        - connections:read
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
    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
    AccountsEnvelope:
      allOf:
      - $ref: '#/components/schemas/EnvelopeBase'
      - type: object
        properties:
          success:
            const: true
          data:
            type: object
            properties:
              accounts:
                type: array
                items:
                  $ref: '#/components/schemas/PublicAccount'
              count:
                type: integer
    PublicAccount:
      type: object
      properties:
        id:
          type: string
          description: 'The account ID to pass as `account_id` when creating a post.

            For Facebook Pages and Instagram business accounts this is the platform''s page/account ID.

            For LinkedIn companies this is the organization ID.

            For other platforms (TikTok, Twitter, YouTube) this is the connection UUID.

            '
          example: '123456789012345'
        connection_id:
          type: string
          format: uuid
          description: UUID of the parent social connection this account belongs to.
        platform:
          $ref: '#/components/schemas/Platform'
        account_type:
          type: string
          enum:
          - personal
          - page
          - business
          - company
          - organization
          - location
          description: '- `personal` — personal user account (LinkedIn personal, TikTok, Twitter, YouTube, Bluesky, Threads, Pinterest)

            - `page` — Facebook Page

            - `business` — Instagram Business account

            - `company` — LinkedIn Company page

            - `organization` — Reserved for legacy LinkedIn organizations

            - `location` — Google Business Profile location

            '
        name:
          type: string
          description: Display name of the account or page.
          example: My Brand Page
        username:
          type: string
          nullable: true
          description: Platform username or handle, if available.
          example: mybrandpage
        profile_picture_url:
          type: string
          nullable: true
          description: Profile picture URL, if available.
        is_default:
          type: boolean
          description: Whether this is the default account for its platform.
        can_publish:
          type: boolean
          description: Whether the connection has publish permissions.
    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
    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
    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:
    BrandId:
      in: header
      name: x-aidelly-brand-id
      required: false
      schema:
        type: string
      description: Optional brand scope override for brand-compatible API keys.
  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