update_payment_policy

PATCH

/v1/payments/policies/{payment_policy_id}

const url = 'https://app.everruns.com/api/v1/payments/policies/example';
const options = {
  method: 'PATCH',
  headers: {'Content-Type': 'application/json'},
  body: '{"allowed_capabilities":["weather.lookup","shipping.quote","currency.convert"],"allowed_hosts":["api.shippo.com","api.openweathermap.org","api.exchangerate.host"],"max_amount_usd_per_day":1,"max_amount_usd_per_request":1,"max_amount_usd_per_turn":1,"metadata":"example","rail_preference":["mpp_tempo","x402_base"],"require_approval_above_usd":1,"status":"disabled"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request PATCH \
  --url https://app.everruns.com/api/v1/payments/policies/example \
  --header 'Content-Type: application/json' \
  --data '{ "allowed_capabilities": [ "weather.lookup", "shipping.quote", "currency.convert" ], "allowed_hosts": [ "api.shippo.com", "api.openweathermap.org", "api.exchangerate.host" ], "max_amount_usd_per_day": 1, "max_amount_usd_per_request": 1, "max_amount_usd_per_turn": 1, "metadata": "example", "rail_preference": [ "mpp_tempo", "x402_base" ], "require_approval_above_usd": 1, "status": "disabled" }'

Update a payment policy. Only provided fields are modified.

Parameters

Path Parameters

payment_policy_id

required

string

Payment policy ID

Request Body^required

application/json

Request body for the update_payment_policy operation.

object

allowed_capabilities

New capability allowlist. Outer None leaves the field unchanged.

Array<string> | null

Example

[
  "weather.lookup",
  "shipping.quote",
  "currency.convert"
]

allowed_hosts

New host allowlist. Outer None leaves the field unchanged.

Array<string> | null

Example

[
  "api.shippo.com",
  "api.openweathermap.org",
  "api.exchangerate.host"
]

max_amount_usd_per_day

New per-day cap (USD). Advisory only — not yet enforced. Outer None leaves the field unchanged; inner None clears the cap.

number | null format: double

max_amount_usd_per_request

New per-request cap (USD). Enforced by the payment authority. Outer None leaves the field unchanged; inner None clears the cap.

number | null format: double

max_amount_usd_per_turn

New per-turn cap (USD). Advisory only — not yet enforced. Outer None leaves the field unchanged; inner None clears the cap.

number | null format: double

metadata

New free-form metadata. Replaces the existing metadata blob entirely when set. Example: {"owner_team": "ops", "ticket": "OPS-1248", "review_due": "2026-09-01"}.

rail_preference

New rail preference order. Outer None leaves the field unchanged.

Array<string> | null

Example

[
  "mpp_tempo",
  "x402_base"
]

require_approval_above_usd

New approval threshold (USD). Advisory only — not yet enforced. Outer None leaves the field unchanged; inner None disables the (future) gate.

number | null format: double

status

New lifecycle status. Valid values: active, disabled.

string | null

Example

disabled

Responses

200

Payment policy updated

application/json

A payment policy — the binding between a paying account and a subject (agent identity, session) that controls which paid calls are authorized and at what spend caps.

object

allowed_capabilities

required

Capability IDs this policy permits paid calls for. Empty list means no capability gating.

Array<string>

allowed_hosts

required

HTTP host allowlist for paid outbound calls. Empty list means no host gating.

Array<string>

created_at

required

Timestamp when this policy was created (RFC 3339).

string format: date-time

required

Prefixed public identifier. See ID Schema.

string

/^paypol_[0-9a-f]{32}$/

max_amount_usd_per_day

Maximum cumulative amount (USD) per UTC day. Advisory only — not yet enforced. Stored on the policy for forward compatibility; the payment authority currently checks only max_amount_usd_per_request. None means no per-day cap.

number | null format: double

max_amount_usd_per_request

Maximum amount (USD) any single paid request may settle for. Enforced by the payment authority at policy selection. None means no per-request cap.

number | null format: double

max_amount_usd_per_turn

Maximum cumulative amount (USD) per agent turn. Advisory only — not yet enforced. Stored on the policy for forward compatibility; the payment authority currently checks only max_amount_usd_per_request. None means no per-turn cap.

number | null format: double

metadata

required

Free-form metadata attached to this policy.

organization_id

required

Owning organization’s prefixed public identifier.

string

payment_account_id

required

Payment account this policy authorizes spending from.

string

/^payacct_[0-9a-f]{32}$/

rail_preference

required

Preferred settlement rails in priority order; the authority picks the first available.

Array<string>

Allowed values: mpp_tempo x402_base

require_approval_above_usd

Threshold (USD) above which a request would require explicit human approval. Advisory only — not yet enforced. Stored on the policy for forward compatibility; no approval gate is wired up yet. None disables the (future) gate.

number | null format: double

status

required

Current lifecycle status of this policy.

string

Allowed values: active disabled pending succeeded failed released

subject_id

required

Prefixed identifier of the bound subject.

string

subject_type

required

Class of subject this policy binds to (e.g. agent_identity, session).

string

updated_at

required

Timestamp when this policy was last updated (RFC 3339).

string format: date-time

Example

{
  "allowed_capabilities": [
    "paid_search",
    "paid_image_gen"
  ],
  "allowed_hosts": [
    "api.openai.com",
    "api.anthropic.com"
  ],
  "created_at": "2026-04-01T10:00:00Z",
  "id": "paypol_01933b5a00007000800000000000001",
  "max_amount_usd_per_day": 50,
  "max_amount_usd_per_request": 2.5,
  "max_amount_usd_per_turn": 5,
  "organization_id": "org_01933b5a000070008000000000000001",
  "payment_account_id": "payacct_01933b5a00007000800000000000001",
  "rail_preference": [
    "mpp_tempo"
  ],
  "require_approval_above_usd": 10,
  "status": "active",
  "subject_id": "identity_01933b5a000070008000000000000001",
  "subject_type": "agent_identity",
  "updated_at": "2026-05-20T14:00:00Z"
}

400

Invalid input

application/json

Standard error response.

Wire shape is RFC 9457 Problem Details: every error response includes title and status, and may include detail, code, allowed_actions, retry_after_seconds, instance, and type. The content type is rewritten to application/problem+json by [problem_json_content_type].

object

allowed_actions

Recovery actions the caller can take next.

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 documented in specs/api-conventions.md 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. Closed vocabulary documented in specs/api-conventions.md — 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

code

Stable, machine-readable error code (snake_case).

string | null

detail

Human-readable explanation specific to this occurrence.

string | null

instance

Request URI for this occurrence.

string | null

retry_after_seconds

Seconds the caller should wait before retrying (429 / transient 503).

integer | null format: int32

status

required

HTTP status code; mirrors the response status line.

integer format: int32

title

required

Short, human-readable summary of the problem (e.g. “Not Found”).

string

type

RFC 9457 problem type URI. Optional; identifies the problem class.

string | null

Example

{
  "allowed_actions": [
    {
      "method": "POST"
    }
  ],
  "code": "session_not_found",
  "detail": "Session session_01933b5a000070008000000000000001 not found in org org_01933b5a000070008000000000000001.",
  "instance": "/v1/sessions/session_01933b5a000070008000000000000001",
  "retry_after_seconds": 30,
  "status": 404,
  "title": "Session not found",
  "type": "https://docs.everruns.com/errors/session_not_found"
}

404

Not found

application/json

Standard error response.

object

allowed_actions

Recovery actions the caller can take next.

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 documented in specs/api-conventions.md 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

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

string

schema_ref

string | null

code

Stable, machine-readable error code (snake_case).

string | null

detail

Human-readable explanation specific to this occurrence.

string | null

instance

Request URI for this occurrence.

string | null

retry_after_seconds

Seconds the caller should wait before retrying (429 / transient 503).

integer | null format: int32

status

required

HTTP status code; mirrors the response status line.

integer format: int32

title

required

Short, human-readable summary of the problem (e.g. “Not Found”).

string

type

RFC 9457 problem type URI. Optional; identifies the problem class.

string | null

Example

{
  "allowed_actions": [
    {
      "method": "POST"
    }
  ],
  "code": "session_not_found",
  "detail": "Session session_01933b5a000070008000000000000001 not found in org org_01933b5a000070008000000000000001.",
  "instance": "/v1/sessions/session_01933b5a000070008000000000000001",
  "retry_after_seconds": 30,
  "status": 404,
  "title": "Session not found",
  "type": "https://docs.everruns.com/errors/session_not_found"
}

update_payment_policy

Parameters

Path Parameters

Request Body required

Example

Example

Example

Example

Responses

200

Example

400

Example

404

Example

Request Body^required