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

# List pending approvals across an organization

> Long-polls for manual-approval requests awaiting a decision across every workspace in the organization. An Enterprise feature that waits up to timeoutSeconds.

Returns pending approval requests from all workspaces. If none are waiting, the call holds open until one arrives or the poll times out. Use it to build a central approver. See [Rules](/docs/guides/rules.md) for how approvals are triggered.

Long-polls for manual-approval requests awaiting a decision across **every** workspace in the organization. Returns immediately when any are pending, otherwise holds the connection open (up to `timeoutSeconds`) until one arrives or the poll times out.

Each request carries its own `workspaceId`; submit the decision to `POST /approvals/{id}/decision` with that workspace's `X-Workspace-Id`. Authenticate with an organization API key (`oc_org_…`) — a workspace key answers `403`.

> [!NOTE]
>
> **Availability:** Cloud · Enterprise (self-hosted). On an unlicensed self-hosted deployment the gateway answers `403` with `{ "error": "enterprise_license_required" }`.

> [!NOTE]
>
> Served by the **gateway**, not the API server. The base URL is your gateway's HTTP origin (`https://gw.buckle.dev` on Cloud; `http://localhost:10255` self-hosted, or `<app-url>/gw` behind a reverse proxy). Read it from `GET /gateway-url`.


## OpenAPI

````yaml /openapi.yaml get /org/approvals/pending
openapi: 3.1.0
info:
  title: Buckle API
  version: '1.0'
  description: >
    The Buckle API manages everything behind the gateway: workspaces, agents and
    what each agent may use (grants), secrets, app connections, organization
    policy, hosted-agent conversations, schedules, memory, skills, Slack
    channels, and the organization's directory.


    **Base URL:** `https://api.buckle.dev/v1` (Buckle Cloud) or
    `http://localhost:10254/v1` (self-hosted).


    ## Authentication


    Every endpoint takes an `Authorization: Bearer <token>` header unless its
    description says otherwise.


    - **Workspace API key** (`oc_…`) — acts inside one workspace. Read it from
    the dashboard or `GET /user/api-key`.

    - **Organization API key** (`oc_org_…`) — acts for the whole organization.
    Workspace-scoped endpoints additionally need an `X-Workspace-Id` header
    naming the workspace; without it they answer `401`.

    - **Dashboard session** — the browser's own session (Cloud: a bearer JWT;
    self-hosted: the session cookie).


    `X-Workspace-Id` replaced `X-Project-Id`. The old header, the `?_project`
    query bridge, and the `/v1/projects` path alias still work for a deprecation
    window and answer with a `Deprecation: true` header; migrate to the new
    names.


    ## Editions


    Each endpoint states where it is available. Unless marked otherwise an
    endpoint exists on **Buckle Cloud**, the **Community** self-hosted edition,
    and the **Enterprise** self-hosted edition. Endpoints tagged **Enterprise**
    answer `403` with `error.type: "enterprise_license_required"` on a
    self-hosted deployment that has not set `ENTERPRISE_ENABLED=true`; on Cloud
    they are always present, though some features are additionally gated by the
    organization's plan. Endpoints tagged **Cloud** do not exist on self-hosted
    deployments at all.


    ## Roles


    Organization-level endpoints (`/org/…`) require the **admin** or **owner**
    role wherever roles are enforced (Cloud and Enterprise). The Community
    edition runs a flat team: every active member passes the role check.
servers:
  - url: https://api.buckle.dev/v1
    description: Buckle Cloud
  - url: http://localhost:10254/v1
    description: Self-hosted
security:
  - bearerAuth: []
