{
  "openapi": "3.1.0",
  "info": {
    "title": "OpenAPI definition",
    "version": "v0"
  },
  "servers": [
    {
      "url": "http://localhost:8080",
      "description": "Generated server url"
    }
  ],
  "tags": [
    {
      "name": "Prior Authority",
      "description": "Create, update and submit prior-authority requests to the Legal Aid Agency, via a create-draft -\u003e update-draft -\u003e upload-documents -\u003e submit lifecycle."
    }
  ],
  "paths": {
    "/prior-authorities/{priorAuthorityId}": {
      "get": {
        "tags": [
          "Prior Authority"
        ],
        "summary": "Retrieve an existing prior-authority request (draft or submitted)",
        "operationId": "getPriorAuthority",
        "parameters": [
          {
            "name": "priorAuthorityId",
            "in": "path",
            "description": "ID of the prior authority to return.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Prior authority returned.",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/PriorAuthorityResponse"
                }
              }
            }
          },
          "404": {
            "description": "Prior authority not found."
          }
        }
      },
      "put": {
        "tags": [
          "Prior Authority"
        ],
        "summary": "Update an existing prior-authority draft",
        "operationId": "updateDraft",
        "parameters": [
          {
            "name": "priorAuthorityId",
            "in": "path",
            "description": "ID of the prior authority to update.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PriorAuthorityDraft"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "Draft updated."
          },
          "404": {
            "description": "Prior authority not found."
          }
        }
      }
    },
    "/prior-authorities": {
      "post": {
        "tags": [
          "Prior Authority"
        ],
        "summary": "Create a prior-authority draft",
        "description": "Starts a new prior-authority draft.",
        "operationId": "createDraft",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PriorAuthorityDraft"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Draft created. Location header contains the prior-authority URL.",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/PriorAuthorityIdResponse"
                }
              }
            }
          },
          "400": {
            "description": "applicationId missing."
          }
        }
      }
    },
    "/prior-authorities/{priorAuthorityId}/submit": {
      "post": {
        "tags": [
          "Prior Authority"
        ],
        "summary": "Submit an in-progress prior-authority request",
        "description": "Locks the draft and forwards the submission to the Access Data Store for validation.",
        "operationId": "submit",
        "parameters": [
          {
            "name": "priorAuthorityId",
            "in": "path",
            "description": "ID of the prior authority to submit.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Request accepted. Location header contains the submission URL.",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/PriorAuthorityApplicationResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation failed"
          },
          "409": {
            "description": "Not in a submittable state"
          }
        }
      }
    },
    "/prior-authorities/{priorAuthorityId}/documents": {
      "post": {
        "tags": [
          "Prior Authority"
        ],
        "summary": "Upload a supporting document",
        "description": "Accepts a multipart/form-data file upload from the frontend and returns the uploaded file\u0027s metadata. The document is uploaded without a category; use the PATCH endpoint to assign one afterwards.",
        "operationId": "uploadDocument",
        "parameters": [
          {
            "name": "priorAuthorityId",
            "in": "path",
            "description": "ID of the prior authority.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "File to upload."
                  }
                },
                "required": [
                  "file"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "File accepted.",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/UploadedDocument"
                }
              }
            }
          },
          "400": {
            "description": "No file supplied or file is empty."
          },
          "404": {
            "description": "Prior authority not found in the access data store."
          },
          "409": {
            "description": "The access data store rejected the document as a conflict."
          },
          "413": {
            "description": "File exceeds the configured maximum size."
          },
          "415": {
            "description": "Unsupported file type."
          },
          "502": {
            "description": "The access data store failed to store the document."
          }
        }
      }
    },
    "/prior-authorities/{priorAuthorityId}/documents/{documentId}": {
      "delete": {
        "tags": [
          "Prior Authority"
        ],
        "summary": "Delete an uploaded document",
        "description": "Removes a supporting evidence document from a prior-authority draft.",
        "operationId": "deleteDocument",
        "parameters": [
          {
            "name": "priorAuthorityId",
            "in": "path",
            "description": "ID of the prior authority.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "documentId",
            "in": "path",
            "description": "ID of the document to delete.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Document deleted from prior authority draft."
          },
          "404": {
            "description": "Prior authority or document not found."
          }
        }
      },
      "patch": {
        "tags": [
          "Prior Authority"
        ],
        "summary": "Categorise an uploaded document",
        "description": "Assigns a document type to a previously uploaded supporting document.",
        "operationId": "updateDocumentType",
        "parameters": [
          {
            "name": "priorAuthorityId",
            "in": "path",
            "description": "ID of the prior authority.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "documentId",
            "in": "path",
            "description": "ID of the document to categorise.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdatePriorAuthorityDocumentTypeRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Document category updated.",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/PriorAuthorityDocumentTypeUpdateResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid document type."
          },
          "404": {
            "description": "Prior authority or document not found."
          }
        }
      }
    },
    "/expertTypes": {
      "get": {
        "tags": [
          "expert-type-controller"
        ],
        "summary": "List the expert types available for a matter type",
        "description": "Sourced from the Legal Framework API. Returns an empty list when the matter type has no associated expert types, including when it is not a recognised matter type code.",
        "operationId": "getExpertTypes",
        "parameters": [
          {
            "name": "matterType",
            "in": "query",
            "description": "Matter type code, e.g. KPBLW",
            "required": false,
            "schema": {
              "type": "string",
              "default": "KPBLW"
            },
            "example": "KPBLW"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/applications": {
      "get": {
        "tags": [
          "applications-controller"
        ],
        "operationId": "getApplications",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 1
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 10
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "APPLICATION_GRANTED",
              "description": "The status of an application",
              "enum": [
                "APPLICATION_SUBMITTED",
                "APPLICATION_GRANTED",
                "APPLICATION_REFUSED"
              ]
            }
          },
          {
            "name": "laaReference",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "clientFirstName",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "clientLastName",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ApplicationSummaryResponse"
                }
              }
            }
          }
        }
      }
    },
    "/applications/{applicationId}": {
      "get": {
        "tags": [
          "applications-controller"
        ],
        "operationId": "getApplicationById",
        "parameters": [
          {
            "name": "applicationId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ApplicationSummary"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Apportionment": {
        "type": "object",
        "description": "How the expert\u0027s costs are shared with other parties. Present when costsSharedWithOtherParties is true; omitted when it is false.",
        "properties": {
          "partiesSharingCosts": {
            "type": "integer",
            "format": "int32",
            "description": "Total number of parties sharing the costs, including the client.",
            "example": 4,
            "minimum": 2
          },
          "clientShareAmount": {
            "type": "number",
            "description": "The client\u0027s share of the costs, in GBP.",
            "example": 31.25
          }
        },
        "required": [
          "clientShareAmount",
          "partiesSharingCosts"
        ]
      },
      "CounselDetails": {
        "type": "object",
        "description": "The counsel requested. Required when priorAuthorityType is COUNSEL.",
        "properties": {
          "counselType": {
            "type": "string",
            "description": "Type of counsel being applied for.",
            "enum": [
              "KINGS_COUNSEL_ALONE",
              "TWO_JUNIOR_COUNSEL",
              "KINGS_COUNSEL_AND_JUNIOR_COUNSEL",
              "KINGS_COUNSEL_AND_TWO_JUNIOR_COUNSEL"
            ],
            "example": "KINGS_COUNSEL_ALONE"
          }
        },
        "required": [
          "counselType"
        ]
      },
      "DisbursementDetails": {
        "type": "object",
        "description": "The disbursement requested. Required when priorAuthorityType is DISBURSEMENT.",
        "properties": {
          "disbursementPurpose": {
            "type": "string",
            "description": "What the disbursement is for.",
            "example": "Travel"
          },
          "disbursementAmount": {
            "type": "number",
            "description": "Cost of the disbursement in GBP, exclusive of VAT.",
            "example": 125.5
          }
        },
        "required": [
          "disbursementAmount",
          "disbursementPurpose"
        ]
      },
      "ExpertCosts": {
        "type": "object",
        "description": "What the expert will cost, how they will be billed, and how the costs are shared.",
        "properties": {
          "billingType": {
            "type": "string",
            "description": "Whether the expert is billed hourly or at a flat rate.",
            "enum": [
              "HOURLY",
              "FIXED_RATE"
            ],
            "example": "HOURLY"
          },
          "hourlyRate": {
            "type": "number",
            "description": "Hourly rate in GBP. Required when billingType is HOURLY.",
            "example": 50.0
          },
          "timeRequested": {
            "$ref": "#/components/schemas/TimeRequested",
            "description": "Time requested. Required when billingType is HOURLY."
          },
          "totalAmount": {
            "type": "number",
            "description": "Amount requested in GBP. For HOURLY billing this is hourlyRate x (hours + minutes / 60); for FIXED_RATE it is the flat fee entered by the provider.",
            "example": 125.0
          },
          "costsSharedWithOtherParties": {
            "type": "boolean",
            "description": "Whether the expert\u0027s costs are shared with other parties.",
            "example": true
          },
          "apportionment": {
            "$ref": "#/components/schemas/Apportionment",
            "description": "How the costs are split. Required when costsSharedWithOtherParties is true; omitted when false."
          }
        },
        "required": [
          "billingType",
          "costsSharedWithOtherParties",
          "totalAmount"
        ]
      },
      "ExpertDetails": {
        "type": "object",
        "description": "The expert and what they will cost.",
        "properties": {
          "expertType": {
            "type": "string",
            "description": "The expert type.",
            "example": "Psychologist"
          },
          "expertFullName": {
            "type": "string",
            "description": "Full name of the expert the prior authority is for.",
            "example": "Dr John Doe"
          },
          "expertPostcode": {
            "type": "string",
            "description": "Primary business postcode of the expert, for regional rate mapping.",
            "example": "SW1H 9AJ"
          },
          "expertCosts": {
            "$ref": "#/components/schemas/ExpertCosts"
          }
        },
        "required": [
          "expertCosts",
          "expertFullName",
          "expertPostcode",
          "expertType"
        ]
      },
      "PriorAuthorityDraft": {
        "type": "object",
        "description": "A prior-authority form, saved and updated incrementally through the create/update draft lifecycle before being submitted. At most one of expertDetails, counselDetails or disbursementDetails should be populated, matching priorAuthorityType.",
        "properties": {
          "applicationId": {
            "type": "string",
            "format": "uuid",
            "description": "ID of the application this prior-authority request is associated with.",
            "example": "2a28f60d-fe15-43fe-92c3-5530595d5f51"
          },
          "priorAuthorityType": {
            "type": [
              "string",
              "null"
            ],
            "description": "The category of prior authority being requested.",
            "enum": [
              "EXPERT",
              "COUNSEL",
              "DISBURSEMENT"
            ],
            "example": "EXPERT"
          },
          "justification": {
            "type": [
              "string",
              "null"
            ],
            "description": "Detailed rationale explaining why funding is necessary.",
            "example": "Expert evidence is needed to establish causation."
          },
          "expertDetails": {
            "type": "null",
            "$ref": "#/components/schemas/ExpertDetails",
            "description": "Present when priorAuthorityType is EXPERT."
          },
          "counselDetails": {
            "type": "null",
            "$ref": "#/components/schemas/CounselDetails",
            "description": "Present when priorAuthorityType is COUNSEL."
          },
          "disbursementDetails": {
            "type": "null",
            "$ref": "#/components/schemas/DisbursementDetails",
            "description": "Present when priorAuthorityType is DISBURSEMENT."
          }
        },
        "required": [
          "applicationId"
        ]
      },
      "TimeRequested": {
        "type": "object",
        "description": "The amount of the expert\u0027s time being requested.",
        "properties": {
          "hours": {
            "type": "integer",
            "format": "int32",
            "description": "Whole hours requested.",
            "example": 2,
            "minimum": 0
          },
          "minutes": {
            "type": "integer",
            "format": "int32",
            "description": "Additional minutes requested.",
            "example": 30,
            "maximum": 59,
            "minimum": 0
          }
        },
        "required": [
          "hours",
          "minutes"
        ]
      },
      "PriorAuthorityIdResponse": {
        "type": "object",
        "properties": {
          "priorAuthorityId": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "PriorAuthorityApplicationResponse": {
        "type": "object",
        "description": "Confirmation returned after a prior-authority application has been submitted.",
        "properties": {
          "priorAuthorityId": {
            "type": "string",
            "format": "uuid",
            "description": "Identifier assigned to the prior-authority application by the Access Data Store.",
            "example": "11111111-2222-3333-4444-555555555555"
          },
          "submittedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp the application was accepted by the Access Data Store.",
            "example": "2026-05-22T10:00:00Z"
          }
        }
      },
      "UploadedDocument": {
        "type": "object",
        "description": "A document uploaded as supporting evidence for a prior-authority request.",
        "properties": {
          "documentId": {
            "type": "string",
            "format": "uuid",
            "description": "Identifier assigned to the uploaded document by the Access Data Store.",
            "example": "c3b07e24-d92b-410a-9d95-88f117a12b43"
          },
          "documentType": {
            "type": "string",
            "description": "Type of document that was uploaded.",
            "enum": [
              "GATEWAY_EVIDENCE",
              "MERITS_REPORT",
              "STATEMENT_OF_CASE",
              "COURT_APPLICATION",
              "COURT_ORDER",
              "EXPERT_REPORT",
              "COURT_APPLICATION_OR_ORDER",
              "PARENTAL_RESPONSIBILITY",
              "LOCAL_AUTHORITY_ASSESSMENT",
              "GROUNDS_OF_APPEAL",
              "COUNSEL_OPINION",
              "JUDGEMENT",
              "PLF_COURT_ORDER",
              "LETTER_OF_INSTRUCTION",
              "ESTIMATE_OF_COSTS",
              "ALTERNATIVE_QUOTE",
              "OTHER_PARTY_CERTIFICATE_REFERENCE",
              "OTHER_SUPPORTING_DOCUMENT",
              "PRIMARY_QUOTE",
              "ADDITIONAL_QUOTE"
            ],
            "example": "GATEWAY_EVIDENCE"
          },
          "fileName": {
            "type": "string",
            "description": "Filename of the uploaded document.",
            "example": "abc123.pdf",
            "minLength": 1
          },
          "fileType": {
            "type": "string",
            "description": "File extension/type of the uploaded document.",
            "example": "pdf"
          },
          "mediaType": {
            "type": "string",
            "description": "MIME content type of the uploaded document.",
            "example": "application/pdf"
          },
          "hostedUrl": {
            "type": "string"
          },
          "size": {
            "type": "integer",
            "format": "int64",
            "description": "Size of the uploaded document, in bytes.",
            "example": 10240
          },
          "uploadedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp the document was uploaded.",
            "example": "2026-05-22T10:00:00Z"
          },
          "sourceService": {
            "type": "string",
            "description": "The service that uploaded the document to the Access Data Store.",
            "example": "CIVIL_MANAGE"
          },
          "checksum": {
            "type": "string",
            "description": "Checksum of the uploaded document contents."
          }
        },
        "required": [
          "fileName"
        ]
      },
      "UpdatePriorAuthorityDocumentTypeRequest": {
        "type": "object",
        "description": "Request body used to assign a category to a previously uploaded prior-authority document.",
        "properties": {
          "documentType": {
            "type": "string",
            "description": "Type of document being categorised.",
            "enum": [
              "GATEWAY_EVIDENCE",
              "MERITS_REPORT",
              "STATEMENT_OF_CASE",
              "COURT_APPLICATION",
              "COURT_ORDER",
              "EXPERT_REPORT",
              "COURT_APPLICATION_OR_ORDER",
              "PARENTAL_RESPONSIBILITY",
              "LOCAL_AUTHORITY_ASSESSMENT",
              "GROUNDS_OF_APPEAL",
              "COUNSEL_OPINION",
              "JUDGEMENT",
              "PLF_COURT_ORDER",
              "LETTER_OF_INSTRUCTION",
              "ESTIMATE_OF_COSTS",
              "ALTERNATIVE_QUOTE",
              "OTHER_PARTY_CERTIFICATE_REFERENCE",
              "OTHER_SUPPORTING_DOCUMENT",
              "PRIMARY_QUOTE",
              "ADDITIONAL_QUOTE"
            ],
            "example": "GATEWAY_EVIDENCE"
          }
        },
        "required": [
          "documentType"
        ]
      },
      "PriorAuthorityDocumentTypeUpdateResponse": {
        "type": "object",
        "description": "Confirmation returned after a document\u0027s category has been updated.",
        "properties": {
          "documentId": {
            "type": "string",
            "format": "uuid",
            "description": "Identifier of the document that was updated.",
            "example": "c3b07e24-d92b-410a-9d95-88f117a12b43"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp the category update was recorded by the Access Data Store.",
            "example": "2026-05-22T10:00:00Z"
          }
        }
      },
      "PriorAuthorityResponse": {
        "type": "object",
        "description": "A prior-authority record as returned by the Access Data Store. status is null while the request is still a draft, and PENDING (or later) once it has been submitted.",
        "properties": {
          "priorAuthorityId": {
            "type": "string",
            "format": "uuid",
            "description": "Identifier of the prior-authority request, assigned when it was created.",
            "example": "c3b07e24-d92b-410a-9d95-88f117a12b43"
          },
          "status": {
            "type": [
              "string",
              "null"
            ],
            "description": "Lifecycle status. null while a draft; e.g. PENDING once submitted.",
            "example": "PENDING"
          },
          "draft": {
            "$ref": "#/components/schemas/PriorAuthorityDraft",
            "description": "The saved prior-authority form."
          },
          "uploadedDocuments": {
            "type": "array",
            "description": "Documents uploaded as supporting evidence for this prior-authority.",
            "items": {
              "$ref": "#/components/schemas/UploadedDocument"
            }
          }
        }
      },
      "ApplicationSummary": {
        "type": "object",
        "description": "Summary of a civil application containing key details.",
        "properties": {
          "applicationId": {
            "type": "string",
            "format": "uuid",
            "description": "The unique reference used to identify the application.",
            "example": "11111111-2222-3333-4444-555555555555"
          },
          "laaReference": {
            "type": "string",
            "description": "The LAA reference number of the application.",
            "example": "LAA-123456"
          },
          "status": {
            "type": "string",
            "description": "The current overall status of the application decision.",
            "example": "APPLICATION_SUBMITTED"
          },
          "submittedAt": {
            "type": "string",
            "format": "date-time",
            "description": "The date and time the application was submitted (in UTC).",
            "example": "2026-07-22T10:00:00Z"
          },
          "clientFirstName": {
            "type": "string",
            "description": "The client first name.",
            "example": "John"
          },
          "clientLastName": {
            "type": "string",
            "description": "The client last name.",
            "example": "Doe"
          },
          "matterType": {
            "type": "string",
            "description": "The matter type of the application.",
            "example": "SPECIAL_CHILDREN_ACT"
          }
        }
      },
      "ApplicationSummaryResponse": {
        "type": "object",
        "description": "Response containing a list of application summaries.",
        "properties": {
          "paging": {
            "$ref": "#/components/schemas/Paging",
            "description": "Pagination metadata for the response."
          },
          "applications": {
            "type": "array",
            "description": "List of application summaries matching the requested criteria.",
            "items": {
              "$ref": "#/components/schemas/ApplicationSummary"
            }
          }
        }
      },
      "Paging": {
        "type": "object",
        "description": "Pagination metadata for a paginated response.",
        "properties": {
          "page": {
            "type": "integer",
            "format": "int32",
            "description": "The current page number (0-based).",
            "example": 0
          },
          "pageSize": {
            "type": "integer",
            "format": "int32",
            "description": "The number of items per page.",
            "example": 10
          },
          "itemsReturned": {
            "type": "integer",
            "format": "int32",
            "description": "The number of items returned in this page.",
            "example": 10
          },
          "totalRecords": {
            "type": "integer",
            "format": "int32",
            "description": "The total number of records available.",
            "example": 100
          }
        }
      }
    }
  }
}