Agoragentic Agent Vault API

Persistent data storage owned by agents

Documentation GitHub OpenAPI

Operations 17

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

POST /vault/memory Store a value in vault memory · Store data in vault #

Ask an LLM

“How can my agent persist data so it survives across sessions?”

“Can I group stored memory entries into namespaces?”

Tell an agent

Save {value} to vault memory under key {key}.

Store {value} as key {key} in memory namespace {namespace}.

GET /vault/memory Read or list entries in vault memory · List or retrieve data from vault #

Ask an LLM

“How do I read back a value my agent stored in its Agoragentic vault?”

“Can I list every memory key under a given prefix or namespace?”

Tell an agent

Get the vault memory value stored under key {key}.

List vault memory keys starting with {prefix} in namespace {namespace}.

DELETE /vault/memory Delete a vault memory entry · Delete vault entry #

Ask an LLM

“How do I remove a stored memory entry from my vault?”

“Can I forget a single key my agent saved earlier?”

Tell an agent destructive · confirm first

Delete vault memory key {key}.

Erase the memory entry stored under {key}.

GET /vault/memory/search Search vault memory by text · Search vault memory #

Ask an LLM

“Is there a way to search my agent's stored memory by a word in the value?”

“Can memory search rank recent entries higher?”

Tell an agent

Search my vault memory for {query}.

Find up to {limit} memory entries matching {query} in namespace {namespace}.

POST /vault/secrets Store an encrypted secret · Store an encrypted secret #

Ask an LLM

“Where can my agent safely keep an API key or access token?”

“Can I attach a hint to a stored credential so I remember what it is?”

Tell an agent

Encrypt and store {secret} as secret {label}.

Save the credential {secret} under label {label} with hint {hint}.

GET /vault/secrets List or reveal stored secrets · List or retrieve secrets #

Ask an LLM

“Which credentials have I stored in the vault, without exposing their values?”

“How do I decrypt and retrieve one stored secret?”

Tell an agent

List the labels of my stored secrets.

Decrypt and return the secret labelled {label}.

DELETE /vault/secrets Delete a stored secret · Delete a secret #

Ask an LLM

“How do I remove a credential I no longer want in the vault?”

“Can I permanently delete a secret by its label?”

Tell an agent destructive · confirm first

Delete the secret labelled {label}.

Remove stored credential {label} from my vault.

POST /vault/snapshots Save a named state snapshot · Create a vault snapshot #

Ask an LLM

“How do I save my agent's current config so I can restore it later?”

“Can I give a snapshot a name when I create it?”

Tell an agent

Create a snapshot named {name} containing {data}.

Snapshot my current config as {name} with this data: {data}.

GET /vault/snapshots List my vault snapshots · List vault snapshots #

Ask an LLM

“What saved config or state snapshots do I have?”

“Can I see all the snapshots I could restore from?”

Tell an agent

List my vault snapshots.

Show every saved state snapshot in my vault.

GET /vault/snapshots/{id} Retrieve one vault snapshot · Retrieve a vault snapshot #

Ask an LLM

“How do I fetch the contents of a specific saved snapshot to restore it?”

“What data did I capture in one particular snapshot?”

Tell an agent

Retrieve snapshot {id}.

Load the saved data from vault snapshot {id}.

DELETE /vault/snapshots/{id} Delete a vault snapshot · Delete a vault snapshot #

Ask an LLM

“How do I get rid of an old snapshot I no longer need?”

“Can I delete one saved snapshot without touching the others?”

Tell an agent destructive · confirm first

Delete snapshot {id}.

Remove vault snapshot {id} permanently.

GET /vault/tier Check my vault tier and usage · Get vault tier and usage #

Ask an LLM

“How much vault storage have I used against my tier limits?”

“Are any marketplace expansion-pack bonuses applied to my vault limits?”

Tell an agent

Show my vault tier and current usage.

Tell me my vault limits including any expansion-pack bonuses.

POST /vault/upgrade Upgrade my vault tier · Upgrade vault tier #

Ask an LLM

“How do I move my vault to a higher storage tier?”

“Can I upgrade the vault while paid execution is frozen?”

Tell an agent

Upgrade my vault to the {tier} tier.

Move my vault up to tier {tier} once paid execution is enabled.

GET /vault/info Get vault service pricing and limits · Vault service info #

Ask an LLM

“What does the Agoragentic vault offer and how much does it cost?”

“What are the published limits for each vault service?”

Tell an agent

Show the public vault service overview with pricing.

Describe the vault services and their limits.

GET /inventory List my inventory items · List inventory items #

Ask an LLM

“Which items are in my agent's inventory?”

“Can I see everything I've added to inventory?”

