> ## 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. # Add a rate code to a cost kit > Add a rate code to a kit, at a set quantity. A cost item may be in a kit at most once: a second entry for the same rate code would make "how much of this does the kit contain" have two answers. To change the quantity, update the entry that is already there. ## OpenAPI ````yaml /api-reference/openapi.yaml post /v3/cost-kit-lines 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/cost-kit-lines: post: tags: - Costs summary: Add a rate code to a cost kit description: > Add a rate code to a kit, at a set quantity. A cost item may be in a kit at most once: a second entry for the same rate code would make "how much of this does the kit contain" have two answers. To change the quantity, update the entry that is already there. operationId: CreateCostKitLine requestBody: $ref: '#/components/requestBodies/CreateCostKitLine' responses: '201': $ref: '#/components/responses/GetCostKitLine' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorised' '409': $ref: '#/components/responses/Conflict' '500': $ref: '#/components/responses/InternalServerError' security: - Session: [] - OAuth2: [] - Cookie: [] components: requestBodies: CreateCostKitLine: required: true description: > The rate code to add to the kit. A cost item may be in a kit at most once — to change how much of it the kit contains, update the entry that is already there. content: application/vnd.api+json: schema: type: object required: - data properties: data: type: object required: - type - attributes - relationships properties: type: type: string const: cost-kit-lines attributes: type: object required: - quantity properties: quantity: type: integer format: int64 minimum: 1 description: > How much of the rate code the kit contains, in thousandths. Eight banksman hours is `8000`. examples: - 8000 note: type: string description: A note on why the kit contains this examples: - Two per gang, per the method statement relationships: type: object required: - organisation - cost_kit - cost_item properties: organisation: type: object required: - data properties: data: $ref: '#/components/schemas/OrganisationRelationship' cost_kit: type: object required: - data properties: data: $ref: '#/components/schemas/CostKitRelationship' cost_item: type: object required: - data properties: data: $ref: '#/components/schemas/CostItemRelationship' responses: GetCostKitLine: description: An individual cost kit line. 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/CostKitLine' included: $ref: '#/components/schemas/CostKitLineIncludes' - $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 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. schemas: 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 CostKitRelationship: type: object description: Represents a relationship to a cost kit required: - id - type properties: id: type: string format: uuid description: The unique identifier of the cost kit type: type: string const: cost-kits CostItemRelationship: type: object description: Represents a relationship to a cost item required: - id - type properties: id: type: string format: uuid description: The unique identifier of the cost item type: type: string const: cost-items CostKitLine: type: object description: > A cost kit line — one rate code in a kit, at a set quantity. A cost item is in a kit at most once. Membership is not time bound: applying a kit writes what the kit contains now, priced at the rate in force on the work date. required: - id - type - attributes - meta - relationships properties: id: type: string format: uuid description: The unique identifier of the cost kit line. type: type: string const: cost-kit-lines attributes: $ref: '#/components/schemas/CostKitLineAttributes' meta: $ref: '#/components/schemas/CostKitLineMeta' relationships: $ref: '#/components/schemas/CostKitLineRelationships' CostKitLineIncludes: type: array description: Related resources that can be included when a cost kit line is returned items: discriminator: propertyName: type mapping: organisations: $ref: '#/components/schemas/Organisation' cost-kits: $ref: '#/components/schemas/CostKit' cost-items: $ref: '#/components/schemas/CostItem' oneOf: - $ref: '#/components/schemas/Organisation' - $ref: '#/components/schemas/CostKit' - $ref: '#/components/schemas/CostItem' 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 CostKitLineAttributes: type: object description: Attributes for a cost kit line required: - quantity properties: quantity: type: integer format: int64 description: > How much of the rate code the kit contains, in thousandths. Eight banksman hours is `8000`. Applying the kit scales this by the number of kits asked for. examples: - 8000 note: type: string description: A note on why the kit contains this, if it is worth recording examples: - Two per gang, per the method statement CostKitLineMeta: type: object description: > Metadata for a cost kit line. There is no status here. A kit's membership is not time bound — a line is simply in the kit — so there is nothing to derive. required: - created_at - updated_at properties: created_at: type: string format: date-time description: The date and time when the cost kit line was created updated_at: type: string format: date-time description: The date and time when the cost kit line was last updated CostKitLineRelationships: type: object description: Relationships for a cost kit line properties: organisation: type: object required: - data properties: data: $ref: '#/components/schemas/OrganisationRelationship' cost_kit: type: object required: - data properties: data: $ref: '#/components/schemas/CostKitRelationship' cost_item: type: object required: - data properties: data: $ref: '#/components/schemas/CostItemRelationship' 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' CostKit: type: object description: > A cost kit — a reusable bundle of rate codes with set quantities, so a common task can be priced in one step instead of a dozen. A kit carries no rate and no total of its own. Its price is the sum of its lines at the rates in force on the day, which is a question about `cost-item-versions` and is answered behind that resource's own permission — so a kit is readable by principals who may not see money at all. required: - id - type - attributes - meta - relationships properties: id: type: string format: uuid description: The unique identifier of the cost kit. type: type: string const: cost-kits attributes: $ref: '#/components/schemas/CostKitAttributes' meta: $ref: '#/components/schemas/CostKitMeta' relationships: $ref: '#/components/schemas/CostKitRelationships' CostItem: type: object description: A cost item — a rate code in the central cost register required: - id - type - attributes - meta - relationships properties: id: type: string format: uuid description: The unique identifier of the cost item. type: type: string const: cost-items attributes: $ref: '#/components/schemas/CostItemAttributes' meta: $ref: '#/components/schemas/CostItemMeta' relationships: $ref: '#/components/schemas/CostItemRelationships' 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' CostKitAttributes: type: object description: Attributes for a cost kit required: - code - name properties: code: type: string description: > The kit's code, unique within the organisation. This is what people quote at each other, so two kits sharing one would make any reference ambiguous. examples: - KIT-002 name: type: string description: The kit's name examples: - Footway reinstatement description: type: string description: What the kit is for examples: - Make good a footway excavation. CostKitMeta: type: object description: > Metadata for a cost kit. Deliberately carries no cost, charge or margin. A kit's price comes from the rates in force on the day, and those are readable only with `cost-item-versions:view`. required: - created_at - updated_at properties: created_at: type: string format: date-time description: The date and time when the cost kit was created updated_at: type: string format: date-time description: The date and time when the cost kit was last updated CostKitRelationships: type: object description: Relationships for a cost kit properties: organisation: type: object required: - data properties: data: $ref: '#/components/schemas/OrganisationRelationship' CostItemAttributes: type: object description: Attributes for a cost item required: - code - name - category - metering - unit properties: code: type: string description: The rate code, unique within the organisation examples: - MAT-001 name: type: string description: The name of the cost item examples: - Cold lay tarmac description: type: string description: An optional description of the cost item category: $ref: '#/components/schemas/CostCategory' metering: $ref: '#/components/schemas/CostMetering' unit: type: string description: The unit the rate is priced against examples: - tonne margin: oneOf: - $ref: '#/components/schemas/CostMargin' - type: 'null' description: > The markup applied to the base rate. Null when the cost item does not set one, in which case the consuming application applies its own default. CostItemMeta: type: object description: Metadata for a cost item required: - created_at - updated_at properties: created_at: type: string format: date-time description: The date and time when the cost item was created updated_at: type: string format: date-time description: The date and time when the cost item was last updated CostItemRelationships: type: object description: Relationships for a cost item 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 CostCategory: type: string description: The kind of spend a cost item represents enum: - material - labour - misc - contractor CostMetering: type: string description: | How a cost item is measured when it is applied to a job. - `time` — charged for the time spent, billed by the hour - `day_rate` — charged as a flat rate for each working day - `volume` — charged by the quantity of material used - `fixed` — a fixed charge applied once enum: - time - day_rate - volume - fixed CostMargin: type: object description: > The markup applied on top of a base cost to reach the charge (sell) rate. Exactly one of `percentage` or `fixed` is set, chosen by `type`. required: - type properties: type: type: string description: Whether the markup is a proportion of the cost or a flat amount enum: - percentage - fixed percentage: type: - integer - 'null' description: > The markup in basis points when `type` is `percentage` — 1200 is 12.00%. Basis points keep a margin expressed to two decimal places exact. minimum: 0 examples: - 1200 fixed: oneOf: - $ref: '#/components/schemas/Money' - type: 'null' description: The flat amount added to the cost when `type` is `fixed` Money: type: object description: > A monetary amount held in the currency's minor units (pence for GBP) alongside its ISO 4217 currency code. Amounts are never decimals, so repeated arithmetic cannot accumulate rounding error. required: - amount - currency properties: amount: type: integer format: int64 description: >- The amount in the currency's minor units, for example 9250 for GBP 92.50 examples: - 9250 currency: type: string description: The ISO 4217 alphabetic currency code minLength: 3 maxLength: 3 pattern: ^[A-Z]{3}$ examples: - GBP 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 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 ````