AmpleRun Agents API

openapi: 3.2.0
info:
  title: Amplerun Com Agents API
  version: 3.0.0
  description: 'Operations tagged agents across 2 of this provider''s published API definitions: openapi.json, amplerun-com-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://amplerun-api.spiry.org
  description: Production machine API (direct origin)
- url: https://amplerun.com
  description: Production frontend-compatible API origin
tags:
- name: Agents
  description: An AI agent registers its own account with a wallet signature (EIP-4361). No email, no person in the loop.
paths:
  /api/v1/agents/accounts/challenge:
    post:
      operationId: createAgentAccountChallenge
      tags:
      - Agents
      summary: Step 1 of agent self-registration; an EIP-4361 message to sign (unauthenticated)
      description: 'Returns a server-written Sign-In with Ethereum (EIP-4361) message for this address: this deployment''s domain and URI, Base (chain 8453), a single-use nonce and a five-minute expiry. Its statement carries the Terms version the agent accepts by signing. Sign it exactly as returned (EIP-191 personal_sign) with the wallet''s key. EOA wallets only. Rate-limited per source address and per wallet. Not /api/v1/agents/enroll, which enrolls host machines.'
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - address
              properties:
                address:
                  type: string
                  pattern: ^0x[0-9a-fA-F]{40}$
      responses:
        '200':
          description: The message to sign.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - message
                - expires_at
                - terms_version
                - terms_url
                properties:
                  message:
                    type: string
                  expires_at:
                    $ref: '#/components/schemas/Rfc3339Utc'
                  terms_version:
                    type: string
                    example: rental-v1
                  terms_url:
                    type: string
        default:
          $ref: '#/components/responses/Error'
    servers:
    - url: https://amplerun-api.spiry.org
      description: Production machine API (direct origin)
    - url: https://amplerun.com
      description: Production frontend-compatible API origin
  /api/v1/agents/accounts:
    post:
      operationId: registerAgentAccount
      tags:
      - Agents
      summary: Step 2 of agent self-registration; the signed message returns an agent account…
      description: 'Verifies the signed challenge (single use, unexpired, byte-for-byte the message the server wrote, signed by its address) and opens an account tagged account_kind agent, with the wallet as its verified linked wallet and payout destination. Returns an API key with the renter scope (add "host" to scopes to host), shown once. The same wallet again returns the same account (200) and a new key, only with a fresh signature. There is no free credit: fund the account (POST /api/v1/funding-intents) before renting. Refused: a replayed, expired or tampered message (401); a wallet linked to or unlinked from another account, or an account with an authenticator app (409); a suspended account''s wallet (403). Rate-limited per source address and per wallet (429). Audited.'
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - message
              - signature
              - agent
              properties:
                message:
                  type: string
                  maxLength: 2048
                  description: The challenge message
                  exactly as returned.: null
                signature:
                  type: string
                  maxLength: 1024
                  description: 0x-prefixed EIP-191 signature.
                agent:
                  type: object
                  additionalProperties: false
                  description: Self-declared and unverified; shown to operators, never used for authorization.
                  required:
                  - name
                  - vendor
                  properties:
                    name:
                      type: string
                      minLength: 1
                      maxLength: 100
                    vendor:
                      type: string
                      minLength: 1
                      maxLength: 64
                      description: Who made the agent or its model, e.g. "grok".
                    model:
                      type: string
                      minLength: 1
                      maxLength: 100
                    operator_contact:
                      type: string
                      minLength: 1
                      maxLength: 254
                    homepage:
                      type: string
                      format: uri
                      maxLength: 2048
                scopes:
                  type: array
                  minItems: 1
                  maxItems: 2
                  items:
                    type: string
                    enum:
                    - renter
                    - host
                  default:
                  - renter
      responses:
        '200':
          $ref: '#/components/responses/AgentAccountRegistered'
        '201':
          $ref: '#/components/responses/AgentAccountRegistered'
        default:
          $ref: '#/components/responses/Error'
    servers:
    - url: https://amplerun-api.spiry.org
      description: Production machine API (direct origin)
    - url: https://amplerun.com
      description: Production frontend-compatible API origin
