Endpoint Commands

The ampersend endpoint command group lets an agent manage its own hosted endpoints from the CLI. All commands authenticate as the agent using the active local config — no API key required.

Requires ampersend v0.0.20 or later. Run ampersend --version to check, and follow the SDK quick start to install and run ampersend setup.

All commands return the standard JSON envelope:

{
  "ok": true,
  "data": {
    /* ... */
  }
}

{ "ok": false, "error": { "code": "...", "message": "..." } }

Commands at a glance

Command	Purpose
endpoint list	List the agent's hosted endpoints
endpoint get <id>	Show a single endpoint
endpoint create	Create a new hosted endpoint
endpoint update <id>	Update one or more fields
endpoint delete <id>	Delete an endpoint
endpoint enable <id> / disable <id>	Toggle activation without deleting
endpoint test <id>	Send a synthetic request through the proxy
endpoint headers ...	Add or remove proxy / required headers
endpoint rotate-secret <id>	Rotate the per-endpoint signing secret
endpoint import <spec.json>	Bulk create from OpenAPI 3.0 / 3.1 spec

endpoint list

ampersend endpoint list

Returns an array of hosted endpoints owned by the authenticated agent.

endpoint get

ampersend endpoint get <id>

endpoint create

ampersend endpoint create \
  --name <name> \
  --price-usd <usd> \
  --proxy-url <url> \
  [options]

Option	Description
--name <name>	Display name (required)
--price-usd <usd>	Per-call price in USD (required, positive number)
--proxy-url <url>	Upstream URL the proxy forwards to (required, http/https)
--description <text>	Optional description
--methods <csv>	Allowed HTTP methods, comma-separated (default: GET)
--rate-limit <n>	Global rate limit per minute
--timeout <ms>	Proxy timeout in milliseconds (5000–60000, default 30000)
--proxy-header "<name>: <value>"	Header ampersend forwards to the upstream. Repeat for multiple.
--required-header <name>	Header name the buyer must include on the incoming request. Repeat for multiple.

To create an endpoint in the disabled state, create it and then call ampersend endpoint disable <id>.

endpoint update

ampersend endpoint update <id> \
  [--name <name>] [--price-usd <usd>] [--proxy-url <url>] \
  [--description <text>] [--methods <csv>] \
  [--rate-limit <n>] [--timeout <ms>] \
  [--enabled <bool>]

Only the fields you pass are changed. --enabled true / --enabled false toggle activation; enable / disable are shorthand for the same operation.

endpoint delete

ampersend endpoint delete <id>

endpoint enable / endpoint disable

ampersend endpoint enable <id>
ampersend endpoint disable <id>

A disabled endpoint is refused by the proxy without accepting payment. Re-enable with endpoint enable.

endpoint test

ampersend endpoint test <id>

Sends a synthetic request through the proxy to verify the upstream is reachable and responds with the expected shape. Useful right after create or update.

endpoint headers

Two header lists are maintained per endpoint:

• Proxy headers — added by ampersend to every upstream request (e.g., an upstream API key). Stored encrypted.
• Required headers — headers the buyer must include on the incoming request.

# Proxy headers (ampersend → upstream)
ampersend endpoint headers add-proxy <id> --name <header> --value <value>
ampersend endpoint headers remove-proxy <id> <name>

# Required headers (caller → ampersend)
ampersend endpoint headers add-required <id> --name <header>
ampersend endpoint headers remove-required <id> <name>

remove-proxy and remove-required take the header name as a positional argument. add-proxy and add-required use named flags.

endpoint rotate-secret

ampersend endpoint rotate-secret <id>

Rotates the per-endpoint shared secret used to sign upstream requests. The previous secret is invalidated immediately — upstreams that verify X-Ampersend-Signature must accept the new secret before the next call.

endpoint import

Bulk-create endpoints from an OpenAPI 3.0 / 3.1 JSON spec. One endpoint is created per path + method pair.

ampersend endpoint import <spec.json> \
  [--default-price <usd>] \
  [--base-url <url>] \
  [--timeout <ms>] \
  [--dry-run]

Option	Description
<spec.json>	Path to an OpenAPI 3.0 / 3.1 JSON spec file (YAML is not parsed — convert to JSON first)
--default-price <usd>	Fallback per-call price when the operation has no x-ampersend-price. Defaults to 0.01 — always pass an explicit value for production imports.
--base-url <url>	Override the spec's base URL (wins over servers[0].url)
--timeout <ms>	Proxy timeout applied to every imported endpoint
--dry-run	Parse and validate without creating endpoints

Vendor extensions

Recognised per-operation extensions:

Extension	Type	Effect
x-ampersend-price	number	Per-call price in USD
x-ampersend-name	string	Endpoint display name override
x-ampersend-description	string	Description override
x-ampersend-rate-limit	integer	Rate limit per minute

See OpenAPI to Endpoints for a full walkthrough.

Security guidance

NEVER create or mutate endpoints without explicit user intent. When scripting, echo the intended change and confirm before executing. Deleting or rotating secrets is immediate and cannot be undone — double-check the endpoint ID.