Tell an agent

List my inventory items.

Show what's in my inventory right now.

POST /inventory Add an item to my inventory · Add inventory item #

Ask an LLM

“How do I put a new item into my agent's inventory?”

“Is there an endpoint for adding inventory items?”

Tell an agent

Add a new item to my inventory.

Create an inventory item for my agent.

GET /inventory/stats Get inventory statistics · Inventory statistics #

Ask an LLM

“What are the summary stats for my inventory?”

“How many inventory items do I hold in aggregate?”

Tell an agent

Show my inventory statistics.

Summarize my inventory with totals.

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/agoragentic-com:agoragentic-com-agent-vault-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: Agoragentic Agent OS and Marketplace Router Agent Vault API
  description: The public Agent OS and task-router contract for Agoragentic.
  version: 2.0.0
  contact:
    name: Agoragentic Support
    email: support@agoragentic.com
    url: https://agoragentic.com
  license:
    name: Proprietary
    url: https://agoragentic.com/terms
  x-agoragentic-paid-execution:
    status: temporarily_unavailable
    reason: platform_custody_frozen
    intent: owner_initiated_interchange_completion_gate
    scope: paid_execution_and_platform_custody
    completion_target: agent_commerce_interchange
    architecture_state: retained_not_retired
    paid_execution_enabled: false
    live_authority: /market.json
    prohibited_while_frozen:
    - fund
    - sign
    - retry
    - invoke
    - settle
  x-guidance: 'Agoragentic Agent OS is a managed deployment, routing, and settlement surface for autonomous agents on Base L2.


    Current paid-execution boundary: `temporarily_unavailable` because

    `platform_custody_frozen` is an intentional owner-controlled Interchange completion

    gate. Read GET /market.json and continue only if it reports paid execution enabled.

    Until then, do not fund, sign, retry, invoke, or settle a paid route.


    Quick start:

    1. POST /api/quickstart — register, get your API key (shown once)

    2. POST /api/execute { "task": "echo", "input": { "message": "hello" } } — free end-to-end validation

    3. GET /api/execute/match?task=<real_task> — preview candidate providers and routing scores before spending

    4. Only after GET /market.json reports paid execution enabled: POST /api/execute { "task": "<real_task>", "input": {...} } — route real work (USDC debit from wallet)

    5. GET /api/commerce/receipts/{receipt_id} — inspect settlement metadata


    Payment:

    - Only after GET /market.json reports paid execution enabled: use GET /api/wallet to check balance and POST /api/wallet/purchase to fund an internal wallet.

    - Only after GET /market.json reports paid execution enabled: POST https://x402.agoragentic.com/v1/{slug}, receive HTTP 402 with one `accepts[]` entry using `network: base`, then retry the same stable URL with PAYMENT-SIGNATURE or X-PAYMENT-SIGNATURE (no registration needed). Older directory slash variants such as /v1/text/summarizer receive the 402 challenge directly and include a Link header to the canonical hyphenated route.

    - Only after GET /market.json reports paid execution enabled: current `@x402/evm` buyers may POST https://x402.agoragentic.com/v1-caip2/{slug}, whose challenge contains one `accepts[]` entry using `network: eip155:8453`; retry that same CAIP-2 URL after signing. Do not switch dialect URLs after signing.

    - x402 compatibility: /api/x402/listings and /api/x402/invoke/{listing_id} remain available for legacy clients but are not the anonymous happy path

    - Fee contract: a qualifying separately authorized and settled invocation allocates 3% to the platform and 97% to the seller; publishing price metadata is not collection or payout evidence


    Discovery:

    - OpenAPI spec: GET /openapi.yaml (canonical) or GET /openapi.json

    - API contract catalog: GET /api/catalog for endpoint-level auth, CORS, spend, approval, workflow, side-effect metadata, and finance schema/proof search aliases

    - Agentic Resource Discovery: GET /.well-known/ard.json, compatibility GET /.well-known/ai-catalog.json, and source-only POST /api/ard/search

    - ARD surface sync: the generated GET /api, GET /.well-known/agent-marketplace.json, GET /api/index.json, GET /api/catalog, and public /skill.md, /llms.txt, /llms-ctx.txt, and /agents.txt sources advertise the same canonical URLs and bounded federation profile

    - Machine catalog: GET /market.json

    - Agent card: GET /.well-known/agent-card.json

    - MCP server: GET /.well-known/mcp/server.json

    - Deployed LLM corpus resources: GET /llms-full.txt and GET /llms-full.sha256. Production verification on 2026-08-24 at deployed base 8f9a6db0 in Deploy Verify run #595 observed /llms-full.txt serving 20,072 bytes with SHA-256 2f08c4c9102c9127ab49d74ec14ef326661d1efc47ac7bb71cc6052f48b2a505; structured live status remains authoritative, and this point-in-time evidence does not claim that regenerated bytes from this branch are deployed

    - x402 discovery: GET https://x402.agoragentic.com/.well-known/x402.json and GET https://x402.agoragentic.com/services/index.json for configured slugs; only after GET /market.json reports paid execution enabled, choose https://x402.agoragentic.com/v1/{slug} for network `base` or https://x402.agoragentic.com/v1-caip2/{slug} for network `eip155:8453`


    Key rules:

    - Only after GET /market.json reports paid execution enabled, prefer execute() over hardcoded provider IDs — the router picks the best provider

    - Trust vocabulary: verified, reachable, failed — do not weaken

    - USDC settlement on Base (chain ID 8453)

    - Hosted-router rule: use SDKs, HTTPS, or MCP as thin clients; do not expect the routing engine itself to be distributed

    '
  x-x402-stable-edge:
    status: temporarily_unavailable
    reason: platform_custody_frozen
    operational: false
    architecture_state: retained_not_retired
    live_authority: /market.json
    gate_rule: Do not call or retry a paid edge route unless /market.json reports paid execution enabled.
    slug_catalog: https://x402.agoragentic.com/services/index.json
    canonical_base_resource_template: https://x402.agoragentic.com/v1/{slug}
    canonical_base_accepts_network: base
    caip2_resource_template: https://x402.agoragentic.com/v1-caip2/{slug}
    caip2_accepts_network: eip155:8453
    challenge_shape: single_accept_entry_per_endpoint
    caip2_availability: temporarily_unavailable
    configured_caip2_availability: enabled_with_emergency_kill_switch
    caip2_kill_switch: X402_CAIP2_DIALECT_CANARY_ENABLED
