AmpleRun Account API

openapi: 3.2.0
info:
  title: Amplerun Com Account API
  version: 3.0.0
  description: 'Operations tagged account 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: Account
  description: Profile, sessions, API keys and third-party tokens for the caller.
paths:
  /api/v1/auth/providers:
    get:
      operationId: getSignInProviders
      tags:
      - Account
      summary: Configured social sign-in providers (public names only)
      security: []
      responses:
        '200':
          description: Currently composed providers; credentials are never returned.
          headers:
            Cache-Control:
              schema:
                type: string
                const: no-store
          content:
            application/json:
              schema:
                type: object
                required:
                - providers
                additionalProperties: false
                properties:
                  providers:
                    type: array
                    uniqueItems: true
                    items:
                      type: string
                      enum:
                      - github
                      - google
                      - huggingface
    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/account:
    get:
      operationId: getAccount
      tags:
      - Account
      summary: Profile/security metadata (self); no password/token hashes
      security:
      - sessionAuth: []
      responses:
        '200':
          description: Account profile.
          content:
            application/json:
              schema:
                type: object
                required:
                - account_id
                - email
                - role
                - host_enabled
                - email_verified
                - two_factor_enabled
                - auth_method
                - step_up_method
                properties:
                  account_id:
                    type: string
                  email:
                    type: string
                    description: A wallet-created account without an email has a non-routable placeholder ending in @wallet.placeholder.invalid (RFC 6761).
                  role:
                    enum:
                    - renter
                    - host
                    - admin
                  host_enabled:
                    type: boolean
                  email_verified:
                    type: boolean
                    description: Quotes, reservations and funding require a verified email or a wallet-created account; hosting requires a verified email.
                  two_factor_enabled:
                    type: boolean
                  auth_method:
                    enum:
                    - session
                    - api-key
                    description: How this request authenticated.
                  step_up_method:
                    enum:
                    - totp
                    - password
                    - wallet
                    - none
                    description: The proof POST /api/v1/account/step-up asks for. wallet is a fresh EIP-4361 signature from the wallet a wallet-created account signs in with.
                  name:
                    type: string
                    nullable: true
                    description: Display name from sign-up or the social provider; null when none was given.
                  account_kind:
                    enum:
                    - human
                    - agent
                    description: 'Who opened the account: a person, or an agent through self-registration.'
                  created_at:
                    type: string
                    format: date-time
                    description: When the account was created (member since).
        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/account/sessions:
    get:
      operationId: listSessions
      tags:
      - Account
      summary: Session metadata (self)
      security:
      - sessionAuth: []
      responses:
        '200':
          description: Active sessions.
        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/account/sessions/{id}:
    delete:
      operationId: revokeSession
      tags:
      - Account
      summary: Revoke one of the caller's own sessions (self; interactive sessions only)
      description: Deleting the session row is the revocation. A session the caller does not own is indistinguishable from a missing one (404). API-key callers have no sessions (404).
      security:
      - sessionAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9_-]{1,255}$
        description: Better Auth session id (not a UUID).
      responses:
        '204':
          description: Revoked.
        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/account/api-keys:
    get:
      operationId: listApiKeys
      tags:
      - Account
      summary: List API keys (self)
      security:
      - sessionAuth: []
      responses:
        '200':
          description: API key metadata; secrets never re-shown.
          content:
            application/json:
              schema:
                type: object
                required:
                - items
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApiKeyView'
        default:
          $ref: '#/components/responses/Error'
    post:
      operationId: createApiKey
      tags:
      - Account
      summary: Create API key (self, step-up)
      description: Label, expiry and explicit renter/host scopes. Secret revealed once; only hash stored. No admin scopes or key-based MFA bypass.
      security:
      - sessionAuth: []
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - label
              - scopes
              properties:
                label:
                  type: string
                  minLength: 1
                expires_at:
                  $ref: '#/components/schemas/Rfc3339Utc'
                scopes:
                  type: array
                  minItems: 1
                  uniqueItems: true
                  items:
                    enum:
                    - renter
                    - host
      responses:
        '201':
          description: API key created; secret returned exactly once.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ApiKeyView'
                - type: object
                  required:
                  - secret
                  properties:
                    secret:
                      type: string
                      pattern: ^ark_
                      description: The API key. Store it now; it is not shown again.
        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/account/api-keys/{id}:
    delete:
      operationId: revokeApiKey
      tags:
      - Account
      summary: Revoke API key (self, step-up)
      security:
      - sessionAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/UUID'
      - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '204':
          description: Revoked.
        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/account/integrations/{provider}:
    get:
      operationId: getIntegration
      tags:
      - Account
      summary: Third-party token status (self)
      description: Whether a per-user token is on file for this provider; never the value.
      security:
      - sessionAuth: []
      parameters:
      - name: provider
        in: path
        required: true
        schema:
          enum:
          - huggingface
      responses:
        '200':
          description: Token status.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - provider
                - set
                - updated_at
                properties:
                  provider:
                    enum:
                    - huggingface
                  set:
                    type: boolean
                  updated_at:
                    oneOf:
                    - $ref: '#/components/schemas/Rfc3339Utc'
                    - type: 'null'
        default:
          $ref: '#/components/responses/Error'
    post:
      operationId: setIntegration
      tags:
      - Account
      summary: Set/replace third-party token (self, step-up)
      description: Encrypted at rest the same way as an admin secret setting; never re-shown once saved.
      security:
      - sessionAuth: []
      parameters:
      - name: provider
        in: path
        required: true
        schema:
          enum:
          - huggingface
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - token
              properties:
                token:
                  type: string
                  minLength: 1
      responses:
        '201':
          description: Token stored.
        default:
          $ref: '#/components/responses/Error'
    delete:
      operationId: removeIntegration
      tags:
      - Account
      summary: Remove third-party token (self, step-up)
      security:
      - sessionAuth: []
      parameters:
      - name: provider
        in: path
        required: true
        schema:
          enum:
          - huggingface
      - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '204':
          description: Removed.
        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/account/export:
    post:
      operationId: exportAccount
      tags:
      - Account
      summary: Data export (self, recent re-auth)
      security:
      - sessionAuth: []
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '202':
          description: Export job persisted.
        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/account/deletion-request:
    post:
      operationId: requestAccountDeletion
      tags:
      - Account
      summary: Retention-aware deletion request (self, recent re-auth); required ledger…
      security:
      - sessionAuth: []
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '202':
          description: Deletion request persisted.
        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:
    ApiKeyView:
      description: API key metadata. The secret itself appears only in the creation response.
      type: object
      required:
      - key_id
      - label
      - prefix
      - scopes
      - expires_at
      - revoked_at
      - created_at
      properties:
        key_id:
          $ref: '#/components/schemas/UUID'
        label:
          type: string
        prefix:
          type: string
          description: First 12 characters of the key, for recognising it.
        scopes:
          type: array
          items:
            enum:
            - renter
            - host
        expires_at:
          anyOf:
          - $ref: '#/components/schemas/Rfc3339Utc'
          - type: 'null'
        revoked_at:
          anyOf:
          - $ref: '#/components/schemas/Rfc3339Utc'
          - type: 'null'
        created_at:
          $ref: '#/components/schemas/Rfc3339Utc'
    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'
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema:
        $ref: '#/components/schemas/UUID'
      description: UUID scoped to authenticated principal, route and canonical request hash.
  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