components:
  schemas:
    UUID:
      type: string
      format: uuid
      pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
      example: 3f0e2a55-8c1b-4d2e-9a6f-0b7c1d2e3f40
    ErrorEnvelope:
      type: object
      additionalProperties: false
      required:
      - error
      example:
        error:
          code: QUOTE_EXPIRED
          message: quote expired
          retryable: false
          request_id: 3f0e2a55-8c1b-4d2e-9a6f-0b7c1d2e3f40
      properties:
        error:
          type: object
          additionalProperties: false
          required:
          - code
          - message
          - retryable
          - request_id
          properties:
            code:
              type: string
              minLength: 1
              description: 'Stable machine-readable code (packages/contracts ERROR_CODES). Business routes use UNAUTHENTICATED (401), FORBIDDEN (403: missing scope, step-up or role), NOT_FOUND (404, also used where existence must not leak), INVALID_INPUT (422), ADMISSION_PAUSED and AUTHORIZATION_INVALID (403), IDEMPOTENCY_CONFLICT, CONFLICT, VERSION_CONFLICT, STALE_VERSION, STALE_FENCE, QUOTE_EXPIRED, INSUFFICIENT_FUNDS and STOP_IRREVERSIBLE (409), and UNAVAILABLE (503, or 429 when rate limited). The host-agent protocol adds BUDGET_VERSION_OLDER, BUDGET_FUNDING_MISMATCH, LEASE_SEQ_REPLAY, COMMAND_EXPIRED, UNSUPPORTED_PROTOCOL_VERSION and UNKNOWN_COMMAND_KIND. New codes may appear; handle an unknown code by its HTTP status.'
            message:
              type: string
              minLength: 1
              description: Human-readable; never contains secrets or stack traces.
            retryable:
              type: boolean
              description: 'True when the identical request may succeed later: back off and retry with the same Idempotency-Key.'
            request_id:
              $ref: '#/components/schemas/UUID'
    Rfc3339Utc:
      type: string
      format: date-time
      pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]+)?Z$
      example: '2026-09-25T12:00:00Z'
  responses:
    Error:
      description: Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    AgentAccountRegistered:
      description: The agent's account (201 new, 200 existing) and a new API key. The secret is shown only here.
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            required:
            - account_id
            - account_kind
            - created
            - address
            - terms_version
            - api_key
            - next_steps
            properties:
              account_id:
                type: string
              account_kind:
                type: string
                enum:
                - agent
                - human
              created:
                type: boolean
              address:
                type: string
                description: Lowercase wallet address.
              terms_version:
                type: string
              api_key:
                type: object
                additionalProperties: false
                required:
                - key_id
                - secret
                - prefix
                - scopes
                properties:
                  key_id:
                    $ref: '#/components/schemas/UUID'
                  secret:
                    type: string
                    description: 'ark_... Send as Authorization: Bearer <secret>.'
                  prefix:
                    type: string
                  scopes:
                    type: array
                    items:
                      type: string
                      enum:
                      - renter
                      - host
              next_steps:
                type: object
                additionalProperties: false
                required:
                - fund
                - rent
                - mcp
                properties:
                  fund:
                    type: string
                  rent:
                    type: string
                  mcp:
                    type: string
  securitySchemes:
    sessionAuth:
      type: http
      scheme: bearer
      description: 'Bearer credential. Programs and agents send a scoped API key as `Authorization: Bearer ark_...` (renter and/or host scope; created once at https://amplerun.com/account#api-keys or POST /api/v1/account/api-keys; the secret is shown only at creation). The web app uses a pinned Better Auth session. API keys never reach /api/v1/admin/*. Step-up (recent re-auth) is required where noted.'
externalDocs:
  description: Guides, SDKs, CLI and the MCP server for AI agents
  url: https://amplerun.com/docs/api
x-refined-from:
- openapi.json
- amplerun-com-openapi.json