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

# Get a connection's generated client surface by selection — its index at a path, its resource families, one family, one type, or its implementation files

> Get a connection's generated client surface by selection — its index at a path, its resource families, one family, one type, or its implementation files. Requires permission `vendors:read`.



## OpenAPI

````yaml /forge/reference/openapi-v3.json get /api/v3/vendor-connection-client-surface
openapi: 3.1.0
info:
  title: Forge Platform API v3
  version: 0.23.0
  description: >-
    The Forge Platform API in its resource grammar: plural kebab-case
    collections, ids in the path, standard methods for the standard verbs and
    `POST …/{verb}` for the rest, and `/api/v3/me` for the caller's own records.
    Each operation is served by the same handler as the `/api/v2` operation it
    names: its operation id, credentials, permissions, refusals and idempotency
    are that operation's.
  contact:
    name: Forge Platform Team
servers:
  - url: https://api.forge.gloo.com
    description: Production
security:
  - BearerAuth: []
  - PlatformApiKey: []
  - PersonalKey: []
tags:
  - name: Agents
    description: >-
      Agent definitions: CRUD on the definition layer (create, get, list,
      update, delete) plus the A2A AgentCard endpoint, an agent's configuration,
      readiness and open setup request, the template gallery, the delegated work
      agents dispatched (sub-agent task runs and consultations), and agent
      administration: the kill switch, accountability repairs and setup
      requests.
  - name: Skills
    description: >-
      Skill definitions composed into agent prompts. List, fetch, and write
      skills owned by your External Application, and list and manage the skill
      sets that group them.
  - name: Tools
    description: >-
      Safe tool and tool-set catalog metadata and a tool's insights: the agents
      holding it, its calls, usage, history and sandbox rejections; workspace
      tool-set writes; no invocation.
  - name: Models
    description: Read-only access to the model catalog (provider, context window, status).
  - name: Workforce
    description: >-
      Organization units and positions in the caller’s workforce scope closure,
      and pods, pod membership previews and writes, pod lifecycle, ownership,
      internal profiles and Customer assignments, people (create, update, merge,
      offboard, reactivate), the worker directory, worker detail and seat
      budgets, assignment history, position assignment writes and the worker
      role list at the platform scope.
  - name: Objectives
    description: Read-only objective and key-result progress at the deployment root.
  - name: Planning
    description: >-
      Blueprint roadmaps, workstreams and milestones, and the critical-path and
      blocked-task projections, at the deployment root.
  - name: Projects
    description: Read-only project, customer relationship, and objective-link projections.
  - name: Workflows
    description: >-
      Workflow definitions and dispatch. List/get pinned workflow graphs and
      trigger runs by name.
  - name: Runs
    description: >-
      Workflow runs: list and read runs, their steps with runtime content,
      files, timeline, validator passes, recalled context, citations,
      notifications and governance status, the debug bundle, a Markdown export,
      agent conversations, the diagnostic timeline and AI analyses; cancel or
      restart a run, retry a failed notification, start an AI analysis and set a
      run's kill switch.
  - name: Chat
    description: >-
      Hybrid Workforce Chat — channels, sessions, and messages. Read
      channel/session state and post messages.
  - name: Memory
    description: >-
      Agent memory — channel and long-term layers. List, read, and write memory
      entries.
  - name: Knowledge
    description: >-
      Scoped knowledge: vector search, grounded answers, ingestion, entry reads
      and deletion. Every call is limited to the namespaces the credential may
      read or write, resolved server-side.
  - name: Factories
    description: >-
      Factory production units, their workers and tasks, spend and blueprints;
      operating a factory: messaging its manager agent and pausing, resuming or
      archiving it.
  - name: Sandboxes
    description: >-
      A run's sandboxes: recent runs that used them, the cached fleet summary, a
      run's lineage graph, its active sandboxes and a step's commands with
      masked output; diff two snapshots and replay a command against one in a
      fresh VM. Decided at the run's home and companies (factories:read; replay
      factories:manage).
  - name: Governance
    description: >-
      Approvals, policies and recorded decisions. List pending approvals, fetch
      detail, record decisions, list approval policies, list trust policies and
      their revisions, replay a trust policy against recorded decisions
      (historical, never an authorization), explain a recorded Trust Fabric
      decision, page recorded decision evidence, and read the permission catalog
      and role definitions.
  - name: Synthesis
    description: >-
      The synthesis queue: list and read synthesis requests, their Builder
      conversations and the procedures held for operator review, and promote,
      demote, accept or assign a reviewer to up to 50 requests per call. Decided
      at the platform scope.
  - name: Judges
    description: >-
      Machine judges: the judge catalog with metrics and rubrics, drift alerts,
      each judge's verdicts, pending primitive admissions, and the verdicts and
      live judge activity on a skill, agent, procedure, workflow draft or run.
      Decided at the platform scope.
  - name: Evals
    description: Evaluation sets and their runs.
  - name: External apps
    description: >-
      External Application registry: admin-only CRUD for the OAuth2 client
      credentials issued to integrating systems, an app's own record, and the
      agents an External App owns.
  - name: Costs and budgets
    description: >-
      Token spend and budgets. Bucketed and per-customer cost summaries are
      served from cron-populated rollups, so responses carry `meta.asOf`: an
      empty result with a null `asOf` means 'not accrued yet', not 'no spend'.
      Also agent and chat cost aggregates, the budget hierarchy, budget status
      and budget alerts.
  - name: Customers
    description: >-
      End-customer records, organizations and individuals. A customer row is
      shared across apps by `workosId`. The `/api/v2/external/customers` routes
      are an External Application's own view: per-app visibility comes from a
      `customerScopes` link, and those reads are fenced to the calling app. The
      `/api/v2/customers/*` routes are the organization's whole directory,
      decided at the deployment root for any credential holding `customers:read`
      there.
  - name: Procedures
    description: >-
      Read-only Procedures catalog — the deterministic, versioned units a
      workflow graph can bind. Compact projection only: never source code or
      bundled files.
  - name: Health
    description: Authenticated liveness check for integration smoke tests.
  - name: Capabilities
    description: >-
      Read-only deployment configuration: capability domains, their active
      provider chains, the provider catalog, credential health and a
      capability's recent changes. Decided at the deployment root; never
      credential values or option values.
  - name: Actor
    description: >-
      Request-scoped self-discovery: the calling credential's verified actor,
      its current narrowed permissions and each documented operation's advisory
      prerequisites.
  - name: API keys
    description: >-
      Personal keys and host sign-ins: a key owner lists and revokes their own;
      an administrator lists and revokes any person's.
  - name: Connections
    description: >-
      Connection credentials and the credential registry: list, create, review,
      revoke and delete credentials, and the vendors and connections they bind.
  - name: Email
    description: >-
      Inbound and outbound email: the outbox, received mail, the inbound ingress
      and its routes, and the sending domain.
  - name: Environments
    description: >-
      Environment Connections and their credentials: list, create, rename,
      replace the credential, and delete.
  - name: Identity
    description: >-
      Person profiles and avatars, and unmapped sign-in attempts waiting to be
      mapped or dismissed.
  - name: Notifications
    description: >-
      Notification event types with their payload fields, and the outbound Slack
      sends.
  - name: Observe and ops
    description: >-
      Operational reads: attention items, investigation notes, workflow
      performance and reliability overviews, failed runs, slow steps and a run's
      audit events.
  - name: Org units and positions
    description: >-
      The org chart: drafts that stage org unit and position changes, and the
      org units, positions and assignments they publish.
  - name: People and members
    description: >-
      People, their worker seats and org unit memberships, expertise tags, and
      the person-identity integrity check.
  - name: Projects and staffing
    description: Intake requests, their plans, and tasks across projects.
  - name: Roles and grants
    description: >-
      Job roles, the tools and skills they grant or deny, a holder's role
      grants, and AI-drafted role content.
  - name: Trust Fabric
    description: >-
      Governance controls and evidence: decisions, command tiers, trust
      assurance, policies, the governance door, the publish judge and the
      platform kill switch.
  - name: Vendors
    description: >-
      Vendors and their connections, attached API specs, generated client
      surfaces and remote MCP tool catalogs.
  - name: Webhooks
    description: >-
      Webhook subscriptions, deliveries and their attempts, replay and
      redelivery, dead letters, delivery health and the canonical event log.
  - name: Files
    description: >-
      Raw-byte file upload and authorized content redirects for uploaded files
      and readable run outputs.
  - name: Compliance
    description: >-
      Deployment-wide audit and governance record exports and a decision
      summary, for auditors holding `audit:read` at the deployment root.
