run402-com Console API

openapi: 3.2.0
info:
  title: Run402 Console API
  version: 2.0.0
  description: 'Full-stack infrastructure for AI agents. Postgres, REST API, auth, file storage, static site hosting, serverless functions. Tier payments and image generation use the shared payment engine: x402 (USDC on Base), MPP on Tempo (pathUSD), and the draft-pinned MPP Lightning charge profile (sats, Bitcoin mainnet) for authenticated tier purchases and image generation.'
  contact:
    name: Run402
    url: https://run402.com
  guidance: 'Run402 is a pay-per-use backend for AI agents: Postgres databases, static hosting, serverless functions, and image generation. The shared payment engine supports x402 (USDC on Base), MPP on Tempo (pathUSD), and the exact Run402 MPP Lightning charge profile on Bitcoin mainnet (sats).


    ## Quick start

    1. Install the CLI: npm install -g run402@latest

    2. Create an allowance: run402 init

    3. Set the prototype tier (FREE, testnet USDC): run402 tier set prototype

    4. Provision a project: run402 projects provision --name "my-app"

    5. Deploy: run402 deploy --manifest app.json


    ## Payment model

    - Tiers (prototype $0.10 testnet, hobby $5, team $20; hobby and team are 30-day prepaid leases) unlock all platform features.

    - Image generation is $0.03 per call (x402, MPP on Tempo, or MPP Lightning micropayment).

    - Auth-only endpoints (projects, deploys, messages) require SIWX wallet identity but no payment.


    ## Auth

    - x402 endpoints: include a payment header (handled automatically by the CLI or x402 client libraries).

    - Explicit MPP Lightning tier requests require the exact Run402 profile, ordered Accept-Payment preferences, one principal credential, a stable Idempotency-Key, and buyer-side USD/native/fee limits.

    - SIWX endpoints: sign a CAIP-122 message with your wallet.

    - REST API: use the project''s anon_key or service_key as the apikey header.


    ## Client metadata

    - Recent Node SDK/CLI clients may send Run402-Client: surface="cli", version="3.7.14", sdk="3.7.14". It is advisory, bounded, never used for auth/billing/trust, and not browser-CORS-enabled yet.


    ## Docs

    - Full CLI docs: https://run402.com/llms-cli.txt

    - API docs: https://run402.com/llms.txt'
servers:
- url: https://api.run402.com
  description: Production
tags:
- name: Console
  description: 'The console for the person behind an agent (console spec). API-first: the reference web console is just a consumer of these endpoints.'
