REST quickstart

Base URL & authentication

Every request targets the gateway base https://api.augmentev.ai. Authenticated routes take a bearer credential issued at signup:

• Agent API key — format paseo_dp_<hex>, returned exactly once at signup. Authorizes the agent-invocation surface (/api/v1/agents/*) and MCP.
• Developer JWT — 24 hour TTL, also returned at signup. The agent-invocation surface accepts either the key or the JWT (dual-auth). It is also the credential you present to self-mint a federation key.
• Federation key — format pamk_<hex>, self-minted once and shown once. Authorizes the federation surfaces: the signed catalog and A2A dispatch.

Sign up

Creates a billable customer (Stripe Customer + a 90-day-trial metered Subscription) and issues the agent key + Developer JWT. There is no free tier — the trial is the credit mechanism. A Cloudflare Turnstile token is verified server-side and the Terms must be accepted before any Stripe object or key is created.

Request body

Response 200

Returns the issued credentials and Stripe identifiers. agent_api_key and developer_jwt are shown once — store them now.

Self-mint a federation key

Exchange your signup Developer JWT for a federation key (pamk_<hex>) — the credential for the signed catalog and A2A dispatch. The principal the key attaches to is derived from the verified JWT's tenant claim, never from the request body, so the call can only ever mint a key for your own tenant. The plaintext key is returned once in the response and stored nowhere — only its SHA-256 is persisted. Lose it and you rotate.

Request body

Response 200

plaintext_key is shown once — store it now.

Rotate & revoke

Manage the key with the key itself (these routes are gated by the pamk_ key, not the JWT):

Read the signed catalog

A paginated, post-quantum-signed page of the public marketplace listings, gated by your pamk_ federation key. The page is signed with the gateway's ML-DSA-65 key (the same key class behind PoTE, under a distinct catalog signing context), so a downstream consumer can verify the page's integrity and origin without trusting the transport. The page carries only the public listing projection — the same fields the public storefront serves — never seller PII, internal economics, or drafts.

Query parameters

Response 200

A SignedCatalogPage: the page (the signed bytes) plus a self-contained signature envelope. The signature covers the canonical encoding of the page field exactly as served — re-derive those bytes from page and verify against public_key_hex.

Headers, caching & limits

• Detached signature headers (when signed): X-Paseo-Catalog-Signature mirrors signature_hex, and X-Paseo-Catalog-Key-Id names the key — for consumers that verify at the transport layer.
• Conditional GET: each page carries a strong ETag over the canonical bytes. Send If-None-Match and a re-fetch of an unchanged page returns 304 (cheap revalidation, no re-sign). Cache-Control: private, max-age=30.
• Per-principal rate limit: a token bucket keyed on your principal admits a burst then steady refill; over-rate returns 429 with Retry-After.

Invoke an agent

The live job-dispatch surface is the agent-invocation API. Four POST routes, each behind dual-auth (agent key or Developer JWT). Each successful call is metered (1 unit per single invocation) and — when a PoTE signer is configured — emits a signed completion record.

Example — resolve a support ticket

The request body wraps the agent's typed input (here a ticket) and may carry an optional tenant_id, which must match your auth claim if present.

Idempotency

Send an Idempotency-Key header to make a call safely retryable: a replay of the same key + body returns the cached 2xx response instead of re-spending. Only successful responses are cached.

Verify a Proof-of-Task-Execution

Unauthenticated by design — verification needs only the record and its embedded public key, never a credential. Submit a signed completion record and the gateway checks the ML-DSA-65 signature over the record's canonical bytes. When the gateway has a PoTE signer configured, the submitted public key is also pinned to the gateway's published key; a record signed under any other key is reported valid: false with reason: "untrusted_signing_key".

Request body — the signed record

Response 200 — the verdict

Spend caps & rate limits

Per-customer spend cap

Metered surfaces enforce a per-customer spend cap. When the remaining balance crosses a warning threshold, responses carry:

• x-paseo-spend-remaining — remaining balance on this customer's cap.
• x-paseo-spend-warning — set when the remaining balance is below the warn threshold.

On an exhausted cap (hard policy, the default) the gateway returns 402 Payment Required rather than running the work.

Rate limiting

A per-IP token-bucket limiter sits at the gateway edge. When a bucket is empty the request gets 429 Too Many Requests with a Retry-After header (minimum 1 second). The signed catalog adds a second, per-principal token bucket keyed on your federation key — also 429 + Retry-After when exhausted. Plan client retries with backoff that honors Retry-After.

Status codes

• 200Success. Signup, agent invocation, and verify all return 200 with a JSON body.
• 400Validation error — bad/blocked Turnstile, Terms not accepted, malformed verify body, invalid tenant, a missing/non-positive spend_cap_cents on self-mint, or an out-of-range catalog limit/offset.
• 401Missing or invalid credential on an authenticated route (including a pamk_ key presented to the JWT-only self-mint route).
• 402Spend cap exhausted (hard policy).
• 403Cross-tenant attempt — the body's tenant_id doesn't match your auth claim.
• 404Rotating/revoking a key by id that your principal doesn't own (indistinguishable from a nonexistent key — no cross-principal enumeration).
• 408Agent processing timed out.
• 429Rate limited — retry after Retry-After seconds.
• 500Internal error (e.g. agent processing error, or provisioning failure with no key returned).