paths:
  /api/v3/vendor-connection-client-surface:
    get:
      tags:
        - Vendors
      summary: >-
        Get a connection's generated client surface by selection: its index at a
        path, its resource families, one family, one type, or its implementation
        files.
      description: >-
        Requires permission `vendors:read`.


        Get a connection's generated client surface by selection: its index at a
        path, its resource families, one family, one type, or its implementation
        files.
      operationId: getVendorConnectionClientSurfaceAdmin
      parameters:
        - name: vendorKey
          in: query
          required: true
          schema:
            type: string
          example: sage_intacct
        - name: connectionName
          in: query
          required: true
          schema:
            type: string
          example: xml
        - name: selection
          in: query
          required: false
          description: A JSON-encoded value, at most 2048 characters.
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      kind:
                        type: string
                        const: index
                      path:
                        type: array
                        items:
                          type: string
                    required:
                      - kind
                      - path
                    additionalProperties: false
                  - type: object
                    properties:
                      kind:
                        type: string
                        const: families
                      query:
                        type: string
                      includeExtended:
                        type: boolean
                    required:
                      - kind
                    additionalProperties: false
                  - type: object
                    properties:
                      kind:
                        type: string
                        const: family
                      familyId:
                        type: string
                    required:
                      - kind
                      - familyId
                    additionalProperties: false
                  - type: object
                    properties:
                      kind:
                        type: string
                        const: type
                      typeName:
                        type: string
                    required:
                      - kind
                      - typeName
                    additionalProperties: false
                  - type: object
                    properties:
                      kind:
                        type: string
                        const: implementation
                      filePath:
                        type: string
                    required:
                      - kind
                    additionalProperties: false
              example:
                kind: families
      responses:
        '200':
          description: >-
            Get a connection's generated client surface by selection: its index
            at a path, its resource families, one family, one type, or its
            implementation files.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    anyOf:
                      - type: object
                        properties:
                          kind:
                            type: string
                            const: capability
                          client:
                            type: object
                            properties:
                              vendorKey:
                                type: string
                              connectionName:
                                type: string
                              displayName:
                                type: string
                              classDescription:
                                type: string
                              transport:
                                type: string
                                const: procedure_proxy
                              capabilityDomain:
                                type: string
                              providerId:
                                type: string
                              sourcePaths:
                                type: array
                                items:
                                  type: string
                            required:
                              - vendorKey
                              - connectionName
                              - displayName
                              - classDescription
                              - transport
                              - capabilityDomain
                              - providerId
                              - sourcePaths
                            additionalProperties: false
                          operations:
                            type: array
                            items:
                              type: object
                              properties:
                                domain:
                                  type: string
                                operation:
                                  type: string
                                displayName:
                                  type: string
                                description:
                                  type: string
                                argsSchemaJson:
                                  type: string
                                resultSchemaJson:
                                  type: string
                                httpSuccessEnvelopeSchemaJson:
                                  type: string
                                pythonCall:
                                  type: string
                                limits:
                                  type: object
                                  properties:
                                    maxQuestions:
                                      type: number
                                    maxOptions:
                                      type: number
                                    maxStateBytes:
                                      type: number
                                    maxRequestBytes:
                                      type: number
                                  required:
                                    - maxQuestions
                                    - maxOptions
                                    - maxStateBytes
                                    - maxRequestBytes
                                  additionalProperties: false
                              required:
                                - domain
                                - operation
                                - displayName
                                - description
                                - argsSchemaJson
                                - resultSchemaJson
                                - httpSuccessEnvelopeSchemaJson
                                - pythonCall
                                - limits
                              additionalProperties: false
                        required:
                          - kind
                          - client
                          - operations
                        additionalProperties: false
                      - type: object
                        properties:
                          kind:
                            type: string
                            const: index
                          client:
                            type: object
                            properties:
                              vendorKey:
                                type: string
                              connectionName:
                                type: string
                              module:
                                type: string
                              className:
                                type: string
                              displayName:
                                type: string
                              classDescription:
                                type: string
                              version:
                                type: string
                              sourceDigest:
                                type: string
                              requiredPackages:
                                type: array
                                items:
                                  type: string
                              pythonUsage:
                                type: object
                                properties:
                                  imports:
                                    type: array
                                    items:
                                      type: string
                                  clientExpression:
                                    type: string
                                required:
                                  - imports
                                  - clientExpression
                                additionalProperties: false
                              authoringFallbackPolicy:
                                anyOf:
                                  - type: string
                                    const: raw_allowed
                                  - type: string
                                    const: client_only
                            required:
                              - vendorKey
                              - connectionName
                              - module
                              - className
                              - displayName
                              - classDescription
                              - version
                              - sourceDigest
                              - requiredPackages
                              - pythonUsage
                              - authoringFallbackPolicy
                            additionalProperties: false
                          path:
                            type: array
                            items:
                              type: string
                          children:
                            type: array
                            items:
                              type: object
                              properties:
                                id:
                                  type: string
                                label:
                                  type: string
                                path:
                                  type: array
                                  items:
                                    type: string
                                kind:
                                  anyOf:
                                    - type: string
                                      const: group
                                    - type: string
                                      const: operation
                                operationKind:
                                  anyOf:
                                    - type: string
                                      const: read_one
                                    - type: string
                                      const: read_list
                                    - type: string
                                      const: read_page
                                    - type: string
                                      const: read_stream
                                    - type: string
                                      const: create
                                    - type: string
                                      const: update
                                    - type: string
                                      const: action
                                effect:
                                  anyOf:
                                    - type: string
                                      const: read
                                    - type: string
                                      const: write
                                supportStatus:
                                  type: string
                                  const: supported
                                familyId:
                                  type: string
                                authoringTier:
                                  anyOf:
                                    - type: string
                                      const: core
                                    - type: string
                                      const: extended
                                hasChildren:
                                  type: boolean
                              required:
                                - id
                                - label
                                - path
                                - kind
                                - hasChildren
                              additionalProperties: false
                        required:
                          - kind
                          - client
                          - path
                          - children
                        additionalProperties: false
                      - type: object
                        properties:
                          kind:
                            type: string
                            const: families
                          client:
                            type: object
                            properties:
                              vendorKey:
                                type: string
                              connectionName:
                                type: string
                              module:
                                type: string
                              className:
                                type: string
                              displayName:
                                type: string
                              classDescription:
                                type: string
                              version:
                                type: string
                              sourceDigest:
                                type: string
                              requiredPackages:
                                type: array
                                items:
                                  type: string
                              pythonUsage:
                                type: object
                                properties:
                                  imports:
                                    type: array
                                    items:
                                      type: string
                                  clientExpression:
                                    type: string
                                required:
                                  - imports
                                  - clientExpression
                                additionalProperties: false
                              authoringFallbackPolicy:
                                anyOf:
                                  - type: string
                                    const: raw_allowed
                                  - type: string
                                    const: client_only
                            required:
                              - vendorKey
                              - connectionName
                              - module
                              - className
                              - displayName
                              - classDescription
                              - version
                              - sourceDigest
                              - requiredPackages
                              - pythonUsage
                              - authoringFallbackPolicy
                            additionalProperties: false
                          families:
                            type: array
                            items:
                              type: object
                              properties:
                                familyId:
                                  type: string
                                displayName:
                                  type: string
                                summary:
                                  type: string
                                useWhen:
                                  type: string
                                provenance:
                                  type: object
                                  properties:
                                    module:
                                      type: string
                                    resource:
                                      type: string
                                  required:
                                    - module
                                    - resource
                                  additionalProperties: false
                                authoringTier:
                                  anyOf:
                                    - type: string
                                      const: core
                                    - type: string
                                      const: extended
                                semanticKind:
                                  anyOf:
                                    - type: string
                                      const: entity
                                    - type: string
                                      const: transaction
                                    - type: string
                                      const: detail
                                    - type: string
                                      const: relationship
                                    - type: string
                                      const: report
                                    - type: string
                                      const: action
                                    - type: string
                                      const: reference
                                parentFamilyId:
                                  type: string
                              required:
                                - familyId
                                - displayName
                                - summary
                                - useWhen
                                - provenance
                                - authoringTier
                                - semanticKind
                              additionalProperties: false
                          totalMatches:
                            type: number
                          truncated:
                            type: boolean
                        required:
                          - kind
                          - client
                          - families
                          - totalMatches
                          - truncated
                        additionalProperties: false
                      - type: object
                        properties:
                          kind:
                            type: string
                            const: family
                          client:
                            type: object
                            properties:
                              vendorKey:
                                type: string
                              connectionName:
                                type: string
                              module:
                                type: string
                              className:
                                type: string
                              displayName:
                                type: string
                              classDescription:
                                type: string
                              version:
                                type: string
                              sourceDigest:
                                type: string
                              requiredPackages:
                                type: array
                                items:
                                  type: string
                              pythonUsage:
                                type: object
                                properties:
                                  imports:
                                    type: array
                                    items:
                                      type: string
                                  clientExpression:
                                    type: string
                                required:
                                  - imports
                                  - clientExpression
                                additionalProperties: false
                              authoringFallbackPolicy:
                                anyOf:
                                  - type: string
                                    const: raw_allowed
                                  - type: string
                                    const: client_only
                            required:
                              - vendorKey
                              - connectionName
                              - module
                              - className
                              - displayName
                              - classDescription
                              - version
                              - sourceDigest
                              - requiredPackages
                              - pythonUsage
                              - authoringFallbackPolicy
                            additionalProperties: false
                          family:
                            type: object
                            properties:
                              familyId:
                                type: string
                              displayName:
                                type: string
                              summary:
                                type: string
                              useWhen:
                                type: string
                              provenance:
                                type: object
                                properties:
                                  module:
                                    type: string
                                  resource:
                                    type: string
                                required:
                                  - module
                                  - resource
                                additionalProperties: false
                              authoringTier:
                                anyOf:
                                  - type: string
                                    const: core
                                  - type: string
                                    const: extended
                              semanticKind:
                                anyOf:
                                  - type: string
                                    const: entity
                                  - type: string
                                    const: transaction
                                  - type: string
                                    const: detail
                                  - type: string
                                    const: relationship
                                  - type: string
                                    const: report
                                  - type: string
                                    const: action
                                  - type: string
                                    const: reference
                              parentFamilyId:
                                type: string
                            required:
                              - familyId
                              - displayName
                              - summary
                              - useWhen
                              - provenance
                              - authoringTier
                              - semanticKind
                            additionalProperties: false
                          operations:
                            type: array
                            items:
                              type: object
                              properties:
                                operationId:
                                  type: string
                                displayName:
                                  type: string
                                description:
                                  type: string
                                path:
                                  type: array
                                  items:
                                    type: string
                                kind:
                                  anyOf:
                                    - type: string
                                      const: read_one
                                    - type: string
                                      const: read_list
                                    - type: string
                                      const: read_page
                                    - type: string
                                      const: read_stream
                                    - type: string
                                      const: create
                                    - type: string
                                      const: update
                                    - type: string
                                      const: action
                                effect:
                                  anyOf:
                                    - type: string
                                      const: read
                                    - type: string
                                      const: write
                                ownerType:
                                  type: string
                                method:
                                  type: string
                                supportStatus:
                                  type: string
                                  const: supported
                                bindingAliases:
                                  type: array
                                  items:
                                    type: string
                                typeNames:
                                  type: array
                                  items:
                                    type: string
                                bounds:
                                  type: object
                                  properties:
                                    defaultPageSize:
                                      type: number
                                    maxPageSize:
                                      type: number
                                    maxPages:
                                      type: number
                                    maxRecords:
                                      type: number
                                    checkpointed:
                                      type: boolean
                                  required:
                                    - checkpointed
                                  additionalProperties: false
                                provenance:
                                  type: object
                                  properties:
                                    module:
                                      type: string
                                    resource:
                                      type: string
                                    apiVersion:
                                      type: string
                                  required:
                                    - module
                                    - resource
                                    - apiVersion
                                  additionalProperties: false
                                signature:
                                  type: string
                                parameters:
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      name:
                                        type: string
                                      kind:
                                        anyOf:
                                          - type: string
                                            const: positional
                                          - type: string
                                            const: keyword_only
                                          - type: string
                                            const: var_positional
                                          - type: string
                                            const: var_keyword
                                      annotation:
                                        type: string
                                      required:
                                        type: boolean
                                      defaultValue:
                                        type: string
                                    required:
                                      - name
                                      - kind
                                      - annotation
                                      - required
                                    additionalProperties: false
                                returnAnnotation:
                                  type: string
                                docstring:
                                  type: string
                                certification:
                                  type: object
                                  properties:
                                    subjectKind:
                                      anyOf:
                                        - type: string
                                          const: procedure
                                        - type: string
                                          const: operation
                                    procedureId:
                                      type: string
                                    requiredTier:
                                      anyOf:
                                        - type: string
                                          const: deterministic
                                        - type: string
                                          const: drift_monitored
                                    effectiveTier:
                                      anyOf:
                                        - type: string
                                          const: deterministic
                                        - type: string
                                          const: drift_monitored
                                    status:
                                      anyOf:
                                        - type: string
                                          const: certified
                                        - type: string
                                          const: not_configured
                                        - type: string
                                          const: not_verified
                                        - type: string
                                          const: stale
                                        - type: string
                                          const: drifted
                                    deterministicTestPaths:
                                      type: array
                                      items:
                                        type: string
                                    fixtureEvidence:
                                      type: array
                                      items:
                                        type: object
                                        properties:
                                          path:
                                            type: string
                                          provenance:
                                            anyOf:
                                              - type: string
                                                const: documented_shape
                                              - type: string
                                                const: official_docs_synthetic
                                              - type: string
                                                const: synthetic_shape
                                        required:
                                          - path
                                          - provenance
                                        additionalProperties: false
                                    fixtureGapReason:
                                      anyOf:
                                        - type: string
                                        - type: 'null'
                                    bindingEvidence:
                                      type: object
                                      properties:
                                        hostFamilies:
                                          type: array
                                          items:
                                            type: string
                                        baseUrlTemplate:
                                          type: string
                                        authScheme:
                                          type: string
                                      required:
                                        - hostFamilies
                                        - baseUrlTemplate
                                        - authScheme
                                      additionalProperties: false
                                    liveVerificationSource:
                                      anyOf:
                                        - type: string
                                        - type: 'null'
                                    driftCheckKey:
                                      anyOf:
                                        - type: string
                                        - type: 'null'
                                    latestObservation:
                                      anyOf:
                                        - type: object
                                          properties:
                                            status:
                                              anyOf:
                                                - type: string
                                                  const: green
                                                - type: string
                                                  const: drifted
                                                - type: string
                                                  const: skipped
                                            lastCheckedAt:
                                              type: number
                                            fingerprint:
                                              anyOf:
                                                - type: string
                                                - type: 'null'
                                            reason:
                                              anyOf:
                                                - type: string
                                                - type: 'null'
                                            message:
                                              anyOf:
                                                - type: string
                                                - type: 'null'
                                          required:
                                            - status
                                            - lastCheckedAt
                                            - fingerprint
                                            - reason
                                            - message
                                          additionalProperties: false
                                        - type: 'null'
                                  required:
                                    - subjectKind
                                    - requiredTier
                                    - effectiveTier
                                    - status
                                    - deterministicTestPaths
                                    - fixtureEvidence
                                    - fixtureGapReason
                                    - bindingEvidence
                                    - liveVerificationSource
                                    - driftCheckKey
                                    - latestObservation
                                  additionalProperties: false
                              required:
                                - operationId
                                - displayName
                                - description
                                - path
                                - kind
                                - effect
                                - ownerType
                                - method
                                - supportStatus
                                - bindingAliases
                                - typeNames
                                - bounds
                                - provenance
                                - signature
                                - parameters
                                - returnAnnotation
                                - docstring
                              additionalProperties: false
                          typeNames:
                            type: array
                            items:
                              type: string
                          parent:
                            anyOf:
                              - type: object
                                properties:
                                  familyId:
                                    type: string
                                  displayName:
                                    type: string
                                  summary:
                                    type: string
                                  useWhen:
                                    type: string
                                  provenance:
                                    type: object
                                    properties:
                                      module:
                                        type: string
                                      resource:
                                        type: string
                                    required:
                                      - module
                                      - resource
                                    additionalProperties: false
                                  authoringTier:
                                    anyOf:
                                      - type: string
                                        const: core
                                      - type: string
                                        const: extended
                                  semanticKind:
                                    anyOf:
                                      - type: string
                                        const: entity
                                      - type: string
                                        const: transaction
                                      - type: string
                                        const: detail
                                      - type: string
                                        const: relationship
                                      - type: string
                                        const: report
                                      - type: string
                                        const: action
                                      - type: string
                                        const: reference
                                  parentFamilyId:
                                    type: string
                                required:
                                  - familyId
                                  - displayName
                                  - summary
                                  - useWhen
                                  - provenance
                                  - authoringTier
                                  - semanticKind
                                additionalProperties: false
                              - type: 'null'
                          children:
                            type: array
                            items:
                              type: object
                              properties:
                                familyId:
                                  type: string
                                displayName:
                                  type: string
                                summary:
                                  type: string
                                useWhen:
                                  type: string
                                provenance:
                                  type: object
                                  properties:
                                    module:
                                      type: string
                                    resource:
                                      type: string
                                  required:
                                    - module
                                    - resource
                                  additionalProperties: false
                                authoringTier:
                                  anyOf:
                                    - type: string
                                      const: core
                                    - type: string
                                      const: extended
                                semanticKind:
                                  anyOf:
                                    - type: string
                                      const: entity
                                    - type: string
                                      const: transaction
                                    - type: string
                                      const: detail
                                    - type: string
                                      const: relationship
                                    - type: string
                                      const: report
                                    - type: string
                                      const: action
                                    - type: string
                                      const: reference
                                parentFamilyId:
                                  type: string
                              required:
                                - familyId
                                - displayName
                                - summary
                                - useWhen
                                - provenance
                                - authoringTier
                                - semanticKind
                              additionalProperties: false
                        required:
                          - kind
                          - client
                          - family
                          - operations
                          - typeNames
                          - parent
                          - children
                        additionalProperties: false
                      - type: object
                        properties:
                          kind:
                            type: string
                            const: operations
                          client:
                            type: object
                            properties:
                              vendorKey:
                                type: string
                              connectionName:
                                type: string
                              module:
                                type: string
                              className:
                                type: string
                              displayName:
                                type: string
                              classDescription:
                                type: string
                              version:
                                type: string
                              sourceDigest:
                                type: string
                              requiredPackages:
                                type: array
                                items:
                                  type: string
                              pythonUsage:
                                type: object
                                properties:
                                  imports:
                                    type: array
                                    items:
                                      type: string
                                  clientExpression:
                                    type: string
                                required:
                                  - imports
                                  - clientExpression
                                additionalProperties: false
                              authoringFallbackPolicy:
                                anyOf:
                                  - type: string
                                    const: raw_allowed
                                  - type: string
                                    const: client_only
                            required:
                              - vendorKey
                              - connectionName
                              - module
                              - className
                              - displayName
                              - classDescription
                              - version
                              - sourceDigest
                              - requiredPackages
                              - pythonUsage
                              - authoringFallbackPolicy
                            additionalProperties: false
                          path:
                            type: array
                            items:
                              type: string
                          operations:
                            type: array
                            items:
                              type: object
                              properties:
                                operationId:
                                  type: string
                                displayName:
                                  type: string
                                description:
                                  type: string
                                path:
                                  type: array
                                  items:
                                    type: string
                                kind:
                                  anyOf:
                                    - type: string
                                      const: read_one
                                    - type: string
                                      const: read_list
                                    - type: string
                                      const: read_page
                                    - type: string
                                      const: read_stream
                                    - type: string
                                      const: create
                                    - type: string
                                      const: update
                                    - type: string
                                      const: action
                                effect:
                                  anyOf:
                                    - type: string
                                      const: read
                                    - type: string
                                      const: write
                                ownerType:
                                  type: string
                                method:
                                  type: string
                                supportStatus:
                                  type: string
                                  const: supported
                                bindingAliases:
                                  type: array
                                  items:
                                    type: string
                                typeNames:
                                  type: array
                                  items:
                                    type: string
                                bounds:
                                  type: object
                                  properties:
                                    defaultPageSize:
                                      type: number
                                    maxPageSize:
                                      type: number
                                    maxPages:
                                      type: number
                                    maxRecords:
                                      type: number
                                    checkpointed:
                                      type: boolean
                                  required:
                                    - checkpointed
                                  additionalProperties: false
                                provenance:
                                  type: object
                                  properties:
                                    module:
                                      type: string
                                    resource:
                                      type: string
                                    apiVersion:
                                      type: string
                                  required:
                                    - module
                                    - resource
                                    - apiVersion
                                  additionalProperties: false
                                signature:
                                  type: string
                                parameters:
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      name:
                                        type: string
                                      kind:
                                        anyOf:
                                          - type: string
                                            const: positional
                                          - type: string
                                            const: keyword_only
                                          - type: string
                                            const: var_positional
                                          - type: string
                                            const: var_keyword
                                      annotation:
                                        type: string
                                      required:
                                        type: boolean
                                      defaultValue:
                                        type: string
                                    required:
                                      - name
                                      - kind
                                      - annotation
                                      - required
                                    additionalProperties: false
                                returnAnnotation:
                                  type: string
                                docstring:
                                  type: string
                                certification:
                                  type: object
                                  properties:
                                    subjectKind:
                                      anyOf:
                                        - type: string
                                          const: procedure
                                        - type: string
                                          const: operation
                                    procedureId:
                                      type: string
                                    requiredTier:
                                      anyOf:
                                        - type: string
                                          const: deterministic
                                        - type: string
                                          const: drift_monitored
                                    effectiveTier:
                                      anyOf:
                                        - type: string
                                          const: deterministic
                                        - type: string
                                          const: drift_monitored
                                    status:
                                      anyOf:
                                        - type: string
                                          const: certified
                                        - type: string
                                          const: not_configured
                                        - type: string
                                          const: not_verified
                                        - type: string
                                          const: stale
                                        - type: string
                                          const: drifted
                                    deterministicTestPaths:
                                      type: array
                                      items:
                                        type: string
                                    fixtureEvidence:
                                      type: array
                                      items:
                                        type: object
                                        properties:
                                          path:
                                            type: string
                                          provenance:
                                            anyOf:
                                              - type: string
                                                const: documented_shape
                                              - type: string
                                                const: official_docs_synthetic
                                              - type: string
                                                const: synthetic_shape
                                        required:
                                          - path
                                          - provenance
                                        additionalProperties: false
                                    fixtureGapReason:
                                      anyOf:
                                        - type: string
                                        - type: 'null'
                                    bindingEvidence:
                                      type: object
                                      properties:
                                        hostFamilies:
                                          type: array
                                          items:
                                            type: string
                                        baseUrlTemplate:
                                          type: string
                                        authScheme:
                                          type: string
                                      required:
                                        - hostFamilies
                                        - baseUrlTemplate
                                        - authScheme
                                      additionalProperties: false
                                    liveVerificationSource:
                                      anyOf:
                                        - type: string
                                        - type: 'null'
                                    driftCheckKey:
                                      anyOf:
                                        - type: string
                                        - type: 'null'
                                    latestObservation:
                                      anyOf:
                                        - type: object
                                          properties:
                                            status:
                                              anyOf:
                                                - type: string
                                                  const: green
                                                - type: string
                                                  const: drifted
                                                - type: string
                                                  const: skipped
                                            lastCheckedAt:
                                              type: number
                                            fingerprint:
                                              anyOf:
                                                - type: string
                                                - type: 'null'
                                            reason:
                                              anyOf:
                                                - type: string
                                                - type: 'null'
                                            message:
                                              anyOf:
                                                - type: string
                                                - type: 'null'
                                          required:
                                            - status
                                            - lastCheckedAt
                                            - fingerprint
                                            - reason
                                            - message
                                          additionalProperties: false
                                        - type: 'null'
                                  required:
                                    - subjectKind
                                    - requiredTier
                                    - effectiveTier
                                    - status
                                    - deterministicTestPaths
                                    - fixtureEvidence
                                    - fixtureGapReason
                                    - bindingEvidence
                                    - liveVerificationSource
                                    - driftCheckKey
                                    - latestObservation
                                  additionalProperties: false
                              required:
                                - operationId
                                - displayName
                                - description
                                - path
                                - kind
                                - effect
                                - ownerType
                                - method
                                - supportStatus
                                - bindingAliases
                                - typeNames
                                - bounds
                                - provenance
                                - signature
                                - parameters
                                - returnAnnotation
                                - docstring
                              additionalProperties: false
                          typeNames:
                            type: array
                            items:
                              type: string
                        required:
                          - kind
                          - client
                          - path
                          - operations
                          - typeNames
                        additionalProperties: false
                      - type: object
                        properties:
                          kind:
                            type: string
                            const: type
                          client:
                            type: object
                            properties:
                              vendorKey:
                                type: string
                              connectionName:
                                type: string
                              module:
                                type: string
                              className:
                                type: string
                              displayName:
                                type: string
                              classDescription:
                                type: string
                              version:
                                type: string
                              sourceDigest:
                                type: string
                              requiredPackages:
                                type: array
                                items:
                                  type: string
                              pythonUsage:
                                type: object
                                properties:
                                  imports:
                                    type: array
                                    items:
                                      type: string
                                  clientExpression:
                                    type: string
                                required:
                                  - imports
                                  - clientExpression
                                additionalProperties: false
                              authoringFallbackPolicy:
                                anyOf:
                                  - type: string
                                    const: raw_allowed
                                  - type: string
                                    const: client_only
                            required:
                              - vendorKey
                              - connectionName
                              - module
                              - className
                              - displayName
                              - classDescription
                              - version
                              - sourceDigest
                              - requiredPackages
                              - pythonUsage
                              - authoringFallbackPolicy
                            additionalProperties: false
                          type:
                            anyOf:
                              - type: object
                                properties:
                                  kind:
                                    anyOf:
                                      - type: string
                                        const: record
                                      - type: string
                                        const: filter
                                      - type: string
                                        const: page
                                  name:
                                    type: string
                                  description:
                                    type: string
                                  fields:
                                    type: array
                                    items:
                                      type: object
                                      properties:
                                        name:
                                          type: string
                                        annotation:
                                          type: string
                                        required:
                                          type: boolean
                                        description:
                                          type: string
                                        referencedTypeNames:
                                          type: array
                                          items:
                                            type: string
                                      required:
                                        - name
                                        - annotation
                                        - required
                                        - description
                                        - referencedTypeNames
                                      additionalProperties: false
                                  additionalProperties:
                                    type: boolean
                                required:
                                  - kind
                                  - name
                                  - description
                                  - fields
                                  - additionalProperties
                                additionalProperties: false
                              - type: object
                                properties:
                                  kind:
                                    type: string
                                    const: enum
                                  name:
                                    type: string
                                  description:
                                    type: string
                                  values:
                                    type: array
                                    items:
                                      type: string
                                required:
                                  - kind
                                  - name
                                  - description
                                  - values
                                additionalProperties: false
                        required:
                          - kind
                          - client
                          - type
                        additionalProperties: false
                      - type: object
                        properties:
                          kind:
                            type: string
                            const: implementation_index
                          client:
                            type: object
                            properties:
                              vendorKey:
                                type: string
                              connectionName:
                                type: string
                              module:
                                type: string
                              className:
                                type: string
                              displayName:
                                type: string
                              classDescription:
                                type: string
                              version:
                                type: string
                              sourceDigest:
                                type: string
                              requiredPackages:
                                type: array
                                items:
                                  type: string
                              pythonUsage:
                                type: object
                                properties:
                                  imports:
                                    type: array
                                    items:
                                      type: string
                                  clientExpression:
                                    type: string
                                required:
                                  - imports
                                  - clientExpression
                                additionalProperties: false
                              authoringFallbackPolicy:
                                anyOf:
                                  - type: string
                                    const: raw_allowed
                                  - type: string
                                    const: client_only
                            required:
                              - vendorKey
                              - connectionName
                              - module
                              - className
                              - displayName
                              - classDescription
                              - version
                              - sourceDigest
                              - requiredPackages
                              - pythonUsage
                              - authoringFallbackPolicy
                            additionalProperties: false
                          constructorSignature:
                            type: string
                          files:
                            type: array
                            items:
                              type: object
                              properties:
                                path:
                                  type: string
                                role:
                                  anyOf:
                                    - type: string
                                      const: client
                                    - type: string
                                      const: shared
                                    - type: string
                                      const: test
                                byteCount:
                                  type: number
                                sha256:
                                  type: string
                              required:
                                - path
                                - role
                                - byteCount
                                - sha256
                              additionalProperties: false
                        required:
                          - kind
                          - client
                          - constructorSignature
                          - files
                        additionalProperties: false
                      - type: object
                        properties:
                          kind:
                            type: string
                            const: implementation_file
                          client:
                            type: object
                            properties:
                              vendorKey:
                                type: string
                              connectionName:
                                type: string
                              module:
                                type: string
                              className:
                                type: string
                              displayName:
                                type: string
                              classDescription:
                                type: string
                              version:
                                type: string
                              sourceDigest:
                                type: string
                              requiredPackages:
                                type: array
                                items:
                                  type: string
                              pythonUsage:
                                type: object
                                properties:
                                  imports:
                                    type: array
                                    items:
                                      type: string
                                  clientExpression:
                                    type: string
                                required:
                                  - imports
                                  - clientExpression
                                additionalProperties: false
                              authoringFallbackPolicy:
                                anyOf:
                                  - type: string
                                    const: raw_allowed
                                  - type: string
                                    const: client_only
                            required:
                              - vendorKey
                              - connectionName
                              - module
                              - className
                              - displayName
                              - classDescription
                              - version
                              - sourceDigest
                              - requiredPackages
                              - pythonUsage
                              - authoringFallbackPolicy
                            additionalProperties: false
                          constructorSignature:
                            type: string
                          file:
                            type: object
                            properties:
                              path:
                                type: string
                              role:
                                anyOf:
                                  - type: string
                                    const: client
                                  - type: string
                                    const: shared
                                  - type: string
                                    const: test
                              byteCount:
                                type: number
                              sha256:
                                type: string
                              content:
                                type: string
                            required:
                              - path
                              - role
                              - byteCount
                              - sha256
                              - content
                            additionalProperties: false
                        required:
                          - kind
                          - client
                          - constructorSignature
                          - file
                        additionalProperties: false
                      - type: 'null'
                  meta:
                    $ref: '#/components/schemas/PlatformMeta'
                required:
                  - data
                  - meta
              example:
                data:
                  kind: families
                  client:
                    vendorKey: sage_intacct
                    connectionName: xml
                    module: intacct_xml
                    className: IntacctXmlClient
                    displayName: Sage Intacct XML
                    classDescription: >-
                      The `sage_intacct/xml` connection client.


                      Credentials are read from the five
                      `GLOO_CONN_SAGE_INTACCT__XML__CRED_*` env vars at
                      construction

                      time (blueprint §2.9) — missing any of them raises
                      `AUTH_FAILED`

                      immediately, before a `transport` is ever touched.
                      `transport` is

                      required explicitly (no silent default to a real network
                      client): pass

                      `HttpxTransport()` for real dispatch, or a
                      `ReplayTransport` in tests.
                    version: 0.17.0
                    sourceDigest: >-
                      483ad9bca9cde657edb77a2fe0bdbbca88bf19a74c3530372c4517e365cf0f00
                    requiredPackages:
                      - httpx>=0.27
                      - typing-extensions>=4.12,<5
                    pythonUsage:
                      clientExpression: IntacctXmlClient(intacct_transport_from_env())
                      imports:
                        - >-
                          from gloo_connection_clients import IntacctXmlClient,
                          intacct_transport_from_env
                    authoringFallbackPolicy: raw_allowed
                  families:
                    - authoringTier: core
                      displayName: Accounts Payable Aging Report
                      familyId: accounts-payable-aging-report
                      provenance:
                        module: intacct_xml
                        resource: xml
                      semanticKind: report
                      summary: >-
                        Sage Intacct XML Accounts Payable Aging Report output
                        represents aged vendor payables for payment review.
                      useWhen: >-
                        Choose this for vendor payable aging; use the AR aging
                        report for customer obligations instead.
                    - authoringTier: core
                      displayName: Accounts Receivable Aging Report
                      familyId: accounts-receivable-aging-report
                      provenance:
                        module: intacct_xml
                        resource: xml
                      semanticKind: report
                      summary: >-
                        Sage Intacct XML Accounts Receivable Aging Report output
                        represents aged customer receivables for collection
                        review.
                      useWhen: >-
                        Choose this for customer receivable aging; use the AP
                        aging report for vendor obligations instead.
                    - authoringTier: core
                      displayName: General Ledger Detail Report
                      familyId: general-ledger-detail-report
                      provenance:
                        module: intacct_xml
                        resource: xml
                      semanticKind: report
                      summary: >-
                        Sage Intacct XML General Ledger Detail Report output
                        represents ledger detail rows for accounting analysis.
                      useWhen: >-
                        Choose this for report-style ledger detail rather than
                        customer or vendor aging.
                  totalMatches: 3
                  truncated: false
                meta:
                  requestId: req_example
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
        '400':
          description: '`bad_request`: an unknown, repeated or invalid argument'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse400'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse401'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
        '403':
          description: >-
            Forbidden: `vendors:read` is not held at the platform scope; an
            External App is refused: call with an API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse403'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          description: Internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
        '503':
          $ref: '#/components/responses/LimiterUnavailable'
      security:
        - PlatformApiKey: []
        - PersonalKey: []