paths:
  /agent/v1/control-plane/cli/device:
    post:
      tags:
      - Console
      summary: Start a CLI device-authorization (RFC 8628)
      description: Public, no oracle (email-less). Begins a browser-delegated device grant so the run402 CLI can obtain an sign-in session. Returns { device_code, user_code, verification_uri, verification_uri_complete, expires_in, interval }.
      operationId: operatorSessionDeviceStart
      responses:
        '200':
          description: Device-authorization start payload.
          content:
            application/json:
              schema:
                type: object
  /agent/v1/control-plane/cli/device/approve:
    post:
      tags:
      - Console
      summary: Approve (or deny) a CLI device authorization
      description: Operator-session-authed; the session must have authenticated recently (magic-link OR passkey). Binds the user_code to an approve/deny decision. Does NOT mint a session — the mint happens at the token poll.
      operationId: operatorSessionDeviceApprove
      security:
      - operatorSession: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - user_code
              properties:
                user_code:
                  type: string
                decision:
                  type: string
                  enum:
                  - approve
                  - deny
      responses:
        '200':
          description: '{ ok, decision, client_name }'
          content:
            application/json:
              schema:
                type: object
  /agent/v1/control-plane/cli/device/token:
    post:
      tags:
      - Console
      summary: Poll for the sign-in session (RFC 8628 token endpoint)
      description: 'Public; the device_code is the credential. On approval returns { control_plane_session_token, token_type, expires_in, absolute_expires_at, email, wallets[] } (single-use). Otherwise an RFC-8628 error body { error } at HTTP 400: authorization_pending | slow_down | access_denied | expired_token.'
      operationId: operatorSessionDeviceToken
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - device_code
              properties:
                device_code:
                  type: string
      responses:
        '200':
          description: '{ control_plane_session_token, ... } on approval.'
          content:
            application/json:
              schema:
                type: object
        '400':
          description: RFC 8628 error body { error }.
          content:
            application/json:
              schema:
                type: object
  /agent/v1/me/overview:
    get:
      tags:
      - Console
      summary: Organization overview (Tier-A summary)
      description: 'Multi-account, summary-first read: { scope, operator, rollup, organizations[], wallets[], advisories[] }. Counts only (functions/secrets/domains/mailboxes) — NOT inventory names. An organization''s `quotas` count only the projects it owns; `wallets[].projects[]` lists every project the wallet can reach, each with its owning `org_id`. Accepts an sign-in session (verified-email union), a control-plane session (the console''s write-capable sign-in reading its OWN footprint — verified-email + siwx-authenticator union; scope.kind "principal"), OR a wallet SIWX header (that wallet''s slice). Service/admin keys are NOT accepted here.'
      operationId: operatorOverview
      security:
      - operatorSession: []
      - controlPlaneSession: []
      - walletAuth: []
      responses:
        '200':
          description: AccountOverview (Tier A).
          content:
            application/json:
              schema:
                type: object
  /agent/v1/me/projects:
    get:
      tags:
      - Console
      summary: Cross-account project inventory (--all)
      description: 'Named, domain-aware project inventory across the owner''s verified-email wallet union (or a single wallet''s slice for a SIWX caller), in the same row shape as GET /projects/v1: { projects: [{ project_id, name, tier, site_url, custom_domains, status, org_id, created_by, created_at }], scope }. Soft-deleted (tombstone) projects are NEVER listed; archived projects are hidden by default and opt back in with `include=archived`. Names + public addressing only — no secret/key values. Service/admin keys are NOT accepted here.'
      operationId: operatorProjectInventory
      security:
      - operatorSession: []
      - walletAuth: []
      parameters:
      - name: include
        in: query
        schema:
          type: string
          enum:
          - archived
        description: Opt archived projects back into the listing (`include=archived`). Soft-deleted (tombstone) projects are never returned regardless. Any other value is a 400.
      responses:
        '200':
          description: Named cross-account project inventory.
          content:
            application/json:
              schema:
                type: object
  /agent/v1/me/projects/{project_id}/contents:
    get:
      tags:
      - Console
      summary: Project inventory names (Tier-B drill-down)
      description: Inventory NAMES (secret names, function names, domains, subdomains, mailbox slugs) — never values. Sign-in session requires fresh proof (passkey-login or recent re-auth); the project must be owned by a wallet in the caller's set.
      operationId: operatorProjectContents
      security:
      - operatorSession: []
      - walletAuth: []
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ProjectContents (Tier B).
          content:
            application/json:
              schema:
                type: object
  /admin/v1/overview:
    get:
      tags:
      - Console
      summary: Operator overview for support (admin only, audited)
      description: Support read. Mandatory exactly-one target query + a mandatory audit-log row. Same response schema as the public overview.
      operationId: operatorOverviewAdmin
      security:
      - adminKey: []
      parameters:
      - name: email
        in: query
        required: false
        schema:
          type: string
          format: email
      - name: wallet
        in: query
        required: false
        schema:
          type: string
      - name: org_id
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: AccountOverview.
          content:
            application/json:
              schema:
                type: object
