> ## Documentation Index > Fetch the complete documentation index at: https://docs.ctrl-hub.com/llms.txt > Use this file to discover all available pages before exploring further. # List archived submission documents > Retrieve the archived PDFs of submitted form submission versions. Every submitted version gets one automatically, so this reports which versions have a document and whether it is ready yet. Filter by `eq(submission,)` to answer that for a whole version list in one request, or by `eq(version,)` for a single version. A version with no record here has no document. That is the normal state for anything submitted before archiving was switched on, and it is distinguishable from a document that is still generating, which has a record with a `pending` status. Authorised by the same view grants that govern reading the submissions themselves. An artefact carries no permissions of its own: it is the same information, in a different format. **Never paginated, and nothing is sideloaded.** The response is the whole scoped set: a filter names one submission or one version, which bounds it to a handful of records, so there is nothing to page through and nothing is ever truncated. `included` is absent for the same reason a caller cannot ask for it: every relationship on an artefact is a resource the caller already had in hand when it named the scope. ## OpenAPI ````yaml /api-reference/openapi.yaml get /v3/form-submission-artefacts openapi: 3.1.0 info: contact: email: support@ctrl-hub.com name: Ctrl Hub url: https://www.ctrl-hub.com description: > Ctrl Hub is the all-in-one platform for high-risk industries like utilities, construction, infrastructure, and renewables. We help teams manage everything from risk assessments and HAVS exposure to vehicle and equipment checks, with a guaranteed minimum of 200% ROI. license: name: MIT License url: https://opensource.org/licenses/MIT summary: An API for managing your compliance and risk posture termsOfService: https://www.ctrl-hub.com/terms-conditions title: Ctrl Hub version: 1.0.0 servers: - description: Production url: https://api.ctrl-hub.com - description: Staging url: https://api.ctrl-hub.dev - description: Development url: https://api.ctrl-hub.run security: [] tags: - description: | Actions are follow-ups assigned to users and teams, produced manually or by domain producers such as the data-capture workflow runner. name: Actions - description: | Audit events are the events that are logged by the system. name: Audit Events - description: | View the platform's health and availability. name: Status - description: > User-owned dashboards composed of cards on a fixed-slot bento layout. Cards come from a per-domain registry; the API stores their config as opaque JSON. name: Dashboards - description: > A record of documents the platform generated and handed over, retained as evidence of what was issued. `subject_type` says what kind of records an export covers, and it is what decides how the request is authorised: there is no export permission of its own, so if you can see the records you can export them. name: Exports - description: > Scheduled delivery of a saved query's results, as a CSV attachment or a summary email. Every run is retained with the file it sent, so what a recipient received stays retrievable. A report runs as the person who created it, under their own access. name: Reports - description: | Manage appointments for work to be carried out with your customers name: Customer Appointments - description: | Manage interactions you have with your customers name: Customer Interactions - description: | Manage accounts for your customers name: Customer Accounts and Contacts - description: | Qualifications are the skills and knowledge that an organisation requires. name: Qualifications - description: | Workflows allow you to automate your processes. name: Workflows - description: | Manage documents name: Documents - description: | Manage documents name: Folders - description: | Manage documents name: Document Reviews - description: | Manage feature configurations for an organisation. name: Feature Configurations - description: | Equipment are the physical assets that an organisation manages. name: Equipment - description: | The central cost register: time-versioned rate codes for material, labour, contractor and miscellaneous spend, used to cost work against the job hierarchy. name: Costs - description: > Locations are places an organisation manages, optionally classified by a location type. name: Locations - description: | Manage your forms and their schemas name: Forms, Schemas and Categories - description: | Create and view form submissions name: Submissions - description: | View the roles available in the system. name: IAM Roles - description: > IAM role groups can be assigned to principals to manage authorisation centrally. name: IAM Role Groups - description: | Manage service accounts which can access the API programmatically. name: Service Accounts - description: | Manage bridges between organisations. name: Bridges - description: | Manage settings for an organisation. name: Settings - description: | Manage teams within an organisation. name: Teams - description: | Manage job roles within an organisation. name: Job Roles - description: | Manage users and accounts. name: Users - description: | Invite and manage invitations to organisations. name: Invitations - description: > IAM grants are the asignment of roles or permissions to principals to manage resource access. name: IAM Grants - description: | View the permissions available in the system. name: IAM Permissions - description: | SSO providers are the identity providers for an organisation. name: SSO Providers - description: | Whoami returns information about the currently authenticated principal. name: Whoami - description: | Manage your images name: Images - description: > AI agent personas that synthesise data into role-specific intelligent briefings. name: Agents - description: | Briefings generated by AI agents, including reasoning traces. name: Briefings - description: > Organisations are the center point for most resources in the platform. Most other endpoints are subresources of an organisation. name: Organisations - description: | Permits managements, integrated with street manager. name: Permits - description: | Projects manage your work and governance. name: Projects - description: > Import templates allow users to save and reuse their CSV importer configuration as named templates. name: Import Templates - description: | Properties are the physical locations. name: Properties - description: | Search across schemes, work orders, and operations. name: Search - description: | Provides the API specification in JSON and YAML formats name: Specifications - description: | Streets are the physical roads. name: Streets - description: | Integration with street manager name: Street Manager - description: | Vehicles are the physical vehicles that an organisation manages. name: Vehicles - description: > Scheme contracts (also known as regions) group schemes allocated from the network to a contractor. name: Scheme Contracts - description: > Scheme shares allow you to share your schemes with other organisations across bridges. name: Scheme Shares - description: | Schemes are large programmes of work name: Schemes - description: | Work orders the component parts of a scheme. name: Work Orders - description: | Operations are the work to be carried out within work orders. name: Operations externalDocs: description: More documentation and resources url: https://docs.ctrl-hub.com paths: /v3/form-submission-artefacts: get: tags: - Submissions summary: List archived submission documents description: > Retrieve the archived PDFs of submitted form submission versions. Every submitted version gets one automatically, so this reports which versions have a document and whether it is ready yet. Filter by `eq(submission,)` to answer that for a whole version list in one request, or by `eq(version,)` for a single version. A version with no record here has no document. That is the normal state for anything submitted before archiving was switched on, and it is distinguishable from a document that is still generating, which has a record with a `pending` status. Authorised by the same view grants that govern reading the submissions themselves. An artefact carries no permissions of its own: it is the same information, in a different format. **Never paginated, and nothing is sideloaded.** The response is the whole scoped set: a filter names one submission or one version, which bounds it to a handful of records, so there is nothing to page through and nothing is ever truncated. `included` is absent for the same reason a caller cannot ask for it: every relationship on an artefact is a resource the caller already had in hand when it named the scope. operationId: ListFormSubmissionArtefacts parameters: - $ref: '#/components/parameters/form_submission_artefacts_sort' - $ref: '#/components/parameters/form_submission_artefacts_filter' responses: '200': $ref: '#/components/responses/ListFormSubmissionArtefacts' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorised' '500': $ref: '#/components/responses/InternalServerError' security: - Session: [] - Cookie: [] - OAuth2: [] components: parameters: form_submission_artefacts_sort: in: query name: sort description: A comma separated list of fields to sort by. Defaults to newest first. required: false style: form explode: false schema: type: array items: type: string enum: - created_at - '-created_at' - generated_at - '-generated_at' form_submission_artefacts_filter: name: filter in: query description: > Filters the response data based on the value provided. Available filters: - `version`: Filter by the version the document is of, e.g. `eq(version,)`. - `submission`: Filter by submission, e.g. `eq(submission,)`. This is how a version list shows which of its versions have a document, in one request rather than one per version. - `organisation`: Filter by organisation, e.g. `eq(organisation,)`. - `form`: Filter by form, e.g. `eq(form,)`. - `status`: Filter by where generation has got to, e.g. `eq(status,ready)`. - `generated_at`: Filter by when the document was written, e.g. `ge(generated_at,2026-08-01T00:00:00Z)`. - `created_at`: Filter by when the record was first written, e.g. `ge(created_at,2026-08-01T00:00:00Z)`. For more information on using named filters, see [the docs](https://docs.ctrl-hub.com/api-reference/features#filtering) required: false schema: type: string default: '' responses: ListFormSubmissionArtefacts: description: List of archived submission documents. headers: Content-Type: $ref: '#/components/headers/content-type' Content-Length: $ref: '#/components/headers/content-length' X-Request-ID: $ref: '#/components/headers/x-request-id' content: application/vnd.api+json: schema: allOf: - type: object required: - data properties: data: title: A list of archived submission documents type: array items: $ref: '#/components/schemas/FormSubmissionArtefact' - $ref: '#/components/schemas/DocumentMeta' - $ref: '#/components/schemas/JSONAPI' BadRequest: description: > There was an error with the request - this could be due to an invalid body, query parameters, or headers that were sent to the API. headers: Content-Type: $ref: '#/components/headers/content-type' Content-Length: $ref: '#/components/headers/content-length' X-Request-ID: $ref: '#/components/headers/x-request-id' content: application/vnd.api+json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/Error' example: id: 98ca4a78-b66f-4234-9719-aaf832ee6669 status: '400' title: A validation error was encountered source: parameter: include meta: resource: wrong_value Unauthorised: description: Authentication failed headers: Content-Type: $ref: '#/components/headers/content-type' Content-Length: $ref: '#/components/headers/content-length' X-Request-ID: $ref: '#/components/headers/x-request-id' content: application/vnd.api+json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/Error' example: id: 05fc9c8d-73b9-4697-9337-57f7a567a48f status: '401' title: You are not authorised to access this resource detail: In order to access this resource, you need the 'admin' role. code: AUTH.001 InternalServerError: description: There was a problem handling the request on the server side headers: Content-Type: $ref: '#/components/headers/content-type' Content-Length: $ref: '#/components/headers/content-length' X-Request-ID: $ref: '#/components/headers/x-request-id' content: application/vnd.api+json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/Error' example: id: fe9d9a69-f0a7-4fdc-bb2c-176027f316c5 status: '500' title: Internal Server Error detail: An unexpected error occurred on the server. headers: content-type: description: The content type of the response schema: type: string example: application/vnd.api+json content-length: description: The length of the response body in bytes schema: type: integer format: int32 example: 1234 x-request-id: description: >- An ID that can be provided when reporting bugs to help identify the issue schema: type: string example: 8470f56af4cf25e22be08e72c70dbbdc schemas: FormSubmissionArtefact: type: object description: > The archived PDF of one submitted form submission version. Every submitted version gets one automatically, rendered from the form's own schema view. It is a property of the version rather than a record of anybody's request: nobody asks for it, nothing is emailed, and there is no requester. A separate resource rather than a field on the version, because a version's representation is served as immutable and cached, while this changes as generation progresses. required: - id - type - attributes - meta - relationships properties: id: type: string format: uuid description: The unique identifier of the artefact. type: type: string const: form-submission-artefacts attributes: $ref: '#/components/schemas/FormSubmissionArtefactAttributes' meta: $ref: '#/components/schemas/FormSubmissionArtefactMeta' relationships: $ref: '#/components/schemas/FormSubmissionArtefactRelationships' DocumentMeta: type: object description: Document level meta about the resources on the server in list endpoints. required: - meta properties: meta: type: object required: - pagination properties: features: $ref: '#/components/schemas/Features' pagination: $ref: '#/components/schemas/Pagination' JSONAPI: type: object description: JSON API response object required: - jsonapi properties: jsonapi: type: object required: - version properties: version: type: string description: The version of the JSON API specification examples: - '1.0' Error: type: object description: An error response properties: id: description: >- A unique identifier for this particular occurrence of the problem. If you encounter this, please provide us with the error ID and we can investigate it on our side. type: string format: uuid examples: - 05fc9c8d-73b9-4697-9337-57f7a567a48f status: description: >- The status code for the error. This might not match the HTTP status code if there are more that one errors to return with different status codes. type: string examples: - '401' - '500' title: description: A human readable title for the error. type: string examples: - You are not authorised to access this resource detail: description: >- Where there is more detail that we can provide outside of the title, we will provide it here. type: string examples: - In order to access this resource, you need the 'admin' role. code: description: >- A unique code for the error that may help us to diagnose the issue. Not all errors have codes, so this is usually empty. type: string examples: - AUTH.001 source: description: A JSON object containing additional information about the error. type: object properties: pointer: description: >- A JSON Pointer to the value in the request that caused the error. type: string examples: - /data/attributes/email parameter: description: >- A string indicating which query parameter in the request caused the error. type: string examples: - include required: - id - status - title FormSubmissionArtefactAttributes: type: object description: Attributes of a submitted version's archived document required: - status properties: status: type: string description: > Where generation has got to. `pending` is normal for a short while after a version is submitted: the document is rendered from an event rather than in the request, so a client seeing it should wait rather than treat it as a fault. `failed` carries the reason in `error`; the platform retries on its own, so a failure is not necessarily final. enum: - pending - ready - failed content_type: type: - string - 'null' description: >- The media type of the stored document. Null until it has been stored. size: type: - integer - 'null' format: int64 minimum: 0 description: >- The size of the stored document in bytes. Null until it has been stored. error: type: - string - 'null' description: >- Why a failed generation failed. Null on an artefact that has not failed. FormSubmissionArtefactMeta: type: object description: Metadata for a submitted version's archived document required: - created_at properties: created_at: type: string format: date-time description: >- When the platform first recorded that this version needed a document. generated_at: type: - string - 'null' format: date-time description: > When the document was written to storage. Null until it has been. This is what the artefact was issued at, so it answers "what did we hand over, and when". It is not re-stamped if the record is touched again. FormSubmissionArtefactRelationships: type: object description: Relationships for a submitted version's archived document required: - organisation - version - submission - form properties: organisation: type: object required: - data properties: data: $ref: '#/components/schemas/OrganisationRelationship' description: The organisation the submission belongs to. version: type: object required: - data properties: data: $ref: '#/components/schemas/FormSubmissionVersionRelationship' description: > The version this document is of. One version has at most one artefact, so this identifies the record as surely as its own id does. submission: type: object required: - data properties: data: $ref: '#/components/schemas/FormSubmissionRelationship' description: The submission the version belongs to. form: type: object required: - data properties: data: $ref: '#/components/schemas/FormRelationship' description: The form the submission answers. Features: type: object description: Represents feature configurations of the API properties: include: type: object properties: options: type: array items: type: string examples: - related.resource Pagination: type: object description: Represents pagination details for API responses required: - counts - current_page - offsets - requested properties: counts: type: object required: - pages - resources properties: pages: type: integer examples: - 1 resources: type: integer examples: - 1 current_page: type: integer examples: - 1 offsets: type: object required: - next - previous properties: next: type: - integer - 'null' examples: - null previous: type: - integer - 'null' examples: - null requested: type: object required: - limit - offset properties: limit: type: integer examples: - 10 offset: type: integer examples: - 0 OrganisationRelationship: type: object description: Represents a relationship to an organisation required: - id - type properties: id: type: string format: uuid description: The unique identifier of the organisation type: type: string const: organisations FormSubmissionVersionRelationship: type: object description: Represents a relationship to a form submission version required: - id - type properties: id: type: string format: uuid description: The unique identifier of the form submission version type: type: string const: form-submission-versions FormSubmissionRelationship: type: object description: Represents a relationship to a form submission required: - id - type properties: id: type: string format: uuid description: The unique identifier of the form submission type: type: string const: form-submissions FormRelationship: type: object description: Represents a relationship to a form required: - id - type properties: id: type: string format: uuid description: The unique identifier of the form type: type: string const: forms securitySchemes: Session: description: | Session token for authentication. in: header name: X-Session-Token type: apiKey Cookie: description: | Cookie token for authentication. in: cookie name: ctrl_hub_session type: apiKey OAuth2: description: | OAuth2 token for authentication. flows: clientCredentials: scopes: {} tokenUrl: https://auth.ctrl-hub.com/oauth2/token type: oauth2 ````