> ## 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 operations > List all of the operations in an organisation. ## OpenAPI ````yaml /api-reference/openapi.yaml get /v3/operations 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: | 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: | 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: | 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: > 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/operations: get: tags: - Operations description: List all of the operations in an organisation. operationId: ListOperations parameters: - $ref: '#/components/parameters/operations_include' - $ref: '#/components/parameters/operation_filter' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/operations_sort' responses: '200': $ref: '#/components/responses/ListOperations' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorised' '500': $ref: '#/components/responses/InternalServerError' security: - Session: [] - OAuth2: [] - Cookie: [] components: parameters: operations_include: name: include in: query description: A comma separated list of related resources to include. required: false style: form explode: false schema: type: array items: type: string enum: - appointment - assignees - forms - operation_type - organisation - permits - properties - scheme - streets - teams - template - work_order operation_filter: name: filter in: query description: > Filters the response data based on the value provided. Available filters: - `id_in`: Filter by ID(s) - `in_schemes`: Filter for operations that are part of a scheme(s) by their ID(s) - `in_work_orders`: Filter for operations that are part of a work order(s) by their ID(s) - `assigned_to`: Filter for operations assigned to a user(s) by their ID(s) - `at_properties`: Filter for operations at a property(s) by their ID(s) - `unscheduled`: Filter for unscheduled operations - `no_start`: Filter operations with no start time - `no_end`: Filter operations with no end time - `has_appointment`: Filter operations that have appointments - `no_appointment`: Filter operations that do not have appointments - `has_property`: Filter operations that have any related property - this does not accept arguments, it just checks for the existence of a related property. You can use `at_properties` to find operations at a specific property. 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: '' limit: name: limit in: query description: Limit the number of resources returned by the API required: false schema: type: integer format: int64 minimum: 1 default: 100 offset: name: offset in: query description: Offset the resources returned by the API required: false schema: type: integer format: int64 minimum: 0 default: 0 operations_sort: in: query name: sort description: A comma separated list of fields to sort by. required: false style: form explode: false schema: type: array items: type: string enum: - code - '-code' - created_at - '-created_at' - name - '-name' - postcode - '-postcode' responses: ListOperations: description: List of operations. 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 operations type: array items: $ref: '#/components/schemas/Operation' included: $ref: '#/components/schemas/OperationIncludes' - $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: Operation: type: object description: An operation required: - id - type - attributes - meta - relationships properties: id: type: string format: uuid description: The unique identifier of the operation. type: type: string const: operations attributes: $ref: '#/components/schemas/OperationAttributes' meta: $ref: '#/components/schemas/OperationMeta' relationships: $ref: '#/components/schemas/OperationRelationships' OperationIncludes: type: array description: Related resources that can be included when an operation is returned items: discriminator: propertyName: type mapping: forms: $ref: '#/components/schemas/Form' operation-templates: $ref: '#/components/schemas/OperationTemplate' operation-types: $ref: '#/components/schemas/OperationType' organisations: $ref: '#/components/schemas/Organisation' properties: $ref: '#/components/schemas/Property' schemes: $ref: '#/components/schemas/Scheme' streets: $ref: '#/components/schemas/Street' street-manager-permits: $ref: '#/components/schemas/StreetManagerPermit' teams: $ref: '#/components/schemas/Team' users: $ref: '#/components/schemas/User' work-orders: $ref: '#/components/schemas/WorkOrder' oneOf: - $ref: '#/components/schemas/Form' - $ref: '#/components/schemas/OperationTemplate' - $ref: '#/components/schemas/OperationType' - $ref: '#/components/schemas/Organisation' - $ref: '#/components/schemas/Property' - $ref: '#/components/schemas/Scheme' - $ref: '#/components/schemas/Street' - $ref: '#/components/schemas/StreetManagerPermit' - $ref: '#/components/schemas/Team' - $ref: '#/components/schemas/User' - $ref: '#/components/schemas/WorkOrder' 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 OperationAttributes: type: object description: Attributes for an operation required: - name - status properties: name: type: string code: type: string description: type: string dates: type: object properties: scheduled: type: object properties: start: type: string format: date-time end: type: string format: date-time labels: type: array items: $ref: '#/components/schemas/Label' requirements: oneOf: - type: object properties: forms: oneOf: - type: array items: type: object required: - id - required properties: id: type: string format: uuid required: type: boolean - type: 'null' - type: 'null' status: type: string enum: - done - in_progress - todo done_reason: type: - string - 'null' enum: - aborted - completed - cancelled - null allOf: - if: properties: status: const: done then: required: - done_reason OperationMeta: type: object description: Metadata for an operation required: - created_at - updated_at - counts properties: created_at: type: string format: date-time description: The date and time when the operation was created updated_at: type: string format: date-time description: The date and time when the operation was last updated counts: type: object required: - streets - properties properties: streets: type: integer description: The number of streets in this operation format: int64 minimum: 0 default: 0 properties: type: integer description: The number of properties in this operation format: int64 minimum: 0 default: 0 related_data: type: object description: Related resources for the operation properties: properties: type: array description: Array of property IDs with postcodes items: type: object description: Property ID and Postcode required: - id - postcode properties: id: type: string format: uuid description: The ID of the property postcode: type: string description: Postcode of the property OperationRelationships: type: object description: Relationships for an operation required: - work_order - scheme - organisation properties: organisation: type: object required: - data properties: data: $ref: '#/components/schemas/OrganisationRelationship' appointment: type: object required: - data properties: data: $ref: '#/components/schemas/AppointmentRelationship' scheme: type: object required: - data properties: data: $ref: '#/components/schemas/SchemeRelationship' work_order: type: object required: - data properties: data: $ref: '#/components/schemas/WorkOrderRelationship' permits: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/PermitRelationship' template: type: object required: - data properties: data: $ref: '#/components/schemas/OperationTemplateRelationship' type: type: object properties: data: $ref: '#/components/schemas/OperationTypeRelationship' teams: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/TeamRelationship' assignees: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/UserRelationship' properties: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/PropertyRelationship' streets: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/StreetRelationship' Form: type: object description: A form required: - id - type - attributes - meta - relationships properties: id: type: string format: uuid description: The unique identifier of the form. type: type: string const: forms attributes: $ref: '#/components/schemas/FormAttributes' meta: $ref: '#/components/schemas/FormMeta' relationships: $ref: '#/components/schemas/FormRelationships' OperationTemplate: type: object description: An operation template required: - id - type - attributes - meta - relationships properties: id: type: string format: uuid description: The unique identifier of the operation template. type: type: string const: operation-templates attributes: $ref: '#/components/schemas/OperationTemplateAttributes' meta: $ref: '#/components/schemas/OperationTemplateMeta' relationships: $ref: '#/components/schemas/OperationTemplateRelationships' OperationType: type: object description: An operation type required: - id - type - attributes - meta - relationships properties: id: type: string format: uuid description: The unique identifier of the operation type. type: type: string const: operation-types attributes: $ref: '#/components/schemas/OperationTypeAttributes' meta: $ref: '#/components/schemas/OperationTypeMeta' relationships: $ref: '#/components/schemas/OperationTypeRelationships' Organisation: type: object description: An organisation required: - id - type - attributes - meta properties: id: type: string format: uuid description: The unique identifier of the organisation. type: type: string const: organisations attributes: $ref: '#/components/schemas/OrganisationAttributes' meta: $ref: '#/components/schemas/OrganisationMeta' relationships: $ref: '#/components/schemas/OrganisationRelationships' Property: type: object description: A property required: - id - type - attributes - meta - relationships properties: id: type: string format: uuid description: The unique identifier of the property. type: type: string const: properties attributes: $ref: '#/components/schemas/PropertyAttributes' meta: $ref: '#/components/schemas/PropertyMeta' relationships: $ref: '#/components/schemas/PropertyRelationships' Scheme: type: object description: A scheme required: - id - type - attributes - meta - relationships properties: id: type: string format: uuid description: The unique identifier of the scheme. type: type: string const: schemes attributes: $ref: '#/components/schemas/SchemeAttributes' meta: $ref: '#/components/schemas/SchemeMeta' relationships: $ref: '#/components/schemas/SchemeRelationships' Street: type: object description: A street required: - id - type - attributes - meta - relationships properties: id: type: string format: uuid description: The unique identifier of the street. type: type: string const: streets attributes: $ref: '#/components/schemas/StreetAttributes' meta: $ref: '#/components/schemas/StreetMeta' relationships: $ref: '#/components/schemas/StreetRelationships' StreetManagerPermit: type: object description: A street manager permit required: - id - type - attributes - meta - relationships properties: id: type: string format: uuid description: The unique identifier of the street manager permit. type: type: string const: street-manager-permits attributes: $ref: '#/components/schemas/StreetManagerPermitAttributes' meta: $ref: '#/components/schemas/StreetManagerPermitMeta' relationships: $ref: '#/components/schemas/StreetManagerPermitRelationships' Team: type: object description: A team required: - id - type - attributes properties: id: type: string format: uuid description: The unique identifier of the team. type: type: string const: teams attributes: $ref: '#/components/schemas/TeamAttributes' meta: $ref: '#/components/schemas/TeamMeta' relationships: $ref: '#/components/schemas/TeamRelationships' User: type: object description: A user required: - id - type - attributes properties: id: type: string format: uuid description: The unique identifier of the user. examples: - 123e4567-e89b-12d3-a456-426614174000 type: type: string const: users attributes: $ref: '#/components/schemas/UserAttributes' meta: $ref: '#/components/schemas/UserMeta' relationships: $ref: '#/components/schemas/UserRelationships' WorkOrder: type: object description: A work order required: - id - type - attributes - meta - relationships properties: id: type: string format: uuid description: The unique identifier of the work order. examples: - fb082ee5-b678-4451-b02b-8269aaf262a3 type: type: string const: work-orders attributes: $ref: '#/components/schemas/WorkOrderAttributes' meta: $ref: '#/components/schemas/WorkOrderMeta' relationships: $ref: '#/components/schemas/WorkOrderRelationships' 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 Label: type: object description: A label object required: - key - value properties: key: type: string minLength: 1 examples: - Your label key value: type: string examples: - Your label value 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 AppointmentRelationship: type: object description: Represents a relationship to an appointment required: - id - type properties: id: type: string format: uuid description: The unique identifier of the appointment type: type: string const: appointments SchemeRelationship: type: object description: Represents a relationship to a scheme required: - id - type properties: id: type: string format: uuid description: The unique identifier of the scheme type: type: string const: schemes WorkOrderRelationship: type: object description: Represents a relationship to a work order required: - id - type properties: id: type: string format: uuid description: The unique identifier of the work order type: type: string const: work-orders PermitRelationship: type: object description: Represents a relationship to a permit required: - id - type properties: id: type: string format: uuid description: The unique identifier of the permit type: type: string const: permits OperationTemplateRelationship: type: object description: Represents a relationship to an operation template required: - id - type properties: id: type: string format: uuid description: The unique identifier of the operation template type: type: string const: operation-templates OperationTypeRelationship: type: object description: Represents a relationship to an operation type required: - id - type properties: id: type: string format: uuid description: The unique identifier of the operation type type: type: string const: operation-types TeamRelationship: type: object description: Represents a relationship to a team required: - id - type properties: id: type: string format: uuid description: The unique identifier of the team type: type: string const: teams UserRelationship: type: object description: Represents a relationship to a user required: - id - type properties: id: type: string format: uuid description: The unique identifier of the user type: type: string const: users PropertyRelationship: type: object description: Represents a relationship to a property required: - id - type properties: id: type: string format: uuid description: The unique identifier of the property type: type: string const: properties StreetRelationship: type: object description: Represents a relationship to a street required: - id - type properties: id: type: string format: uuid description: The unique identifier of the street type: type: string const: streets FormAttributes: type: object description: Attributes for a form required: - name - description - status properties: name: type: string description: The name of the form description: type: string description: The description of the form status: type: string enum: - draft - active - archived default: draft description: The current status of the form FormMeta: type: object description: Metadata for a form required: - created_at - updated_at - modified_at - counts properties: created_at: type: string format: date-time description: The date and time when the form was created updated_at: type: string format: date-time description: The date and time when the form was last updated modified_at: type: string format: date-time description: The date and time when the form was last modified counts: type: object properties: schemas: type: integer description: The number of schemas this form has. format: int64 minimum: 0 default: 0 categories: type: integer description: The number of categories this form has. format: int64 minimum: 0 default: 0 submissions: type: integer description: The number of submissions this form has. format: int64 minimum: 0 default: 0 submission_versions: type: integer description: The number of submission versions this form has. format: int64 minimum: 0 default: 0 FormRelationships: type: object description: Relationships for a form required: - organisation - categories - schemas properties: author: type: object required: - data properties: data: $ref: '#/components/schemas/UserRelationship' organisation: type: object required: - data properties: data: $ref: '#/components/schemas/OrganisationRelationship' categories: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/FormCategoryRelationship' workflow: type: object required: - data properties: data: oneOf: - $ref: '#/components/schemas/WorkflowDefinitionRelationship' - type: 'null' latest_schema: type: object required: - data properties: data: $ref: '#/components/schemas/FormSchemaRelationship' schemas: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/FormSchemaRelationship' submissions: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/FormSubmissionRelationship' OperationTemplateAttributes: type: object description: Attributes for an operation template required: - name properties: name: type: string description: The name of the operation template operation_name_template: type: string description: The template for the operation name operation_code_template: type: string description: The template for the operation code labels: type: array description: The labels associated with the operation template items: $ref: '#/components/schemas/Label' requirements: type: object description: The requirements for the operation template properties: forms: type: array description: The forms required for this operation template items: type: object required: - id - required properties: id: type: string format: uuid description: The ID of the required form required: type: boolean description: Whether this form is required OperationTemplateMeta: type: object description: Metadata for an operation template required: - created_at - updated_at properties: created_at: type: string format: date-time description: The date and time when the operation template was created updated_at: type: string format: date-time description: The date and time when the operation template was last updated OperationTemplateRelationships: type: object description: Relationships for an operation template properties: organisation: type: object required: - data properties: data: $ref: '#/components/schemas/OrganisationRelationship' scheme_template: type: object required: - data properties: data: $ref: '#/components/schemas/SchemeTemplateRelationship' OperationTypeAttributes: type: object description: Attributes for an operation type required: - name properties: name: type: string description: The name of the operation type description: type: string description: An optional description of the operation type colour_palette: $ref: '#/components/schemas/OperationTypeColourPalette' colour_shade: $ref: '#/components/schemas/OperationTypeColourShade' OperationTypeMeta: type: object description: Metadata for an operation type required: - created_at - updated_at properties: created_at: type: string format: date-time description: The date and time when the operation type was created updated_at: type: string format: date-time description: The date and time when the operation type was last updated OperationTypeRelationships: type: object description: Relationships for an operation type properties: organisation: type: object required: - data properties: data: $ref: '#/components/schemas/OrganisationRelationship' template: type: object properties: data: $ref: '#/components/schemas/OperationTemplateRelationship' OrganisationAttributes: type: object description: Attributes for an organisation required: - name - slug - sandbox properties: name: type: string description: The name of the organisation. examples: - Acme Construction Ltd slug: type: string description: The URL-friendly identifier for the organisation. examples: - acme-construction description: type: string description: A short description of the organisation. examples: - >- Leading construction company specializing in infrastructure projects sandbox: type: boolean description: Whether the organisation is a sandbox (i.e. a test organisation) examples: - false settings: type: object OrganisationMeta: type: object description: Meta information for an organisation required: - v3 - status properties: created_at: type: string format: date-time description: The creation time of the organisation. examples: - '2023-01-15T10:30:00.000Z' updated_at: type: string format: date-time description: The last update time of the organisation. examples: - '2023-02-20T14:45:00.000Z' v3: type: boolean description: Whether the organisation is using version 3 exclusively. examples: - true status: type: string enum: - active - inactive default: active description: The current status of the organisation. examples: - active features: type: array description: Available features and their limits for the organisation. items: type: object properties: name: type: string description: The name of the feature. examples: - advanced_reporting enabled: type: boolean description: Whether the feature is enabled. examples: - true limit: type: integer description: The usage limit for this feature (if applicable). examples: - 1000 OrganisationRelationships: type: object description: Relationships for an organisation properties: users: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/UserRelationship' service_accounts: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/ServiceAccountRelationship' groups: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/UserGroupRelationship' teams: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/TeamRelationship' nomenclature: type: object required: - data properties: data: oneOf: - $ref: '#/components/schemas/NomenclatureRelationship' - type: 'null' PropertyAttributes: type: object description: Attributes for a property required: - address properties: address: type: object properties: description: type: string department: type: string organisation: type: string number: type: string name: type: string thoroughfare: type: string dependent_thoroughfare: type: string post_town: type: string postcode: type: string po_box: type: string country: type: string uprn: type: number psr: description: Deprecated. Use the psrs relationship instead. type: object properties: indicator: type: boolean priority: type: - integer - 'null' notes: type: - string - 'null' contact: type: - string - 'null' meters: description: Deprecated. Use the meters relationship instead. type: array items: type: object properties: type: type: string number: type: integer location: type: object properties: british_national_grid: type: - object - 'null' properties: easting: type: number format: double northing: type: number format: double lat_long: type: - object - 'null' properties: latitude: type: number format: double longitude: type: number format: double PropertyMeta: type: object description: Metadata for a property required: - created_at - updated_at properties: created_at: type: string format: date-time description: The date and time when the property was created updated_at: type: string format: date-time description: The date and time when the property was last updated PropertyRelationships: type: object description: Relationships for a property properties: street: type: object required: - data properties: data: $ref: '#/components/schemas/StreetRelationship' meters: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/MeterRelationship' psrs: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/PSRRelationship' SchemeAttributes: type: object description: Attributes for a scheme required: - name properties: name: type: string code: type: string description: type: string dates: type: object properties: anticipated: type: object properties: start: type: string format: date-time end: type: string format: date-time labels: type: array items: $ref: '#/components/schemas/Label' SchemeMeta: type: object description: Metadata for a scheme required: - created_at - updated_at - from_template - modified_at - dates - completeness - counts - is_default properties: created_at: type: string format: date-time updated_at: type: string format: date-time modified_at: type: string format: date-time imported_at: type: string format: date-time from_template: description: Whether this scheme was created from a template. type: boolean dates: type: object properties: scheduled: type: object properties: start: type: string format: date-time end: type: string format: date-time counts: type: object properties: operations: type: integer description: >- The number of operations in this scheme (from all of the work orders). format: int64 minimum: 0 default: 0 permits: type: integer description: >- The number of permits in this scheme (from all of the operations in all of the work orders). format: int64 minimum: 0 default: 0 properties: type: integer description: >- The number of properties in this scheme (from all of the operations in all of the work orders). format: int64 minimum: 0 default: 0 streets: type: integer description: >- The number of streets in this scheme (from all of the operations in all of the work orders). format: int64 minimum: 0 default: 0 work_orders: type: integer description: The number of work orders in this scheme. format: int64 minimum: 0 default: 0 completeness: type: object required: - counts - percentage - statuses - done_reasons properties: percentage: type: object required: - completed - aborted - unknown - cancelled properties: completed: type: number minimum: 0 maximum: 100 default: 0 aborted: type: number minimum: 0 maximum: 100 default: 0 unknown: type: number minimum: 0 maximum: 100 default: 100 cancelled: type: number minimum: 0 maximum: 100 default: 0 counts: type: object required: - completed - aborted - unknown - cancelled properties: completed: type: integer minimum: 0 default: 0 aborted: type: integer minimum: 0 default: 0 unknown: type: integer minimum: 0 default: 1 cancelled: type: integer minimum: 0 default: 0 statuses: type: object required: - counts - percentages properties: counts: type: object required: - done - in_progress - todo properties: done: type: integer minimum: 0 default: 0 in_progress: type: integer minimum: 0 default: 0 todo: type: integer minimum: 0 default: 0 percentages: type: object required: - done - in_progress - todo properties: done: type: number minimum: 0 maximum: 100 default: 0 in_progress: type: number minimum: 0 maximum: 100 default: 0 todo: type: number minimum: 0 maximum: 100 default: 0 done_reasons: type: object required: - counts - percentages properties: counts: type: object required: - aborted - cancelled - completed properties: aborted: type: integer minimum: 0 default: 0 cancelled: type: integer minimum: 0 default: 0 completed: type: integer minimum: 0 default: 0 percentages: type: object required: - aborted - cancelled - completed properties: aborted: type: number minimum: 0 maximum: 100 default: 0 cancelled: type: number minimum: 0 maximum: 100 default: 0 completed: type: number minimum: 0 maximum: 100 default: 0 is_default: type: boolean default: false SchemeRelationships: type: object description: Relationships for a scheme required: - organisation properties: scheme_template: type: object required: - data properties: data: $ref: '#/components/schemas/SchemeTemplateRelationship' work_orders: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/WorkOrderRelationship' template: type: object required: - data properties: data: $ref: '#/components/schemas/SchemeTemplateRelationship' site_managers: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/UserRelationship' assignees: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/UserRelationship' teams: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/TeamRelationship' organisation: type: object required: - data properties: data: $ref: '#/components/schemas/OrganisationRelationship' folder: type: object required: - data properties: data: $ref: '#/components/schemas/FolderRelationship' contracts: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/SchemeContractRelationship' StreetAttributes: type: object description: Attributes for a street required: - usrn properties: name: type: string examples: - Main Street usrn: type: number examples: - 14930043 location: type: object required: - british_national_grid properties: british_national_grid: type: array items: type: array items: type: object required: - northing - easting properties: northing: type: number examples: - 557794 easting: type: number examples: - 426415 highway_authority: type: string examples: - National Highways highway_authority_code: type: number examples: - 1350 town: type: string examples: - Birmingham StreetMeta: type: object description: Metadata for a street required: - created_at - updated_at properties: created_at: type: string format: date-time description: The date and time when the street was created updated_at: type: string format: date-time description: The date and time when the street was last updated StreetRelationships: type: object description: Relationships for a street properties: properties: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/PropertyRelationship' StreetManagerPermitAttributes: type: object description: Attributes for a street manager permit required: - activated - end_date - permit_reference_number - permit_reference_number_iteration - start_date - status - usrn - work_reference_number - work_status_ref properties: activated: type: boolean description: Whether the permit is activated or not usrn: type: number description: Unique Street Reference Number permit_reference_number: type: string description: The unique reference number for this permit permit_reference_number_iteration: type: integer description: >- The iteration number of the permit based on the permit reference number work_reference_number: type: string description: The reference number for the work associated with this permit status: type: string description: The current status of the permit enum: - submitted - granted - permit_modification_request - refused - closed - cancelled - revoked - progressed work_status_ref: type: string description: The current status of the work as a reference enum: - completed - cancelled - planned - in_progress start_date: type: string format: date-time description: The start date of the permit end_date: type: string format: date-time description: The end date of the permit StreetManagerPermitMeta: type: object description: Metadata for a street manager permit required: - created_at - modified_at - updated_at properties: created_at: type: string format: date-time description: The date and time when the street manager permit was created modified_at: type: string format: date-time description: The date and time when the street manager permit was last modified updated_at: type: string format: date-time description: The date and time when the street manager permit was last updated StreetManagerPermitRelationships: type: object description: Relationships for a street manager permit properties: latest_version: type: object required: - data properties: data: $ref: '#/components/schemas/StreetManagerPermitVersionRelationship' versions: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/StreetManagerPermitVersionRelationship' TeamAttributes: type: object description: Attributes for a team properties: name: type: string description: The name of the team. examples: - Customer Service Representatives description: type: string description: A description of the team. examples: - >- Team responsible for handling customer inquiries and support requests TeamMeta: type: object description: Meta information for a team properties: created_at: type: string format: date-time description: The creation time of the team. examples: - '2025-07-16T12:42:40.000Z' updated_at: type: string format: date-time description: The last update time of the team. examples: - '2025-07-16T12:42:44.000Z' TeamRelationships: type: object description: Relationships for a team properties: members: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/UserRelationship' organisation: type: object required: - data properties: data: $ref: '#/components/schemas/OrganisationRelationship' schemas: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/FormSchemaRelationship' UserAttributes: type: object description: Attributes for a user properties: email: type: string format: email description: The email address of the user. examples: - john.doe@example.com status: type: string enum: - active - inactive - pending - unknown description: > The membership status of this user in the organisation in the request URL. Only populated on org-scoped member endpoints; absent on global user endpoints. examples: - active identities: type: array items: type: object properties: id: type: string format: uuid description: The unique identifier for the identity. examples: - 39ce13b8-1116-416a-ad5f-3c5edfd44f53 platform: type: string description: The platform of the identity. examples: - multi_tenant meta: type: - object - 'null' additionalProperties: true description: Additional metadata for the identity. profile: type: object properties: work: type: object properties: occupation: type: string description: The occupation of the user. examples: - Site Manager cscs: type: string description: The CSCS card number of the user. examples: - CSC123456 eusr: type: string description: The EUSR card number of the user. examples: - EUR789123 start_date: type: string format: date description: The start date of the user's employment. examples: - '2020-03-01T00:00:00.000Z' personal: type: object properties: first_name: type: string description: The first name of the user. examples: - John last_name: type: string description: The last name of the user. examples: - Doe dob: type: string format: date description: The date of birth of the user. examples: - '1985-06-15T00:00:00.000Z' username: type: string description: The username of the user. examples: - johndoe contact: type: object properties: mobile: type: string description: The mobile number of the user. examples: - +44 7700 900123 landline: type: string description: The landline of the user. examples: - +44 20 7946 0958 address: type: object properties: number: type: string description: The house number of the user's address. default: '' examples: - '42' street: type: string description: The street of the user's address. examples: - High Street area: type: string description: The area of the user's address. examples: - Westminster town: type: string description: The town of the user's address. examples: - London county: type: string description: The county of the user's address. examples: - Greater London postcode: type: string description: The postcode of the user's address. examples: - SW1A 1AA country_code: type: string description: The country code of the user's address. examples: - GB what3words: type: string description: The what3words location of the user's address. examples: - filled.count.soap settings: type: object properties: preferred_language: type: string description: The preferred language of the user. default: en-GB examples: - en-GB timezone: type: string description: The timezone of the user. examples: - Europe/London UserMeta: type: object description: Metadata for a user properties: grants: type: array items: type: string description: >- This data is only returned on the whoami endpoint - it contains all of the user's granted permissions. UserRelationships: type: object description: Relationships for a user properties: organisations: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/OrganisationRelationship' teams: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/TeamRelationship' managing_organisation: type: object required: - data properties: data: $ref: '#/components/schemas/OrganisationRelationship' WorkOrderAttributes: type: object description: Attributes for a work order required: - name properties: name: type: string description: The name of the work order examples: - Infrastructure Maintenance Work Order code: type: string description: The code of the work order examples: - WO-2025-001 description: type: string description: The description of the work order examples: - Routine maintenance and inspection of electrical infrastructure dates: type: object description: The dates associated with the work order properties: anticipated: type: object description: The anticipated start and end dates properties: start: type: string format: date-time description: The anticipated start date examples: - '2025-08-01T09:00:00Z' end: type: string format: date-time description: The anticipated end date examples: - '2025-08-15T17:00:00Z' labels: type: array description: The labels associated with the work order items: $ref: '#/components/schemas/Label' WorkOrderMeta: type: object description: Metadata for a work order required: - created_at - updated_at - modified_at - counts - dates - completeness properties: created_at: type: string format: date-time description: The date and time when the work order was created examples: - '2025-05-06T18:37:12Z' updated_at: type: string format: date-time description: The date and time when the work order was last updated examples: - '2025-05-07T21:12:46Z' modified_at: type: string format: date-time description: The date and time when the work order was last modified examples: - '2025-05-07T21:12:46Z' dates: type: object description: The scheduled dates for the work order properties: scheduled: type: object description: The scheduled start and end dates properties: start: type: string format: date-time description: The scheduled start date examples: - '2025-08-01T09:00:00Z' end: type: string format: date-time description: The scheduled end date examples: - '2025-08-15T17:00:00Z' counts: type: object description: The counts of related entities required: - operations - properties - streets properties: operations: type: integer description: The number of operations in this work order format: int64 minimum: 0 default: 0 examples: - 1 streets: type: integer description: >- The number of streets in this work order (from all of the operations in this work order) format: int64 minimum: 0 default: 0 examples: - 1 properties: type: integer description: >- The number of properties in this work order (from all of the operations in this work order) format: int64 minimum: 0 default: 0 examples: - 1 completeness: type: object description: The completeness statistics for the work order required: - percentage - counts - statuses - done_reasons properties: percentage: type: object description: The percentage breakdown of completion status required: - completed - aborted - unknown - cancelled properties: completed: type: number minimum: 0 maximum: 100 default: 0 description: The percentage of completed operations examples: - 25 aborted: type: number minimum: 0 maximum: 100 default: 0 description: The percentage of aborted operations examples: - 0 unknown: type: number minimum: 0 maximum: 100 default: 0 description: The percentage of operations with unknown status examples: - 75 cancelled: type: number minimum: 0 maximum: 100 default: 0 description: The percentage of cancelled operations examples: - 0 counts: type: object description: The count breakdown of completion status required: - completed - aborted - unknown - cancelled properties: completed: type: integer minimum: 0 default: 0 description: The number of completed operations examples: - 1 aborted: type: integer minimum: 0 default: 0 description: The number of aborted operations examples: - 0 unknown: type: integer minimum: 0 default: 0 description: The number of operations with unknown status examples: - 3 cancelled: type: integer minimum: 0 default: 0 description: The number of cancelled operations examples: - 0 statuses: type: object required: - counts - percentages properties: counts: type: object required: - done - in_progress - todo properties: done: type: integer minimum: 0 default: 0 examples: - 3 in_progress: type: integer minimum: 0 default: 0 examples: - 1 todo: type: integer minimum: 0 default: 0 examples: - 1 percentages: type: object required: - done - in_progress - todo properties: done: type: number minimum: 0 maximum: 100 default: 0 examples: - 60 in_progress: type: number minimum: 0 maximum: 100 default: 0 examples: - 20 todo: type: number minimum: 0 maximum: 100 default: 0 examples: - 20 done_reasons: type: object required: - counts - percentages properties: counts: type: object required: - aborted - cancelled - completed properties: aborted: type: integer minimum: 0 default: 0 examples: - 1 cancelled: type: integer minimum: 0 default: 0 examples: - 2 completed: type: integer minimum: 0 default: 0 examples: - 2 percentages: type: object required: - aborted - cancelled - completed properties: aborted: type: number minimum: 0 maximum: 100 default: 0 examples: - 20 cancelled: type: number minimum: 0 maximum: 100 default: 0 examples: - 40 completed: type: number minimum: 0 maximum: 100 default: 0 examples: - 40 WorkOrderRelationships: type: object description: Relationships for a work order required: - organisation - scheme - operations properties: organisation: type: object required: - data properties: data: $ref: '#/components/schemas/OrganisationRelationship' assignees: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/UserRelationship' teams: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/TeamRelationship' scheme: type: object required: - data properties: data: $ref: '#/components/schemas/SchemeRelationship' operations: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/OperationRelationship' template: type: object required: - data properties: data: $ref: '#/components/schemas/WorkOrderTemplateRelationship' site_managers: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/UserRelationship' folder: type: object required: - data properties: data: $ref: '#/components/schemas/FolderRelationship' FormCategoryRelationship: type: object description: Represents a relationship to a form category required: - id - type properties: id: type: string format: uuid description: The unique identifier of the form category type: type: string const: form-categories WorkflowDefinitionRelationship: type: object description: Represents a relationship to a workflow definition required: - id - type properties: id: type: string format: uuid description: The unique identifier of the workflow definition type: type: string const: workflow-definitions FormSchemaRelationship: type: object description: Represents a relationship to a form schema required: - id - type properties: id: type: string format: uuid description: The unique identifier of the form schema type: type: string const: form-schemas 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 SchemeTemplateRelationship: type: object description: Represents a relationship to a scheme template required: - id - type properties: id: type: string format: uuid description: The unique identifier of the scheme template type: type: string const: scheme-templates OperationTypeColourPalette: type: string description: The palette component of the operation type's colour enum: - purple - blue - green - yellow - red - orange - grey OperationTypeColourShade: type: string description: The shade component of the operation type's colour enum: - '50' - '100' - '200' - '300' - '400' - '500' - '600' - '700' - '800' - '900' - '950' ServiceAccountRelationship: type: object description: Represents a relationship to a service account required: - id - type properties: id: type: string format: uuid description: The unique identifier of the service account type: type: string const: service-accounts UserGroupRelationship: type: object description: Represents a relationship to a group required: - id - type properties: id: type: string format: uuid description: The unique identifier of the group type: type: string const: groups NomenclatureRelationship: type: object description: Represents a relationship to a nomenclature resource required: - id - type properties: id: type: string format: uuid description: The unique identifier of the nomenclature resource type: type: string const: nomenclature MeterRelationship: type: object description: Represents a relationship to a meter required: - id - type properties: id: type: string format: uuid description: The unique identifier of the meter type: type: string const: meters PSRRelationship: type: object description: Represents a relationship to a PSR record required: - id - type properties: id: type: string format: uuid description: The unique identifier of the PSR record type: type: string const: psrs FolderRelationship: type: object description: Represents a relationship to a folder required: - id - type properties: id: type: string format: uuid description: The unique identifier of the folder type: type: string const: folders SchemeContractRelationship: type: object description: Represents a relationship to a scheme contract required: - id - type properties: id: type: string format: uuid description: The unique identifier of the scheme contract type: type: string const: scheme-contracts StreetManagerPermitVersionRelationship: type: object description: Represents a relationship to a street manager permit version required: - id - type properties: id: type: string format: uuid description: The unique identifier of the street manager permit version type: type: string const: street-manager-permit-versions OperationRelationship: type: object description: Represents a relationship to an operation required: - id - type properties: id: type: string format: uuid description: The unique identifier of the operation type: type: string const: operations WorkOrderTemplateRelationship: type: object description: Represents a relationship to a work order template required: - id - type properties: id: type: string format: uuid description: The unique identifier of the work order template type: type: string const: work-order-templates securitySchemes: Session: description: | Session token for authentication. in: header name: X-Session-Token type: apiKey OAuth2: description: | OAuth2 token for authentication. flows: clientCredentials: scopes: {} tokenUrl: https://auth.ctrl-hub.com/oauth2/token type: oauth2 Cookie: description: | Cookie token for authentication. in: cookie name: ctrl_hub_session type: apiKey ````