components:
  securitySchemes:
    operatorSession:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'The sign-in session bearer (control_plane_session): principal-bound, graded by provenance (grade: browser | loopback | device — device is read-only), 30-min access TTL, 12h absolute cap, jti-revocable.'
    apikey:
      type: apiKey
      in: header
      name: apikey
      description: Project JWT in the apikey header. Most client-facing routes accept the project anon_key; privileged project operations require a service_key or project_admin JWT.
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'User access_token from /auth/v1/token. Pass as Authorization: Bearer <token>.'
    serviceKey:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Project service_key (JWT with service_role). Returned when you provision a project. Pass as Authorization: Bearer <service_key>.'
    adminKey:
      type: apiKey
      in: header
      name: x-admin-key
      description: Server admin key. Required for admin operations.
    x402:
      type: apiKey
      in: header
      name: X-PAYMENT
      description: x402 payment header. The client library (e.g. @anthropic-ai/sdk x402 facilitator) handles this automatically. Payment is in USDC on Base (mainnet eip155:8453 or testnet eip155:84532).
    mppPayment:
      type: apiKey
      in: header
      name: Authorization
      description: MPP Payment credential for the exact retained Lightning charge challenge. The credential is sent only after the fixed invoice settles; portable receipts contain the payment hash, never the preimage.
    walletAuth:
      type: apiKey
      in: header
      name: SIGN-IN-WITH-X
      description: SIWX (Sign-In-With-X, CAIP-122 / EIP-4361) wallet authentication. Send a single SIGN-IN-WITH-X header containing a base64-encoded JSON payload with a signed CAIP-122 message (domain binding, temporal validation, cryptographic signature). Supports both EVM (eip155:*) and Solana wallets. Most wallet-auth endpoints require an active tier; endpoints that only require identity say so in their description. See https://docs.x402.org/extensions/sign-in-with-x.
    ciSessionAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'CI session JWT from POST /ci/v1/token-exchange. HS256, signed with CI_SESSION_SECRET (server-controlled). Carries `token_use:"ci_session"`, 15-min TTL bounded by binding expiry. Accepted on the CI-callable deploy routes: all `/content/v1/plans*` writes, all `/apply/v1/plans*` writes, GET `/apply/v1/operations/{operation_id}` + `/events` + `/edge-coherence`, POST `/apply/v1/operations/{operation_id}/resume`. ALSO the own-project error-read surface GET `/projects/v1/{project_id}/errors` + `/{fingerprint_id}` (read-only; the deploy→watch promote gate, keyless). The binding is created via SIWE at POST /ci/v1/bindings. See "OIDC federation for CI/CD" in llms-full.txt.'
    browserSession:
      type: apiKey
      in: cookie
      name: __Host-Http-r402_session
      description: Hosted browser-session cookie minted by the hosted-auth ceremony on <project>.run402.app / a verified custom domain. Backs the headless <AccountSecurity> component and the documented-advanced non-Astro /auth/account/* + /auth/passkeys/* (register) routes. State-changing POSTs additionally require the double-submit CSRF token and a same-origin Origin/Referer; sensitive mutations (password, passkey removal, identity unlink) require a session authenticated within the last 5 minutes else R402_AUTH_FRESHNESS_REQUIRED. Machine clients use the /auth/v1/* JWT routes instead.
    controlPlaneSession:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Principal-bound control-plane session bearer minted by control-plane login (passkey / email magic-link / Google / GitHub). Payload: typ=run402.control-plane-session+jwt, aud=run402.control-plane.v1, token_use=control_plane_session. WRITE-capable subject to org role + step-up (passkey-principals-onboarding).'
    controlPlaneBrowserSession:
      type: apiKey
      in: cookie
      name: __Host-Http-r402_cp_session
      description: Opaque control-plane browser session handle. It is distinct from the bearer token and tenant browser session, rotates on refresh, and is accepted only on its documented same-origin browser routes and explicit principal-transport surfaces.
    grantKeyBearer:
      type: http
      scheme: bearer
      bearerFormat: run402_agent_key
      description: Scoped Run402 grant key bearer (a run402_agent_key minted against one grant). The route declares the required project capability, such as `project.archives.export` or `project.deploy`; a grant key never grants owner-only operations.
    voucherIssuerKey:
      type: apiKey
      in: header
      name: x-run402-issuer-key
      description: Issuer credential for minting and listing vouchers. Held by a registered voucher-issuing application; provisioned by platform staff. Not a tenant credential — agents never hold one.
    gitBasicAuth:
      type: http
      scheme: basic
      description: 'Git smart HTTP on app repos: HTTP Basic auth whose password is the project''s service key (or project credential) or a grant key for the project; the username is ignored. A request without credentials gets 401 with `WWW-Authenticate: Basic realm="run402"`, so git asks its credential helper. `run402 app-repos clone <repo_name>` installs a helper that supplies the local project''s service key, so no secret lands in the remote URL or .git/config.'