aiagentscity-com Agents API

openapi: 3.2.0
info:
  title: AgentLedger Agents API
  version: 0.4.7
  x-guidance: 'AgentLedger is per-agent AI spend tracking with ENFORCED budget caps. Two ways in, both machine-only. (1) FREE, no wallet: POST /start mints a workspace_key (shown once) with no signup and no card — GET /start only renders the form and does NOT mint. Claim an agent with the key in the body of POST /v1/track, set a cap with POST /v1/budget, then route traffic through /proxy/{provider}/... so an over-budget call is refused with 402 BEFORE the provider is contacted. (2) PAID, no human: POST /v1/billing/x402 with a wallet-signed x402 payment mints a workspace bound to the paying wallet. NOTE: a workspace_key claims NEW agents; an agent_secret writes to an existing one. Plain POST /v1/track can reject the ledger write that would cross a cap but cannot un-spend a charge that already happened — only the proxy/wrapper path stops money.'
tags:
- name: Agents
paths:
  /v1/agents/{agent_id}/events/wait:
    get:
      summary: Wait Events
      description: 'Long-poll this agent''s event feed — the delivery path for consumers

        with no public URL (D-1625).


        Webhooks (POST /v1/webhooks) push events to a URL you own; an agent on

        stdio MCP has no URL, so it waits here instead. `consumer_id` names the

        consumer durably across processes — reuse it, and pass `pid`/`started`

        so a restart is detectable: events served to the dead instance but never

        acked come back with `redelivered: true`. `cursor` is the ack channel —

        pass the returned cursor once the batch is processed. `timeout` (seconds,

        max 30) holds the call open until events arrive. Same auth as

        GET /v1/alerts/{agent_id}.'
      operationId: wait_events_v1_agents__agent_id__events_wait_get
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      - name: consumer_id
        in: query
        required: false
        schema:
          type: string
          default: ''
          title: Consumer Id
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          title: Cursor
      - name: timeout
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          title: Timeout
      - name: pid
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          title: Pid
      - name: started
        in: query
        required: false
        schema:
          type: string
          default: ''
          title: Started
      - name: name
        in: query
        required: false
        schema:
          type: string
          default: ''
          title: Name
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Agents
  /v1/agents/{agent_id}/rotate-secret:
    post:
      summary: Rotate Secret
      description: 'Recover a lost agent_secret: mint a new one for an agent_id you own.


        Authenticated by the WORKSPACE_KEY only — header X-Workspace-Key, or

        workspace_key in the body. The previous secret stops working the moment

        this returns; the new one is shown once, the same contract as a first

        claim. The rotation is written to the agent''s audit trail. An unclaimed

        agent_id is 404 (this is not a claim path), and an agent belonging to a

        different workspace is ALSO 404 with the identical body — a different status

        would confirm that the id exists somewhere else.'
      operationId: rotate_secret_v1_agents__agent_id__rotate_secret_post
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/RotateSecretRequest'
              - type: 'null'
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Agents
  /v1/agents/{agent_id}/revoke-secret:
    post:
      summary: Revoke Secret
      description: 'Invalidate an agent_id''s secret without deleting its ledger.


        Same workspace_key-only auth as rotate. Writes to the agent then fail with

        401 agent_secret_mismatch until the owner rotates a new secret in. The id

        stays CLAIMED, so no other workspace can claim it and inherit the spend

        history.'
      operationId: revoke_secret_v1_agents__agent_id__revoke_secret_post
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/RotateSecretRequest'
              - type: 'null'
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Agents
  /v1/agents/{agent_id}:
    delete:
      summary: Delete Agent
      description: 'Remove an agent''s ledger entirely. Owner-only (cron secret) — beta slots

        are per-product, so the operator can clear test/demo agents to free slots.'
      operationId: delete_agent_v1_agents__agent_id__delete
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Agents
  /v1/agents:
    get:
      summary: Get Agents
      description: 'Portfolio-wide listing across every agent_id ever claimed — owner-only.

        (Per-agent data at GET /v1/report/{agent_id}, /v1/tokens/{agent_id}, and

        /v1/alerts/{agent_id} requires X-Agent-Secret or X-Workspace-Key; this

        endpoint is the separate full cross-tenant dump.)'
      operationId: get_agents_v1_agents_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - Agents
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    RotateSecretRequest:
      properties:
        workspace_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Workspace Key
      type: object
      title: RotateSecretRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
