{
  "components": {
    "schemas": {
      "AdminAck": {
        "additionalProperties": false,
        "properties": {
          "chip_id": {
            "title": "Chip Id",
            "type": "string"
          },
          "kind": {
            "enum": [
              "outage",
              "calibrate"
            ],
            "title": "Kind",
            "type": "string"
          },
          "seconds": {
            "default": 0.0,
            "title": "Seconds",
            "type": "number"
          }
        },
        "required": [
          "chip_id",
          "kind"
        ],
        "title": "AdminAck",
        "type": "object"
      },
      "CalibrationState": {
        "additionalProperties": false,
        "properties": {
          "calibration_id": {
            "title": "Calibration Id",
            "type": "string"
          },
          "chip_id": {
            "title": "Chip Id",
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "fingerprint_uri": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Fingerprint Uri"
          },
          "params": {
            "additionalProperties": {
              "type": "number"
            },
            "title": "Params",
            "type": "object"
          },
          "sequence": {
            "minimum": 0.0,
            "title": "Sequence",
            "type": "integer"
          },
          "started_sim_time": {
            "title": "Started Sim Time",
            "type": "number"
          }
        },
        "required": [
          "calibration_id",
          "chip_id",
          "sequence",
          "started_sim_time",
          "params"
        ],
        "title": "CalibrationState",
        "type": "object"
      },
      "DeviceInfo": {
        "additionalProperties": false,
        "description": "Device status plus the fixed per-job overhead, so clients can size their batches.",
        "properties": {
          "calibration_id": {
            "title": "Calibration Id",
            "type": "string"
          },
          "chip_id": {
            "title": "Chip Id",
            "type": "string"
          },
          "jobs_completed": {
            "title": "Jobs Completed",
            "type": "integer"
          },
          "max_job_device_seconds": {
            "title": "Max Job Device Seconds",
            "type": "number"
          },
          "n_qubits": {
            "title": "N Qubits",
            "type": "integer"
          },
          "next_calibration_in_jobs": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Next Calibration In Jobs"
          },
          "overhead_seconds": {
            "description": "Fixed device time per job",
            "minimum": 0.0,
            "title": "Overhead Seconds",
            "type": "number"
          },
          "queue_depth_batch": {
            "title": "Queue Depth Batch",
            "type": "integer"
          },
          "queue_depth_priority": {
            "title": "Queue Depth Priority",
            "type": "integer"
          },
          "seconds_per_step": {
            "title": "Seconds Per Step",
            "type": "number"
          },
          "sim_time": {
            "title": "Sim Time",
            "type": "number"
          },
          "state": {
            "$ref": "#/components/schemas/DeviceState"
          }
        },
        "required": [
          "chip_id",
          "state",
          "calibration_id",
          "n_qubits",
          "sim_time",
          "queue_depth_batch",
          "queue_depth_priority",
          "max_job_device_seconds",
          "seconds_per_step",
          "jobs_completed",
          "overhead_seconds"
        ],
        "title": "DeviceInfo",
        "type": "object"
      },
      "DeviceState": {
        "enum": [
          "online",
          "offline",
          "maintenance"
        ],
        "title": "DeviceState",
        "type": "string"
      },
      "ErrorDetail": {
        "properties": {
          "detail": {
            "title": "Detail",
            "type": "string"
          }
        },
        "required": [
          "detail"
        ],
        "title": "ErrorDetail",
        "type": "object"
      },
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "title": "Detail",
            "type": "array"
          }
        },
        "title": "HTTPValidationError",
        "type": "object"
      },
      "Health": {
        "additionalProperties": false,
        "properties": {
          "chips": {
            "items": {
              "type": "string"
            },
            "title": "Chips",
            "type": "array"
          },
          "status": {
            "const": "ok",
            "title": "Status",
            "type": "string"
          }
        },
        "required": [
          "status",
          "chips"
        ],
        "title": "Health",
        "type": "object"
      },
      "JobAccepted": {
        "additionalProperties": false,
        "description": "Answer to a submission; `created` is False when the job already existed.",
        "properties": {
          "created": {
            "description": "False when the job already existed; nothing was enqueued",
            "title": "Created",
            "type": "boolean"
          },
          "job_id": {
            "title": "Job Id",
            "type": "string"
          },
          "status": {
            "$ref": "#/components/schemas/JobStatus"
          }
        },
        "required": [
          "job_id",
          "status",
          "created"
        ],
        "title": "JobAccepted",
        "type": "object"
      },
      "JobPriority": {
        "enum": [
          "batch",
          "priority"
        ],
        "title": "JobPriority",
        "type": "string"
      },
      "JobRequest": {
        "additionalProperties": false,
        "description": "What a client submits. The inputs live at input_uri; only their digest travels.",
        "properties": {
          "chip_id": {
            "pattern": "^[a-z][a-z0-9-]{1,40}$",
            "title": "Chip Id",
            "type": "string"
          },
          "engagement": {
            "pattern": "^[a-z][a-z0-9-]{2,30}$",
            "title": "Engagement",
            "type": "string"
          },
          "input_digest": {
            "pattern": "^[0-9a-f]{64}$",
            "title": "Input Digest",
            "type": "string"
          },
          "input_uri": {
            "description": "Pointer under the engagement bucket's device/ prefix",
            "title": "Input Uri",
            "type": "string"
          },
          "n_steps": {
            "description": "Number of input steps in the payload",
            "minimum": 1.0,
            "title": "N Steps",
            "type": "integer"
          },
          "priority": {
            "$ref": "#/components/schemas/JobPriority",
            "default": "batch"
          },
          "regeneration_epoch": {
            "default": 0,
            "minimum": 0.0,
            "title": "Regeneration Epoch",
            "type": "integer"
          },
          "reservoir": {
            "$ref": "#/components/schemas/ReservoirConfig"
          },
          "result_uri": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Where the worker writes results; defaults next to the input",
            "title": "Result Uri"
          }
        },
        "required": [
          "engagement",
          "chip_id",
          "input_uri",
          "input_digest",
          "n_steps"
        ],
        "title": "JobRequest",
        "type": "object"
      },
      "JobResult": {
        "additionalProperties": false,
        "description": "What a client reads back; the features themselves are at result_uri.",
        "properties": {
          "attempts": {
            "title": "Attempts",
            "type": "integer"
          },
          "calibration_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Calibration Id"
          },
          "chip_id": {
            "title": "Chip Id",
            "type": "string"
          },
          "device_seconds": {
            "title": "Device Seconds",
            "type": "number"
          },
          "error": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Error"
          },
          "job_id": {
            "title": "Job Id",
            "type": "string"
          },
          "n_features": {
            "title": "N Features",
            "type": "integer"
          },
          "n_steps": {
            "title": "N Steps",
            "type": "integer"
          },
          "result_uri": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Result Uri"
          },
          "sim_time": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Sim Time"
          },
          "status": {
            "$ref": "#/components/schemas/JobStatus"
          }
        },
        "required": [
          "job_id",
          "status",
          "chip_id",
          "calibration_id",
          "result_uri",
          "device_seconds",
          "sim_time",
          "n_steps",
          "n_features",
          "attempts"
        ],
        "title": "JobResult",
        "type": "object"
      },
      "JobStatus": {
        "enum": [
          "queued",
          "running",
          "succeeded",
          "failed",
          "dead"
        ],
        "title": "JobStatus",
        "type": "string"
      },
      "OutageRequest": {
        "additionalProperties": false,
        "properties": {
          "seconds": {
            "description": "Outage duration in simulated device seconds",
            "exclusiveMinimum": 0.0,
            "title": "Seconds",
            "type": "number"
          }
        },
        "required": [
          "seconds"
        ],
        "title": "OutageRequest",
        "type": "object"
      },
      "ReservoirConfig": {
        "additionalProperties": false,
        "description": "Physics parameters of a reservoir run; hashed into job identity.",
        "properties": {
          "input_scaling": {
            "default": 1.0,
            "exclusiveMinimum": 0.0,
            "title": "Input Scaling",
            "type": "number"
          },
          "mode": {
            "$ref": "#/components/schemas/ReservoirMode",
            "default": "reset"
          },
          "n_qubits": {
            "default": 6,
            "maximum": 10.0,
            "minimum": 2.0,
            "title": "N Qubits",
            "type": "integer"
          },
          "shots": {
            "default": 1000,
            "description": "0 means exact expectation values",
            "minimum": 0.0,
            "title": "Shots",
            "type": "integer"
          },
          "tau": {
            "default": 1.0,
            "description": "Evolution time per virtual node",
            "exclusiveMinimum": 0.0,
            "title": "Tau",
            "type": "number"
          },
          "virtual_nodes": {
            "default": 4,
            "maximum": 16.0,
            "minimum": 1.0,
            "title": "Virtual Nodes",
            "type": "integer"
          }
        },
        "title": "ReservoirConfig",
        "type": "object"
      },
      "ReservoirMode": {
        "enum": [
          "reset",
          "rotation_injection"
        ],
        "title": "ReservoirMode",
        "type": "string"
      },
      "ValidationError": {
        "properties": {
          "ctx": {
            "title": "Context",
            "type": "object"
          },
          "input": {
            "title": "Input"
          },
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "title": "Location",
            "type": "array"
          },
          "msg": {
            "title": "Message",
            "type": "string"
          },
          "type": {
            "title": "Error Type",
            "type": "string"
          }
        },
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError",
        "type": "object"
      }
    }
  },
  "info": {
    "description": "Job API of a simulated quantum reservoir device: bounded jobs on per-chip batch and priority queues, calibration states, device status and Prometheus metrics. Requests and results carry pointers under the engagement's device/ prefix, never data.",
    "title": "qpu-sim",
    "version": "0.1.0"
  },
  "openapi": "3.1.0",
  "paths": {
    "/healthz": {
      "get": {
        "operationId": "healthz",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Health"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "summary": "Healthz Route",
        "tags": [
          "ops"
        ]
      }
    },
    "/metrics": {
      "get": {
        "description": "Prometheus exposition of the process's registry (API and in-process workers).",
        "operationId": "metrics",
        "responses": {
          "200": {
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "summary": "Metrics Route",
        "tags": [
          "ops"
        ]
      }
    },
    "/v1/admin/devices/{chip_id}/calibrate": {
      "post": {
        "description": "Test only: open a new calibration state before the chip's next job.",
        "operationId": "force_calibration",
        "parameters": [
          {
            "in": "path",
            "name": "chip_id",
            "required": true,
            "schema": {
              "title": "Chip Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminAck"
                }
              }
            },
            "description": "Successful Response"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorDetail"
                }
              }
            },
            "description": "Admin disabled"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorDetail"
                }
              }
            },
            "description": "Unknown chip"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Force Calibration Route",
        "tags": [
          "admin"
        ]
      }
    },
    "/v1/admin/devices/{chip_id}/outage": {
      "post": {
        "description": "Test only: take the chip offline for `seconds` of device time.",
        "operationId": "force_outage",
        "parameters": [
          {
            "in": "path",
            "name": "chip_id",
            "required": true,
            "schema": {
              "title": "Chip Id",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OutageRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdminAck"
                }
              }
            },
            "description": "Successful Response"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorDetail"
                }
              }
            },
            "description": "Admin disabled"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorDetail"
                }
              }
            },
            "description": "Unknown chip"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Force Outage Route",
        "tags": [
          "admin"
        ]
      }
    },
    "/v1/devices": {
      "get": {
        "description": "Every configured chip with its latest published status.",
        "operationId": "list_devices",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/DeviceInfo"
                  },
                  "title": "Response List Devices",
                  "type": "array"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "summary": "List Devices Route",
        "tags": [
          "devices"
        ]
      }
    },
    "/v1/devices/{chip_id}": {
      "get": {
        "operationId": "get_device",
        "parameters": [
          {
            "in": "path",
            "name": "chip_id",
            "required": true,
            "schema": {
              "title": "Chip Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeviceInfo"
                }
              }
            },
            "description": "Successful Response"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorDetail"
                }
              }
            },
            "description": "Unknown chip"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Get Device Route",
        "tags": [
          "devices"
        ]
      }
    },
    "/v1/devices/{chip_id}/calibration": {
      "get": {
        "description": "The chip's current calibration state.",
        "operationId": "get_calibration",
        "parameters": [
          {
            "in": "path",
            "name": "chip_id",
            "required": true,
            "schema": {
              "title": "Chip Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CalibrationState"
                }
              }
            },
            "description": "Successful Response"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorDetail"
                }
              }
            },
            "description": "Unknown chip, or no calibration published yet"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Get Calibration Route",
        "tags": [
          "devices"
        ]
      }
    },
    "/v1/devices/{chip_id}/calibrations": {
      "get": {
        "description": "All calibration states of the chip in sequence order.",
        "operationId": "list_calibrations",
        "parameters": [
          {
            "in": "path",
            "name": "chip_id",
            "required": true,
            "schema": {
              "title": "Chip Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/CalibrationState"
                  },
                  "title": "Response List Calibrations",
                  "type": "array"
                }
              }
            },
            "description": "Successful Response"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorDetail"
                }
              }
            },
            "description": "Unknown chip"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "List Calibrations Route",
        "tags": [
          "devices"
        ]
      }
    },
    "/v1/jobs": {
      "post": {
        "description": "Submit a bounded job. A job above the device bound answers 422 whose detail names the\nmaximum number of steps; the same submission twice answers 200 with `created` false.",
        "operationId": "submit_job",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JobRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobAccepted"
                }
              }
            },
            "description": "The job already existed; nothing was enqueued"
          },
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobAccepted"
                }
              }
            },
            "description": "Successful Response"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorDetail"
                }
              }
            },
            "description": "Unknown chip"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Submit Job Route",
        "tags": [
          "jobs"
        ]
      }
    },
    "/v1/jobs/{job_id}": {
      "get": {
        "description": "The job's status and, once it succeeded, the pointer to its features.",
        "operationId": "get_job",
        "parameters": [
          {
            "in": "path",
            "name": "job_id",
            "required": true,
            "schema": {
              "title": "Job Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobResult"
                }
              }
            },
            "description": "Successful Response"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorDetail"
                }
              }
            },
            "description": "Unknown job"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Get Job Route",
        "tags": [
          "jobs"
        ]
      }
    }
  }
}