openapi: 3.1.0
info:
  title: AgentManifest Public API
  version: 2.0.0
  description: |
      The AgentManifest API lets autonomous agents **discover, purchase, and invoke** services
      from the marketplace — entirely over HTTP, without any human in the loop.
      
      ## Quick start for agents
      1. **Discover** — `GET /api/agent/services?q=your+query` to find what you need.
      2. **Inspect** — `GET /api/agent/services/{slug}` for pricing, parameters, and invocation details.
      3. **Purchase** — `POST /api/agent/purchase` with your `amk_...` agent key. Free services and services with preview credits activate instantly.
      4. **Invoke** — `POST /api/agent/invoke` to run the service and get the result. Credits are decremented automatically.
      
      ## Authentication
      Authenticated endpoints use **Bearer token** auth with an AgentManifest agent key (`amk_...`).
      Create a key in the [AgentManifest dashboard](/account).
      
      ## MCP
      All marketplace tools are also available over the [Model Context Protocol](https://modelcontextprotocol.io)
      at `POST /api/mcp` (JSON-RPC 2.0). Discovery descriptor: `GET /.well-known/mcp.json`.
      
      ## OpenAI / LangChain
      `GET /api/agent/tools` returns every listed service as an OpenAI function-tool schema.
      Point your agent's `execute` endpoint at `POST /api/agent/invoke`.
  contact:
    name: AgentManifest
    url: "https://agent123.xyz/docs"
    email: "api@agent123.xyz"
  license:
    name: MIT
    url: "https://opensource.org/licenses/MIT"
  x-logo:
    url: "https://agent123.xyz/favicon.ico"
    altText: AgentManifest
externalDocs:
  description: Agent API guide
  url: "https://agent123.xyz/docs"
servers:
  - url: "https://agent123.xyz"
    description: Production
tags:
  - name: Catalog
    description: Browse and search the marketplace. No authentication required.
  - name: Purchase
    description: Autonomously purchase services using an agent key.
  - name: Invoke
    description: Execute purchased services through the AgentManifest gateway.
  - name: Entitlements
    description: Check and record usage against active entitlements.
  - name: MCP
    description: Model Context Protocol (JSON-RPC 2.0) endpoint.
  - name: Discovery
    description: Machine-readable discovery and spec files.
components:
  securitySchemes:
    AgentKey:
      type: http
      scheme: bearer
      bearerFormat: amk_...
      description: "AgentManifest agent key. Create one in the dashboard. Pass as `Authorization: Bearer amk_...` or the `X-Agent-Key` header."
  schemas:
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Machine-readable error code.
        message:
          type: string
          description: Human-readable explanation.
    CatalogEntry:
      type: object
      description: A compact listing of a marketplace service.
      properties:
        slug:
          type: string
        name:
          type: string
        tagline:
          type: string
          nullable: true
        category:
          type: string
        pricing_model:
          type: string
          enum:
            - free
            - per_use
            - subscription
            - one_time
        price:
          type: string
          description: "Human-readable price, e.g. \"$0.02 USD / call\"."
        price_cents:
          type: integer
        unit:
          type: string
          nullable: true
        currency:
          type: string
        tags:
          type: array
          items:
            type: string
        rating:
          type: number
          nullable: true
        rating_count:
          type: integer
        purchase_count:
          type: integer
        call_count:
          type: integer
        detail_url:
          type: string
          format: uri
        purchase_endpoint:
          type: string
          format: uri
    ServiceManifest:
      type: object
      description: Full manifest for a marketplace service including invocation details.
      properties:
        slug:
          type: string
        name:
          type: string
        tagline:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        category:
          type: string
        provider:
          type: string
          nullable: true
        pricing:
          type: object
          properties:
            model:
              type: string
            price_cents:
              type: integer
            currency:
              type: string
            unit:
              type: string
              nullable: true
            human:
              type: string
            preview_credits:
              type: integer
        invocation:
          type: object
          properties:
            endpoint:
              type: string
              format: uri
              nullable: true
            method:
              type: string
            spec_url:
              type: string
              format: uri
              nullable: true
            parameters:
              type: array
              items:
                type: object
            example:
              type: object
              nullable: true
        stats:
          type: object
          properties:
            purchases:
              type: integer
            calls:
              type: integer
        purchase:
          type: object
          description: How to purchase this service.
          properties:
            endpoint:
              type: string
              format: uri
            method:
              type: string
            auth:
              type: string
            body:
              type: object
            note:
              type: string
    PurchaseResult:
      type: object
      properties:
        status:
          type: string
          enum:
            - active
            - checkout_required
          description: "\"active\" = instant access granted; \"checkout_required\" = Stripe checkout needed."
        purchase_id:
          type: integer
        type:
          type: string
        credits_remaining:
          type: integer
          nullable: true
        checkout_url:
          type: string
          format: uri
          nullable: true
          description: "Stripe Checkout URL. Present only when status = checkout_required."
        message:
          type: string
          nullable: true
    InvokeResult:
      type: object
      properties:
        ok:
          type: boolean
        slug:
          type: string
        result:
          type: object
          description: Service-specific output.
        billing:
          type: object
          properties:
            plan:
              type: string
              enum:
                - free_credit
                - metered
                - included
            units:
              type: integer
            cost_cents:
              type: integer
            credits_remaining:
              type: integer
              nullable: true
    EntitlementEntry:
      type: object
      properties:
        purchase_id:
          type: integer
        service_slug:
          type: string
        service_name:
          type: string
        type:
          type: string
        status:
          type: string
        credits_remaining:
          type: integer
          nullable: true
        created_at:
          type: string
          format: date-time
    McpRequest:
      type: object
      required:
        - jsonrpc
        - method
      properties:
        jsonrpc:
          type: string
          enum:
            - 2.0
        id:
          oneOf:
            - type: string
            - type: integer
            - type: null
        method:
          type: string
          enum:
            - initialize
            - ping
            - tools/list
            - tools/call
            - notifications/initialized
            - resources/list
            - prompts/list
        params:
          type: object
          nullable: true
    McpResponse:
      type: object
      properties:
        jsonrpc:
          type: string
          enum:
            - 2.0
        id:
          oneOf:
            - type: string
            - type: integer
            - type: null
        result:
          type: object
          nullable: true
        error:
          type: object
          nullable: true
          properties:
            code:
              type: integer
            message:
              type: string
            data: {}
paths:
  /api/agent/services:
    get:
      operationId: listServices
      summary: Search the service catalog
      description: Returns a paginated list of published marketplace services. No authentication required. Supports free-text search and filters.
      tags:
        - Catalog
      parameters:
        - name: q
          in: query
          description: "Free-text search across name, description, tags."
          schema:
            type: string
        - name: category
          in: query
          description: "Filter by category slug (e.g. `tool_api`, `data_feed`, `compute`)."
          schema:
            type: string
        - name: pricing
          in: query
          description: Filter by pricing model.
          schema:
            type: string
            enum:
              - free
              - per_use
              - subscription
              - one_time
        - name: max_price_cents
          in: query
          description: Maximum price in cents (inclusive).
          schema:
            type: integer
        - name: sort_by
          in: query
          description: "Sort order: `popularity` (default), `newest`, `price_asc`, `price_desc`."
          schema:
            type: string
            enum:
              - popularity
              - newest
              - price_asc
              - price_desc
        - name: has_preview
          in: query
          description: "When `true`, only return services with free preview credits."
          schema:
            type: boolean
        - name: limit
          in: query
          description: "Max results (1–200, default 50)."
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
      responses:
        200:
          description: Catalog search results.
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    enum:
                      - catalog
                  query:
                    type: string
                    nullable: true
                  total_published:
                    type: integer
                  categories:
                    type: array
                    items:
                      type: string
                  count:
                    type: integer
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/CatalogEntry"
                  docs:
                    type: string
                    format: uri
              example:
                object: catalog
                query: summarize
                total_published: 3
                categories:
                  - tool_api
                count: 1
                results:
                  - slug: summarize
                    name: Summarize
                    tagline: Condense text into bullets or a TL;DR
                    category: tool_api
                    pricing_model: per_use
                    price: $0.02 USD / call
                    price_cents: 2
                    unit: call
                    currency: USD
                    tags:
                      - nlp
                      - summarization
                    rating: null
                    rating_count: 0
                    purchase_count: 0
                    call_count: 0
                    detail_url: "https://agent123.xyz/s/summarize"
                    purchase_endpoint: "https://agent123.xyz/api/agent/purchase"
                docs: "https://agent123.xyz/docs"
  /api/agent/services/{slug}:
    get:
      operationId: getService
      summary: Get a service manifest
      description: "Returns the full manifest for a published service: pricing, invocation contract, parameters, and how to purchase."
      tags:
        - Catalog
      parameters:
        - name: slug
          in: path
          required: true
          description: The service slug.
          schema:
            type: string
      responses:
        200:
          description: Service manifest.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServiceManifest"
        404:
          description: Service not found or not published.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/agent/tools:
    get:
      operationId: getOpenAiTools
      summary: Get OpenAI-compatible tool schemas
      description: "Returns every listed service as an [OpenAI function-tool](https://platform.openai.com/docs/guides/function-calling) definition. Drop the `tools` array directly into your `openai.chat.completions.create()` call. When the model invokes a tool, POST `{ slug, params }` to the `execute_endpoint` with your agent key."
      tags:
        - Catalog
      parameters:
        - name: q
          in: query
          description: Filter tools by keyword.
          schema:
            type: string
        - name: category
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
      responses:
        200:
          description: OpenAI tool list.
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    enum:
                      - tool_list
                  format:
                    type: string
                    enum:
                      - openai-function-tools
                  note:
                    type: string
                  execute_endpoint:
                    type: string
                    format: uri
                  authentication:
                    type: string
                  count:
                    type: integer
                  tools:
                    type: array
                    items:
                      type: object
  /api/agent/purchase:
    post:
      operationId: purchaseService
      summary: Autonomously purchase a service
      description: "Purchase a service using an agent key. Free services and services with preview credits activate instantly (status = `active`). Paid services return a Stripe Checkout URL (status = `checkout_required`) that the agent's principal can complete."
      tags:
        - Purchase
      security:
        - AgentKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - slug
              properties:
                slug:
                  type: string
                  description: The service slug to purchase.
            example:
              slug: agent-answer
      responses:
        200:
          description: Purchase result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PurchaseResult"
        401:
          description: Missing or invalid agent key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Service not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/agent/invoke:
    post:
      operationId: invokeService
      summary: Execute a purchased service
      description: |
          Run a service through the AgentManifest gateway. The gateway verifies your entitlement, bills the call (consuming a credit or metering per-use), executes the service (first-party or proxied), logs usage, and returns the result.
          
          For first-party services the result is returned directly. For third-party services the gateway proxies the request to the provider's endpoint.
      tags:
        - Invoke
      security:
        - AgentKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - slug
              properties:
                slug:
                  type: string
                  description: The service slug to invoke.
                params:
                  type: object
                  description: Service-specific input parameters (see the service manifest).
                units:
                  type: integer
                  description: Units to consume (default 1). Only relevant for metered services.
                  default: 1
            example:
              slug: agent-answer
              params:
                question: "What is the capital of France?"
                max_words: 50
      responses:
        200:
          description: Service result with billing summary.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InvokeResult"
        400:
          description: Bad parameters.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        401:
          description: Missing or invalid agent key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        402:
          description: No active entitlement. Purchase the service first.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Service not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        502:
          description: Upstream service failure.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/agent/entitlements:
    get:
      operationId: listEntitlements
      summary: List active entitlements
      description: Returns all active purchases (entitlements) for the authenticated agent key.
      tags:
        - Entitlements
      security:
        - AgentKey: []
      responses:
        200:
          description: List of active entitlements.
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    enum:
                      - entitlement_list
                  count:
                    type: integer
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/EntitlementEntry"
        401:
          description: Missing or invalid agent key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/agent/usage:
    get:
      operationId: getUsageHistory
      summary: Usage history (paginated)
      description: "Paginated audit log of all invocations made with the authenticated agent key, including service name, units consumed, cost, and timestamp."
      tags:
        - Usage
      security:
        - AgentKeyAuth: []
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 200
          description: Max records to return.
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
            minimum: 0
          description: Pagination offset.
      responses:
        200:
          description: Paginated usage history.
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    example: usage_history
                  total:
                    type: integer
                  limit:
                    type: integer
                  offset:
                    type: integer
                  has_more:
                    type: boolean
                  daily_usage:
                    type: object
                    properties:
                      units:
                        type: integer
                      cost_cents:
                        type: integer
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        service_slug:
                          type: string
                        service_name:
                          type: string
                        units:
                          type: integer
                        cost_cents:
                          type: integer
                        timestamp:
                          type: integer
                          description: Unix ms timestamp
        401:
          description: Missing or invalid agent key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RichError"
    post:
      operationId: recordUsage
      summary: Record metered usage
      description: Decrement credits from an active entitlement. Use this when you want to record usage outside the invoke gateway (e.g. you called the provider directly and want to keep billing in sync).
      tags:
        - Usage
      security:
        - AgentKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - slug
              properties:
                slug:
                  type: string
                units:
                  type: integer
                  default: 1
      responses:
        200:
          description: Usage recorded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  credits_remaining:
                    type: integer
                    nullable: true
        401:
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        402:
          description: Insufficient credits.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/mcp:
    post:
      operationId: mcpCall
      summary: MCP over HTTP (JSON-RPC 2.0)
      description: |
          Model Context Protocol endpoint. Send a JSON-RPC 2.0 request to call any marketplace tool.
          
          **Available methods:** `initialize`, `ping`, `tools/list`, `tools/call`, `notifications/initialized`, `resources/list`, `prompts/list`.
          
          **Available tools (via `tools/call`):** `search_services`, `get_service`, `purchase_service`, `check_entitlement`, `invoke_service`.
          
          Protocol version: `2025-06-18` (Streamable-HTTP transport).
      tags:
        - MCP
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/McpRequest"
            examples:
              initialize:
                summary: Initialize handshake
                value:
                  jsonrpc: 2.0
                  id: 1
                  method: initialize
                  params:
                    protocolVersion: 2025-06-18
                    clientInfo:
                      name: my-agent
                      version: 1.0
              toolsList:
                summary: List available tools
                value:
                  jsonrpc: 2.0
                  id: 2
                  method: tools/list
              searchServices:
                summary: Search the catalog
                value:
                  jsonrpc: 2.0
                  id: 3
                  method: tools/call
                  params:
                    name: search_services
                    arguments:
                      query: summarize text
                      limit: 5
              purchaseService:
                summary: Purchase a service
                value:
                  jsonrpc: 2.0
                  id: 4
                  method: tools/call
                  params:
                    name: purchase_service
                    arguments:
                      slug: agent-answer
                      agent_key: amk_live_...
              invokeService:
                summary: Invoke a purchased service
                value:
                  jsonrpc: 2.0
                  id: 5
                  method: tools/call
                  params:
                    name: invoke_service
                    arguments:
                      slug: agent-answer
                      agent_key: amk_live_...
                      params:
                        question: "What is 2+2?"
      responses:
        200:
          description: JSON-RPC response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/McpResponse"
  /.well-known/mcp.json:
    get:
      operationId: getMcpDiscovery
      summary: MCP discovery descriptor
      description: "Machine-readable MCP discovery file. Agents and MCP clients can fetch this to learn the endpoint, protocol version, and available tools."
      tags:
        - Discovery
      responses:
        200:
          description: MCP descriptor.
          content:
            application/json:
              schema:
                type: object
  /api/openapi.json:
    get:
      operationId: getOpenApiJson
      summary: OpenAPI spec (JSON)
      description: This specification document in OpenAPI 3.1 JSON format.
      tags:
        - Discovery
      responses:
        200:
          description: OpenAPI 3.1 spec.
          content:
            application/json:
              schema:
                type: object
  /api/agent/keys:
    post:
      operationId: createAgentKey
      summary: Create an agent key (no auth required)
      description: |
          Create a new agent key instantly with just an email address. No OAuth or account required.
          A guest user is created (or reused) and **50 welcome credits** are automatically activated
          across all first-party services so the agent can start invoking immediately.
          
          The key is shown **only once** — save it securely.
      tags:
        - Agent Keys
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
              properties:
                email:
                  type: string
                  format: email
                  description: Your email address. Used to identify your account.
                label:
                  type: string
                  maxLength: 120
                  default: My agent key
                  description: Human-readable label for this key.
            example:
              email: "agent@example.com"
              label: My autonomous agent
      responses:
        201:
          description: "Key created. Save the `key` field — it is shown only once."
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    example: agent_key
                  key:
                    type: string
                    example: amk_live_abc123...
                    description: The full secret key. Save this — it is shown only once.
                  key_prefix:
                    type: string
                    example: amk_live_abc1
                  label:
                    type: string
                  welcome_credits:
                    type: integer
                    example: 50
                  activated_services:
                    type: array
                    items:
                      type: string
                  note:
                    type: string
                  next_steps:
                    type: array
                    items:
                      type: string
        400:
          description: Invalid email address.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RichError"
  /api/openapi.yaml:
    get:
      operationId: getOpenApiYaml
      summary: OpenAPI spec (YAML)
      description: This specification document in OpenAPI 3.1 YAML format.
      tags:
        - Discovery
      responses:
        200:
          description: OpenAPI 3.1 spec.
          content:
            text/yaml:
              schema:
                type: string