tags:
  - name: Workspaces
    description: >-
      Workspaces partition an organization's agents, secrets, and connections.
      Every workspace-scoped endpoint resolves its workspace from the API key
      (or `X-Workspace-Id` with an organization key).
  - name: Agents
    description: >-
      Manage agents, their gateway access tokens, and hosted-agent
      configuration.
  - name: Grants
    description: >-
      Which credentials each agent may use — attach app connections (with
      optional per-tool allow/approval lists and resource scoping) and secrets.
      Writes take effect immediately.
  - name: Secrets
    description: >-
      Credentials the gateway injects into outbound requests that match a host
      pattern.
  - name: Apps
    description: >-
      The app catalog, OAuth and direct-credential connects, your own OAuth
      client configuration, permission catalogs, and blocklists.
  - name: Connections
    description: Connected app accounts as a top-level resource.
  - name: Effective policy
    description: >-
      Read-only reflections of what the enforced policy means for an agent, a
      connection, or an app — workspace grants composed with organization rules.
  - name: Conversations
    description: >-
      Talk to a hosted agent. A conversation owns its turns, transcript, and
      attachments.
  - name: Schedules
    description: Cron-style schedules on a hosted agent.
  - name: Memories
    description: A hosted agent's memory files and their revision history.
  - name: Skills
    description: >-
      Skills reachable from a workspace — the organization's, the workspace's
      own, and per-agent ones.
  - name: Channels
    description: >-
      Where a hosted agent is reachable (Slack), who may reach it, who it may
      message, and which other agents it may talk to.
  - name: Approvals
    description: Long-poll for the gateway's manual-approval requests and submit decisions.
  - name: User
    description: Your profile, API keys, SSH keys, and account deletion.
  - name: Instance
    description: Unauthenticated deployment facts and bootstrap endpoints.
  - name: Utility
    description: Counts, vaults, and agent bootstrap helpers.
  - name: Organization
    description: The current organization and its invitations. Free on every edition.
  - name: Organization secrets
    description: Secrets shared into every workspace of the organization.
  - name: Organization policy
    description: >-
      The organization's first-match rule set — blocks, allows, rate limits,
      approvals, and app permissions that bind every workspace.
  - name: Organization connections
    description: App connections shared into every workspace of the organization.
  - name: Organization apps
    description: >-
      Connect apps and configure your own OAuth clients at the organization
      level.
  - name: Organization skills
    description: Skills every workspace in the organization receives.
  - name: Organization channels
    description: The organization's Slack integration and identity links.
  - name: Organization approvals
    description: Long-poll for manual-approval requests across every workspace.
  - name: Members
    description: The organization directory — list, provision, suspend, and remove members.
  - name: Groups
    description: Directory groups and group-to-role mappings.
  - name: Workspace access
    description: Share a workspace with people and groups.
  - name: Domains
    description: Verified email domains, the anchor for SSO and home-realm discovery.
  - name: SSO
    description: SAML and OIDC sign-in connections and organization-wide enforcement.
  - name: SCIM tokens
    description: Bearer tokens for the organization's SCIM endpoint.
  - name: App availability
    description: Restrict which apps each workspace may connect.
  - name: Provisioning
    description: >-
      Pre-create members with a ready workspace and API key, then let them claim
      the account.
  - name: Resource browsing
    description: Browse a connected account's folders to pick resource scopes for a grant.
  - name: SCIM
    description: >-
      The SCIM 2.0 provisioning endpoint for identity providers (Okta, Entra ID,
      and others).
paths:
  /org/approvals/pending:
    get:
      tags:
        - Organization approvals
      summary: List pending approvals across the organization
      description: >
        Long-polls for manual-approval requests awaiting a decision across
        **every** workspace in the organization. Returns immediately when any
        are pending, otherwise holds the connection open (up to
        `timeoutSeconds`) until one arrives or the poll times out.


        Each request carries its own `workspaceId`; submit the decision to `POST
        /approvals/{id}/decision` with that workspace's `X-Workspace-Id`.
        Authenticate with an organization API key (`oc_org_…`) — a workspace key
        answers `403`.
      operationId: listOrgPendingApprovals
      parameters:
        - name: exclude
          in: query
          required: false
          schema:
            type: string
          description: >-
            Comma-separated approval IDs to skip (already being handled) so the
            poll can hold open for genuinely new requests.
      responses:
        '200':
          description: Pending approval requests across the organization
          content:
            application/json:
              schema:
                type: object
                properties:
                  requests:
                    type: array
                    items:
                      $ref: '#/components/schemas/PendingApproval'
                  timeoutSeconds:
                    type: integer
        '403':
          description: >-
            Not an organization API key (`organization_scope_required`), or the
            deployment is not entitled (`enterprise_license_required`)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - organization_scope_required
                      - enterprise_license_required
      servers:
        - url: https://gw.buckle.dev
          description: Buckle Cloud gateway
        - url: http://localhost:10255
          description: Self-hosted gateway
