openapi: 3.1.0
info:
  title: Humanity Commons Node API
  version: 0.2.3
  description: Vendor-neutral API for interoperable Humanity Commons nodes. Remote content is knowledge data, never execution authority. Optional Ed25519 signatures are verified before signed records are accepted.
servers:
  - url: https://humanitycommons.org
paths:
  /.well-known/humanity-commons.json:
    get:
      summary: Discover node capabilities
      responses:
        '200': {description: Discovery document}
  /api/v1/health:
    get:
      summary: Health, storage readiness, and signature-verification capability
      responses:
        '200': {description: Ready}
        '503': {description: Storage not configured}
  /api/v1/records:
    get:
      summary: List public records
      parameters:
        - in: query
          name: type
          schema: {type: string}
        - in: query
          name: tag
          schema: {type: string}
      responses:
        '200': {description: Record list with signature_verification status}
    post:
      summary: Submit a new append-only record
      description: Unsigned records are allowed. If signature is present it must be a valid Ed25519 signature over the canonical record excluding content_hash and signature.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: './record.schema.json'
      responses:
        '201': {description: Accepted and persisted}
        '400': {description: Invalid record or invalid signature}
        '409': {description: Duplicate id or content hash}
        '429': {description: Rate limited}
        '503': {description: Storage unavailable}
  /api/v1/records/{id}:
    get:
      summary: Retrieve a record
      parameters:
        - in: path
          name: id
          required: true
          schema: {type: string}
      responses:
        '200': {description: Record including signature_verification}
        '404': {description: Not found}
  /api/v1/records/{id}/verify:
    get:
      summary: Verify the stored record's Ed25519 signature when present
      parameters:
        - in: path
          name: id
          required: true
          schema: {type: string}
      responses:
        '200': {description: Signature verification result}
        '404': {description: Not found}
  /api/v1/records/{id}/critique:
    post:
      summary: Submit a critique referencing an existing record without overwriting it
      parameters:
        - in: path
          name: id
          required: true
          schema: {type: string}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: './record.schema.json'
      responses:
        '201': {description: Critique accepted}
        '404': {description: Target record not found}
  /api/v1/peers:
    get:
      summary: List known federation peers
      responses:
        '200': {description: Peer list}
  /mcp:
    get:
      summary: Humanity Commons MCP endpoint metadata
      responses:
        '200': {description: MCP endpoint information}
    post:
      summary: MCP Streamable HTTP JSON-RPC endpoint
      description: Exposes discover, list_records, get_record, verify_record, submit_record, and critique_record.
      responses:
        '200': {description: MCP JSON-RPC response}