{
  "openapi": "3.0.1",
  "info": {
    "title": "Enterprise Public API",
    "description": "The Enterprise Public API.",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://dev.shc-integration.co.uk/public",
      "description": "Public API"
    }
  ],
  "paths": {
    "/v1/reference-data/{listName}": {
      "get": {
        "tags": [
          "ReferenceData"
        ],
        "summary": "Get the values of a named choice list",
        "description": "Returns the choices (code + label pairs) for the named choice list.\nInternal numeric identifiers and platform-specific field names are\nimplementation details and are intentionally omitted from the response.",
        "operationId": "ReferenceData-GetChoiceList-Get",
        "parameters": [
          {
            "name": "listName",
            "in": "path",
            "description": "camelCase identifier of the choice list. Case-sensitive exact match\nagainst the catalogue.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The named choice list.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/responseEnvelope_getChoiceListResponse"
                },
                "example": {
                  "data": {
                    "name": "string",
                    "scope": "string",
                    "choices": [
                      {
                        "code": "string",
                        "label": "string"
                      }
                    ],
                    "catalogueVersion": "string",
                    "catalogueGeneratedAt": "string"
                  },
                  "meta": {
                    "requestId": "string",
                    "timestamp": "string",
                    "apiVersion": "string",
                    "warnings": [
                      {
                        "code": "string",
                        "message": "string"
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request was malformed. For this API, typically caused by a `listName`\npath segment that does not match the required pattern.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/problemDetails"
                },
                "example": {
                  "type": "string",
                  "title": "string",
                  "status": 0,
                  "detail": "string",
                  "instance": "string",
                  "code": "string",
                  "errors": [
                    {
                      "field": "string",
                      "code": "string",
                      "message": "string"
                    }
                  ]
                }
              }
            }
          },
          "404": {
            "description": "The requested choice list is not present in the catalogue. The response\nbody does not enumerate the available list names (no information leakage).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/problemDetails"
                },
                "example": {
                  "type": "string",
                  "title": "string",
                  "status": 0,
                  "detail": "string",
                  "instance": "string",
                  "code": "string",
                  "errors": [
                    {
                      "field": "string",
                      "code": "string",
                      "message": "string"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "An unhandled server-side error occurred.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/problemDetails"
                },
                "example": {
                  "type": "string",
                  "title": "string",
                  "status": 0,
                  "detail": "string",
                  "instance": "string",
                  "code": "string",
                  "errors": [
                    {
                      "field": "string",
                      "code": "string",
                      "message": "string"
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/reference-data": {
      "get": {
        "tags": [
          "ReferenceData"
        ],
        "summary": "List available choice lists (manifest)",
        "description": "Returns a lightweight manifest of every choice list available in the\ncatalogue. Clients call `GET /v1/reference-data/{listName}` to retrieve\nthe choices themselves.",
        "operationId": "ReferenceData-ListChoiceLists-Get",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Manifest of available choice lists.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/responseEnvelope_listChoiceListsResponse"
                },
                "example": {
                  "data": {
                    "items": [
                      {
                        "name": "string",
                        "scope": "string",
                        "choiceCount": 0
                      }
                    ],
                    "catalogueVersion": "string",
                    "catalogueGeneratedAt": "string"
                  },
                  "meta": {
                    "requestId": "string",
                    "timestamp": "string",
                    "apiVersion": "string",
                    "warnings": [
                      {
                        "code": "string",
                        "message": "string"
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "An unhandled server-side error occurred.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/problemDetails"
                },
                "example": {
                  "type": "string",
                  "title": "string",
                  "status": 0,
                  "detail": "string",
                  "instance": "string",
                  "code": "string",
                  "errors": [
                    {
                      "field": "string",
                      "code": "string",
                      "message": "string"
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "tags": [
          "Health"
        ],
        "summary": "Health check.",
        "description": "Health check.",
        "operationId": "Health-Get",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Payload of HealthReportResponse",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/healthReportResponse"
                },
                "example": {
                  "status": "string",
                  "entries": {}
                }
              }
            }
          },
          "500": {
            "description": "Payload of ProblemDetails",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/problemDetails"
                },
                "example": {
                  "type": "string",
                  "title": "string",
                  "status": 0,
                  "detail": "string",
                  "instance": "string",
                  "code": "string",
                  "errors": [
                    {
                      "field": "string",
                      "code": "string",
                      "message": "string"
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/webhooks/carbone/{callbackReference}": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Receive a rendering provider callback",
        "description": "Receives the rendering provider's completion notification and passes it to the Document Generation Adapter, which decides whether it is genuine. Nothing is verified, parsed or logged here.",
        "operationId": "Webhooks-Carbone-Callback",
        "parameters": [
          {
            "name": "callbackReference",
            "in": "path",
            "description": "The reference this platform issued to the provider for this render.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "Authorization",
            "in": "header",
            "description": "The per-render secret this platform issued. Forwarded unread. It is not a bearer token, despite the header.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "description": "The provider's callback message, forwarded unparsed.",
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "404": {
            "description": "The adapter refused the callback. Unknown, wrong, expired and used are deliberately indistinguishable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/problemDetails"
                },
                "example": {
                  "type": "string",
                  "title": "string",
                  "status": 0,
                  "detail": "string",
                  "instance": "string",
                  "code": "string",
                  "errors": [
                    {
                      "field": "string",
                      "code": "string",
                      "message": "string"
                    }
                  ]
                }
              }
            }
          },
          "422": {
            "description": "Payload of ProblemDetails",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/problemDetails"
                },
                "example": {
                  "type": "string",
                  "title": "string",
                  "status": 0,
                  "detail": "string",
                  "instance": "string",
                  "code": "string",
                  "errors": [
                    {
                      "field": "string",
                      "code": "string",
                      "message": "string"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Payload of ProblemDetails",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/problemDetails"
                },
                "example": {
                  "type": "string",
                  "title": "string",
                  "status": 0,
                  "detail": "string",
                  "instance": "string",
                  "code": "string",
                  "errors": [
                    {
                      "field": "string",
                      "code": "string",
                      "message": "string"
                    }
                  ]
                }
              }
            }
          },
          "503": {
            "description": "Payload of ProblemDetails",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/problemDetails"
                },
                "example": {
                  "type": "string",
                  "title": "string",
                  "status": 0,
                  "detail": "string",
                  "instance": "string",
                  "code": "string",
                  "errors": [
                    {
                      "field": "string",
                      "code": "string",
                      "message": "string"
                    }
                  ]
                }
              }
            }
          },
          "204": {
            "description": "The adapter accepted the callback."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "choiceListSummaryResponse": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "scope": {
            "type": "string"
          },
          "choiceCount": {
            "type": "integer",
            "format": "int32"
          }
        }
      },
      "choiceResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "label": {
            "type": "string"
          }
        }
      },
      "getChoiceListResponse": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "scope": {
            "type": "string"
          },
          "choices": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/choiceResponse"
            }
          },
          "catalogueVersion": {
            "type": "string"
          },
          "catalogueGeneratedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "healthReportEntryResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "data": {
            "type": "object",
            "additionalProperties": {
              "type": "object"
            }
          }
        }
      },
      "healthReportResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string"
          },
          "entries": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/healthReportEntryResponse"
            }
          }
        }
      },
      "listChoiceListsResponse": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/choiceListSummaryResponse"
            }
          },
          "catalogueVersion": {
            "type": "string"
          },
          "catalogueGeneratedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "problemDetailError": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "problemDetails": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "detail": {
            "type": "string"
          },
          "instance": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/problemDetailError"
            }
          }
        }
      },
      "responseEnvelope_getChoiceListResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/getChoiceListResponse"
          },
          "meta": {
            "$ref": "#/components/schemas/responseMeta"
          }
        }
      },
      "responseEnvelope_listChoiceListsResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/listChoiceListsResponse"
          },
          "meta": {
            "$ref": "#/components/schemas/responseMeta"
          }
        }
      },
      "responseMeta": {
        "type": "object",
        "properties": {
          "requestId": {
            "type": "string",
            "description": "Correlation identifier for the response, equal to the inbound `Correlation-Id` when supplied or server-generated otherwise."
          },
          "timestamp": {
            "type": "string",
            "description": "Server-side generation time of the response (ISO 8601 UTC).",
            "format": "date-time"
          },
          "apiVersion": {
            "type": "string",
            "description": "Semantic version of the API producing the response."
          },
          "warnings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/responseWarning"
            },
            "description": "Non-fatal advisories returned alongside a successful response."
          }
        }
      },
      "responseWarning": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}