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

# Describe one outcome: its schemas and the capability steps it may run



## OpenAPI

````yaml /specs/platform.json get /v1/outcomes/{id}
openapi: 3.1.0
info:
  title: Pramaan API
  version: 1.0.0
  description: Provider-neutral capabilities behind one API. Prices are in micro-USD.
servers:
  - url: https://api.pramaan.dev
security: []
paths:
  /v1/outcomes/{id}:
    get:
      tags:
        - outcomes
      summary: 'Describe one outcome: its schemas and the capability steps it may run'
      operationId: describeOutcome
      parameters:
        - schema:
            type: string
          required: true
          name: id
          in: path
      responses:
        '200':
          description: The outcome
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/OutcomeInfo'
                  - type: object
                    properties:
                      input_schema:
                        type: object
                        additionalProperties: {}
                      options_schema:
                        type: object
                        additionalProperties: {}
                      result_schema:
                        type: object
                        additionalProperties: {}
                      steps:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            label:
                              type: string
                            capability:
                              type: string
                            effect_class:
                              type: string
                            required:
                              type: boolean
                            max_calls:
                              type: integer
                            requires_approval:
                              type: boolean
                            price_max_micro:
                              type: integer
                            mode:
                              type: string
                              enum:
                                - sync
                                - async
                            needs_connection:
                              type: boolean
                          required:
                            - id
                            - label
                            - capability
                            - effect_class
                            - required
                            - max_calls
                            - requires_approval
                            - price_max_micro
                            - mode
                            - needs_connection
                    required:
                      - input_schema
                      - options_schema
                      - result_schema
                      - steps
        default:
          description: Error (see the error guide for codes)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearer: []
components:
  schemas:
    OutcomeInfo:
      type: object
      properties:
        read_only_key:
          type: boolean
          description: True when the calling key may only run read_only capabilities.
        id:
          type: string
        description:
          type: string
        version:
          type: integer
        effect_class:
          type: string
          description: The highest effect class among the steps it may run.
        mode:
          type: string
          enum:
            - sync
            - async
          description: 'async: the run answers 202 with a job; poll GET /v1/jobs/{id}.'
        price_max_micro:
          type: integer
          description: The most a run can cost with every step on, micro-USD.
        personal_data:
          type: boolean
          description: 'true: a step looks up, scores or contacts a person.'
        requires_approval:
          type: boolean
          enum:
            - true
          description: >-
            Present when a step asks a person to approve: a run then needs
            Pramaan-Plan.
        available:
          type: boolean
          description: 'false: a step''s capability is not served yet.'
        capability_ids:
          type: array
          items:
            type: string
          description: Capability ids in mission step order.
      required:
        - id
        - description
        - version
        - effect_class
        - mode
        - price_max_micro
        - personal_data
        - available
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - addendum_required
                - invalid_request
                - unauthorized
                - forbidden
                - spend_cap_reached
                - not_found
                - job_not_found
                - conflict
                - connection_required
                - rate_limited
                - internal
                - upstream_unavailable
                - upstream_timeout
            message:
              type: string
              maxLength: 200
            next:
              type: string
              maxLength: 200
            request_id:
              type: string
            retryable:
              type: boolean
            effect:
              type: string
              enum:
                - none
              description: >-
                Present when nothing was sent, charged or created: every source
                refused before acting, or the request was refused before
                anything ran (validation, approval, balance, limits). Absent
                when anything may have happened: check before retrying an
                action.
            slot:
              type: string
            required_micro:
              type: integer
              description: >-
                With `spend_cap_reached`: the most the request can cost,
                micro-USD.
            reason:
              type: string
              enum:
                - balance
                - daily_cap
                - member_limit
                - approval_required
              description: >-
                With `spend_cap_reached`: not enough credit, the daily spend
                cap, or the spending limit of the member the call acts as. With
                `forbidden`: `approval_required`, the call needs an approver
                (send `Pramaan-Approved-By`).
            plan:
              type: string
              description: >-
                With `approval_required` on an outcome: the plan to show a
                person, then send in `Pramaan-Plan`.
            needs:
              type: array
              items:
                type: object
                properties:
                  kind:
                    type: string
                    enum:
                      - approval
                  step:
                    type: string
                  detail:
                    type: string
                required:
                  - kind
                  - detail
              description: >-
                With `approval_required` on an outcome: the steps that ask a
                person to approve.
          required:
            - code
            - message
            - next
            - request_id
            - retryable
      required:
        - error
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: 'API key: `sk_live_…`'

````

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