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

> ## Agent Instructions
> Use Stable documentation by default. Honor an explicit Beta request or a URL under /docs/beta/. If the requested version conflicts with the installed CLI package or API origin, clarify the target before writing integration code.
> Pages under /docs/beta/ document Beta; other product pages document Stable. Keep the CLI package, commands, API origin, and credentials within the selected version. State the documentation version in your answer.
> For MCP search, always pass version: Stable or version: Beta. Unfiltered search mixes both versions. For filesystem reads, keep Beta queries under /beta/ and exclude /beta/ from Stable queries; discover paths before reading them.
> The public docs base is https://photon.codes/docs. Convert MCP page paths to public URLs under that base, preserving /beta/ when present. Read https://photon.codes/docs/skill.md for version selection and https://photon.codes/docs/llms.txt for the version indexes.

# List billing plans

> Lists the billing plan catalog, grouped by their public plan-metadata type. Use the returned plan information when choosing the category and planCode for a plan change. The catalog is the same for every project, and reading it does not purchase a plan.



## OpenAPI

````yaml https://api.photon.codes/openapi.json get /v1/projects/{projectId}/billing/plans
openapi: 3.1.0
info:
  title: Photon API
  version: 1.0.0
servers:
  - url: https://api.photon.codes
security: []
paths:
  /v1/projects/{projectId}/billing/plans:
    get:
      tags:
        - Project Billing
      summary: List billing plans
      description: >-
        Lists the billing plan catalog, grouped by their public plan-metadata
        type. Use the returned plan information when choosing the category and
        planCode for a plan change. The catalog is the same for every project,
        and reading it does not purchase a plan.
      operationId: listBillingPlans
      parameters:
        - description: The project being billed.
          in: path
          name: projectId
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListBillingPlansResponse'
          description: Billing plans grouped by their public plan-metadata type.
          headers:
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
            Link:
              $ref: '#/components/headers/Link'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
            Sunset:
              $ref: '#/components/headers/Sunset'
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
            X-Trace-ID:
              $ref: '#/components/headers/X-Trace-ID'
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/InvalidArgumentProblem'
          description: 'INVALID_ARGUMENT: Invalid Argument'
          headers:
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
            Link:
              $ref: '#/components/headers/Link'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
            Sunset:
              $ref: '#/components/headers/Sunset'
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
            X-Trace-ID:
              $ref: '#/components/headers/X-Trace-ID'
        '401':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/NotAuthenticatedProblem'
          description: 'NOT_AUTHENTICATED: Not Authenticated'
          headers:
            Link:
              description: Optional related resources.
              schema:
                type: string
            RateLimit:
              description: Optional rate limit information.
              schema:
                type: string
            RateLimit-Policy:
              description: Optional rate limit policy.
              schema:
                type: string
            Retry-After:
              description: Optional retry delay or HTTP date.
              schema:
                type: string
            WWW-Authenticate:
              required: true
              schema:
                type: string
            X-Request-ID:
              description: Application request identifier.
              schema:
                type: string
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ListBillingPlansForbiddenProblem'
          description: >-
            FORBIDDEN: Forbidden; RESOURCE_MISMATCH: Resource Mismatch


            FORBIDDEN: Forbidden; INSUFFICIENT_SCOPE: Insufficient Scope;
            ORGANIZATION_SSO_REQUIRED: Organization SSO Required
          headers:
            Deprecation:
              description: >-
                RFC 9745 structured-field Date at which the operation was or
                will be deprecated: `@` followed by Unix seconds, for example
                `@1767225599`.
              schema:
                pattern: ^@-?[0-9]+$
                type: string
            Idempotent-Replayed:
              description: True when this response was replayed from an earlier attempt.
              schema:
                type: boolean
            Link:
              description: |-
                Links related to lifecycle or remediation documentation.

                Optional related resources.
              schema:
                type: string
            RateLimit:
              description: |-
                Current rate-limit state.

                Optional rate limit information.
              schema:
                type: string
            RateLimit-Policy:
              description: |-
                Rate-limit policy applied by the gateway.

                Optional rate limit policy.
              schema:
                type: string
            Retry-After:
              description: |-
                Delay before retrying, in seconds or as an HTTP date.

                Optional retry delay or HTTP date.
              schema:
                type: string
            Sunset:
              description: >-
                RFC 8594 HTTP-date (IMF-fixdate) after which the operation may
                become unavailable, for example `Thu, 31 Dec 2026 23:59:59 GMT`.
              schema:
                pattern: >-
                  ^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), [0-9]{2}
                  (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) [0-9]{4}
                  [0-9]{2}:[0-9]{2}:[0-9]{2} GMT$
                type: string
            X-Request-ID:
              description: |-
                Identifier for this HTTP attempt.

                Application request identifier.
              schema:
                type: string
            X-Trace-ID:
              description: >-
                Trace ID of this request. Sent alongside X-Request-ID when a
                middleware published a trace ID for the request.
              schema:
                pattern: ^(?!0{32}$)[0-9a-f]{32}$
                type: string
        '409':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/FailedPreconditionProblem'
          description: 'FAILED_PRECONDITION: Failed Precondition'
          headers:
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
            Link:
              $ref: '#/components/headers/Link'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
            Sunset:
              $ref: '#/components/headers/Sunset'
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
            X-Trace-ID:
              $ref: '#/components/headers/X-Trace-ID'
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationFailedProblem'
          description: 'VALIDATION_FAILED: Request Validation Failed'
          headers:
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
            Link:
              $ref: '#/components/headers/Link'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
            Sunset:
              $ref: '#/components/headers/Sunset'
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
            X-Trace-ID:
              $ref: '#/components/headers/X-Trace-ID'
        '500':
          content:
            application/problem+json:
              schema:
                $ref: >-
                  #/components/schemas/ListBillingPlansInternalServerErrorProblem
          description: |-
            INVALID_AUTH_CONTEXT: Invalid Authentication Context

            INTERNAL_ERROR: Internal Server Error
          headers:
            Deprecation:
              description: >-
                RFC 9745 structured-field Date at which the operation was or
                will be deprecated: `@` followed by Unix seconds, for example
                `@1767225599`.
              schema:
                pattern: ^@-?[0-9]+$
                type: string
            Idempotent-Replayed:
              description: True when this response was replayed from an earlier attempt.
              schema:
                type: boolean
            Link:
              description: |-
                Links related to lifecycle or remediation documentation.

                Optional related resources.
              schema:
                type: string
            RateLimit:
              description: |-
                Current rate-limit state.

                Optional rate limit information.
              schema:
                type: string
            RateLimit-Policy:
              description: |-
                Rate-limit policy applied by the gateway.

                Optional rate limit policy.
              schema:
                type: string
            Retry-After:
              description: |-
                Delay before retrying, in seconds or as an HTTP date.

                Optional retry delay or HTTP date.
              schema:
                type: string
            Sunset:
              description: >-
                RFC 8594 HTTP-date (IMF-fixdate) after which the operation may
                become unavailable, for example `Thu, 31 Dec 2026 23:59:59 GMT`.
              schema:
                pattern: >-
                  ^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), [0-9]{2}
                  (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) [0-9]{4}
                  [0-9]{2}:[0-9]{2}:[0-9]{2} GMT$
                type: string
            X-Request-ID:
              description: |-
                Identifier for this HTTP attempt.

                Application request identifier.
              schema:
                type: string
            X-Trace-ID:
              description: >-
                Trace ID of this request. Sent alongside X-Request-ID when a
                middleware published a trace ID for the request.
              schema:
                pattern: ^(?!0{32}$)[0-9a-f]{32}$
                type: string
        '502':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/UpstreamFailureProblem'
          description: 'UPSTREAM_FAILURE: Upstream Service Failure'
          headers:
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
            Link:
              $ref: '#/components/headers/Link'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
            Sunset:
              $ref: '#/components/headers/Sunset'
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
            X-Trace-ID:
              $ref: '#/components/headers/X-Trace-ID'
        '503':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/UpstreamUnavailableProblem'
          description: 'UPSTREAM_UNAVAILABLE: Upstream Service Unavailable'
          headers:
            Deprecation:
              description: >-
                RFC 9745 structured-field Date at which the operation was or
                will be deprecated: `@` followed by Unix seconds, for example
                `@1767225599`.
              schema:
                pattern: ^@-?[0-9]+$
                type: string
            Idempotent-Replayed:
              description: True when this response was replayed from an earlier attempt.
              schema:
                type: boolean
            Link:
              description: |-
                Links related to lifecycle or remediation documentation.

                Optional related resources.
              schema:
                type: string
            RateLimit:
              description: |-
                Current rate-limit state.

                Optional rate limit information.
              schema:
                type: string
            RateLimit-Policy:
              description: |-
                Rate-limit policy applied by the gateway.

                Optional rate limit policy.
              schema:
                type: string
            Retry-After:
              description: |-
                Delay before retrying, in seconds or as an HTTP date.

                Optional retry delay or HTTP date.
              schema:
                type: string
            Sunset:
              description: >-
                RFC 8594 HTTP-date (IMF-fixdate) after which the operation may
                become unavailable, for example `Thu, 31 Dec 2026 23:59:59 GMT`.
              schema:
                pattern: >-
                  ^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), [0-9]{2}
                  (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) [0-9]{4}
                  [0-9]{2}:[0-9]{2}:[0-9]{2} GMT$
                type: string
            X-Request-ID:
              description: |-
                Identifier for this HTTP attempt.

                Application request identifier.
              schema:
                type: string
            X-Trace-ID:
              description: >-
                Trace ID of this request. Sent alongside X-Request-ID when a
                middleware published a trace ID for the request.
              schema:
                pattern: ^(?!0{32}$)[0-9a-f]{32}$
                type: string
        '504':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ListBillingPlansGatewayTimeoutProblem'
          description: >-
            REQUEST_TIMEOUT: Request Timeout; UPSTREAM_TIMEOUT: Upstream Service
            Timeout
          headers:
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
            Link:
              $ref: '#/components/headers/Link'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
            Sunset:
              $ref: '#/components/headers/Sunset'
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
            X-Trace-ID:
              $ref: '#/components/headers/X-Trace-ID'
      security:
        - accountServiceKey: []
        - projectApiKey: []
        - oauth2:
            - project:read_usage
