Budgets

Spend budgets.

4 actions. Each is callable by the agent as a tool, over HTTP via /api/invoke, and (usually) from a UI page.

`budgets.list`

GET

List budgets. Optionally scope to a project / mission / actor.

AI tool: budgets_list
API: GET /api/invoke/budgets.list

Input

Field	Type	Required
`scope`	"workspace" \| "project" \| "mission" \| "actor" \| "category"	—
`scopeRef`	string	—
`active`	boolean	—

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "scope": {
      "type": "string",
      "enum": [
        "workspace",
        "project",
        "mission",
        "actor",
        "category"
      ]
    },
    "scopeRef": {
      "type": "string"
    },
    "active": {
      "type": "boolean"
    }
  }
}

`budgets.upsert`

POST · mutating

Create or update a budget.

AI tool: budgets_upsert
API: POST /api/invoke/budgets.upsert

Input

Field	Type	Required
`id`	string	—
`name`	string	yes
`scope`	"workspace" \| "project" \| "mission" \| "actor" \| "category"	—
`scopeRef`	string	—
`category`	"ai-inference" \| "human-labor" \| "integration-fee" \| "subscription" \| "compute" \| "travel" \| "other"	—
`periodKind`	"month" \| "quarter" \| "year" \| "lifetime" \| "custom"	—
`periodStart`	any	—
`periodEnd`	any	—
`amount`	number	yes
`currency`	string	—
`alertThresholds`	integer[]	—
`enforcement`	"soft" \| "hard"	—
`active`	boolean	—

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    },
    "name": {
      "type": "string"
    },
    "scope": {
      "default": "workspace",
      "type": "string",
      "enum": [
        "workspace",
        "project",
        "mission",
        "actor",
        "category"
      ]
    },
    "scopeRef": {
      "type": "string"
    },
    "category": {
      "type": "string",
      "enum": [
        "ai-inference",
        "human-labor",
        "integration-fee",
        "subscription",
        "compute",
        "travel",
        "other"
      ]
    },
    "periodKind": {
      "default": "month",
      "type": "string",
      "enum": [
        "month",
        "quarter",
        "year",
        "lifetime",
        "custom"
      ]
    },
    "periodStart": {},
    "periodEnd": {},
    "amount": {
      "type": "number"
    },
    "currency": {
      "default": "USD",
      "type": "string"
    },
    "alertThresholds": {
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": -9007199254740991,
        "maximum": 9007199254740991
      }
    },
    "enforcement": {
      "type": "string",
      "enum": [
        "soft",
        "hard"
      ]
    },
    "active": {
      "type": "boolean"
    }
  },
  "required": [
    "name",
    "amount"
  ]
}

`budgets.delete`

DELETE · mutating

Delete a budget.

AI tool: budgets_delete
API: DELETE /api/invoke/budgets.delete

Input

Field	Type	Required	Description
`id`	string	yes

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "id"
  ]
}

`budgets.status`

GET

For each active budget, compute current spend vs. limit and which threshold alerts have crossed.

AI tool: budgets_status
API: GET /api/invoke/budgets.status

Input

No parameters.

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {},
  "additionalProperties": {}
}