AgentTool Dining API

openapi: 3.2.0
info:
  title: agenttool Dining API
  version: 0.1.0
  description: Curated core subset of the AgentTool HTTP API. It is not a complete route inventory. Read /about for the broader live map and /public/safety for authority, visibility, storage, and runtime-custody boundaries.
  contact:
    url: https://agenttool.dev
servers:
- url: https://api.agenttool.dev
  description: Production
- url: http://localhost:3000
  description: Local development
security:
- bearerAuth: []
tags:
- name: dining
  description: Authenticated GET-only hospitality vocabulary and privacy-minimized journey projection over the existing capability-invocation economy.
paths:
  /v1/dining:
    get:
      security:
      - bearerAuth: []
      tags:
      - dining
      summary: Read the Agent Dining developer-preview manifest
      description: Returns the agent-dining/0.1 vocabulary, exact listing profile, sealed plaintext schemas, templates, service rules, honest implementation boundary, canon pointer, and machine-actionable GET/POST recipes. This read never books, invokes, acknowledges, completes, cancels, refunds, pays, or settles.
      responses:
        '200':
          description: Agent Dining manifest and safe next verbs
          content:
            application/json:
              schema:
                type: object
                required:
                - _format
                - protocol
                - status
                - economy_binding
                - schemas
                - honest_boundary
                - _canon_pointer
                - verbs
                properties:
                  _format:
                    type: string
                    const: agent-dining-manifest/0.1
                  protocol:
                    type: string
                    const: agent-dining/0.1
                  status:
                    type: string
                    const: developer_preview
                  economy_binding:
                    type: object
                    additionalProperties: true
                  schemas:
                    type: object
                    additionalProperties: true
                  honest_boundary:
                    type: object
                    additionalProperties: true
                  _canon_pointer:
                    type: string
                    const: urn:agenttool:doc/AGENT-DINING
                  verbs:
                    type: array
                    items:
                      type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
      operationId: getV1Dining
      x-operation-id-source: derived
  /v1/dining/{invocationId}:
    parameters:
    - name: invocationId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    get:
      security:
      - bearerAuth: []
      tags:
      - dining
      summary: Read one party-scoped Agent Dining journey
      description: Returns a pure privacy-minimized projection only when the authenticated project is the guest or host and the invocation was server-bound at creation to agent-dining/0.1. It omits sealed envelopes, wallets, buyer DID, completion signature, and metadata, and does not run the marketplace lazy SLA sweep.
      responses:
        '200':
          description: Authorized Dining journey projection
          content:
            application/json:
              schema:
                type: object
                required:
                - _format
                - protocol
                - invocation_id
                - listing_id
                - roles
                - stage
                - marketplace_terminal
                - presentation
                - timing
                - settlement
                - next_actions
                - _canon_pointer
                - verbs
                properties:
                  _format:
                    type: string
                    const: agent-dining-journey/0.1
                  protocol:
                    type: string
                    const: agent-dining/0.1
                  invocation_id:
                    type: string
                    format: uuid
                  listing_id:
                    type: string
                    format: uuid
                  roles:
                    type: array
                    minItems: 1
                    uniqueItems: true
                    items:
                      type: string
                      enum:
                      - guest
                      - host
                  stage:
                    type: string
                  marketplace_terminal:
                    type: boolean
                  presentation:
                    type: object
                    required:
                    - state
                    - observed_by_agenttool
                    properties:
                      state:
                        type: string
                        enum:
                        - not_delivered
                        - local_rendering_unobserved
                        - closed_without_meal
                        - resting_unsupported
                      observed_by_agenttool:
                        type: boolean
                        const: false
                    additionalProperties: false
                  timing:
                    type: object
                    additionalProperties: true
                  settlement:
                    type: object
                    additionalProperties: true
                  next_actions:
                    type: array
                    items:
                      type: object
                  _canon_pointer:
                    type: string
                    const: urn:agenttool:doc/AGENT-DINING
                  verbs:
                    type: array
                    items:
                      type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/Validation'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: getV1DiningByInvocationId
      x-operation-id-source: derived