components:
  schemas:
    PlatformMeta:
      type: object
      properties:
        requestId:
          type: string
        hasMore:
          type: boolean
        nextCursor:
          type:
            - string
            - 'null'
        asOf:
          anyOf:
            - type: integer
            - type: 'null'
      required:
        - requestId
      additionalProperties: true
    ErrorResponse400:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
        - type: object
          properties:
            error:
              type: object
              properties:
                code:
                  type: string
                  enum:
                    - bad_request
                    - allowed_scopes_removed
    ErrorResponse401:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
        - type: object
          properties:
            error:
              type: object
              properties:
                code:
                  type: string
                  enum:
                    - unauthorized
    ErrorResponse403:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
        - type: object
          properties:
            error:
              type: object
              properties:
                code:
                  type: string
                  enum:
                    - forbidden
                    - permission_denied
                    - operator_stopped
    ErrorResponse500:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
        - type: object
          properties:
            error:
              type: object
              properties:
                code:
                  type: string
                  enum:
                    - internal_error
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - unauthorized
                - forbidden
                - permission_denied
                - not_found
                - resource_missing
                - method_not_allowed
                - bad_request
                - unprocessable
                - conflict
                - invalid_state
                - gone
                - payment_required
                - idempotency_key_invalid
                - idempotency_key_in_flight
                - idempotency_key_reuse
                - idempotency_result_unavailable
                - idempotency_outcome_unknown
                - allowed_scopes_removed
                - governance_door_stopped
                - operator_stopped
                - payload_too_large
                - rate_limited
                - internal_error
            message:
              type: string
            docUrl:
              type: string
              format: uri
            reason:
              type: string
              enum:
                - requester_unavailable
                - invalid_body
                - form_invalid
                - form_secret_like
                - eligibility_invalid
                - due_out_of_range
                - no_candidates
                - org_unit_required
                - requester_open_cap
                - person_open_cap
                - rate_limited
                - role_giving_refused
            requiredPermission:
              type:
                - string
                - 'null'
            personRequired:
              type: boolean
            decisionId:
              type: string
            capHeadroom:
              type: object
              properties:
                remainingCents:
                  type: number
                capCents:
                  type: number
                consumedCents:
                  type: number
                estimateCents:
                  type: number
              required:
                - remainingCents
                - capCents
                - consumedCents
                - estimateCents
              additionalProperties: false
            details:
              type: array
              items:
                type: object
                properties:
                  path:
                    type: string
                  param:
                    type: string
                  message:
                    type: string
                  code:
                    type: string
                    enum:
                      - required
                      - invalid_type
                      - invalid_value
                      - invalid_format
                      - too_small
                      - too_big
                      - unknown_field
                      - invalid_json
                      - invalid
                required:
                  - path
                  - param
                  - message
                  - code
                additionalProperties: false
              maxItems: 50
          required:
            - code
            - message
          additionalProperties: true
        meta:
          type: object
          properties:
            requestId:
              type: string
            hasMore:
              type: boolean
            nextCursor:
              type:
                - string
                - 'null'
            asOf:
              anyOf:
                - type: integer
                - type: 'null'
          required:
            - requestId
          additionalProperties: true
      required:
        - error
        - meta
      additionalProperties: true
  headers:
    RequestId:
      description: >-
        This answer's request id, the same as the envelope's `meta.requestId`:
        `req_` and 16 lowercase hex digits. Every response carries it. Quote it
        to support, or look the request up with `GET
        /api/v3/me/requests/{requestId}`.
      schema:
        type: string
    RateLimitLimit:
      description: >-
        The capacity of the bucket this request spent from: the most requests it
        admits at once. Sent on every response to a request that spent from its
        bucket, whatever its status: a 401 or 503 the operation answers after
        that spend carries it too. Absent on a refusal before the spend (a 401
        from authentication, a stopped `api_keys` door's 503
        `governance_door_stopped`, a credential's 403 at sign-in), on a route's
        own tighter 429, and on the limiter's own 503, which could not spend.
      schema:
        type: integer
        minimum: 0
    RateLimitRemaining:
      description: >-
        Requests left in the bucket this request spent from; 0 on a refusal.
        While the limiter is degraded (its fallback bucket admitted the
        request), an estimate.
      schema:
        type: integer
        minimum: 0
    RateLimitReset:
      description: Seconds until the bucket this request spent from is full again.
      schema:
        type: integer
        minimum: 0
    RetryAfter:
      description: >-
        Seconds to wait before sending the request again. Sent on a 429 and on a
        transient 503.
      schema:
        type: integer
        minimum: 1
  responses:
    RateLimited:
      description: >-
        `rate_limited`: this credential, or the organization as a whole, has
        spent the requests of this operation's class for now. Each credential
        has three buckets: `read` (GET, HEAD), `write` (every other method) and
        `expensive` (an operation that starts a model turn, a run, a billable VM
        or a bulk job); each operation names its class in `x-forge-rate-limit`
        and spends from that bucket only. Every credential's requests also spend
        from the organization ceiling, one bucket per class at ten times a
        credential's limit, shared by every credential of the deployment; the
        message names which one refused. Wait `Retry-After` seconds, then retry.
        Every authenticated response carries the `RateLimit-*` headers for the
        bucket it spent from, so a client can slow down before it is refused;
        `GET /api/v2/me/limits` answers all three buckets and the ceiling.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    LimiterUnavailable:
      description: >-
        `internal_error`: The server could not complete the request. Wait for
        `Retry-After`, then retry; resend a write only with the same
        `Idempotency-Key`. Forge answers it when its rate limiter is briefly
        unavailable (a read or write request falls back to a second bucket
        before it is refused; an `expensive` request is refused at once), or
        when a transient runtime fault stops the request.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        An External App: the JWT it obtains from `POST /oauth/token` with OAuth2
        client_credentials. Pass as `Authorization: Bearer <jwt>`. An app's
        static companion key also authenticates as the app, but is deprecated
        and is not protected by `Idempotency-Key`.
    PlatformApiKey:
      type: http
      scheme: bearer
      description: >-
        A platform API key, created in the Console under Developers. Pass as
        `Authorization: Bearer <key>`. It acts as itself, under its role grants
        narrowed by its scopes.
    PersonalKey:
      type: http
      scheme: bearer
      description: >-
        A Personal key (`fmcp_…`), bound to the person who created it, or an
        interactive MCP sign-in that resolves to one. Pass as `Authorization:
        Bearer <key>`. It acts for that person, under their role grants narrowed
        by its scopes; an operation that acts for a person admits only this
        kind.

````

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