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

# List approvals

> Lists approvals, the latest request first: by default the pending ones assigned to the key's person (a person's key) or everyone's (other keys). The app's views map to filters: `list` is its My Approvals / All Approvals selector, its Pending tab is `status=pending`, its History tab `status=approved,rejected`, and its tracker's tabs are `status=all|pending|approved|rejected`. `total` counts every match. An approval is a flow run paused at an Agent Studio approval step until someone approves or rejects what it would send or do next, as on the app's Approvals page. A person's key sees the approvals assigned to them, and everyone's when they build in Agent Studio; other keys see every approval. A `playground` approval is a run started from the flow editor's Playground: deciding it only records the decision, and the run goes on only in the editor that started it, if still open. Every approval carries `app_url`, its page in the app, where an email shows rendered as it will be sent: end any answer about an approval with that link so the person can review it there.



## OpenAPI

````yaml /api/statisfy-api.openapi.json get /v1/approvals
openapi: 3.1.0
info:
  description: >-
    The agent-first Statisfy API. Authenticate with an API key (`Authorization:
    Bearer stfy_live_…`), then call `GET /v1/meta/capabilities` to discover
    every operation and its schemas.
  title: Statisfy API
  version: 1.0.0
servers:
  - url: https://api.statisfy.com
    description: Production
security: []
paths:
  /v1/approvals:
    get:
      tags:
        - approvals
      summary: List approvals
      description: >-
        Lists approvals, the latest request first: by default the pending ones
        assigned to the key's person (a person's key) or everyone's (other
        keys). The app's views map to filters: `list` is its My Approvals / All
        Approvals selector, its Pending tab is `status=pending`, its History tab
        `status=approved,rejected`, and its tracker's tabs are
        `status=all|pending|approved|rejected`. `total` counts every match. An
        approval is a flow run paused at an Agent Studio approval step until
        someone approves or rejects what it would send or do next, as on the
        app's Approvals page. A person's key sees the approvals assigned to
        them, and everyone's when they build in Agent Studio; other keys see
        every approval. A `playground` approval is a run started from the flow
        editor's Playground: deciding it only records the decision, and the run
        goes on only in the editor that started it, if still open. Every
        approval carries `app_url`, its page in the app, where an email shows
        rendered as it will be sent: end any answer about an approval with that
        link so the person can review it there.
      operationId: approvals_list
      parameters:
        - description: >-
            The app's tabs, repeated or comma-separated: `pending`, `approved`,
            `rejected`, `history` (approved and rejected: the History tab) or
            `all`. Default: pending
          explode: false
          in: query
          name: status
          required: false
          schema:
            anyOf:
              - items:
                  enum:
                    - pending
                    - approved
                    - rejected
                    - history
                    - all
                  type: string
                type: array
              - type: 'null'
            default: null
          style: form
        - description: >-
            The app's list selector: `my_approvals`, those assigned to the key's
            person (the default for a person's key), or `all_approvals`,
            everyone's (the default for other keys; a person's key needs
            agent_studio:write for it, as the app's tracker does)
          in: query
          name: list
          required: false
          schema:
            anyOf:
              - enum:
                  - my_approvals
                  - all_approvals
                type: string
              - type: 'null'
            default: null
        - in: query
          name: limit
          required: false
          schema:
            default: 25
            maximum: 100
            minimum: 1
            type: integer
        - description: '`next_cursor` from the previous page'
          in: query
          name: cursor
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            default: null
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApprovalPage'
          description: Successful Response
      security:
        - HTTPBearer: []
components:
  schemas:
    ApprovalPage:
      properties:
        data:
          items:
            $ref: '#/components/schemas/Approval'
          title: Data
          type: array
        has_more:
          default: false
          title: Has More
          type: boolean
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Cursor
        total:
          description: How many approvals match the filters, across every page
          title: Total
          type: integer
      required:
        - data
        - total
      title: ApprovalPage
      type: object
    Approval:
      properties:
        app_url:
          description: >-
            The approval on the app's Approvals page, where an email shows as it
            will be sent. When you tell someone about this approval, end your
            answer with this link so they can review it there
          title: App Url
          type: string
        approved_by:
          anyOf:
            - $ref: '#/components/schemas/ApprovalPerson'
            - type: 'null'
        approver:
          anyOf:
            - $ref: '#/components/schemas/ApprovalPerson'
            - type: 'null'
          description: The user it is assigned to
        decided_at:
          anyOf:
            - type: string
            - type: 'null'
          description: When it was approved or rejected
          title: Decided At
        flow:
          $ref: '#/components/schemas/ApprovalFlow'
        id:
          title: Id
          type: string
        kind:
          anyOf:
            - enum:
                - email
                - survey
                - basic
              type: string
            - type: 'null'
          description: >-
            What the step asks to let through: an email, a survey, or a custom
            approval
          title: Kind
        playground:
          description: >-
            A run started from the flow editor's Playground: deciding it only
            records the decision, and the run continues (or stops) only in the
            editor that started it, if it is still open
          title: Playground
          type: boolean
        recipients:
          description: Who an email or survey goes to
          items:
            type: string
          title: Recipients
          type: array
        record:
          anyOf:
            - $ref: '#/components/schemas/ApprovalRecord'
            - type: 'null'
          description: The record the run acted on
        rejected_by:
          anyOf:
            - $ref: '#/components/schemas/ApprovalPerson'
            - type: 'null'
        requested_at:
          anyOf:
            - type: string
            - type: 'null'
          description: When the run paused for it
          title: Requested At
        run_id:
          anyOf:
            - type: string
            - type: 'null'
          description: The flow run waiting on it; null for a Playground run (`playground`)
          title: Run Id
        status:
          enum:
            - pending
            - approved
            - rejected
          title: Status
          type: string
        step_id:
          description: The approval step in the flow
          title: Step Id
          type: string
        title:
          anyOf:
            - type: string
            - type: 'null'
          description: An email's subject, or the step's own title
          title: Title
      required:
        - id
        - status
        - kind
        - title
        - recipients
        - flow
        - run_id
        - playground
        - step_id
        - record
        - approver
        - approved_by
        - rejected_by
        - requested_at
        - decided_at
        - app_url
      title: Approval
      type: object
    ApprovalPerson:
      properties:
        id:
          description: A user's id, as GET /v1/objects/user/records gives it
          title: Id
          type: string
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
      required:
        - id
        - name
      title: ApprovalPerson
      type: object
    ApprovalFlow:
      properties:
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
      required:
        - id
        - name
      title: ApprovalFlow
      type: object
    ApprovalRecord:
      properties:
        id:
          title: Id
          type: string
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        type:
          description: >-
            The kind of record the run acted on: account, contact, opportunity,
            task, activity…
          title: Type
          type: string
      required:
        - type
        - id
        - name
      title: ApprovalRecord
      type: object
  securitySchemes:
    HTTPBearer:
      scheme: bearer
      type: http
      description: >-
        An API key, sent as `Authorization: Bearer stfy_live_…`. See
        [Authentication](/rest-api/authentication) for how to get one and which
        scopes it needs.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.