> ## 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. # Update an equipment certificate > Replace an equipment certificate. The expiry is re-derived from the performed date plus the certification's renewal period. ## OpenAPI ````yaml /api-reference/openapi.yaml put /v3/equipment-certificates/{equipment_certificate_id} 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: | 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: > 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/equipment-certificates/{equipment_certificate_id}: put: tags: - Equipment summary: Update an equipment certificate description: >- Replace an equipment certificate. The expiry is re-derived from the performed date plus the certification's renewal period. operationId: UpdateEquipmentCertificate parameters: - $ref: '#/components/parameters/equipment_certificate_id' requestBody: $ref: '#/components/requestBodies/UpdateEquipmentCertificate' responses: '200': $ref: '#/components/responses/GetEquipmentCertificate' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorised' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '500': $ref: '#/components/responses/InternalServerError' security: - Session: [] - Cookie: [] - OAuth2: [] components: parameters: equipment_certificate_id: name: equipment_certificate_id in: path required: true description: The unique identifier for the equipment certificate. schema: type: string format: uuid example: e2f3a4b5-c6d7-4e8f-9012-2b3c4d5e6f70 requestBodies: UpdateEquipmentCertificate: required: true description: The equipment certificate to update. content: application/vnd.api+json: schema: type: object required: - data properties: data: type: object required: - type - id - attributes properties: id: type: string format: uuid type: type: string const: equipment-certificates attributes: type: object required: - performed_at - certificate_number - provider_name properties: performed_at: type: - string - 'null' format: date-time certificate_number: type: - string - 'null' provider_name: type: - string - 'null' responses: GetEquipmentCertificate: description: Get an equipment certificate. 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: $ref: '#/components/schemas/EquipmentCertificate' included: $ref: '#/components/schemas/EquipmentCertificateIncludes' - $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 NotFound: description: The requested resource could not be found 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: 7b4c8f12-3e9a-4d5b-8c6f-1a2b3c4d5e6f status: '404' title: Resource not found detail: The requested resource could not be found or does not exist. code: NOT_FOUND.001 Conflict: description: The request conflicts with the current state of the resource 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: 8e2f9a34-b5c6-4d7e-9f8a-2b3c4d5e6f7g status: '409' title: Conflict detail: The request conflicts with the current state of the resource. code: CONFLICT.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: EquipmentCertificate: type: object description: >- An equipment certificate — a dated check proving an equipment item holds a certification (e.g. a 12-month safety check that was performed). required: - id - type - attributes - meta - relationships properties: id: type: string format: uuid description: The unique identifier of the equipment certificate. type: type: string const: equipment-certificates attributes: $ref: '#/components/schemas/EquipmentCertificateAttributes' meta: $ref: '#/components/schemas/EquipmentCertificateMeta' relationships: $ref: '#/components/schemas/EquipmentCertificateRelationships' EquipmentCertificateIncludes: type: array description: >- Related resources that can be included when an equipment certificate is returned. items: discriminator: propertyName: type mapping: organisations: $ref: '#/components/schemas/Organisation' equipment-items: $ref: '#/components/schemas/EquipmentItem' equipment-certifications: $ref: '#/components/schemas/EquipmentCertification' oneOf: - $ref: '#/components/schemas/Organisation' - $ref: '#/components/schemas/EquipmentItem' - $ref: '#/components/schemas/EquipmentCertification' 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 EquipmentCertificateAttributes: type: object description: Attributes for an equipment certificate properties: performed_at: type: - string - 'null' format: date-time description: The date the check was performed. expires_at: type: - string - 'null' format: date-time readOnly: true description: >- The date and time this certificate expires, derived from the performed date plus the certification's renewal period. Read-only — never accepted on write. certificate_number: type: - string - 'null' description: The certificate number issued for this check. provider_name: type: - string - 'null' description: The name of the provider who performed or issued the check. risk_status: type: string readOnly: true description: The current risk level of this certificate. enum: - none - low - medium - high - critical next_check: type: - string - 'null' format: date-time readOnly: true description: >- The date and time when the next risk check is scheduled. Null if no check is required. EquipmentCertificateMeta: type: object description: Metadata for an equipment certificate required: - created_at - updated_at properties: created_at: type: string format: date-time updated_at: type: string format: date-time EquipmentCertificateRelationships: type: object description: Relationships for an equipment certificate required: - organisation - equipment_item - equipment_certification properties: organisation: type: object required: - data properties: data: $ref: '#/components/schemas/OrganisationRelationship' equipment_item: type: object description: The equipment item this certificate belongs to. required: - data properties: data: $ref: '#/components/schemas/EquipmentItemRelationship' equipment_certification: type: object description: The certification this certificate proves. required: - data properties: data: $ref: '#/components/schemas/EquipmentCertificationRelationship' 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' EquipmentItem: type: object description: An equipment item required: - id - type - attributes - meta - relationships properties: id: type: string format: uuid description: The unique identifier of the equipment item. type: type: string const: equipment-items attributes: $ref: '#/components/schemas/EquipmentItemAttributes' meta: $ref: '#/components/schemas/EquipmentItemMeta' relationships: $ref: '#/components/schemas/EquipmentItemRelationships' EquipmentCertification: type: object description: An equipment certification required: - id - type - attributes - meta - relationships properties: id: type: string format: uuid description: The unique identifier of the equipment certification. type: type: string const: equipment-certifications attributes: $ref: '#/components/schemas/EquipmentCertificationAttributes' meta: $ref: '#/components/schemas/EquipmentCertificationMeta' relationships: $ref: '#/components/schemas/EquipmentCertificationRelationships' 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 EquipmentItemRelationship: type: object description: Represents a relationship to an equipment item required: - id - type properties: id: type: string format: uuid description: The unique identifier for the equipment item type: type: string const: equipment-items EquipmentCertificationRelationship: type: object description: Represents a relationship to an equipment certification required: - id - type properties: id: type: string format: uuid description: The unique identifier of the equipment certification type: type: string const: equipment-certifications 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 properties: teams: type: object description: Team-related settings for the organisation. properties: customer_representatives: type: array description: > IDs of teams within this organisation whose members act as customer service representatives. Each entry must reference a team that belongs to this organisation. items: type: string format: uuid uniqueItems: true examples: - - b234c567-8901-2345-6789-abcdef012345 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' EquipmentItemAttributes: type: object description: Attributes for an equipment item required: - reference - serial - asset_number allOf: - if: properties: vibration_source: const: true required: - vibration_source then: required: - vibration_magnitude properties: vibration_magnitude: type: number else: not: required: - vibration_magnitude properties: reference: type: string description: The reference for the equipment item. examples: - REF-001 serial: type: string description: The serial number of the equipment item. examples: - CH-001 asset_number: type: string description: >- The asset number for the equipment item (unique within the organisation). examples: - A-12345 is_rented: type: boolean description: Whether the equipment item is rented rather than owned. purchased_at: type: - string - 'null' format: date description: The date the equipment item was purchased (date only). examples: - '2024-01-15T00:00:00.000Z' vibration_source: type: boolean description: Whether the equipment item is a source of hand-arm vibration. vibration_magnitude: type: - number - 'null' description: > The vibration magnitude in m/s². Required when vibration_source is true and must be omitted otherwise. examples: - 2.7 description: type: - string - 'null' description: An optional description of the equipment item. status: type: - string - 'null' description: The equipment item's status (e.g. active, retired, in-service). EquipmentItemMeta: type: object description: Metadata for an equipment item required: - created_at - updated_at properties: created_at: type: string format: date-time description: The date and time when the equipment item was created updated_at: type: string format: date-time description: The date and time when the equipment item was last updated EquipmentItemRelationships: type: object description: > Relationships for an equipment item. `manufacturer` and `model` are both optional; if `model` is set then `manufacturer` is also set and the model belongs to that manufacturer. required: - organisation properties: organisation: type: object required: - data properties: data: $ref: '#/components/schemas/OrganisationRelationship' manufacturer: type: object properties: data: oneOf: - $ref: '#/components/schemas/EquipmentManufacturerRelationship' - type: 'null' model: type: object properties: data: oneOf: - $ref: '#/components/schemas/EquipmentModelRelationship' - type: 'null' vehicle: type: object properties: data: oneOf: - $ref: '#/components/schemas/VehicleRelationship' - type: 'null' location: type: object properties: data: oneOf: - $ref: '#/components/schemas/LocationRelationship' - type: 'null' business_area: type: object required: - data properties: data: $ref: '#/components/schemas/BusinessAreaRelationship' owner: type: object required: - data properties: data: oneOf: - $ref: '#/components/schemas/OwnerRelationship' - type: 'null' status: type: object required: - data properties: data: oneOf: - $ref: '#/components/schemas/EquipmentStatusRelationship' - type: 'null' categories: type: object description: The categories assigned directly to this item. required: - data properties: data: type: array items: $ref: '#/components/schemas/EquipmentCategoryRelationship' inherited_categories: type: object readOnly: true description: >- Read-only. The categories this item inherits from its model, copied onto the item when its model or model assignment changes. Not accepted on write. required: - data properties: data: type: array items: $ref: '#/components/schemas/EquipmentCategoryRelationship' certifications: type: object readOnly: true description: >- Read-only. The certifications this item is required to hold (its required-certification list). Managed via the item's /relationships/certifications endpoints, not accepted on item write. required: - data properties: data: type: array items: $ref: '#/components/schemas/EquipmentCertificationRelationship' EquipmentCertificationAttributes: type: object description: Attributes for an equipment certification required: - name properties: name: type: string description: The name of the equipment certification. examples: - PAT Test description: type: - string - 'null' description: A description of the equipment certification. renewal_period: type: - integer - 'null' minimum: 1 description: The number of days between renewals. Null if no renewal is required. examples: - 365 high_risk_duration: type: - integer - 'null' minimum: 1 description: >- Days before expiry at which high risk begins. Null if not configured. medium_risk_duration: type: - integer - 'null' minimum: 1 description: >- Days before expiry at which medium risk begins. Requires high_risk_duration to be set and must be greater than or equal to high_risk_duration. low_risk_duration: type: - integer - 'null' minimum: 1 description: >- Days before expiry at which low risk begins. Requires medium_risk_duration to be set and must be greater than or equal to medium_risk_duration. EquipmentCertificationMeta: type: object description: Metadata for an equipment certification required: - created_at - updated_at properties: created_at: type: string format: date-time updated_at: type: string format: date-time EquipmentCertificationRelationships: type: object description: Relationships for an equipment certification required: - organisation properties: organisation: type: object required: - data properties: data: $ref: '#/components/schemas/OrganisationRelationship' 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 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 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 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 EquipmentManufacturerRelationship: type: object description: Represents a relationship to an equipment manufacturer required: - id - type properties: id: type: string format: uuid description: The unique identifier for the equipment manufacturer type: type: string const: equipment-manufacturers EquipmentModelRelationship: type: object description: Represents a relationship to an equipment model required: - id - type properties: id: type: string format: uuid description: The unique identifier for the equipment model type: type: string const: equipment-models VehicleRelationship: type: object description: Represents a relationship to a vehicle required: - id - type properties: id: type: string format: uuid description: The unique identifier of the vehicle type: type: string const: vehicles LocationRelationship: type: object description: Represents a relationship to a location required: - id - type properties: id: type: string format: uuid description: The unique identifier of the location type: type: string const: locations BusinessAreaRelationship: type: object description: Represents a relationship to a business area required: - id - type properties: id: type: string format: uuid description: The unique identifier of the business area type: type: string const: business-areas OwnerRelationship: type: object description: Represents a relationship to an owner required: - id - type properties: id: type: string format: uuid description: The unique identifier of the owner type: type: string const: owners EquipmentStatusRelationship: type: object description: Represents a relationship to an equipment status required: - id - type properties: id: type: string format: uuid description: The unique identifier of the equipment status type: type: string const: equipment-statuses EquipmentCategoryRelationship: type: object description: Represents a relationship to an equipment category required: - id - type properties: id: type: string format: uuid description: The unique identifier of the equipment category type: type: string const: equipment-categories 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 ````