Opper AI Account API

openapi: 3.2.0
info:
  description: Schema-driven generative API that orchestrates LLM-powered workflows.
  title: Task Account API
  version: 3.0.0
servers:
- description: Production
  url: https://api.opper.ai
- description: Local development
  url: http://localhost:8080
security:
- BearerAuth: []
tags:
- description: Caller identity, credits, and usage
  name: Account
paths:
  /v3/me:
    get:
      description: 'Identity and billing snapshot for the calling API key: organization and project names, the key''s own project spend and budget this billing period, for a personal key its owner''s own spend and allowance (`member_spend`), and whether spending is currently blocked (`balance_exhausted`, `project_spend_cap_hit`, `member_spend_cap_hit` when a personal key''s owner reached their own or their role''s cap, or `org_spend_cap_hit`). The organization-wide balance, spend and budget appear only when the key''s owner holds the `billing:read` permission (owners and admins, or a custom role granted it); `visibility.organization_finance` says whether they were included. Answers even while spending is blocked, so a blocked key can learn why. Useful as a pre-flight "can I still spend?" check before starting expensive work.'
      operationId: getMe
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  balance:
                    description: Remaining prepaid credits (organization-wide). Present only when `visibility.organization_finance` is true.
                    properties:
                      balance_cents:
                        description: Remaining balance in USD cents. May be briefly negative when usage overshoots the last top-up.
                        type: integer
                      balance_dollars:
                        description: The same balance in USD.
                        type: number
                      currency:
                        enum:
                        - usd
                        type: string
                    type: object
                  block_reason:
                    description: Why spending is blocked; present only when `blocked` is true.
                    enum:
                    - balance_exhausted
                    - project_spend_cap_hit
                    - member_spend_cap_hit
                    - org_spend_cap_hit
                    type: string
                  blocked:
                    description: True when new spend is currently rejected.
                    type: boolean
                  member_spend:
                    description: 'The personal key''s owner: their spend on personal keys in the current billing period, and the cap that applies to them. `limit_scope` is `member` when a cap names them, which takes precedence, or `role` when it comes from their role; a role cap applies to each member holding the role, not to the role as a whole. Present only for personal keys, since project keys never count against a member''s cap.'
                    properties:
                      budget_period:
                        description: How often the budget resets; present only with a budget. Spend, period_start and period_end then describe the budget's current window; a total budget has no period_end.
                        enum:
                        - day
                        - week
                        - month
                        - total
                        type: string
                      currency:
                        enum:
                        - usd
                        type: string
                      limit_cents:
                        description: 'The budget for this scope in USD cents. Null means no budget targets this scope, not unlimited spending: the organization''s funding and budget still apply, and `blocked` reports them.'
                        type:
                        - integer
                        - 'null'
                      limit_scope:
                        description: Which budget the limit comes from; null when there is none.
                        enum:
                        - member
                        - role
                        - null
                        type:
                        - string
                        - 'null'
                      period_end:
                        format: date-time
                        type: string
                      period_start:
                        format: date-time
                        type: string
                      remaining_cents:
                        description: Budget left, never below zero; null when there is no budget.
                        type:
                        - integer
                        - 'null'
                      spent_cents:
                        type: integer
                      spent_dollars:
                        type: number
                    type: object
                  object:
                    example: me
                    type: string
                  organization:
                    properties:
                      name:
                        type: string
                      plan:
                        description: Billing plan (e.g. free, gateway, control_plane, enterprise).
                        type: string
                    type: object
                  project:
                    properties:
                      name:
                        type: string
                    type: object
                  project_spend:
                    description: 'The key''s own project: its spend in the current billing period, and its budget if one targets this project directly. An organization budget is never reported here. Present whenever billing is configured.'
                    properties:
                      budget_period:
                        description: How often the budget resets; present only with a budget. Spend, period_start and period_end then describe the budget's current window; a total budget has no period_end.
                        enum:
                        - day
                        - week
                        - month
                        - total
                        type: string
                      currency:
                        enum:
                        - usd
                        type: string
                      limit_cents:
                        description: 'The budget for this scope in USD cents. Null means no budget targets this scope, not unlimited spending: the organization''s funding and budget still apply, and `blocked` reports them.'
                        type:
                        - integer
                        - 'null'
                      limit_scope:
                        description: Which budget the limit comes from; null when there is none.
                        enum:
                        - project
                        - null
                        type:
                        - string
                        - 'null'
                      period_end:
                        format: date-time
                        type: string
                      period_start:
                        format: date-time
                        type: string
                      remaining_cents:
                        description: Budget left, never below zero; null when there is no budget.
                        type:
                        - integer
                        - 'null'
                      spent_cents:
                        type: integer
                      spent_dollars:
                        type: number
                    type: object
                  spend:
                    description: Organization-wide usage spend in the current billing period, and the organization budget if one is set. Present only when `visibility.organization_finance` is true.
                    properties:
                      budget_period:
                        description: How often the budget resets; present only with a budget. Spend, period_start and period_end then describe the budget's current window; a total budget has no period_end.
                        enum:
                        - day
                        - week
                        - month
                        - total
                        type: string
                      currency:
                        enum:
                        - usd
                        type: string
                      limit_cents:
                        description: 'The budget for this scope in USD cents. Null means no budget targets this scope, not unlimited spending: the organization''s funding and budget still apply, and `blocked` reports them.'
                        type:
                        - integer
                        - 'null'
                      limit_scope:
                        description: Which budget the limit comes from; null when there is none.
                        enum:
                        - organization
                        - null
                        type:
                        - string
                        - 'null'
                      period_end:
                        format: date-time
                        type: string
                      period_start:
                        format: date-time
                        type: string
                      remaining_cents:
                        description: Budget left, never below zero; null when there is no budget.
                        type:
                        - integer
                        - 'null'
                      spent_cents:
                        type: integer
                      spent_dollars:
                        type: number
                    type: object
                  visibility:
                    description: What this key may see. Omitted when billing is not configured.
                    properties:
                      organization_finance:
                        description: True when the key's owner holds `billing:read`, so `balance` and `spend` are included. False means they were withheld, not that they are zero.
                        type: boolean
                    type: object
                type: object
          description: Successful response
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad request
        '401':
          description: Unauthorized - missing or invalid API key
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      summary: Get caller identity and credits
      tags:
      - Account
components:
  schemas:
    ErrorResponse:
      properties:
        error:
          properties:
            code:
              type: string
            details:
              description: Any value
            message:
              type: string
          required:
          - code
          - message
          type: object
        meta:
          type: object
      required:
      - error
      type: object
  securitySchemes:
    BearerAuth:
      bearerFormat: API Key
      description: API key authentication. Pass your API key as a Bearer token.
      scheme: bearer
      type: http
    MCPBearer:
      description: Delegated user OAuth access token for the Opper MCP resource. Obtain through advertised OAuth authorization; runtime and management service keys are not accepted.
      scheme: bearer
      type: http
    ManagementBearer:
      bearerFormat: Management API Key
      description: Management API authentication. Pass an `op-mak-…` management token as a Bearer token. Runtime `op-…` API keys are rejected with 403 — they belong on the data-plane endpoints. Mint a management key from the platform UI under Settings → API keys.
      scheme: bearer
      type: http