Gvnr

Gvnr Budget API

The Budget API from Gvnr — 4 operation(s) for budget.

GitHub OpenAPI

Operations 5

POST /v1/budget/clear Clearance call — approve or deny agent spend #
POST /v1/budget/reconcile Reconcile a prior clearance with actual LLM usage; applies drift to the agent… #
PUT /v1/budget/envelope Create or update agent spend envelope #
GET /v1/budget/envelope/{agent_id} Read envelope state #
DELETE /v1/budget/envelope/{agent_id} Delete an agent envelope #

Specifications

⚙
OpenAPI
https://artifacts.apis.io/gvnr-dev/openapi/gvnr-dev-budget-api-openapi.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/gvnr-dev:gvnr-dev-budget-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

gvnr-dev-budget-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Gvnr Budget API
  version: 1.8.1
  description: Budget & cost control for AI agents — per-agent spend caps, rate limits, idempotency, post-call reconciliation, and human approval bridges, enforced before each call.
servers:
- url: https://gvnr.dev
tags:
- name: Budget
paths:
  /v1/budget/clear:
    post:
      summary: Clearance call — approve or deny agent spend
      security:
      - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - agent_id
              - model
              - estimated_tokens
              properties:
                agent_id:
                  type: string
                  maxLength: 128
                  description: Agent identifier (must have a spend envelope set via PUT /v1/budget/envelope)
                model:
                  type: string
                  description: Provider model identifier (e.g. claude-sonnet-4-6, gpt-4o, text-embedding-3-small)
                estimated_tokens:
                  type: integer
                  minimum: 1
                  description: Output tokens for chat models, input tokens for embedding/input-only models
      responses:
        '200':
          description: Clearance result — always 200; check `approved` field
          content:
            application/json:
              schema:
                type: object
                required:
                - approved
                - remaining_usd
                properties:
                  approved:
                    type: boolean
                    description: True if the call is authorized; false if denied
                  remaining_usd:
                    type: number
                    description: USD remaining on the agent envelope after this clearance (0 if denied for no_credits/no_envelope)
                  operations_remaining:
                    type: integer
                    description: Governance operations remaining after this clearance (present when approved=true)
                  reason:
                    type: string
                    enum:
                    - no_credits
                    - no_envelope
                    - envelope_exceeded
                    description: Present only when approved=false. no_credits = governance quota exhausted
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Budget
      operationId: postV1BudgetClear
      x-operation-id-source: derived
  /v1/budget/reconcile:
    post:
      summary: Reconcile a prior clearance with actual LLM usage; applies drift to the agent…
      security:
      - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - agent_id
              - actual_input_tokens
              - actual_output_tokens
              properties:
                agent_id:
                  type: string
                  maxLength: 128
                actual_input_tokens:
                  type: integer
                  minimum: 0
                  description: Actual input tokens reported by the provider
                actual_output_tokens:
                  type: integer
                  minimum: 0
                  description: Actual output tokens reported by the provider
      responses:
        '200':
          description: Drift applied — the agent envelope (spend cap) corrected by (actual − estimated). warning="drift_exceeds_2x_threshold" when actual cost was >2× the estimate
          content:
            application/json:
              schema:
                type: object
                required:
                - ok
                - drift_usd
                - remaining_usd
                - operations_remaining
                properties:
                  ok:
                    type: boolean
                    description: Always true on 200; false outcomes return 400
                  drift_usd:
                    type: number
                    description: 'Signed: positive if actual > estimated, negative if actual < estimated. Adjusts the spend cap only'
                  remaining_usd:
                    type: number
                    description: USD remaining on the agent envelope after drift applied
                  operations_remaining:
                    type: integer
                    description: Governance operations remaining (unchanged by reconcile)
                  warning:
                    type: string
                    enum:
                    - drift_exceeds_2x_threshold
        default:
          description: Error (no_envelope, no_pending_clearance, invalid_params)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Budget
      operationId: postV1BudgetReconcile
      x-operation-id-source: derived
  /v1/budget/envelope:
    put:
      summary: Create or update agent spend envelope
      security:
      - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - agent_id
              - limit_usd
              properties:
                agent_id:
                  type: string
                  maxLength: 128
                limit_usd:
                  type: number
                  minimum: 1.0e-06
                  maximum: 1000000
                  description: Spend cap in USD over the window
                window:
                  type: string
                  enum:
                  - daily
                  - session
                  description: 'daily=resets at UTC midnight; session=never resets (caller-managed). Default: daily'
      responses:
        '200':
          description: Envelope created or updated (running spent_usd and reset_at preserved on update)
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - agent_id
                - limit_usd
                - window
                properties:
                  success:
                    type: boolean
                    enum:
                    - true
                  agent_id:
                    type: string
                  limit_usd:
                    type: number
                  window:
                    type: string
                    enum:
                    - daily
                    - session
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Budget
      operationId: putV1BudgetEnvelope
      x-operation-id-source: derived
  /v1/budget/envelope/{agent_id}:
    get:
      summary: Read envelope state
      security:
      - bearerAuth: []
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Current envelope record
          content:
            application/json:
              schema:
                type: object
                required:
                - agent_id
                - limit_usd
                - spent_usd
                - remaining_usd
                - window
                - reset_at
                properties:
                  agent_id:
                    type: string
                  limit_usd:
                    type: number
                  spent_usd:
                    type: number
                    description: Cumulative spend in the current window
                  remaining_usd:
                    type: number
                    description: Always max(0, limit − spent)
                  window:
                    type: string
                    enum:
                    - daily
                    - session
                  reset_at:
                    type: integer
                    description: Unix ms when the daily window next resets (informational for session)
        '404':
          description: Envelope not found for this agent_id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Budget
      operationId: getV1BudgetEnvelopeByAgentId
      x-operation-id-source: derived
    delete:
      summary: Delete an agent envelope
      security:
      - bearerAuth: []
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Envelope deleted
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - agent_id
                properties:
                  success:
                    type: boolean
                    enum:
                    - true
                  agent_id:
                    type: string
        '404':
          description: Envelope not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Budget
      operationId: deleteV1BudgetEnvelopeByAgentId
      x-operation-id-source: derived
components:
  schemas:
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Stable machine-readable error code (e.g. "invalid_params", "rate_limited", "not_found")
        required:
          type: array
          items:
            type: string
          description: Names/descriptors of required fields when error is "invalid_params"
        hint:
          type: string
          description: Human-readable guidance for resolving the error
        detail:
          type: string
          description: Additional context for the error
        valid:
          type: array
          items:
            type: string
          description: Allowed values when input was rejected as out-of-set
        valid_channels:
          type: array
          items:
            type: string
          description: Allowed notification channels (for approval requests)
        retryable:
          type: boolean
          description: Whether retrying the same request can succeed. false = fix input / auth / config first, or terminal. Omitted when retryability is already implied by required/valid (fix the input) or retry_after_ms (wait, then retry).
        retry_after_ms:
          type: integer
          description: Milliseconds to wait before retrying — present on rate_limited (429). Matches the runtime rate_check field.
        limit:
          type: string
          description: Description of the limit that was hit
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key from POST /v1/account