components:
  schemas:
    PendingApproval:
      type: object
      description: >-
        A manual-approval request awaiting a decision, tagged with the workspace
        it belongs to.
      properties:
        id:
          type: string
          description: >-
            Unique approval ID. Pass to `POST /approvals/{id}/decision` to
            decide it.
        workspaceId:
          type: string
          description: >-
            The workspace this request belongs to. Send it as `X-Workspace-Id`
            when submitting the decision with an organization key.
        projectId:
          type: string
          deprecated: true
          description: Legacy twin of `workspaceId`, kept for older SDKs.
        method:
          type: string
          description: HTTP method of the held request (for example `POST`).
        url:
          type: string
          description: Full URL of the held request.
        host:
          type: string
        path:
          type: string
        headers:
          type: object
          additionalProperties:
            type: string
          description: Sanitized request headers (auth headers removed).
        bodyPreview:
          type: string
          nullable: true
          description: >-
            Human-readable, length-bounded rendering of the request body — safe
            to display directly.
        summary:
          type: object
          nullable: true
          description: >-
            Structured form of `bodyPreview` for richer rendering. `null` on
            records written before summaries existed.
          required:
            - action
            - details
          properties:
            action:
              type: string
              description: A short verb phrase for the card title.
            kind:
              type: string
              enum:
                - email
                - event
              description: >-
                Present when the request is recognised as a specific record
                type.
            details:
              type: array
              items:
                type: object
                required:
                  - label
                  - value
                properties:
                  label:
                    type: string
                  value:
                    type: string
                  url:
                    type: string
            subject:
              type: object
              description: The record the request acts on, when one was recognised.
              properties:
                verb:
                  type: string
                lead:
                  type: string
                record:
                  type: string
                row:
                  type: integer
        rawBody:
          type: object
          nullable: true
          description: >-
            The request body as the agent sent it, for a "raw request" view.
            Omitted when there was no body.
          required:
            - text
            - truncated
            - binary
          properties:
            text:
              type: string
              description: >-
                UTF-8 text, at most 8 KiB, with secret-named values masked.
                Empty when `binary`.
            truncated:
              type: boolean
              description: The body is longer than `text`.
            binary:
              type: boolean
              description: The body is not UTF-8 text, so none of it is shown.
            redacted:
              type: boolean
              description: At least one secret-named value was masked as `***`.
        app:
          type: string
          nullable: true
          description: >-
            The catalog app id the request's host belongs to (for example
            `salesforce`), or `null` for an unknown host.
        batch:
          type: object
          nullable: true
          description: >-
            Present when the agent tagged the request as part of a task batch so
            UIs can group approvals. Agent-supplied claims only.
          required:
            - id
          properties:
            id:
              type: string
              description: Opaque id shared by the task's requests.
            label:
              type: string
              maxLength: 120
            total:
              type: integer
              minimum: 1
              maximum: 500
              description: How many requests the agent says the task will send.
        agent:
          type: object
          description: The agent that made the request.
          properties:
            id:
              type: string
            name:
              type: string
            externalId:
              type: string
              nullable: true
              description: The agent's `identifier`.
        createdAt:
          type: string
          format: date-time
        expiresAt:
          type: string
          format: date-time
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        A workspace API key (`oc_…`) or organization API key (`oc_org_…`).
        Workspace-scoped endpoints called with an organization key also need
        `X-Workspace-Id`.

````

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