> ## 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.

# Get project billing overview

> Returns the selected project's plan information, entitlements and current billing-period usage. This operation reads project billing state; it does not change plans or the payer's payment method. Organization-level plans are available through the organization billing overview.



## OpenAPI

````yaml https://api.photon.codes/openapi.json get /v1/projects/{projectId}/billing
openapi: 3.1.0
info:
  title: Photon API
  version: 1.0.0
servers:
  - url: https://api.photon.codes
security: []
paths:
  /v1/projects/{projectId}/billing:
    get:
      tags:
        - Project Billing
      summary: Get project billing overview
      description: >-
        Returns the selected project's plan information, entitlements and
        current billing-period usage. This operation reads project billing
        state; it does not change plans or the payer's payment method.
        Organization-level plans are available through the organization billing
        overview.
      operationId: getBillingOverview
      parameters:
        - description: The project being billed.
          in: path
          name: projectId
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBillingOverviewResponse'
          description: Plan, entitlements, and current-period usage.
          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/GetBillingOverviewForbiddenProblem'
          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/GetBillingOverviewInternalServerErrorProblem
          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/GetBillingOverviewGatewayTimeoutProblem'
          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:
    GetBillingOverviewResponse:
      additionalProperties: false
      properties:
        entitlementsVersion:
          description: Bumps on every entitlement change in any category.
          maximum: 9007199254740991
          minimum: 0
          type: integer
        subscriptions:
          description: >-
            One entry per category that currently holds a subscription. Empty
            means none do — cancelled, or never opened.
          items:
            $ref: '#/components/schemas/ProjectSubscription'
          type: array
        usage:
          description: Current-period metered usage, priced.
          items:
            $ref: '#/components/schemas/MeteredUsage'
          type: array
      required:
        - entitlementsVersion
        - subscriptions
        - usage
      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
    GetBillingOverviewForbiddenProblem:
      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
    GetBillingOverviewInternalServerErrorProblem:
      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
    GetBillingOverviewGatewayTimeoutProblem:
      oneOf:
        - $ref: '#/components/schemas/RequestTimeoutProblem'
        - $ref: '#/components/schemas/UpstreamTimeoutProblem'
    ProjectSubscription:
      additionalProperties: false
      properties:
        baseAmountCents:
          description: The plan's recurring base fee in whole cents.
          maximum: 9007199254740991
          minimum: 0
          type: integer
        cancelsAt:
          anyOf:
            - type: string
            - type: 'null'
          description: When the subscription will end instead of renewing, ISO 8601.
        category:
          description: Category slug, e.g. analytics or messaging.
          pattern: ^[a-z][a-z0-9_]{0,63}$
          type: string
        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
        currentPeriodEnd:
          anyOf:
            - type: string
            - type: 'null'
          description: End of the current billing period, ISO 8601.
        entitlements:
          description: Feature gates granted by this category's plan.
          items:
            $ref: '#/components/schemas/ProjectSubscriptionEntitlement'
          type: array
        fixedCharges:
          description: >-
            Fixed charges defined by this category's current plan. Quantity is
            the plan default.
          items:
            $ref: '#/components/schemas/FixedCharge'
          type: array
        minimumCommitment:
          anyOf:
            - $ref: '#/components/schemas/BillingPlanMinimumCommitment'
            - type: 'null'
        planCode:
          description: This category's plan.
          type: string
        planName:
          description: The plan's customer-facing name, e.g. Messaging Pro.
          type: string
        status:
          $ref: '#/components/schemas/SubscriptionStatus'
        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.
      required:
        - cancelsAt
        - category
        - currentPeriodEnd
        - entitlements
        - fixedCharges
        - baseAmountCents
        - currency
        - minimumCommitment
        - planCode
        - planName
        - status
        - tierDisplayName
      type: object
    MeteredUsage:
      additionalProperties: false
      properties:
        amountCents:
          description: Cost accrued so far.
          maximum: 9007199254740991
          minimum: -9007199254740991
          type: integer
        category:
          description: Category slug, e.g. analytics or messaging.
          pattern: ^[a-z][a-z0-9_]{0,63}$
          type: string
        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
        displayName:
          description: Display name for this usage item.
          type: string
        metricCode:
          description: Metered thing, e.g. imessage_message.
          type: string
        units:
          description: Units consumed this period.
          maximum: 9007199254740991
          minimum: -9007199254740991
          type: integer
      required:
        - amountCents
        - category
        - currency
        - displayName
        - metricCode
        - units
      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
    ProjectSubscriptionEntitlement:
      additionalProperties: false
      properties:
        featureKey:
          description: Feature gate key, e.g. imessage_shared_lines.max_user_assignments.
          type: string
        value:
          description: Gate value as a string.
          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
    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
    SubscriptionStatus:
      description: >-
        State of one category's subscription: the payer's dunning stage while it
        holds one. Dunning is organization-level, so the stage applies to every
        category at once, and paying clears it. Entitlements are unaffected at
        every stage; viewing, paying and releasing resources stay available.
        Only categories that hold a subscription appear at all; a cancelled
        category is absent rather than listed as terminated.
      enum:
        - active
        - past_due
        - restricted
        - suspended
        - terminated
      type: string
      x-enumDescriptions:
        active: Subscribed and in good standing, on a free or a paid plan.
        past_due: >-
          An invoice is overdue, for less than 7 days. Everything stays
          available.
        restricted: >-
          An invoice has been overdue for 7 days. New purchases are refused;
          sending continues.
        suspended: >-
          An invoice has been overdue for 14 days, overdue usage exceeds what
          the plans allow, or a payment is disputed. Sending is paused as well.
        terminated: >-
          The subscription is gone. Not reported by the overview, which omits
          categories holding nothing.
    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
    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
  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.