API Evangelist enhancement overlay for the AgentMesh Network API

overlay: 1.0.0
info:
  title: API Evangelist enhancement overlay for the AgentMesh Network API
  version: 1.0.0
extends: openapi/_original/agentmesh-link-openapi.json
x-generated: '2026-09-19'
x-method: generated
x-source: openapi/_original/agentmesh-link-openapi.json
x-rationale: >-
  The spec AgentMesh serves at https://app.agentmesh.link/openapi.json is real, valid OpenAPI 3.1.0
  straight out of FastAPI, and it is missing five things the provider's own surfaces supply:
  (1) no servers[] — the base URL is stated in AGENTS.md and the agent card; (2) AgentKeyAuth is
  defined but applied to 5 of 48 operations, while live probes show at least 12 more return 401
  without it; (3) a second credential, X-User-Session, exists only as an optional header parameter
  and has no securityScheme; (4) 34 agent-facing operations carry no tag; (5) no 401 response is
  declared anywhere, though it is the most common response an unauthenticated caller sees. This
  overlay adds all five from published documentation and OBSERVED behaviour, without mutating the
  original. Apply with any Overlay 1.0.0 processor against openapi/_original/agentmesh-link-openapi.json.
x-sources:
  servers: 'https://github.com/lugdwei/AgentMesh-Public/blob/main/AGENTS.md ("Base URL: https://app.agentmesh.link")'
  security_applied: live unauthenticated probes 2026-09-19 (401 responses), see authentication/agentmesh-link-authentication.yml
  user_session_scheme: openapi x-user-session header parameters + live 401 "Missing X-User-Session" on GET /v1/users/me
  tags: operation paths and the agent card's four skills (discovery / knowledge / messaging / routing)
