> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryordinal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List workspace approvals

> List all approval requests across the workspace in one paginated stream. Use for incremental sync by external integrations instead of polling each post individually. Supports keyset pagination and filters by status, post, approver, requester, and date range. Approvals on archived posts are included; filter client-side with `post.archivedAt`. Soft-deleted approvals are omitted from results.



## OpenAPI

````yaml /api/openapi.json get /approvals
openapi: 3.1.0
info:
  title: Ordinal API
  version: 1.0.0
  description: API to create and manage Ordinal workspaces, posts, profiles, and analytics
servers:
  - url: https://app.tryordinal.com/api/v1
    description: Production server
security:
  - bearerAuth: []
tags:
  - name: Analytics
    description: Social media analytics data
  - name: Approvals
    description: Post approval workflows
  - name: Comments
    description: >-
      Post comments for team collaboration. Supports @mentions using the format
      @[Display Name](userId).
  - name: Engagements
    description: Team engagements for posts (likes, comments, reposts)
  - name: Invites
    description: Workspace invitations for adding new users
  - name: Labels
    description: Labels for organizing posts
  - name: Instagram
    description: Instagram utilities for location search and tagging
  - name: LinkedIn
    description: LinkedIn utilities for profile lookups, tagging, and mentions
  - name: Posts
    description: Create and manage posts
  - name: Profiles
    description: List connected social profiles
  - name: Slack Boosts
    description: >-
      List connected Slack channels (webhooks), then create and manage slack
      boosts so teams get notified in Slack when posts publish. Requires Slack
      connected with marketing boost channels.
  - name: Subscribers
    description: Post subscribers for notifications
  - name: File Uploads
    description: >-
      Upload files from URLs for use in posts. Supports images (JPEG, PNG, GIF,
      WebP) up to 10 MB and videos (MP4, MOV) up to 350 MB.
  - name: Ideas
    description: >-
      Create and manage content ideas. Ideas are draft posts without scheduled
      dates that can be converted to calendar posts.
  - name: Inline Comments
    description: >-
      Text-anchored comments on specific post content. Read-only API for
      retrieving inline comments across channels.
  - name: Users
    description: Workspace users
  - name: Webhooks
    description: >-
      Create, list, get, update, and delete webhooks to receive real-time event
      notifications
  - name: Workspaces
    description: Workspace information
