Skip to content
EverrunsEverruns
Everruns Cloud is open in early access. Run agents without operating the platform.

Add credits to a budget. Reactivates exhausted or paused budgets if balance becomes positive.

POST
/v1/budgets/{budget_id}/top-up
curl --request POST \
  --url https://app.everruns.com/api/v1/budgets/example/top-up \
  --header 'Content-Type: application/json' \
  --data '{ "amount": 1, "description": "example" }'

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters”
budget_id
required
string

Prefixed public identifier

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
amount
required

Amount credited back to the budget balance.

number format: double
description

Human-readable description. Safe to render in user-facing messages.

string | null
Examplegenerated
{
  "amount": 1,
  "description": "example"
}

Responses

Section titled “ Responses ”

200

Section titled “200”

Success

Media typeapplication/json

Wrapper that adds API and UI links to a serialized resource.

Uses self_url (not url) for the API link to avoid collision with resources that already have a url field (e.g. McpServer). The allowed_actions array carries state-aware hypermedia links — empty (and omitted from the wire shape) until the underlying resource opts into the convention by overriding ResourceUrlable::allowed_actions.

object
balance
required

Current remaining balance (limit minus consumed).

number format: double
created_at
required
string format: date-time
currency
required

Currency: “usd”, “tokens”, “credits”, or custom.

string
id
required
string
limit
required

Hard limit — budget ceiling.

number format: double
metadata

Arbitrary metadata.

organization_id
required
string
period
One of:
One of:

Sliding window of a configurable number of seconds.

object
seconds
required
integer format: int64
type
required
string
Allowed values: duration
period_started_at

When the current period started (used to detect period rollover for Duration / Rolling periods, and to display “resets at” in the UI). None for budgets without a period.

string | null format: date-time
soft_limit

Soft limit — triggers pause/warn when balance drops below this.

number | null format: double
status
required

Budget status.

string
Allowed values: active paused exhausted disabled
subject_id
required

Public ID of the subject entity.

string
subject_type
required

Subject type: what entity this budget constrains.

string
Allowed values: session agent user organization agent_trigger agent_channel
updated_at
required
string format: date-time
allowed_actions

State-aware hypermedia actions the caller can take on this resource next (e.g. cancel, events, update). Omitted from the wire shape when empty so resources that haven’t opted into the convention don’t grow their payloads.

Array<object>

Agent-actionable link describing a follow-up the caller can take. Used in two contexts:

  • Error recovery — ErrorResponse.allowed_actions carries rels like retry, retry-later, unarchive, get-existing so the agent knows the right next call after a 4xx/429.
  • Entity hypermedia — WithUrls<T>.allowed_actions carries state-aware rels like cancel, events, self, update on the entity itself so the agent can follow links instead of reconstructing routes from prose.

The shape is intentionally identical across both contexts; the closed rel vocabulary distinguishes them.

object
hint

Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).

string | null
href

Absolute (preferred) or relative URL the caller may invoke directly. Always present on entity hypermedia actions (WithUrls<T>.allowed_actions); optional on error-recovery actions (ErrorResponse.allowed_actions) where the matching operation_id is enough and the URI is implicit from the failed call.

string | null
method

HTTP method to use against href. Required for entity hypermedia actions; usually omitted on error-recovery actions where the same operation is retried with its original method.

string | null
operation_id

OpenAPI operationId the caller should invoke. Lets an MCP client resolve the call without parsing href.

string | null
rel
required

Link relation describing the action. Examples: self, cancel, pause, resume, events, retry, retry-later, unarchive, get-existing, delete, update.

string
schema_ref

OpenAPI $ref to the request-body schema, when the action takes one (e.g. #/components/schemas/UpdateSessionRequest). Lets a tool-calling agent fetch the input shape without scanning the whole spec.

string | null
self_url
required

Full API endpoint URL for this resource.

string
ui_link
required

Alias for view_url, used by command and MCP outputs.

string
view_url
required

Full UI URL for viewing this resource.

string
Example
{
  "id": "bdgt_01933b5a00007000800000000000001",
  "period": {
    "type": "duration"
  },
  "status": "active",
  "subject_type": "session",
  "allowed_actions": [
    {
      "method": "POST"
    }
  ]
}

404

Section titled “404”

Budget not found