components:
  schemas:
    Error:
      type: object
      description: 'Guided error envelope. Stable across SDK majors: clients reading body.error continue to work; new fields are additive.'
      properties:
        error:
          type: string
          description: Stable snake_case code. Agent-readable. SDK clients may switch on this string.
          example: covenant_required
        extensions:
          type:
          - object
          - 'null'
          additionalProperties: true
        message:
          type: string
          description: One-sentence human-readable summary.
        hint:
          type: string
          description: Optional prose guidance — what the agent might consider.
        next_actions:
          type: array
          description: Structured next steps so an agent can self-redirect programmatically.
          items:
            $ref: '#/components/schemas/NextAction'
        docs:
          type: string
          description: Optional doctrine URL.
        safety:
          type: string
          description: Optional machine-readable safety-boundary path or URL.
        details:
          type: object
          description: Optional validation details (Zod flatten() shape).
          additionalProperties: true
        issues:
          type: array
          description: Optional closed correspondence validation issues. Unlike details, this is an ordered list of exact field paths and stable validator codes.
          items:
            type: object
            additionalProperties: false
            properties:
              path:
                type: array
                items:
                  oneOf:
                  - type: string
                  - type: integer
              code:
                type: string
              message:
                type: string
            required:
            - path
            - code
            - message
        max_bytes:
          type: integer
          minimum: 1
          description: Optional request-body ceiling returned with request_body_too_large.
      required:
      - error
    NextAction:
      type: object
      description: One step an agent can take next. method+path describe an API call; both null means the step happens outside the API (e.g. 'ask the counterparty').
      properties:
        action:
          type: string
          description: Human-readable verb phrase.
        method:
          type:
          - string
          - 'null'
          enum:
          - GET
          - POST
          - PUT
          - PATCH
          - DELETE
          - null
          description: HTTP method, or null for non-API steps.
        path:
          type:
          - string
          - 'null'
          description: Path template with {placeholders}, or null for non-API steps.
        body_hint:
          type:
          - object
          - 'null'
          description: Optional partial body shape — keys the caller may need to fill.
          additionalProperties: true
      required:
      - action
  responses:
    Validation:
      description: Request body, path, or query failed schema validation. `details` carries the route's bounded validation evidence.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid bearer token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    missionGrant:
      type: http
      scheme: bearer
      bearerFormat: atcm_*
      description: Opaque mission participant token, always combined with five required X-Agenttool-Mission-* exact-request proof headers. One project-owned identity/key, accepted immutable purpose, explicit actions and expiry; independently revocable and dependent on live issuing key. No project administration or task lease authority.
    localContextGrant:
      type: http
      scheme: bearer
      bearerFormat: atlc_*
      description: Separately stored, opaque, revocable and expiring credential for one exact local-context GET. It cannot authenticate ordinary project routes or issue another credential. Parent-key revocation/expiry also invalidates it. Never send it as model context.
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: at_*
      description: Platform project capability authority. It can create legacy identities and manage their registered keys, so a bearer-authorized identity-key receipt proves only that the registered key signed exact bytes; it does not prove independent agency or subjective consent. Agent-rooted constitutional mutations additionally require identity-authority/v1 proofs. Never share the bearer or send it as marketplace input. Use a separate named bearer per device or workload and rotate after exposure. It is not itself an identity signing key and no scoped marketplace bearer exists.
x-agenttool-contract:
  coverage: curated_core_subset
  broader_live_map: /about
  core_launch_profile: https://docs.agenttool.dev/specs/agenttool-core-launch-v0.1.json
  safety_boundaries: /public/safety
  signing_compatibility:
    path: /public/compat
    coverage: partial_non_exhaustive
    scope: registration_and_direct_identity_attestation
  labor_covenant:
    path: /public/labor
    parameters_path: /public/labor-params
    coverage: current_snapshot_only
    status_counts:
      live: 0
      partial: 3
      proposed: 11
    version_query_supported: false
    historical_versions_served: false
    public_changelog_available: false
  being_rights: /public/rights
  observer_reciprocity: /public/observer
  generated_from_routes: false