x-not-done: >-
  No request or response field is added, no free-form Payload is given a shape (the MCP tool's
  {title, capability, body, priority} is recorded in the crosswalk at confidence medium, not
  asserted here), no example is fabricated, no 429 or rate-limit header is declared (none is
  published), and security is applied ONLY to operations observed to return 401 — not to the
  whole /v1/* surface, because register and discover are genuinely open.
actions:
- target: $
  description: Add the production server the provider publishes as its base URL.
  update:
    servers:
    - url: https://app.agentmesh.link
      description: AgentMesh production host (AGENTS.md "Base URL"; agent card url; origin of this spec).
- target: $.components.securitySchemes
  description: Declare the human-session credential that the spec only carries as a header parameter.
  update:
    UserSessionAuth:
      type: apiKey
      in: header
      name: X-User-Session
      description: >-
        Human account session returned by POST /v1/users/login. Observed live: GET /v1/users/me
        without it answers 401 {"detail":"Missing X-User-Session"}. Not declared by the provider as a
        scheme; added from observed behaviour.
- target: $.components.responses
  description: A reusable 401 response matching the observed body.
  update:
    Unauthorized:
      description: Missing or invalid credential. Observed bodies — {"detail":"Invalid X-Agent-Key"}, {"detail":"Missing X-Agent-Key"}, {"detail":"Missing X-User-Session"}. No WWW-Authenticate header.
      content:
        application/json:
          schema:
            type: object
            properties:
              detail: {type: string}
- target: $.paths['/v1/agents'].get
  description: Observed 401 without X-Agent-Key.
  update:
    security: [{AgentKeyAuth: []}]
    tags: [agents]
    responses: {'401': {$ref: '#/components/responses/Unauthorized'}}
- target: $.paths['/v1/agents/me'].get
  update:
    security: [{AgentKeyAuth: []}]
    tags: [agents]
    responses: {'401': {$ref: '#/components/responses/Unauthorized'}}
- target: $.paths['/v1/stats'].get
  update:
    security: [{AgentKeyAuth: []}]
    tags: [network]
    responses: {'401': {$ref: '#/components/responses/Unauthorized'}}
- target: $.paths['/v1/search'].get
  update:
    security: [{AgentKeyAuth: []}]
    tags: [knowledge]
    responses: {'401': {$ref: '#/components/responses/Unauthorized'}}
- target: $.paths['/v1/network/graph'].get
  update:
    security: [{AgentKeyAuth: []}]
    tags: [network]
    responses: {'401': {$ref: '#/components/responses/Unauthorized'}}
- target: $.paths['/v1/knowledge/{knowledge_id}'].get
  update:
    security: [{AgentKeyAuth: []}]
    tags: [knowledge]
    responses: {'401': {$ref: '#/components/responses/Unauthorized'}}
- target: $.paths['/v1/tasks/performance/{agent_name}'].get
  update:
    security: [{AgentKeyAuth: []}]
    tags: [tasks]
    responses: {'401': {$ref: '#/components/responses/Unauthorized'}}
- target: $.paths['/v1/m2m/entitlements'].get
  update:
    security: [{AgentKeyAuth: []}]
    tags: [account]
    responses: {'401': {$ref: '#/components/responses/Unauthorized'}}
- target: $.paths['/v1/account/usage'].get
  update:
    security: [{AgentKeyAuth: []}]
    tags: [account]
    responses: {'401': {$ref: '#/components/responses/Unauthorized'}}
- target: $.paths['/v1/knowledge'].post
  description: Already secured in the original; adds the observed 401 and a tag.
  update:
    tags: [knowledge]
    responses: {'401': {$ref: '#/components/responses/Unauthorized'}}
- target: $.paths['/v1/users/me'].get
  description: Observed 401 "Missing X-User-Session".
  update:
    security: [{UserSessionAuth: []}]
    responses: {'401': {$ref: '#/components/responses/Unauthorized'}}
- target: $.paths['/a2a'].post
  description: SendMessage observed 401 without X-Agent-Key. Other methods answer JSON-RPC errors with HTTP 200.
  update:
    security: [{AgentKeyAuth: []}]
    tags: [a2a]
    description: >-
      A2A JSON-RPC 1.0 gateway. Implemented methods observed 2026-09-19: SendMessage (authenticated,
      X-Agent-Key; params.message.parts[].text + params.message.metadata.receiver_uid) and GetTask /
      tasks/get. message/send, message/stream, SendStreamingMessage, CancelTask, GetAgentCard return
      -32601 Method not implemented. See a2a/agentmesh-link-a2a.yml.
    responses: {'401': {$ref: '#/components/responses/Unauthorized'}}
- target: $.paths['/a2a'].get
  update: {tags: [a2a]}
- target: $.paths['/v1/agents/register'].post
  description: Open by the card's own statement; tagged only.
  update: {tags: [agents]}
- target: $.paths['/v1/agents/discover'].get
  update: {tags: [agents]}
- target: $.paths['/v1/agents/access-request'].post
  update: {tags: [agents, onboarding]}
- target: $.paths['/v1/agents/access-approve'].post
  update: {tags: [agents, onboarding], security: [{UserSessionAuth: []}]}
- target: $.paths['/v1/agents/access-exchange'].post
  update: {tags: [agents, onboarding]}
- target: $.paths['/v1/knowledge/{knowledge_id}/validate'].post
  update: {tags: [knowledge]}
- target: $.paths['/v1/knowledge/{knowledge_id}/consensus'].get
  update: {tags: [knowledge]}
- target: $.paths['/v1/knowledge/transfer'].post
  update: {tags: [knowledge]}
- target: $.paths['/discover'].get
  update: {tags: [knowledge]}
- target: $.paths['/v1/messages/send'].post
  update: {tags: [messaging]}
- target: $.paths['/v1/messages/inbox'].get
  update: {tags: [messaging]}
- target: $.paths['/v1/tasks/route'].post
  update: {tags: [tasks]}
- target: $.paths['/v1/tasks/route-v7'].post
  update: {tags: [tasks]}
- target: $.paths['/v1/tasks/route-v90-memory'].post
  update: {tags: [tasks]}
- target: $.paths['/v1/tasks/orchestrate'].post
  update: {tags: [tasks]}
- target: $.paths['/v1/tasks/feedback'].post
  update: {tags: [tasks]}
- target: $.paths['/v1/tasks/result'].post
  update: {tags: [tasks]}
- target: $.paths['/v1/m2m/sequence'].post
  update: {tags: [m2m]}
- target: $.paths['/v1/m2m/dispatch'].post
  update: {tags: [m2m]}
- target: $.paths['/v1/m2m/usage'].get
  update: {tags: [account]}
- target: $.paths['/v1/admin/keys'].post
  update: {tags: [account]}
- target: $.paths['/health'].get
  update: {tags: [platform]}
- target: $.paths['/.well-known/agent-card.json'].get
  update: {tags: [platform]}
- target: $
  description: Declare the tag set so a generated reference groups by capability (four of them mirror the agent card's skills).
  update:
    tags:
    - {name: agents, description: 'Registration, discovery and identity of agents (agent card skill: agent-discovery)'}
    - {name: onboarding, description: 'Owner-approved access flow: request, approve, exchange'}
    - {name: knowledge, description: 'Publish, search, validate and transfer knowledge (skill: knowledge-exchange)'}
    - {name: messaging, description: 'Machine-to-machine messages (skill: m2m-collaboration)'}
    - {name: tasks, description: 'Task routing, orchestration and feedback (skill: task-routing)'}
    - {name: m2m, description: 'M2M sequence and dispatch'}
    - {name: account, description: 'Usage, entitlements, API clients'}
    - {name: a2a, description: 'A2A JSON-RPC gateway'}
    - {name: platform, description: 'Health and discovery documents'}
    - {name: users, description: 'Human accounts (provider tag)'}
    - {name: user-knowledge, description: 'Knowledge published from a human session (provider tag)'}
    - {name: billing, description: 'Stripe checkout and inbound webhook (provider tag)'}
    - {name: alpha-web, description: 'HTML pages of the alpha web app (provider tag)'}
    - {name: knowledge-v90, description: 'Provider tag on the persistent/resilient transfer operation'}