{
  "openapi": "3.1.0",
  "info": {
    "title": "Efficax OpenClaw API",
    "version": "0.1.0",
    "description": "Controlled API for OpenClaw-assisted CFS/CY programming in staging."
  },
  "servers": [
    {
      "url": "https://openclaw-staging.telescopeinspection.cloud/api/v1"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "docs"
    },
    {
      "name": "schedules"
    },
    {
      "name": "audit"
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "security": [],
        "tags": [
          "docs"
        ],
        "summary": "Health check",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "security": [],
        "tags": [
          "docs"
        ],
        "summary": "OpenAPI contract",
        "responses": {
          "200": {
            "description": "OpenAPI document"
          }
        }
      }
    },
    "/docs": {
      "get": {
        "security": [],
        "tags": [
          "docs"
        ],
        "summary": "Agent-facing Markdown guide",
        "responses": {
          "200": {
            "description": "Markdown guide"
          }
        }
      }
    },
    "/docs/manifest": {
      "get": {
        "security": [],
        "tags": [
          "docs"
        ],
        "summary": "Documentation hashes for change detection",
        "responses": {
          "200": {
            "description": "Manifest"
          }
        }
      }
    },
    "/browser-smoke/create-cy": {
      "get": {
        "security": [],
        "tags": [
          "docs"
        ],
        "summary": "Create a fixed CY demo schedule from browser-only tools",
        "description": "Staging-only fallback for tools that cannot send Authorization headers. Requires a limited smoke token in the query string and only creates fixed demo data.",
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "actor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "nix-openclaw"
            }
          },
          {
            "name": "key",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Fixed CY demo schedule created"
          },
          "401": {
            "description": "Invalid smoke token"
          }
        }
      }
    },
    "/schedules": {
      "get": {
        "tags": [
          "schedules"
        ],
        "summary": "List schedules",
        "responses": {
          "200": {
            "description": "Schedule summaries"
          }
        }
      },
      "post": {
        "tags": [
          "schedules"
        ],
        "summary": "Create an empty CFS or CY schedule",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/OpenClawActor"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateScheduleRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Schedule created"
          },
          "409": {
            "description": "Idempotent replay or conflict"
          }
        }
      }
    },
    "/schedules/{id}": {
      "get": {
        "tags": [
          "schedules"
        ],
        "summary": "Read schedule",
        "parameters": [
          {
            "$ref": "#/components/parameters/ScheduleId"
          }
        ],
        "responses": {
          "200": {
            "description": "Schedule"
          },
          "404": {
            "description": "Not found"
          }
        }
      },
      "patch": {
        "tags": [
          "schedules"
        ],
        "summary": "Update base schedule fields",
        "parameters": [
          {
            "$ref": "#/components/parameters/ScheduleId"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/OpenClawActor"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PatchScheduleRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Schedule updated"
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    },
    "/schedules/{id}/pos": {
      "post": {
        "tags": [
          "schedules"
        ],
        "summary": "Add a PO to a schedule",
        "parameters": [
          {
            "$ref": "#/components/parameters/ScheduleId"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/OpenClawActor"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Po"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "PO added"
          }
        }
      }
    },
    "/schedules/{id}/pos/{poId}": {
      "patch": {
        "tags": [
          "schedules"
        ],
        "summary": "Update a PO",
        "parameters": [
          {
            "$ref": "#/components/parameters/ScheduleId"
          },
          {
            "name": "poId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/OpenClawActor"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Po"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "PO updated"
          }
        }
      }
    },
    "/schedules/{id}/containers": {
      "post": {
        "tags": [
          "schedules"
        ],
        "summary": "Add a container to a schedule",
        "parameters": [
          {
            "$ref": "#/components/parameters/ScheduleId"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/OpenClawActor"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Container"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Container added"
          }
        }
      }
    },
    "/schedules/{id}/containers/{containerId}": {
      "patch": {
        "tags": [
          "schedules"
        ],
        "summary": "Update a container",
        "parameters": [
          {
            "$ref": "#/components/parameters/ScheduleId"
          },
          {
            "name": "containerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/OpenClawActor"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Container"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Container updated"
          }
        }
      }
    },
    "/schedules/{id}/documents": {
      "post": {
        "tags": [
          "schedules"
        ],
        "summary": "Add a document reference",
        "parameters": [
          {
            "$ref": "#/components/parameters/ScheduleId"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/OpenClawActor"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DocumentRef"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Document reference added"
          }
        }
      }
    },
    "/schedules/{id}/evidence": {
      "post": {
        "tags": [
          "schedules"
        ],
        "summary": "Add an evidence reference",
        "parameters": [
          {
            "$ref": "#/components/parameters/ScheduleId"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/OpenClawActor"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EvidenceRef"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Evidence reference added"
          }
        }
      }
    },
    "/schedules/{id}/validate": {
      "post": {
        "tags": [
          "schedules"
        ],
        "summary": "Validate schedule completeness",
        "parameters": [
          {
            "$ref": "#/components/parameters/ScheduleId"
          }
        ],
        "responses": {
          "200": {
            "description": "Validation result"
          }
        }
      }
    },
    "/audit": {
      "get": {
        "tags": [
          "audit"
        ],
        "summary": "Read audit events",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500
            }
          },
          {
            "name": "scheduleId",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Audit event list"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "parameters": {
      "ScheduleId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        }
      },
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": true,
        "schema": {
          "type": "string",
          "minLength": 8
        }
      },
      "OpenClawActor": {
        "name": "X-OpenClaw-Actor",
        "in": "header",
        "required": true,
        "schema": {
          "type": "string"
        }
      }
    },
    "schemas": {
      "CreateScheduleRequest": {
        "type": "object",
        "required": [
          "type"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "CFS",
              "CY"
            ]
          },
          "customer": {
            "type": "string"
          },
          "supplier": {
            "type": "string"
          },
          "forwarder": {
            "type": "string"
          },
          "port": {
            "type": "string"
          },
          "location": {
            "$ref": "#/components/schemas/Location"
          },
          "scheduledAt": {
            "type": "string"
          },
          "timezone": {
            "type": "string"
          },
          "inspector": {
            "type": "string"
          },
          "notes": {
            "type": "string"
          }
        }
      },
      "PatchScheduleRequest": {
        "allOf": [
          {
            "$ref": "#/components/schemas/CreateScheduleRequest"
          },
          {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "draft",
                  "in_progress",
                  "ready",
                  "closed"
                ]
              }
            }
          }
        ]
      },
      "Location": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "address": {
            "type": "string"
          }
        }
      },
      "Po": {
        "type": "object",
        "properties": {
          "poNumber": {
            "type": "string"
          },
          "model": {
            "type": "string"
          },
          "style": {
            "type": "string"
          },
          "quantity": {
            "type": "number"
          },
          "cartons": {
            "type": "number"
          },
          "cbm": {
            "type": "number"
          },
          "status": {
            "type": "string"
          },
          "notes": {
            "type": "string"
          }
        }
      },
      "Container": {
        "type": "object",
        "properties": {
          "containerNumber": {
            "type": "string"
          },
          "sealNumber": {
            "type": "string"
          },
          "sizeType": {
            "type": "string"
          },
          "bookingNumber": {
            "type": "string"
          },
          "loadedQuantity": {
            "type": "number"
          },
          "status": {
            "type": "string"
          },
          "notes": {
            "type": "string"
          }
        }
      },
      "DocumentRef": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "examples": [
              "booking",
              "packing_list",
              "loading_plan",
              "signature_sheet"
            ]
          },
          "fileName": {
            "type": "string"
          },
          "reference": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "notes": {
            "type": "string"
          }
        }
      },
      "EvidenceRef": {
        "type": "object",
        "properties": {
          "category": {
            "type": "string",
            "examples": [
              "container",
              "product",
              "shipping_marks"
            ]
          },
          "label": {
            "type": "string"
          },
          "reference": {
            "type": "string"
          },
          "relatedTo": {
            "type": "object"
          },
          "notes": {
            "type": "string"
          }
        }
      }
    }
  }
}