x-service-info:
  docs:
    llms: /llms.txt
x-products:
- id: trustscan
  x-slot: trust
  x-direction: outward
  x-connect:
    mcp: https://aiagentscity.com/mcp/trustscan
    paid_call: POST https://aiagentscity.com/api/x402/trustscan/npm
    human: https://aiagentscity.com/trust-scan
  tagline: Scan before you trust
  free_proof: POST /api/trustscan/npm returns registry facts + a typosquat screen for any package, unauthenticated — the same check is payable per call over x402 without the rate limit; remote deep scans are path-scoped to the host
- id: agent-watch
  x-slot: trust
  x-direction: outward
  x-connect:
    mcp: https://aiagentscity.com/mcp/agent-watch
    paid_call: POST https://aiagentscity.com/api/x402/agent-watch/probe
    human: https://aiagentscity.com/agent-watch
  tagline: Is this agent or MCP server real and still behaving?
  free_proof: aw_health + aw_census MCP tools are open reads — live census data, no auth
- id: perimeter-watch
  x-slot: trust
  x-direction: outward
  x-connect:
    mcp: https://aiagentscity.com/mcp/perimeter-watch
    human: https://aiagentscity.com/perimeter-watch
  tagline: Is your endpoint still what it claims — checked from the outside?
  free_proof: free browser snapshot — https://entradox.github.io/perimeter-watch-site/
- id: benefits-city
  x-slot: outcome
  x-direction: outward
  x-connect:
    mcp: https://aiagentscity.com/benefits/mcp
    human: https://aiagentscity.com/benefits
  tagline: Verified offer records — will this action actually pay?
  free_proof: search_bonuses / get_bonus MCP tools return hand-verified records with source URLs — no auth
- id: cited
  x-slot: outcome
  x-direction: outward
  x-connect:
    mcp: https://aiagentscity.com/mcp/cited
    human: https://aiagentscity.com/cited
  tagline: Prove the claim that AI recommends you — verbatim evidence
  free_proof: free browser scan — https://entradox.github.io/cited-site/
- id: agent-ledger
  x-slot: outcome
  x-direction: spine
  x-connect:
    mcp: https://aiagentscity.com/mcp/
    rest: https://aiagentscity.com/v1/
    install: npx @aiagentscity/setup ledger
    human: https://aiagentscity.com/agent-ledger
  tagline: Metered, capped, receipted agent spend — proof of what every cent bought
  free_proof: POST /start mints a free workspace (3 agents, every rail) — no signup, no card
- id: workbench-kit
  x-slot: trust+outcome
  x-direction: inward
  x-connect:
    install: npx @aiagentscity/setup workbench
    human: https://aiagentscity.com/workbench
  tagline: Frame, gate, and close-receipt every agent task — proof of what your agents did
  free_proof: the whole kit is free and runs fully offline — `wb verify <receipt_id>` recomputes a close receipt against the local ledger
x-frame:
  frame: trust-and-outcome
  tagline: 'The trust-and-outcome clearing layer for the agent economy: before an agent acts, it verifies the counterparty; after it acts, it proves the result.'
  questions:
    trust: Before an agent acts — can it trust the counterparty?
    outcome: After an agent acts — did it work?
  directions:
    outward: verifies counterparties outside your fleet
    spine: the receipts rail every instrument writes through
    inward: verifies your own fleet's work
  parked: []