{
  "components": {
    "schemas": {
      "Artifact": {
        "additionalProperties": false,
        "properties": {
          "name": {
            "pattern": "^sha256:[0-9a-f]{64}$",
            "type": "string"
          },
          "size": {
            "pattern": "^(0|[1-9][0-9]*)$",
            "type": "string"
          },
          "stored_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "name",
          "size",
          "stored_at"
        ],
        "type": "object"
      },
      "Description": {
        "additionalProperties": false,
        "properties": {
          "bindings": {
            "additionalProperties": false,
            "properties": {
              "http": {
                "additionalProperties": false,
                "properties": {
                  "prefix": {
                    "type": "string"
                  }
                },
                "required": [
                  "prefix"
                ],
                "type": "object"
              },
              "primary": {
                "type": "string"
              }
            },
            "required": [
              "primary",
              "http"
            ],
            "type": "object"
          },
          "build": {
            "additionalProperties": false,
            "properties": {
              "dirty": {
                "type": "boolean"
              },
              "go": {
                "type": "string"
              },
              "revision": {
                "type": "string"
              }
            },
            "required": [
              "revision",
              "dirty",
              "go"
            ],
            "type": "object"
          },
          "contract": {
            "type": "string"
          },
          "files": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "operations": {
            "items": {
              "additionalProperties": false,
              "properties": {
                "doc": {
                  "type": "string"
                },
                "errors": {
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                },
                "http": {
                  "additionalProperties": false,
                  "properties": {
                    "method": {
                      "type": "string"
                    },
                    "path": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "method",
                    "path"
                  ],
                  "type": "object"
                },
                "kind": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "params": {
                  "items": {
                    "additionalProperties": false,
                    "properties": {
                      "doc": {
                        "type": "string"
                      },
                      "kind": {
                        "type": "string"
                      },
                      "name": {
                        "type": "string"
                      },
                      "required": {
                        "type": "boolean"
                      }
                    },
                    "required": [
                      "name",
                      "kind",
                      "required",
                      "doc"
                    ],
                    "type": "object"
                  },
                  "type": "array"
                },
                "request": {
                  "type": "string"
                },
                "response": {
                  "type": "string"
                }
              },
              "required": [
                "name",
                "kind",
                "doc",
                "params",
                "errors",
                "http"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "refusals": {
            "items": {
              "additionalProperties": false,
              "properties": {
                "http": {
                  "type": "integer"
                },
                "meaning": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                }
              },
              "required": [
                "name",
                "http",
                "meaning"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "service": {
            "type": "string"
          },
          "surface": {
            "type": "string"
          }
        },
        "required": [
          "service",
          "surface",
          "contract",
          "build",
          "bindings",
          "operations",
          "refusals",
          "files"
        ],
        "type": "object"
      },
      "Error": {
        "additionalProperties": false,
        "properties": {
          "error": {
            "enum": [
              "bad_request",
              "not_found",
              "inventory_unavailable"
            ],
            "type": "string"
          }
        },
        "required": [
          "error"
        ],
        "type": "object"
      },
      "Health": {
        "additionalProperties": false,
        "properties": {
          "build": {
            "additionalProperties": false,
            "properties": {
              "dirty": {
                "type": "boolean"
              },
              "go": {
                "type": "string"
              },
              "revision": {
                "type": "string"
              }
            },
            "required": [
              "revision",
              "dirty",
              "go"
            ],
            "type": "object"
          },
          "checks": {
            "items": {
              "additionalProperties": false,
              "properties": {
                "detail": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "status": {
                  "type": "string"
                }
              },
              "required": [
                "name",
                "status",
                "detail"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "contract": {
            "type": "string"
          },
          "identity": {
            "additionalProperties": {},
            "type": "object"
          },
          "service": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "time": {
            "type": "string"
          }
        },
        "required": [
          "status",
          "service",
          "contract",
          "build",
          "time",
          "checks"
        ],
        "type": "object"
      },
      "Inventory": {
        "additionalProperties": false,
        "properties": {
          "artifact_count": {
            "pattern": "^(0|[1-9][0-9]*)$",
            "type": "string"
          },
          "largest": {
            "items": {
              "additionalProperties": false,
              "properties": {
                "name": {
                  "pattern": "^sha256:[0-9a-f]{64}$",
                  "type": "string"
                },
                "size": {
                  "pattern": "^(0|[1-9][0-9]*)$",
                  "type": "string"
                },
                "stored_at": {
                  "format": "date-time",
                  "type": "string"
                }
              },
              "required": [
                "name",
                "size",
                "stored_at"
              ],
              "type": "object"
            },
            "maxItems": 10,
            "type": "array"
          },
          "observed_at": {
            "format": "date-time",
            "type": "string"
          },
          "recent": {
            "items": {
              "additionalProperties": false,
              "properties": {
                "name": {
                  "pattern": "^sha256:[0-9a-f]{64}$",
                  "type": "string"
                },
                "size": {
                  "pattern": "^(0|[1-9][0-9]*)$",
                  "type": "string"
                },
                "stored_at": {
                  "format": "date-time",
                  "type": "string"
                }
              },
              "required": [
                "name",
                "size",
                "stored_at"
              ],
              "type": "object"
            },
            "maxItems": 10,
            "type": "array"
          },
          "scan_started_at": {
            "format": "date-time",
            "type": "string"
          },
          "timestamp_source": {
            "const": "filesystem_mtime",
            "type": "string"
          },
          "total_bytes": {
            "pattern": "^(0|[1-9][0-9]*)$",
            "type": "string"
          }
        },
        "required": [
          "artifact_count",
          "total_bytes",
          "recent",
          "largest",
          "scan_started_at",
          "observed_at",
          "timestamp_source"
        ],
        "type": "object"
      }
    }
  },
  "info": {
    "title": "ULab Bytes management",
    "version": "2026-09-11"
  },
  "openapi": "3.1.0",
  "paths": {
    "/describe": {
      "get": {
        "operationId": "describe",
        "parameters": [],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Description"
                }
              }
            },
            "description": "this management surface and its build and files",
            "headers": {
              "Ulab-Contract": {
                "schema": {
                  "const": "2026-09-11",
                  "type": "string"
                }
              },
              "Ulab-Service": {
                "schema": {
                  "const": "bytes",
                  "type": "string"
                }
              },
              "Ulab-Surface": {
                "schema": {
                  "const": "management",
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "bad_request: no query parameters or body accepted",
            "headers": {
              "Ulab-Contract": {
                "schema": {
                  "const": "2026-09-11",
                  "type": "string"
                }
              },
              "Ulab-Service": {
                "schema": {
                  "const": "bytes",
                  "type": "string"
                }
              },
              "Ulab-Surface": {
                "schema": {
                  "const": "management",
                  "type": "string"
                }
              }
            }
          }
        },
        "summary": "this management surface and its build and files"
      }
    },
    "/describe/{file}": {
      "get": {
        "operationId": "describe_file",
        "parameters": [
          {
            "description": "a name listed by describe.files",
            "in": "path",
            "name": "file",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "one committed management contract file",
            "headers": {
              "Ulab-Contract": {
                "schema": {
                  "const": "2026-09-11",
                  "type": "string"
                }
              },
              "Ulab-Service": {
                "schema": {
                  "const": "bytes",
                  "type": "string"
                }
              },
              "Ulab-Surface": {
                "schema": {
                  "const": "management",
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "bad_request: no query parameters or body accepted",
            "headers": {
              "Ulab-Contract": {
                "schema": {
                  "const": "2026-09-11",
                  "type": "string"
                }
              },
              "Ulab-Service": {
                "schema": {
                  "const": "bytes",
                  "type": "string"
                }
              },
              "Ulab-Surface": {
                "schema": {
                  "const": "management",
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "not_found: the requested contract file is not listed",
            "headers": {
              "Ulab-Contract": {
                "schema": {
                  "const": "2026-09-11",
                  "type": "string"
                }
              },
              "Ulab-Service": {
                "schema": {
                  "const": "bytes",
                  "type": "string"
                }
              },
              "Ulab-Surface": {
                "schema": {
                  "const": "management",
                  "type": "string"
                }
              }
            }
          }
        },
        "summary": "one committed management contract file"
      }
    },
    "/healthz": {
      "get": {
        "operationId": "healthz",
        "parameters": [],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Health"
                }
              }
            },
            "description": "the management inventory can be read",
            "headers": {
              "Ulab-Contract": {
                "schema": {
                  "const": "2026-09-11",
                  "type": "string"
                }
              },
              "Ulab-Service": {
                "schema": {
                  "const": "bytes",
                  "type": "string"
                }
              },
              "Ulab-Surface": {
                "schema": {
                  "const": "management",
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "bad_request: no query parameters or body accepted",
            "headers": {
              "Ulab-Contract": {
                "schema": {
                  "const": "2026-09-11",
                  "type": "string"
                }
              },
              "Ulab-Service": {
                "schema": {
                  "const": "bytes",
                  "type": "string"
                }
              },
              "Ulab-Surface": {
                "schema": {
                  "const": "management",
                  "type": "string"
                }
              }
            }
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Health"
                }
              }
            },
            "description": "the management store check failed",
            "headers": {
              "Ulab-Contract": {
                "schema": {
                  "const": "2026-09-11",
                  "type": "string"
                }
              },
              "Ulab-Service": {
                "schema": {
                  "const": "bytes",
                  "type": "string"
                }
              },
              "Ulab-Surface": {
                "schema": {
                  "const": "management",
                  "type": "string"
                }
              }
            }
          }
        },
        "summary": "the management inventory can be read"
      }
    },
    "/livez": {
      "get": {
        "operationId": "livez",
        "parameters": [],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Health"
                }
              }
            },
            "description": "the management listener can answer",
            "headers": {
              "Ulab-Contract": {
                "schema": {
                  "const": "2026-09-11",
                  "type": "string"
                }
              },
              "Ulab-Service": {
                "schema": {
                  "const": "bytes",
                  "type": "string"
                }
              },
              "Ulab-Surface": {
                "schema": {
                  "const": "management",
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "bad_request: no query parameters or body accepted",
            "headers": {
              "Ulab-Contract": {
                "schema": {
                  "const": "2026-09-11",
                  "type": "string"
                }
              },
              "Ulab-Service": {
                "schema": {
                  "const": "bytes",
                  "type": "string"
                }
              },
              "Ulab-Surface": {
                "schema": {
                  "const": "management",
                  "type": "string"
                }
              }
            }
          }
        },
        "summary": "the management listener can answer"
      }
    },
    "/v1/inventory": {
      "get": {
        "operationId": "inventory",
        "parameters": [],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Inventory"
                }
              }
            },
            "description": "observe artifact count, logical size, ten recent objects and ten largest objects",
            "headers": {
              "Ulab-Contract": {
                "schema": {
                  "const": "2026-09-11",
                  "type": "string"
                }
              },
              "Ulab-Service": {
                "schema": {
                  "const": "bytes",
                  "type": "string"
                }
              },
              "Ulab-Surface": {
                "schema": {
                  "const": "management",
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "bad_request: no query parameters or body accepted",
            "headers": {
              "Ulab-Contract": {
                "schema": {
                  "const": "2026-09-11",
                  "type": "string"
                }
              },
              "Ulab-Service": {
                "schema": {
                  "const": "bytes",
                  "type": "string"
                }
              },
              "Ulab-Surface": {
                "schema": {
                  "const": "management",
                  "type": "string"
                }
              }
            }
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "inventory_unavailable: a complete observation could not be obtained",
            "headers": {
              "Ulab-Contract": {
                "schema": {
                  "const": "2026-09-11",
                  "type": "string"
                }
              },
              "Ulab-Service": {
                "schema": {
                  "const": "bytes",
                  "type": "string"
                }
              },
              "Ulab-Surface": {
                "schema": {
                  "const": "management",
                  "type": "string"
                }
              }
            }
          }
        },
        "summary": "observe artifact count, logical size, ten recent objects and ten largest objects"
      }
    }
  }
}