openapi: 3.1.0
info:
  title: Synthetic Order Status Review API
  version: 1.0.0
  summary: A fictional API contract prepared for the public API-to-Agent case.
  description: >-
    This specification contains invented entities, paths, and examples. No live
    server, private schema, enterprise permission model, or customer record is
    represented.
servers:
  - url: https://orders.example.invalid
    description: Reserved non-resolving example host; no service is deployed.
tags:
  - name: Orders
    description: Read-only order status retrieval.
  - name: Decisions
    description: Human-confirmed review decisions.
  - name: Audit
    description: Reviewable event receipts.
paths:
  /v1/orders:
    get:
      operationId: listOrders
      tags: [Orders]
      summary: List synthetic order-status records
      parameters:
        - name: status
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/OrderStatus'
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
      responses:
        '200':
          description: A page of synthetic order records.
          content:
            application/json:
              schema:
                type: object
                required: [items, nextCursor]
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Order'
                  nextCursor:
                    type: [string, 'null']
              example:
                items:
                  - orderId: SYN-ORD-1007
                    accountName: Cedar Vale Workshop
                    status: needs_review
                    amount: 48200
                    currency: USD
                    updatedAt: '2026-08-01T14:30:00Z'
                nextCursor: null
  /v1/orders/{orderId}:
    get:
      operationId: getOrder
      tags: [Orders]
      summary: Retrieve one synthetic order and its evidence
      parameters:
        - $ref: '#/components/parameters/OrderId'
      responses:
        '200':
          description: Synthetic order record found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderDetail'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/orders/{orderId}/review-decisions:
    post:
      operationId: createReviewDecision
      tags: [Decisions]
      summary: Record a human-confirmed review decision
      description: >-
        The caller must first prepare a dry run and obtain a confirmation ID
        from the human reviewer. The API never infers confirmation.
      parameters:
        - $ref: '#/components/parameters/OrderId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReviewDecisionInput'
      responses:
        '201':
          description: Decision receipt created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionReceipt'
        '400':
          description: Confirmation ID, decision, or reason is missing.
  /v1/audit-events:
    get:
      operationId: listAuditEvents
      tags: [Audit]
      summary: List synthetic decision receipts
      parameters:
        - name: orderId
          in: query
          required: false
          schema:
            type: string
            pattern: '^SYN-ORD-[0-9]{4}$'
      responses:
        '200':
          description: Audit events, newest first.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AuditEvent'
components:
  parameters:
    OrderId:
      name: orderId
      in: path
      required: true
      schema:
        type: string
        pattern: '^SYN-ORD-[0-9]{4}$'
      example: SYN-ORD-1007
  schemas:
    OrderStatus:
      type: string
      enum: [draft, needs_review, cleared, returned]
    Order:
      type: object
      additionalProperties: false
      required: [orderId, accountName, status, amount, currency, updatedAt]
      properties:
        orderId:
          type: string
        accountName:
          type: string
        status:
          $ref: '#/components/schemas/OrderStatus'
        amount:
          type: number
          minimum: 0
        currency:
          type: string
          enum: [USD, EUR, GBP]
        updatedAt:
          type: string
          format: date-time
    OrderDetail:
      allOf:
        - $ref: '#/components/schemas/Order'
        - type: object
          required: [evidence, reviewState]
          properties:
            evidence:
              type: array
              items:
                type: object
                additionalProperties: false
                required: [evidenceId, label, value]
                properties:
                  evidenceId:
                    type: string
                  label:
                    type: string
                  value:
                    type: string
            reviewState:
              type: object
              additionalProperties: false
              required: [systemRecommendation, humanDecision]
              properties:
                systemRecommendation:
                  type: string
                humanDecision:
                  type: [string, 'null']
    ReviewDecisionInput:
      type: object
      additionalProperties: false
      required: [decision, reason, confirmationId, dryRun]
      properties:
        decision:
          type: string
          enum: [accept, modify, return]
        reason:
          type: string
          minLength: 8
        confirmationId:
          type: string
          description: Identifier explicitly supplied after human confirmation.
        dryRun:
          type: boolean
          description: True previews a receipt; false records the confirmed decision.
    DecisionReceipt:
      type: object
      additionalProperties: false
      required: [receiptId, orderId, decision, recordedAt, dryRun]
      properties:
        receiptId:
          type: string
        orderId:
          type: string
        decision:
          type: string
        recordedAt:
          type: string
          format: date-time
        dryRun:
          type: boolean
    AuditEvent:
      type: object
      additionalProperties: false
      required: [eventId, orderId, actorType, action, recordedAt]
      properties:
        eventId:
          type: string
        orderId:
          type: string
        actorType:
          type: string
          enum: [human, agent]
        action:
          type: string
        recordedAt:
          type: string
          format: date-time
  responses:
    NotFound:
      description: Synthetic order ID was not found.