components:
  schemas:
    ListBillingPlansResponse:
      additionalProperties: false
      properties:
        plans:
          additionalProperties:
            items:
              $ref: '#/components/schemas/BillingPlan'
            type: array
          description: >-
            Plans grouped by valid metadata type and explicitly published with
            visible="true". Each group is in display order: by tier, plans
            without one last, then by planCode.
          propertyNames:
            description: Category slug, e.g. analytics or messaging.
            pattern: ^[a-z][a-z0-9_]{0,63}$
            type: string
          type: object
      required:
        - plans
      type: object
    InvalidArgumentProblem:
      additionalProperties:
        $ref: '#/components/schemas/JsonValue'
      example:
        code: INVALID_ARGUMENT
        status: 400
        title: Invalid Argument
        type: https://photon.codes/docs/problems/invalid-argument
      properties:
        code:
          const: INVALID_ARGUMENT
          type: string
        detail:
          minLength: 1
          type: string
        instance:
          minLength: 1
          type: string
        remediation:
          not: {}
        requestId:
          minLength: 1
          type: string
        status:
          const: 400
          type: number
        title:
          const: Invalid Argument
          type: string
        type:
          const: https://photon.codes/docs/problems/invalid-argument
          type: string
      required:
        - code
        - status
        - title
        - type
      type: object
    NotAuthenticatedProblem:
      additionalProperties:
        $ref: '#/components/schemas/JsonValue'
      example:
        code: NOT_AUTHENTICATED
        status: 401
        title: Not Authenticated
        type: https://photon.codes/docs/problems/not-authenticated
      properties:
        code:
          const: NOT_AUTHENTICATED
          type: string
        detail:
          minLength: 1
          type: string
        instance:
          minLength: 1
          type: string
        remediation:
          not: {}
        requestId:
          minLength: 1
          type: string
        status:
          const: 401
          type: number
        title:
          const: Not Authenticated
          type: string
        type:
          const: https://photon.codes/docs/problems/not-authenticated
          type: string
      required:
        - code
        - status
        - title
        - type
      type: object
    ListBillingPlansForbiddenProblem:
      oneOf:
        - $ref: '#/components/schemas/ForbiddenProblem'
        - $ref: '#/components/schemas/InsufficientScopeProblem'
        - $ref: '#/components/schemas/OrganizationSsoRequiredProblem'
        - $ref: '#/components/schemas/ResourceMismatchProblem'
    FailedPreconditionProblem:
      additionalProperties:
        $ref: '#/components/schemas/JsonValue'
      example:
        code: FAILED_PRECONDITION
        status: 409
        title: Failed Precondition
        type: https://photon.codes/docs/problems/failed-precondition
      properties:
        code:
          const: FAILED_PRECONDITION
          type: string
        detail:
          minLength: 1
          type: string
        instance:
          minLength: 1
          type: string
        remediation:
          not: {}
        requestId:
          minLength: 1
          type: string
        status:
          const: 409
          type: number
        title:
          const: Failed Precondition
          type: string
        type:
          const: https://photon.codes/docs/problems/failed-precondition
          type: string
      required:
        - code
        - status
        - title
        - type
      type: object
    ValidationFailedProblem:
      additionalProperties:
        $ref: '#/components/schemas/JsonValue'
      example:
        code: VALIDATION_FAILED
        issues:
          - code: invalid_type
            location: json
            message: Expected a string.
            path: /name
        status: 422
        title: Request Validation Failed
        type: https://photon.codes/docs/problems/validation-failed
      properties:
        code:
          const: VALIDATION_FAILED
          type: string
        detail:
          minLength: 1
          type: string
        instance:
          minLength: 1
          type: string
        issues:
          items:
            $ref: '#/components/schemas/ValidationIssue'
          type: array
        remediation:
          not: {}
        requestId:
          minLength: 1
          type: string
        status:
          const: 422
          type: number
        title:
          const: Request Validation Failed
          type: string
        type:
          const: https://photon.codes/docs/problems/validation-failed
          type: string
      required:
        - issues
        - code
        - status
        - title
        - type
      type: object
    ListBillingPlansInternalServerErrorProblem:
      oneOf:
        - $ref: '#/components/schemas/InternalErrorProblem'
        - $ref: '#/components/schemas/InvalidAuthContextProblem'
    UpstreamFailureProblem:
      additionalProperties:
        $ref: '#/components/schemas/JsonValue'
      example:
        code: UPSTREAM_FAILURE
        status: 502
        title: Upstream Service Failure
        type: https://photon.codes/docs/problems/upstream-failure
      properties:
        code:
          const: UPSTREAM_FAILURE
          type: string
        detail:
          minLength: 1
          type: string
        instance:
          minLength: 1
          type: string
        remediation:
          not: {}
        requestId:
          minLength: 1
          type: string
        status:
          const: 502
          type: number
        title:
          const: Upstream Service Failure
          type: string
        type:
          const: https://photon.codes/docs/problems/upstream-failure
          type: string
      required:
        - code
        - status
        - title
        - type
      type: object
    UpstreamUnavailableProblem:
      additionalProperties:
        $ref: '#/components/schemas/JsonValue'
      example:
        code: UPSTREAM_UNAVAILABLE
        status: 503
        title: Upstream Service Unavailable
        type: https://photon.codes/docs/problems/upstream-unavailable
      properties:
        code:
          const: UPSTREAM_UNAVAILABLE
          type: string
        detail:
          minLength: 1
          type: string
        instance:
          minLength: 1
          type: string
        remediation:
          not: {}
        requestId:
          minLength: 1
          type: string
        status:
          const: 503
          type: number
        title:
          const: Upstream Service Unavailable
          type: string
        type:
          const: https://photon.codes/docs/problems/upstream-unavailable
          type: string
      required:
        - code
        - status
        - title
        - type
      type: object
    ListBillingPlansGatewayTimeoutProblem:
      oneOf:
        - $ref: '#/components/schemas/RequestTimeoutProblem'
        - $ref: '#/components/schemas/UpstreamTimeoutProblem'
    BillingPlan:
      additionalProperties: false
      properties:
        baseAmountCents:
          description: Recurring base price in whole cents.
          maximum: 9007199254740991
          minimum: 0
          type: integer
        categoryDisplayName:
          anyOf:
            - maxLength: 255
              minLength: 1
              type: string
            - type: 'null'
          description: >-
            Display name for the subscription category; absent or null when
            unconfigured.
        currency:
          description: ISO currency code.
          type: string
        description:
          anyOf:
            - type: string
            - type: 'null'
        entitlements:
          items:
            $ref: '#/components/schemas/BillingPlanEntitlement'
          type: array
        fixedCharges:
          items:
            $ref: '#/components/schemas/FixedCharge'
          type: array
        interval:
          $ref: '#/components/schemas/BillingPlanInterval'
        isDefault:
          description: >-
            The category's default plan: the one a project holds when it pays
            for none, and moves to at the period end when it leaves a paid plan.
            At most one per category.
          type: boolean
        minimumCommitment:
          anyOf:
            - $ref: '#/components/schemas/BillingPlanMinimumCommitment'
            - type: 'null'
        name:
          type: string
        payInAdvance:
          type: boolean
        planCode:
          maxLength: 64
          minLength: 1
          type: string
        tier:
          anyOf:
            - maximum: 9007199254740991
              minimum: -9007199254740991
              type: integer
            - type: 'null'
          description: >-
            Rank within the category: moving to a higher tier is an upgrade and
            applies now, to a lower one a downgrade scheduled for the period
            end. Null when the plan has none.
        tierDisplayName:
          anyOf:
            - maxLength: 255
              minLength: 1
              type: string
            - type: 'null'
          description: >-
            The plan's tier as customers see it, e.g. Pro for Messaging Pro,
            where the category is already clear. Null when unconfigured.
        usageCharges:
          items:
            $ref: '#/components/schemas/UsageCharge'
          type: array
        usageThresholds:
          description: Progressive-billing thresholds, ordered by amount.
          items:
            $ref: '#/components/schemas/BillingPlanUsageThreshold'
          type: array
      required:
        - baseAmountCents
        - currency
        - description
        - entitlements
        - fixedCharges
        - interval
        - isDefault
        - minimumCommitment
        - name
        - payInAdvance
        - planCode
        - tier
        - tierDisplayName
        - usageCharges
        - usageThresholds
      type: object
    JsonValue:
      anyOf:
        - type: string
        - type: number
        - type: boolean
        - type: 'null'
        - items:
            $ref: '#/components/schemas/JsonValue'
          type: array
        - additionalProperties:
            $ref: '#/components/schemas/JsonValue'
          propertyNames:
            type: string
          type: object
    ForbiddenProblem:
      additionalProperties:
        $ref: '#/components/schemas/JsonValue'
      example:
        code: FORBIDDEN
        status: 403
        title: Forbidden
        type: https://photon.codes/docs/problems/forbidden
      properties:
        code:
          const: FORBIDDEN
          type: string
        detail:
          minLength: 1
          type: string
        instance:
          minLength: 1
          type: string
        remediation:
          not: {}
        requestId:
          minLength: 1
          type: string
        status:
          const: 403
          type: number
        title:
          const: Forbidden
          type: string
        type:
          const: https://photon.codes/docs/problems/forbidden
          type: string
      required:
        - code
        - status
        - title
        - type
      type: object
    InsufficientScopeProblem:
      additionalProperties:
        $ref: '#/components/schemas/JsonValue'
      example:
        code: INSUFFICIENT_SCOPE
        status: 403
        title: Insufficient Scope
        type: https://photon.codes/docs/problems/insufficient-scope
      properties:
        code:
          const: INSUFFICIENT_SCOPE
          type: string
        detail:
          minLength: 1
          type: string
        instance:
          minLength: 1
          type: string
        remediation:
          not: {}
        requestId:
          minLength: 1
          type: string
        status:
          const: 403
          type: number
        title:
          const: Insufficient Scope
          type: string
        type:
          const: https://photon.codes/docs/problems/insufficient-scope
          type: string
      required:
        - code
        - status
        - title
        - type
      type: object
    OrganizationSsoRequiredProblem:
      additionalProperties:
        $ref: '#/components/schemas/JsonValue'
      example:
        code: ORGANIZATION_SSO_REQUIRED
        status: 403
        title: Organization SSO Required
        type: https://photon.codes/docs/problems/organization-sso-required
      properties:
        code:
          const: ORGANIZATION_SSO_REQUIRED
          type: string
        detail:
          minLength: 1
          type: string
        instance:
          minLength: 1
          type: string
        remediation:
          not: {}
        requestId:
          minLength: 1
          type: string
        status:
          const: 403
          type: number
        title:
          const: Organization SSO Required
          type: string
        type:
          const: https://photon.codes/docs/problems/organization-sso-required
          type: string
      required:
        - code
        - status
        - title
        - type
      type: object
    ResourceMismatchProblem:
      additionalProperties:
        $ref: '#/components/schemas/JsonValue'
      example:
        code: RESOURCE_MISMATCH
        status: 403
        title: Resource Mismatch
        type: https://photon.codes/docs/problems/resource-mismatch
      properties:
        code:
          const: RESOURCE_MISMATCH
          type: string
        detail:
          minLength: 1
          type: string
        instance:
          minLength: 1
          type: string
        remediation:
          not: {}
        requestId:
          minLength: 1
          type: string
        status:
          const: 403
          type: number
        title:
          const: Resource Mismatch
          type: string
        type:
          const: https://photon.codes/docs/problems/resource-mismatch
          type: string
      required:
        - code
        - status
        - title
        - type
      type: object
    ValidationIssue:
      additionalProperties: false
      properties:
        code:
          minLength: 1
          type: string
        location:
          $ref: '#/components/schemas/ValidationLocation'
        message:
          minLength: 1
          type: string
        path:
          type: string
      required:
        - code
        - location
        - message
        - path
      type: object
    InternalErrorProblem:
      additionalProperties:
        $ref: '#/components/schemas/JsonValue'
      example:
        code: INTERNAL_ERROR
        status: 500
        title: Internal Server Error
        type: https://photon.codes/docs/problems/internal-error
      properties:
        code:
          const: INTERNAL_ERROR
          type: string
        detail:
          minLength: 1
          type: string
        instance:
          minLength: 1
          type: string
        remediation:
          not: {}
        requestId:
          minLength: 1
          type: string
        status:
          const: 500
          type: number
        title:
          const: Internal Server Error
          type: string
        type:
          const: https://photon.codes/docs/problems/internal-error
          type: string
      required:
        - code
        - status
        - title
        - type
      type: object
    InvalidAuthContextProblem:
      additionalProperties:
        $ref: '#/components/schemas/JsonValue'
      example:
        code: INVALID_AUTH_CONTEXT
        status: 500
        title: Invalid Authentication Context
        type: https://photon.codes/docs/problems/invalid-auth-context
      properties:
        code:
          const: INVALID_AUTH_CONTEXT
          type: string
        detail:
          minLength: 1
          type: string
        instance:
          minLength: 1
          type: string
        remediation:
          not: {}
        requestId:
          minLength: 1
          type: string
        status:
          const: 500
          type: number
        title:
          const: Invalid Authentication Context
          type: string
        type:
          const: https://photon.codes/docs/problems/invalid-auth-context
          type: string
      required:
        - code
        - status
        - title
        - type
      type: object
    RequestTimeoutProblem:
      additionalProperties:
        $ref: '#/components/schemas/JsonValue'
      example:
        code: REQUEST_TIMEOUT
        status: 504
        title: Request Timeout
        type: https://photon.codes/docs/problems/request-timeout
      properties:
        code:
          const: REQUEST_TIMEOUT
          type: string
        detail:
          minLength: 1
          type: string
        instance:
          minLength: 1
          type: string
        remediation:
          not: {}
        requestId:
          minLength: 1
          type: string
        status:
          const: 504
          type: number
        title:
          const: Request Timeout
          type: string
        type:
          const: https://photon.codes/docs/problems/request-timeout
          type: string
      required:
        - code
        - status
        - title
        - type
      type: object
    UpstreamTimeoutProblem:
      additionalProperties:
        $ref: '#/components/schemas/JsonValue'
      example:
        code: UPSTREAM_TIMEOUT
        status: 504
        title: Upstream Service Timeout
        type: https://photon.codes/docs/problems/upstream-timeout
      properties:
        code:
          const: UPSTREAM_TIMEOUT
          type: string
        detail:
          minLength: 1
          type: string
        instance:
          minLength: 1
          type: string
        remediation:
          not: {}
        requestId:
          minLength: 1
          type: string
        status:
          const: 504
          type: number
        title:
          const: Upstream Service Timeout
          type: string
        type:
          const: https://photon.codes/docs/problems/upstream-timeout
          type: string
      required:
        - code
        - status
        - title
        - type
      type: object
    BillingPlanEntitlement:
      additionalProperties: false
      properties:
        featureKey:
          type: string
        value:
          type: string
      required:
        - featureKey
        - value
      type: object
    FixedCharge:
      additionalProperties: false
      properties:
        chargeModel:
          $ref: '#/components/schemas/FixedChargeModel'
        displayName:
          type: string
        fixedChargeCode:
          type: string
        payInAdvance:
          type: boolean
        pricing:
          $ref: '#/components/schemas/FixedChargePricing'
        prorated:
          type: boolean
        quantity:
          maximum: 9007199254740991
          minimum: 0
          type: integer
      required:
        - chargeModel
        - displayName
        - fixedChargeCode
        - payInAdvance
        - pricing
        - prorated
        - quantity
      type: object
    BillingPlanInterval:
      enum:
        - weekly
        - monthly
        - quarterly
        - semiannual
        - yearly
      type: string
    BillingPlanMinimumCommitment:
      additionalProperties: false
      description: >-
        When the plan's fees for an interval come to less than amountCents, the
        difference is invoiced at the end of the period.
      properties:
        amountCents:
          description: Least the plan bills each interval, in whole cents.
          maximum: 9007199254740991
          minimum: 0
          type: integer
        displayName:
          anyOf:
            - type: string
            - type: 'null'
      required:
        - amountCents
        - displayName
      type: object
    UsageCharge:
      additionalProperties: false
      properties:
        chargeCode:
          anyOf:
            - type: string
            - type: 'null'
        chargeModel:
          $ref: '#/components/schemas/UsageChargeModel'
        displayName:
          anyOf:
            - type: string
            - type: 'null'
        filters:
          items:
            $ref: '#/components/schemas/UsageChargeFilter'
          type: array
        invoiceable:
          type: boolean
        metricCode:
          type: string
        minimumAmountCents:
          maximum: 9007199254740991
          minimum: 0
          type: integer
        payInAdvance:
          type: boolean
        pricing:
          $ref: '#/components/schemas/UsageChargePricing'
        prorated:
          type: boolean
      required:
        - chargeCode
        - chargeModel
        - displayName
        - filters
        - invoiceable
        - metricCode
        - minimumAmountCents
        - payInAdvance
        - pricing
        - prorated
      type: object
    BillingPlanUsageThreshold:
      additionalProperties: false
      properties:
        amountCents:
          description: >-
            Usage amount, in whole cents, at which usage is invoiced before the
            period ends.
          maximum: 9007199254740991
          minimum: 0
          type: integer
        displayName:
          anyOf:
            - type: string
            - type: 'null'
        recurring:
          description: Whether usage is invoiced again every further amountCents.
          type: boolean
      required:
        - amountCents
        - displayName
        - recurring
      type: object
    ValidationLocation:
      enum:
        - body
        - cookie
        - form
        - header
        - json
        - param
        - query
      type: string
    FixedChargeModel:
      enum:
        - graduated
        - standard
        - volume
      type: string
    FixedChargePricing:
      additionalProperties: false
      properties:
        amount:
          anyOf:
            - description: >-
                Decimal amount in the plan currency. Kept as text so sub-cent
                unit prices remain exact.
              pattern: ^\d+(?:\.\d+)?$
              type: string
            - type: 'null'
        tiers:
          items:
            $ref: '#/components/schemas/FixedChargeTier'
          type: array
      required:
        - amount
        - tiers
      type: object
    UsageChargeModel:
      enum:
        - dynamic
        - graduated
        - graduated_percentage
        - package
        - percentage
        - standard
        - volume
      type: string
    UsageChargeFilter:
      additionalProperties: false
      properties:
        displayName:
          anyOf:
            - type: string
            - type: 'null'
        pricing:
          $ref: '#/components/schemas/UsageChargePricing'
        values:
          items:
            $ref: '#/components/schemas/UsageChargeFilterValue'
          type: array
      required:
        - displayName
        - pricing
        - values
      type: object
    UsageChargePricing:
      additionalProperties: false
      properties:
        amount:
          anyOf:
            - description: >-
                Decimal amount in the plan currency. Kept as text so sub-cent
                unit prices remain exact.
              pattern: ^\d+(?:\.\d+)?$
              type: string
            - type: 'null'
        fixedAmount:
          anyOf:
            - description: >-
                Decimal amount in the plan currency. Kept as text so sub-cent
                unit prices remain exact.
              pattern: ^\d+(?:\.\d+)?$
              type: string
            - type: 'null'
        freeUnits:
          anyOf:
            - maximum: 9007199254740991
              minimum: 0
              type: integer
            - type: 'null'
        freeUnitsPerEvents:
          anyOf:
            - maximum: 9007199254740991
              minimum: 0
              type: integer
            - type: 'null'
        freeUnitsPerTotalAggregation:
          anyOf:
            - description: >-
                Decimal amount in the plan currency. Kept as text so sub-cent
                unit prices remain exact.
              pattern: ^\d+(?:\.\d+)?$
              type: string
            - type: 'null'
        packageSize:
          anyOf:
            - maximum: 9007199254740991
              minimum: 0
              type: integer
            - type: 'null'
        perTransactionMaxAmount:
          anyOf:
            - description: >-
                Decimal amount in the plan currency. Kept as text so sub-cent
                unit prices remain exact.
              pattern: ^\d+(?:\.\d+)?$
              type: string
            - type: 'null'
        perTransactionMinAmount:
          anyOf:
            - description: >-
                Decimal amount in the plan currency. Kept as text so sub-cent
                unit prices remain exact.
              pattern: ^\d+(?:\.\d+)?$
              type: string
            - type: 'null'
        pricingGroupKeys:
          items:
            type: string
          type: array
        rate:
          anyOf:
            - description: >-
                Decimal amount in the plan currency. Kept as text so sub-cent
                unit prices remain exact.
              pattern: ^\d+(?:\.\d+)?$
              type: string
            - type: 'null'
        tiers:
          items:
            $ref: '#/components/schemas/UsageChargeTier'
          type: array
      required:
        - amount
        - fixedAmount
        - freeUnits
        - freeUnitsPerEvents
        - freeUnitsPerTotalAggregation
        - packageSize
        - perTransactionMaxAmount
        - perTransactionMinAmount
        - pricingGroupKeys
        - rate
        - tiers
      type: object
    FixedChargeTier:
      additionalProperties: false
      properties:
        flatAmount:
          anyOf:
            - description: >-
                Decimal amount in the plan currency. Kept as text so sub-cent
                unit prices remain exact.
              pattern: ^\d+(?:\.\d+)?$
              type: string
            - type: 'null'
        fromUnit:
          maximum: 9007199254740991
          minimum: 0
          type: integer
        perUnitAmount:
          anyOf:
            - description: >-
                Decimal amount in the plan currency. Kept as text so sub-cent
                unit prices remain exact.
              pattern: ^\d+(?:\.\d+)?$
              type: string
            - type: 'null'
        toUnit:
          anyOf:
            - maximum: 9007199254740991
              minimum: 0
              type: integer
            - type: 'null'
      required:
        - flatAmount
        - fromUnit
        - perUnitAmount
        - toUnit
      type: object
    UsageChargeFilterValue:
      additionalProperties: false
      properties:
        key:
          type: string
        values:
          items:
            type: string
          type: array
      required:
        - key
        - values
      type: object
    UsageChargeTier:
      additionalProperties: false
      properties:
        flatAmount:
          anyOf:
            - description: >-
                Decimal amount in the plan currency. Kept as text so sub-cent
                unit prices remain exact.
              pattern: ^\d+(?:\.\d+)?$
              type: string
            - type: 'null'
        fromUnit:
          maximum: 9007199254740991
          minimum: 0
          type: integer
        perUnitAmount:
          anyOf:
            - description: >-
                Decimal amount in the plan currency. Kept as text so sub-cent
                unit prices remain exact.
              pattern: ^\d+(?:\.\d+)?$
              type: string
            - type: 'null'
        rate:
          anyOf:
            - description: >-
                Decimal amount in the plan currency. Kept as text so sub-cent
                unit prices remain exact.
              pattern: ^\d+(?:\.\d+)?$
              type: string
            - type: 'null'
        toUnit:
          anyOf:
            - maximum: 9007199254740991
              minimum: 0
              type: integer
            - type: 'null'
      required:
        - flatAmount
        - fromUnit
        - perUnitAmount
        - rate
        - toUnit
      type: object
  headers:
    Deprecation:
      description: >-
        RFC 9745 structured-field Date at which the operation was or will be
        deprecated: `@` followed by Unix seconds, for example `@1767225599`.
      schema:
        pattern: ^@-?[0-9]+$
        type: string
    Idempotent-Replayed:
      description: True when this response was replayed from an earlier attempt.
      schema:
        type: boolean
    Link:
      description: Links related to lifecycle or remediation documentation.
      schema:
        type: string
    RateLimit:
      description: Current rate-limit state.
      schema:
        type: string
    RateLimit-Policy:
      description: Rate-limit policy applied by the gateway.
      schema:
        type: string
    Retry-After:
      description: Delay before retrying, in seconds or as an HTTP date.
      schema:
        type: string
    Sunset:
      description: >-
        RFC 8594 HTTP-date (IMF-fixdate) after which the operation may become
        unavailable, for example `Thu, 31 Dec 2026 23:59:59 GMT`.
      schema:
        pattern: >-
          ^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), [0-9]{2}
          (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) [0-9]{4}
          [0-9]{2}:[0-9]{2}:[0-9]{2} GMT$
        type: string
    X-Request-ID:
      description: Identifier for this HTTP attempt.
      schema:
        type: string
    X-Trace-ID:
      description: >-
        Trace ID of this request. Sent alongside X-Request-ID when a middleware
        published a trace ID for the request.
      schema:
        pattern: ^(?!0{32}$)[0-9a-f]{32}$
        type: string
  securitySchemes:
    accountServiceKey:
      description: >-
        Account Service Key, prefixed with `pho_ask_`, sent as `Authorization:
        Bearer <key>`. Acts on behalf of its owning account, subject to the
        permissions and credential restrictions of each operation. Account
        access tokens and OAuth grants also use the Bearer header. In
        organizations that require SSO, Account Service Keys are not accepted
        for managing the organization's SSO settings, deleting the organization,
        or checking whether it can be deleted.
      scheme: bearer
      type: http
    projectApiKey:
      description: >-
        Project API key, `pho_sk_` prefixed, sent as `Authorization: Bearer
        <key>`. Bound to one project, so it is accepted only under
        `/v1/projects/{projectId}` and refused everywhere else.
      scheme: bearer
      type: http
    oauth2:
      description: >-
        OAuth grant issued by the Photon authorization server. The token is a
        bearer JWT whose consented scope is intersected with the permissions the
        route grants; an empty intersection is `403 insufficient_scope`.
      flows:
        authorizationCode:
          authorizationUrl: https://auth.photon.codes/oauth2/authorize
          scopes:
            account:create_project: Create a project owned by the account.
            account:read: View account profile.
            account:read_projects: >-
              List projects associated with the account; does not grant access
              to project contents.
            account:write: Update account name and profile.
            billing:read: View invoices, usage, payment status.
            events:read: >-
              Query stored Events and discover their SQL schema within a
              project.
            organization:create_project: Create a project in the organization.
            organization:read: View organization name and avatar.
            organization:read_projects: List projects in the organization.
            platforms:read: View project platform configuration.
            platforms:write: Change project platform configuration.
            project:delete: Permanently delete the project.
            project:read: View non-sensitive project settings.
            project:read_usage: View project usage and costs.
            project:write: >-
              Change agent profiles, webhook settings, and other project
              configuration.
            ten_dlc:read: View organization 10DLC Brand and Campaign registration records.
            ten_dlc:write: >-
              Register and update organization 10DLC Brands and Campaigns,
              including OTP operations.
          tokenUrl: https://auth.photon.codes/oauth2/token
      type: oauth2

````

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