paths:
  /approvals:
    get:
      tags:
        - Approvals
      summary: List workspace approvals
      description: >-
        List all approval requests across the workspace in one paginated stream.
        Use for incremental sync by external integrations instead of polling
        each post individually. Supports keyset pagination and filters by
        status, post, approver, requester, and date range. Approvals on archived
        posts are included; filter client-side with `post.archivedAt`.
        Soft-deleted approvals are omitted from results.
      operationId: approvals-list-workspace
      parameters:
        - name: limit
          in: query
          description: Maximum number of approvals to return (1-100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: cursor
          in: query
          description: >-
            Pagination cursor from the previous response's `nextCursor`. Format
            is `timestampMs:approvalId`. When paginating, pass the same `sortBy`
            and `sortOrder` as the initial request.
          schema:
            type: string
        - name: sortBy
          in: query
          description: >-
            Field to sort results by. Use `updatedAt` for incremental sync so
            newly-updated approvals stream in order.
          schema:
            type: string
            enum:
              - createdAt
              - updatedAt
            default: createdAt
        - name: sortOrder
          in: query
          description: Sort order. Use `asc` with `sortBy=updatedAt` for incremental sync.
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
        - name: updatedAtMin
          in: query
          description: >-
            Return approvals updated at or after this time. Pair with
            `sortBy=updatedAt` and `sortOrder=asc` for incremental sync from a
            saved checkpoint.
          schema:
            type: string
            format: date-time
        - name: updatedAtMax
          in: query
          description: Return approvals updated at or before this time.
          schema:
            type: string
            format: date-time
        - name: createdAtMin
          in: query
          description: Return approvals created at or after this time.
          schema:
            type: string
            format: date-time
        - name: createdAtMax
          in: query
          description: Return approvals created at or before this time.
          schema:
            type: string
            format: date-time
        - name: statuses
          in: query
          description: >-
            Filter by approval statuses. Repeat the parameter to match any of
            multiple values.
          schema:
            type: array
            items:
              type: string
              enum:
                - Requested
                - Approved
        - name: postIds
          in: query
          description: >-
            Filter by post IDs. Repeat the parameter to match any of multiple
            values.
          schema:
            type: array
            items:
              type: string
              format: uuid
        - name: approverIds
          in: query
          description: >-
            Filter by approver user IDs. Repeat the parameter to match any of
            multiple values.
          schema:
            type: array
            items:
              type: string
              format: uuid
        - name: requestedByIds
          in: query
          description: >-
            Filter by IDs of users who requested the approval. Repeat the
            parameter to match any of multiple values.
          schema:
            type: array
            items:
              type: string
              format: uuid
      responses:
        '200':
          description: Paginated list of workspace approvals
          content:
            application/json:
              schema:
                type: object
                properties:
                  approvals:
                    type: array
                    items:
                      $ref: '#/components/schemas/WorkspaceApproval'
                  nextCursor:
                    type: string
                    nullable: true
                    description: >-
                      Cursor for the next page, or `null` when there are no more
                      results
                  hasMore:
                    type: boolean
                    description: Whether more approvals are available
              example:
                approvals:
                  - id: 550e8400-e29b-41d4-a716-446655440200
                    status: Requested
                    isBlocking: true
                    message: Please review the messaging before we publish
                    dueDate: '2026-01-14T17:00:00.000Z'
                    approvedAt: null
                    createdAt: '2026-01-05T10:30:00.000Z'
                    updatedAt: '2026-01-05T10:30:00.000Z'
                    postId: 550e8400-e29b-41d4-a716-446655440000
                    approver:
                      id: 550e8400-e29b-41d4-a716-446655440011
                      email: jane.smith@example.com
                      firstName: Jane
                      lastName: Smith
                      createdAt: '2025-01-01T00:00:00.000Z'
                    requestedBy:
                      id: 550e8400-e29b-41d4-a716-446655440010
                      email: john.doe@example.com
                      firstName: John
                      lastName: Doe
                      createdAt: '2025-01-01T00:00:00.000Z'
                    post:
                      id: 550e8400-e29b-41d4-a716-446655440000
                      url: >-
                        https://app.tryordinal.com/your-workspace/posts/550e8400-e29b-41d4-a716-446655440000
                      title: Launch announcement
                      status: ForReview
                      channels:
                        - LinkedIn
                        - Twitter
                      publishDate: '2026-01-15'
                      publishAt: '2026-01-15T14:00:00.000Z'
                      isIdea: false
                      archivedAt: null
                nextCursor: 1736074200000:550e8400-e29b-41d4-a716-446655440200
                hasMore: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  schemas:
    WorkspaceApproval:
      type: object
      description: >-
        An approval returned by the workspace-wide list endpoint. Includes both
        the approver and requester users and a nested post summary.
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - Requested
            - Approved
        isBlocking:
          type: boolean
          description: >-
            Whether the post is blocked from publishing until this approval is
            granted
        message:
          type: string
          nullable: true
        dueDate:
          type: string
          format: date-time
          nullable: true
        approvedAt:
          type: string
          format: date-time
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
          description: >-
            Last time the approval changed. Use with `updatedAtMin` and
            `sortBy=updatedAt` for incremental sync.
        postId:
          type: string
          format: uuid
        approver:
          $ref: '#/components/schemas/ApprovalUser'
        requestedBy:
          $ref: '#/components/schemas/ApprovalUser'
        post:
          type: object
          description: Summary of the post this approval belongs to
          properties:
            id:
              type: string
              format: uuid
            url:
              type: string
              format: uri
              description: Deep link to the post in the Ordinal dashboard
            title:
              type: string
            status:
              $ref: '#/components/schemas/PostStatus'
            channels:
              type: array
              items:
                type: string
              description: Channels the post targets (for example `LinkedIn`, `Twitter`)
            publishDate:
              type: string
              nullable: true
              description: >-
                Scheduled publish date (`YYYY-MM-DD`) in the workspace timezone,
                when set
            publishAt:
              type: string
              format: date-time
              nullable: true
              description: Scheduled publish timestamp when a specific time is set
            isIdea:
              type: boolean
              description: >-
                Whether the post is an idea rather than a scheduled or published
                post
            archivedAt:
              type: string
              format: date-time
              nullable: true
              description: When the post was archived, if applicable
    ApprovalUser:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        firstName:
          type: string
          nullable: true
        lastName:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time
    PostStatus:
      type: string
      enum:
        - Tentative
        - ToDo
        - InProgress
        - ForReview
        - Blocked
        - Finalized
        - Scheduled
        - Posted
    ValidationError:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        data:
          type: object
          properties:
            errors:
              type: object
              additionalProperties:
                type: array
                items:
                  type: string
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
  responses:
    BadRequest:
      description: Bad Request - Invalid input parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationError'
          example:
            code: BAD_REQUEST
            message: Bad Request
            data:
              errors:
                publishAt:
                  - Invalid date format
                status:
                  - Invalid enum value
    Unauthorized:
      description: Unauthorized - Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: UNAUTHORIZED
            message: Invalid or unauthorized API key
    Forbidden:
      description: Forbidden - Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: FORBIDDEN
            message: Engagement profiles cannot be used for analytics
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key authentication. Generate an API key from your workspace
        settings.

````