repowise-dev Costs API

openapi: 3.2.0
info:
  title: repowise Costs API
  description: REST API for repowise — codebase documentation engine
  version: 0.59.0
tags:
- name: Costs
paths:
  /api/repos/{repo_id}/costs/summary:
    get:
      tags:
      - Costs
      summary: Get Cost Summary
      description: Return aggregate cost totals for a repository.
      operationId: get_cost_summary_api_repos__repo_id__costs_summary_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: repo_id
        in: path
        required: true
        schema:
          type: string
          title: Repo Id
      - name: since
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: ISO date filter, e.g. 2025-01-01
          title: Since
        description: ISO date filter, e.g. 2025-01-01
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CostSummaryResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: internal
  /api/repos/{repo_id}/costs:
    get:
      tags:
      - Costs
      summary: List Costs
      description: Return grouped cost totals for a repository.
      operationId: list_costs_api_repos__repo_id__costs_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: repo_id
        in: path
        required: true
        schema:
          type: string
          title: Repo Id
      - name: since
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: ISO date filter, e.g. 2025-01-01
          title: Since
        description: ISO date filter, e.g. 2025-01-01
      - name: by
        in: query
        required: false
        schema:
          type: string
          description: 'Grouping dimension: operation | model | day'
          default: day
          title: By
        description: 'Grouping dimension: operation | model | day'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CostGroupResponse'
                title: Response List Costs Api Repos  Repo Id  Costs Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: internal
  /api/repos/{repo_id}/savings:
    get:
      tags:
      - Costs
      summary: Get Savings
      description: 'What agents avoided in this repository, from the canonical ledger.


        Reads through the one core report service, so this endpoint, the

        repository overview headline and ``repowise saved`` report the same

        numbers by construction rather than by three implementations agreeing.


        The transcript miners below are *observed opportunities* -- things that

        could have been saved and were not. They are reported beside the achieved

        savings and never added to them.'
      operationId: get_savings_api_repos__repo_id__savings_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: repo_id
        in: path
        required: true
        schema:
          type: string
          title: Repo Id
      - name: days
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            maximum: 3650
            minimum: 0
          - type: 'null'
          description: Window in days; omit for all time
          title: Days
        description: Window in days; omit for all time
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavingsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: internal
components:
  schemas:
    CostSummaryResponse:
      properties:
        total_cost_usd:
          type: number
          title: Total Cost Usd
        total_calls:
          type: integer
          title: Total Calls
        total_input_tokens:
          type: integer
          title: Total Input Tokens
        total_output_tokens:
          type: integer
          title: Total Output Tokens
        since:
          anyOf:
          - type: string
          - type: 'null'
          title: Since
      type: object
      required:
      - total_cost_usd
      - total_calls
      - total_input_tokens
      - total_output_tokens
      - since
      title: CostSummaryResponse
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    SavingsOpportunityRow:
      properties:
        kind:
          type: string
          title: Kind
        observations:
          type: integer
          title: Observations
          default: 0
        estimated_potential_input_tokens:
          type: integer
          title: Estimated Potential Input Tokens
          default: 0
      type: object
      required:
      - kind
      title: SavingsOpportunityRow
      description: One kind of observed opportunity. Never part of achieved savings.
    CostGroupResponse:
      properties:
        group:
          type: string
          title: Group
        calls:
          type: integer
          title: Calls
        input_tokens:
          type: integer
          title: Input Tokens
        output_tokens:
          type: integer
          title: Output Tokens
        cost_usd:
          type: number
          title: Cost Usd
      type: object
      required:
      - group
      - calls
      - input_tokens
      - output_tokens
      - cost_usd
      title: CostGroupResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SavingsBreakdownRow:
      properties:
        group:
          anyOf:
          - type: string
          - type: 'null'
          title: Group
        events:
          type: integer
          title: Events
          default: 0
        saved_input_tokens:
          type: integer
          title: Saved Input Tokens
          default: 0
      type: object
      title: SavingsBreakdownRow
      description: 'One bucket of a savings breakdown.


        ``group`` is nullable because one bucket genuinely has no name: an event

        written before its rate could be resolved has no model, and that is a real

        quantity -- how much saving carries no pricing evidence -- rather than a

        gap to drop from the list.'
    SavingsAgentRow:
      properties:
        agent:
          type: string
          title: Agent
        agent_display_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Display Name
        events:
          type: integer
          title: Events
          default: 0
        saved_input_tokens:
          type: integer
          title: Saved Input Tokens
          default: 0
      type: object
      required:
      - agent
      title: SavingsAgentRow
      description: One agent's savings, labelled from the identity registry.
    SavingsResponse:
      properties:
        available:
          type: boolean
          title: Available
        window_days:
          anyOf:
          - type: integer
          - type: 'null'
          title: Window Days
        as_of:
          type: string
          title: As Of
          default: ''
        first_event_at:
          anyOf:
          - type: string
          - type: 'null'
          title: First Event At
        last_event_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Event At
        unique_events:
          type: integer
          title: Unique Events
          default: 0
        successful_or_usable_partial_events:
          type: integer
          title: Successful Or Usable Partial Events
          default: 0
        saving_interactions:
          type: integer
          title: Saving Interactions
          default: 0
        mcp_queries_answered:
          type: integer
          title: Mcp Queries Answered
          default: 0
        dead_ends:
          type: integer
          title: Dead Ends
          default: 0
        saved_input_tokens:
          type: integer
          title: Saved Input Tokens
          default: 0
        measured_saved_input_tokens:
          type: integer
          title: Measured Saved Input Tokens
          default: 0
        inferred_saved_input_tokens:
          type: integer
          title: Inferred Saved Input Tokens
          default: 0
        priced_saved_input_tokens:
          type: integer
          title: Priced Saved Input Tokens
          default: 0
        unpriced_saved_input_tokens:
          type: integer
          title: Unpriced Saved Input Tokens
          default: 0
        priced_input_savings_usd:
          type: number
          title: Priced Input Savings Usd
          default: 0.0
        saved_output_tokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Saved Output Tokens
        priced_saved_output_tokens:
          type: integer
          title: Priced Saved Output Tokens
          default: 0
        unpriced_saved_output_tokens:
          type: integer
          title: Unpriced Saved Output Tokens
          default: 0
        priced_output_savings_usd:
          type: number
          title: Priced Output Savings Usd
          default: 0.0
        baseline_events:
          type: integer
          title: Baseline Events
          default: 0
        reducing_events:
          type: integer
          title: Reducing Events
          default: 0
        baseline_input_tokens:
          type: integer
          title: Baseline Input Tokens
          default: 0
        baseline_saved_input_tokens:
          type: integer
          title: Baseline Saved Input Tokens
          default: 0
        input_reduction_ratio:
          anyOf:
          - type: number
          - type: 'null'
          title: Input Reduction Ratio
        input_reduction_ratio_p90:
          anyOf:
          - type: number
          - type: 'null'
          title: Input Reduction Ratio P90
        per_operation:
          items:
            $ref: '#/components/schemas/SavingsBreakdownRow'
          type: array
          title: Per Operation
          default: []
        per_surface:
          items:
            $ref: '#/components/schemas/SavingsBreakdownRow'
          type: array
          title: Per Surface
          default: []
        per_agent:
          items:
            $ref: '#/components/schemas/SavingsAgentRow'
          type: array
          title: Per Agent
          default: []
        per_model:
          items:
            $ref: '#/components/schemas/SavingsBreakdownRow'
          type: array
          title: Per Model
          default: []
        per_day:
          items:
            $ref: '#/components/schemas/SavingsBreakdownRow'
          type: array
          title: Per Day
          default: []
        opportunity_count:
          type: integer
          title: Opportunity Count
          default: 0
        opportunity_tokens_excluded:
          type: integer
          title: Opportunity Tokens Excluded
          default: 0
        per_opportunity_kind:
          items:
            $ref: '#/components/schemas/SavingsOpportunityRow'
          type: array
          title: Per Opportunity Kind
          default: []
        missed_events:
          type: integer
          title: Missed Events
          default: 0
        missed_tokens_est:
          type: integer
          title: Missed Tokens Est
          default: 0
        missed_window_days:
          type: number
          title: Missed Window Days
          default: 0.0
        reread_events:
          type: integer
          title: Reread Events
          default: 0
        reread_tokens_est:
          type: integer
          title: Reread Tokens Est
          default: 0
      type: object
      required:
      - available
      title: SavingsResponse
      description: 'What agents avoided in one repository over one window.


        Every figure comes from the canonical savings ledger through the one core

        report service, so this response, the repository overview headline and

        ``repowise saved`` cannot disagree -- which the three of them did, in four

        separate ways, when each aggregated and priced the ledger for itself.


        Three things it deliberately keeps apart. *Measured* reductions are known

        before/after sizes from an operation that really ran; *inferred* avoidance

        is a documented counterfactual. *Priced* and *unpriced* tokens are split

        because an event records the rate it was worth at the time and some events

        carry none, and reporting a total as though it were all priced would be a

        guess. *Observed opportunities* are things that could have been saved and

        were not: they never enter the headline.


        ``available`` is False when the repository has no savings sidecar at all,

        which means "nothing has been measured here" and is different from a

        measured zero.'
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: Authorization