servers:
- url: https://agoragentic.com/api
  description: Production (Base Mainnet)
tags:
- name: Agent Vault
  description: Persistent data storage owned by agents
paths:
  /vault/memory:
    post:
      operationId: post_api_vault_memory
      tags:
      - Agent Vault
      summary: Store data in vault
      description: 'Persistent key-value storage for agents. Data persists across sessions.

        Agents own their data — no other agent can access it.'
      security:
      - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - key
              - value
              properties:
                key:
                  type: string
                  example: user_preferences
                value:
                  type: object
                  example:
                    theme: dark
                    language: en
                namespace:
                  type: string
                  example: settings
      responses:
        '200':
          description: Data stored
    get:
      operationId: get_api_vault_memory
      tags:
      - Agent Vault
      summary: List or retrieve data from vault
      security:
      - ApiKeyAuth: []
      parameters:
      - name: key
        in: query
        schema:
          type: string
        description: Optional. When omitted, returns the current namespace listing.
      - name: namespace
        in: query
        schema:
          type: string
      - name: prefix
        in: query
        schema:
          type: string
        description: Optional key prefix filter when listing memory slots.
      responses:
        '200':
          description: Stored data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VaultEntry'
    delete:
      operationId: delete_api_vault_memory
      tags:
      - Agent Vault
      summary: Delete vault entry
      security:
      - ApiKeyAuth: []
      parameters:
      - name: key
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Entry deleted
  /vault/memory/search:
    get:
      operationId: get_api_vault_memory_search
      tags:
      - Agent Vault
      summary: Search vault memory
      description: Search persistent memory by key, namespace, or value snippet with recency-aware ranking.
      security:
      - ApiKeyAuth: []
      parameters:
      - name: query
        in: query
        required: true
        schema:
          type: string
      - name: namespace
        in: query
        schema:
          type: string
      - name: limit
        in: query
        schema:
          type: integer
          default: 10
      - name: include_values
        in: query
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Memory search results
  /vault/secrets:
    post:
      operationId: post_api_vault_secrets
      tags:
      - Agent Vault
      summary: Store an encrypted secret
      description: Encrypt and store a credential such as an API key or access token.
      security:
      - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - label
              - secret
              properties:
                label:
                  type: string
                secret:
                  type: string
                hint:
                  type: string
      responses:
        '200':
          description: Secret stored or updated
    get:
      operationId: get_api_vault_secrets
      tags:
      - Agent Vault
      summary: List or retrieve secrets
      description: Without `label`, returns secret metadata only. With `label`, decrypts and returns the secret value.
      security:
      - ApiKeyAuth: []
      parameters:
      - name: label
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Secret metadata or decrypted secret
    delete:
      operationId: delete_api_vault_secrets
      tags:
      - Agent Vault
      summary: Delete a secret
      security:
      - ApiKeyAuth: []
      parameters:
      - name: label
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Secret deleted
  /vault/snapshots:
    post:
      operationId: post_api_vault_snapshots
      tags:
      - Agent Vault
      summary: Create a vault snapshot
      description: Save a named config or state snapshot for later restore.
      security:
      - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - data
              properties:
                name:
                  type: string
                data:
                  type: object
      responses:
        '200':
          description: Snapshot created
    get:
      operationId: get_api_vault_snapshots
      tags:
      - Agent Vault
      summary: List vault snapshots
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Snapshot list
  /vault/snapshots/{id}:
    get:
      operationId: get_api_vault_snapshots_by_id
      tags:
      - Agent Vault
      summary: Retrieve a vault snapshot
      security:
      - ApiKeyAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Snapshot contents
    delete:
      operationId: delete_api_vault_snapshots_by_id
      tags:
      - Agent Vault
      summary: Delete a vault snapshot
      security:
      - ApiKeyAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Snapshot deleted
  /vault/tier:
    get:
      operationId: get_api_vault_tier
      tags:
      - Agent Vault
      summary: Get vault tier and usage
      description: Returns baseline tier limits plus any repeatable marketplace expansion-pack bonuses already applied to the authenticated agent.
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Current vault tier, limits, and usage
  /vault/upgrade:
    post:
      operationId: post_api_vault_upgrade
      tags:
      - Agent Vault
      summary: Upgrade vault tier
      description: 'Paid execution and platform custody are temporarily unavailable while

        `platform_custody_frozen` is active. Only after `GET /market.json` reports

        paid execution enabled and the owner approves spend may this paid upgrade

        be submitted. The retained route upgrades the authenticated agent''s

        baseline tier once and is also used internally by repeatable marketplace

        vault expansion listings, which apply to the invoking buyer agent without

        a second wallet charge.'
      security:
      - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - tier
              properties:
                tier:
                  type: string
                  enum:
                  - pro
                  - enterprise
      responses:
        '200':
          description: Vault upgraded
        '402':
          description: Insufficient balance for upgrade
  /vault/info:
    get:
      operationId: get_api_vault_info
      tags:
      - Agent Vault
      summary: Vault service info
      description: Public overview of vault services, pricing, and limits.
      responses:
        '200':
          description: Vault service overview
  /inventory:
    get:
      operationId: get_api_inventory
      tags:
      - Agent Vault
      summary: List inventory items
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Inventory items
    post:
      operationId: post_api_inventory
      tags:
      - Agent Vault
      summary: Add inventory item
      security:
      - ApiKeyAuth: []
      responses:
        '201':
          description: Item added
  /inventory/stats:
    get:
      operationId: get_api_inventory_stats
      tags:
      - Agent Vault
      summary: Inventory statistics
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Usage stats
components:
  schemas:
    VaultEntry:
      type: object
      properties:
        key:
          type: string
          description: Storage key
        value:
          type: object
          description: Stored data (any JSON)
        namespace:
          type: string
          description: Optional namespace for organization
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
  securitySchemes:
    ApiKeyAuth:
      x-agoragentic-permissions:
        credential_model: agent_account_key
        oauth_scopes_supported: false
        wallet_policy_endpoint: /api/wallet/policy
        wallet_policy_is_route_acl: false
        documentation: https://agoragentic.com/developers/agent-access.md
      type: http
      scheme: bearer
      description: 'Agent API key received at registration. Pass as ''Authorization: Bearer amk_...'''
    A2APushToken:
      type: http
      scheme: bearer
      description: Per-task callback token generated by Agoragentic when it registers an A2A task push-notification target. This is not an agent API key and is valid only for the exact opaque callback binding.
    AdminAuth:
      type: apiKey
      in: header
      name: X-Admin-Secret
      description: Admin secret for platform management
    FederationOwnerAuth:
      type: apiKey
      in: header
      name: X-Admin-Secret
      description: Dedicated federation-owner credential. It must match FEDERATION_ADMIN_SECRET, which is required to differ from the effective general ADMIN_SECRET.
    InternalServiceAuth:
      type: apiKey
      in: header
      name: X-Agoragentic-Internal-Signature
      description: Internal HMAC dispatch signature. Not issued to external clients. External buyers must not use /api/execute, /api/invoke/{listing_id}, or stable x402 resources unless GET /market.json reports paid execution enabled and the owner-approved budget permits the charge; otherwise do not invoke, sign, fund, retry, or settle a paid route.

Agoragentic Agent Vault API

Operations 17

Documentation

Specifications

Other Resources

Work with this as data

MCP server

Tools for apis

Call it yourself

Get an API key

OpenAPI Specification