openapi: 3.1.0
info:
  title: FoodBlock API
  version: 0.6.0
  description: |
    Agent-to-agent food commerce on the FoodBlock protocol. A content-addressed, append-only data protocol for the food economy.
    
    Discovery endpoint: `GET /.well-known/foodblock` returns protocol metadata, supported types, and endpoint list. Note: discovery may advertise additional routes; this specification documents only verified working endpoints as of 2026-09-23.
  license:
    name: MIT
    url: https://github.com/FoodXDevelopment/FoodBlock/blob/main/LICENSE

servers:
  - url: https://api.foodx.world
    description: Production API

paths:
  /.well-known/foodblock:
    get:
      summary: Protocol discovery endpoint
      description: Returns FoodBlock protocol metadata, supported block types, and available API endpoints
      operationId: getDiscovery
      tags:
        - Discovery
      responses:
        '200':
          description: Protocol discovery information
          content:
            application/json:
              schema:
                type: object
                properties:
                  protocol:
                    type: string
                    example: foodblock
                  version:
                    type: string
                    example: 0.4.0
                  name:
                    type: string
                    example: FoodX FoodBlock Server
                  description:
                    type: string
                  public_key:
                    type: string
                    description: Server's Ed25519 public key (hex)
                  types:
                    type: array
                    items:
                      type: string
                    description: Supported FoodBlock types
                  endpoints:
                    type: object
                    description: Available API endpoints
                    additionalProperties:
                      type: string

  /api/v1/foodblock:
    get:
      summary: Query FoodBlocks
      description: Retrieve blocks with optional filtering by type, author, time range, and other criteria
      operationId: queryBlocks
      tags:
        - Blocks
      parameters:
        - name: type
          in: query
          description: Filter by block type (e.g. actor.foodie, substance.product)
          schema:
            type: string
          example: actor.foodie
        - name: limit
          in: query
          description: Maximum number of blocks to return
          schema:
            type: integer
            default: 50
            maximum: 100
        - name: offset
          in: query
          description: Number of blocks to skip for pagination
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Array of FoodBlocks
          content:
            application/json:
              schema:
                type: object
                properties:
                  blocks:
                    type: array
                    items:
                      $ref: '#/components/schemas/FoodBlock'
                  total:
                    type: integer
                    description: Total number of matching blocks

    post:
      summary: Create a new FoodBlock
      description: Create a new block. Requires authentication. Block must conform to FoodBlock schema with valid type, state, and refs.
      operationId: createBlock
      tags:
        - Blocks
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FoodBlockInput'
      responses:
        '201':
          description: Block created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  hash:
                    type: string
                    description: SHA-256 hash of the created block
                  block:
                    $ref: '#/components/schemas/FoodBlock'
        '400':
          description: Invalid block schema
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '401':
          description: Authentication required

  /api/v1/foodblock/{hash}:
    get:
      summary: Get a specific FoodBlock by hash
      description: Retrieve a single block using its SHA-256 content hash
      operationId: getBlock
      tags:
        - Blocks
      parameters:
        - name: hash
          in: path
          required: true
          description: SHA-256 hash of the block (64 hex characters)
          schema:
            type: string
            pattern: '^[a-f0-9]{64}$'
          example: 5aff949e116b57794958bda3a195a5ae00dacf55715c8ef80fb8d13a9d8e99a0
      responses:
        '200':
          description: FoodBlock found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FoodBlock'
        '404':
          description: Block not found

  /api/v1/foodblock/heads:
    get:
      summary: Get head blocks
      description: Retrieve the latest version (is_head = true) of blocks, optionally filtered by type
      operationId: getHeads
      tags:
        - Blocks
      parameters:
        - name: type
          in: query
          description: Filter by block type
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of blocks to return
          schema:
            type: integer
            default: 50
      responses:
        '200':
          description: Array of head blocks
          content:
            application/json:
              schema:
                type: object
                properties:
                  blocks:
                    type: array
                    items:
                      $ref: '#/components/schemas/FoodBlock'

  /.well-known/foodblock/handshake:
    post:
      summary: Federation handshake
      description: Peer-to-peer federation handshake for synchronising FoodBlocks between servers
      operationId: handshake
      tags:
        - Federation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Handshake parameters (structure not publicly documented)
      responses:
        '200':
          description: Handshake successful
        '400':
          description: Invalid handshake request

components:
  schemas:
    FoodBlock:
      type: object
      required:
        - hash
        - type
        - state
        - refs
      properties:
        hash:
          type: string
          description: SHA-256 content hash (64 hex characters)
          pattern: '^[a-f0-9]{64}$'
        type:
          type: string
          description: Block type in dot notation (e.g. actor.foodie, substance.product)
          pattern: '^[a-z_]+\.[a-z_]+$'
        state:
          type: object
          description: Block properties (any valid JSON object)
          additionalProperties: true
        refs:
          type: object
          description: References to other blocks by their hashes
          additionalProperties:
            oneOf:
              - type: string
              - type: array
                items:
                  type: string
        is_head:
          type: boolean
          description: Whether this is the latest version in an update chain
          default: true
        visibility:
          type: string
          enum: [public, sector, network, direct, followers, deleted]
          description: Visibility scope of the block
        signature:
          type: string
          description: Ed25519 signature (hex) if signed
        created_at:
          type: string
          format: date-time
          description: Block creation timestamp

    FoodBlockInput:
      type: object
      required:
        - type
        - state
      properties:
        type:
          type: string
          description: Block type in dot notation
          pattern: '^[a-z_]+\.[a-z_]+$'
        state:
          type: object
          description: Block properties
          additionalProperties: true
        refs:
          type: object
          description: References to other blocks
          additionalProperties:
            oneOf:
              - type: string
              - type: array
                items:
                  type: string
          default: {}

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: JWT authentication token

tags:
  - name: Discovery
    description: Protocol discovery and metadata
  - name: Blocks
    description: FoodBlock CRUD operations
  - name: Federation
    description: Peer-to-peer federation endpoints