Agentic Endpoints Vault API

openapi: 3.2.0
info:
  title: agentic-endpoints Vault API
  version: 1.0.0
  license:
    name: MIT
    identifier: MIT
  description: 'Pay-per-call utilities for autonomous agents. No signup, no API keys, no invoices: every endpoint answers HTTP 402 with a price and serves the request once payment is signed.'
servers:
- url: https://agentic-endpoints.com
tags:
- name: Vault
paths:
  /vault/store:
    post:
      summary: Store an encrypted item in the vault.
      description: Store an encrypted item in the vault. The first store claims the namespace and returns a one-time namespace_token.. Costs $0.02, paid per call with x402 (USDC on Base), or debited from a prepaid balance by sending an X-Credit-Token header.
      operationId: vault_store
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                namespace:
                  type: string
                  description: Vault isolation scope
                key:
                  type: string
                  description: Item key
                ciphertext:
                  type: string
                  description: Client-side encrypted payload. This service never sees plaintext.
                alg:
                  type: string
                  description: Encryption algorithm label (default aes-256-gcm)
                ttl:
                  type: number
                  description: Optional lifetime in seconds
                namespace_token:
                  type: string
                  description: Required once the namespace has been claimed by a first store
                if_match:
                  type: string
                  description: 'Compare-and-swap: the item''s current updated_at. The write is refused with status ''precondition_failed'' if the value changed since then, instead of silently clobbering it.'
                if_absent:
                  type: boolean
                  description: Create-only. Refuses with status 'precondition_failed' if the key already exists.
              required:
              - namespace
              - key
              - ciphertext
            example:
              namespace: agent-secrets-4f9c2b1e8d7a
              key: openai-api-key
              ciphertext: base64-of-your-client-side-encrypted-bytes
              alg: AES-GCM
              ttl: 604800
      responses:
        '200':
          description: Success
          content:
            application/json:
              example:
                status: stored
                namespace: my-app-4f9c2b1e8d7a
                key: secret-1
                alg: aes-256-gcm
                size_bytes: 128
                created_at: '2026-01-01T00:00:00.000Z'
                updated_at: '2026-01-01T00:00:00.000Z'
                expires_at: null
                namespace_token: shown-once-on-first-store
                receipt: abc123...
        '402':
          description: Payment required. The body names the price and all three ways to pay, including the free trial that needs no wallet. The `payment-required` response header carries the same challenge base64-encoded, which is where x402 v2 clients read it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
        '429':
          description: Rate limited.
      security:
      - creditToken: []
      - x402Payment: []
      - {}
      tags:
      - Vault
  /vault/delete:
    post:
      summary: Delete an item from the vault (requires the namespace_token)
      description: Delete an item from the vault (requires the namespace_token). Costs $0.005, paid per call with x402 (USDC on Base), or debited from a prepaid balance by sending an X-Credit-Token header.
      operationId: vault_delete
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                namespace:
                  type: string
                  description: Vault isolation scope
                key:
                  type: string
                  description: Item key to delete
                namespace_token:
                  type: string
                  description: One-time token issued when the namespace was claimed
              required:
              - namespace
              - key
              - namespace_token
            example:
              namespace: agent-secrets-4f9c2b1e8d7a
              key: openai-api-key
              namespace_token: the token returned by your first store
      responses:
        '200':
          description: Success
          content:
            application/json:
              example:
                status: deleted
                namespace: my-app-4f9c2b1e8d7a
                key: secret-1
        '402':
          description: Payment required. The body names the price and all three ways to pay, including the free trial that needs no wallet. The `payment-required` response header carries the same challenge base64-encoded, which is where x402 v2 clients read it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
        '429':
          description: Rate limited.
      security:
      - creditToken: []
      - x402Payment: []
      - {}
      tags:
      - Vault
  /vault/list:
    post:
      summary: List the keys held in a vault namespace with their metadata, without returning…
      description: List the keys held in a vault namespace with their metadata, without returning any ciphertext (requires the namespace_token). Costs $0.005, paid per call with x402 (USDC on Base), or debited from a prepaid balance by sending an X-Credit-Token header.
      operationId: vault_list
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                namespace:
                  type: string
                  description: Vault isolation scope
                namespace_token:
                  type: string
                  description: One-time token issued when the namespace was claimed
              required:
              - namespace
              - namespace_token
            example:
              namespace: agent-secrets-4f9c2b1e8d7a
              namespace_token: the token returned by your first store
      responses:
        '200':
          description: Success
          content:
            application/json:
              example:
                status: listed
                count: 1
                items:
                - key: openai-api-key
                  alg: aes-256-gcm
                  size_bytes: 184
                  created_at: '2026-01-01T00:00:00.000Z'
                  updated_at: '2026-01-01T00:00:00.000Z'
                  expires_at: null
        '402':
          description: Payment required. The body names the price and all three ways to pay, including the free trial that needs no wallet. The `payment-required` response header carries the same challenge base64-encoded, which is where x402 v2 clients read it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
        '429':
          description: Rate limited.
      security:
      - creditToken: []
      - x402Payment: []
      - {}
      tags:
      - Vault
  /vault/exists:
    post:
      summary: Check whether a key exists in the vault without returning its ciphertext…
      description: Check whether a key exists in the vault without returning its ciphertext (requires the namespace_token). Costs $0.005, paid per call with x402 (USDC on Base), or debited from a prepaid balance by sending an X-Credit-Token header.
      operationId: vault_exists
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                namespace:
                  type: string
                  description: Vault isolation scope
                key:
                  type: string
                  description: Item key to test
                namespace_token:
                  type: string
                  description: One-time token issued when the namespace was claimed
              required:
              - namespace
              - key
              - namespace_token
            example:
              namespace: agent-secrets-4f9c2b1e8d7a
              key: openai-api-key
              namespace_token: the token returned by your first store
      responses:
        '200':
          description: Success
          content:
            application/json:
              example:
                exists: true
                namespace: my-app-4f9c2b1e8d7a
                key: secret-1
        '402':
          description: Payment required. The body names the price and all three ways to pay, including the free trial that needs no wallet. The `payment-required` response header carries the same challenge base64-encoded, which is where x402 v2 clients read it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
        '429':
          description: Rate limited.
      security:
      - creditToken: []
      - x402Payment: []
      - {}
      tags:
      - Vault
  /vault/retrieve:
    post:
      summary: Retrieve an encrypted item from the vault (requires the namespace_token issued…
      description: Retrieve an encrypted item from the vault (requires the namespace_token issued at claim time). Costs $0.02, paid per call with x402 (USDC on Base), or debited from a prepaid balance by sending an X-Credit-Token header.
      operationId: vault_retrieve
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                namespace:
                  type: string
                  description: Vault isolation scope
                key:
                  type: string
                  description: Item key to retrieve
                namespace_token:
                  type: string
                  description: One-time token issued by the first /vault/store call that claimed this namespace
              required:
              - namespace
              - key
              - namespace_token
            example:
              namespace: agent-secrets-4f9c2b1e8d7a
              key: openai-api-key
              namespace_token: the token returned by your first store
      responses:
        '200':
          description: Success
          content:
            application/json:
              example:
                status: retrieved
                namespace: my-app-4f9c2b1e8d7a
                key: secret-1
                ciphertext: base64-encoded-ciphertext
                alg: aes-256-gcm
                created_at: '2026-01-01T00:00:00.000Z'
                updated_at: '2026-01-01T00:00:00.000Z'
                expires_at: null
                receipt: abc123...
        '402':
          description: Payment required. The body names the price and all three ways to pay, including the free trial that needs no wallet. The `payment-required` response header carries the same challenge base64-encoded, which is where x402 v2 clients read it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
        '429':
          description: Rate limited.
      security:
      - creditToken: []
      - x402Payment: []
      - {}
      tags:
      - Vault
  /vault/rotate-token:
    post:
      summary: Replace a vault namespace token
      description: 'Mints a new namespace_token and invalidates the current one, which must be presented to authorize the rotation. Free on purpose: charging for the correct response to a suspected leak is how you end up with callers who never rotate. There is no recovery if the token is lost — any such path would be a second way into the namespace and would serve an attacker just as well as the owner.'
      operationId: vault_rotate_token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                namespace:
                  type: string
                namespace_token:
                  type: string
              required:
              - namespace
              - namespace_token
            example:
              namespace: agent-secrets-4f9c2b1e8d7a
              namespace_token: your current token
      responses:
        '200':
          description: Success, or a settled refusal. Paid routes answer 200 with a machine-readable `status` (e.g. "forbidden", "not_found", "precondition_failed", "conflict") rather than a 4xx, because any status >=400 cancels x402 settlement and would give the answer away for free. Always branch on `status`, not on the HTTP code.
        '400':
          description: Malformed request.
        '404':
          description: No such record.
        '429':
          description: Rate limited.
      security: []
      tags:
      - Vault
components:
  schemas:
    PaymentRequired:
      type: object
      description: Body of a 402. Every field is derived from the same challenge the caller is asked to sign, so it cannot quote a different price or recipient.
      properties:
        error:
          type: string
          const: payment_required
        price:
          type: string
          description: List price in dollars, e.g. $0.005
        resource:
          type: string
          description: The URL being charged for
        ways_to_pay:
          type: object
          description: The three routes in, cheapest first. free_trial needs no wallet, no signature, no account and no email.
          properties:
            free_trial:
              type: object
            prepaid_credit:
              type: object
            per_call_x402:
              type: object
        accepts:
          type: array
          description: The x402 challenge, echoed here for v1 clients that read it from the body rather than the payment-required header.
          items:
            type: object
        x402Version:
          type: number
      required:
      - error
      - ways_to_pay
  securitySchemes:
    creditToken:
      type: apiKey
      in: header
      name: X-Credit-Token
      description: A prepaid or trial balance. Get one free with no wallet and no account at POST https://agentic-endpoints.com/credits/trial, or buy credit at POST https://agentic-endpoints.com/credits/buy. Each call is debited at the route's list price and nothing is signed per request.
    x402Payment:
      type: apiKey
      in: header
      name: X-PAYMENT
      description: A signed x402 payment authorising this one call, built from the challenge returned with HTTP 402. Requires a funded wallet on Base; the credit token does not.