openapi: 3.0.0 info: title: Capmo REST Organisation Companies Project Site Journals API description: External REST API Documentation for Capmo version: '1.0' contact: {} servers: - url: https://api.capmo.de description: Production tags: - name: Project Site Journals description: '' paths: /api/v1/projects/{projectId}/site-journals: get: description: Gets all the site journals in a paginated response. operationId: getSiteJournalsPaginated parameters: - name: order_by required: false in: query description: Field to order by. schema: default: server_created_at example: server_updated_at type: string enum: - server_created_at - server_updated_at - date - name: order_direction required: false in: query description: Order direction of the `order_by` field. It can be `asc` or `desc`. schema: default: asc example: asc type: string enum: - asc - desc - name: after required: false in: query description: The last element from the previous page. This is a cursor. It will be returned in the output to be used in the next request. When it is not present, the first page is returned. When it is `null`, there are no more pages. schema: type: string - name: limit required: false in: query description: How many items should be in the output. schema: minimum: 1 maximum: 1000 default: 200 example: 20 type: number - name: projectId required: true in: path schema: type: string - name: Request-Id in: header description: The HTTP `Request-Id` request header is an optional and unofficial HTTP header, used to trace individual HTTP requests from the client to the server and back again. It allows the client and server to correlate each HTTP request. If not provided by the client, the server should generate a unique request ID and include it in the response. schema: {} responses: '200': description: The site journals have been successfully retrieved. content: application/json: schema: type: object properties: message: type: string example: Success data: allOf: - $ref: '#/components/schemas/PaginatedOutputDto' - properties: items: type: array items: $ref: '#/components/schemas/ReadSiteJournalDto' '400': description: Bad request, Invalid input content: application/json: schema: type: object properties: type: type: string example: https://capmoapi.readme.io/reference/errors#bad-request message: type: string example: An error occurred errors: type: array items: type: object properties: code: type: string example: BAD_REQUEST message: type: string example: Bad request '401': description: Unauthorized content: application/json: schema: type: object properties: type: type: string example: https://capmoapi.readme.io/reference/errors#unauthorized message: type: string example: An error occurred errors: type: array items: type: object properties: code: type: string example: UNAUTHORIZED message: type: string example: Unauthorized '403': description: Forbidden content: application/json: schema: type: object properties: type: type: string example: https://capmoapi.readme.io/reference/errors#forbidden message: type: string example: An error occurred errors: type: array items: type: object properties: code: type: string example: FORBIDDEN message: type: string example: Forbidden '500': description: Internal server error content: application/json: schema: type: object properties: type: type: string example: https://capmoapi.readme.io/reference/errors#internal-server-error message: type: string example: An error occurred errors: type: array items: type: object properties: code: type: string example: INTERNAL_SERVER_ERROR message: type: string example: Internal server error security: - CapmoAuth: [] summary: '' tags: - Project Site Journals post: description: Creates a new project site journal. operationId: createSiteJournal parameters: - name: projectId required: true in: path description: The unique identifier of the project. schema: example: 123e4567-e89b-12d3-a456-426614174000 type: string - name: Request-Id in: header description: The HTTP `Request-Id` request header is an optional and unofficial HTTP header, used to trace individual HTTP requests from the client to the server and back again. It allows the client and server to correlate each HTTP request. If not provided by the client, the server should generate a unique request ID and include it in the response. schema: {} requestBody: required: true description: The data required to create a project site journal. content: application/json: schema: $ref: '#/components/schemas/CreateSiteJournalDto' responses: '201': description: Site journal successfully created. content: application/json: schema: type: object properties: message: type: string example: Success data: $ref: '#/components/schemas/ReadSiteJournalDto' '400': description: Bad request, Invalid input content: application/json: schema: type: object properties: type: type: string example: https://capmoapi.readme.io/reference/errors#bad-request message: type: string example: An error occurred errors: type: array items: type: object properties: code: type: string example: BAD_REQUEST message: type: string example: Bad request '401': description: Unauthorized content: application/json: schema: type: object properties: type: type: string example: https://capmoapi.readme.io/reference/errors#unauthorized message: type: string example: An error occurred errors: type: array items: type: object properties: code: type: string example: UNAUTHORIZED message: type: string example: Unauthorized '403': description: Forbidden content: application/json: schema: type: object properties: type: type: string example: https://capmoapi.readme.io/reference/errors#forbidden message: type: string example: An error occurred errors: type: array items: type: object properties: code: type: string example: FORBIDDEN message: type: string example: Forbidden '409': description: Conflict content: application/json: schema: type: object properties: type: type: string example: https://capmoapi.readme.io/reference/errors#conflict message: type: string example: An error occurred errors: type: array items: type: object properties: code: type: string example: CONFLICT message: type: string example: Conflict '500': description: Internal server error content: application/json: schema: type: object properties: type: type: string example: https://capmoapi.readme.io/reference/errors#internal-server-error message: type: string example: An error occurred errors: type: array items: type: object properties: code: type: string example: INTERNAL_SERVER_ERROR message: type: string example: Internal server error security: - CapmoAuth: [] summary: '' tags: - Project Site Journals /api/v1/projects/{projectId}/site-journals/{siteJournalId}: get: description: Retrieves a single project site journal by ID. operationId: getSiteJournal parameters: - name: projectId required: true in: path description: The unique identifier of the project. schema: example: 123e4567-e89b-12d3-a456-426614174000 type: string - name: siteJournalId required: true in: path description: The unique identifier of the site journal. schema: example: 123e4567-e89b-12d3-a456-426614174000 type: string - name: Request-Id in: header description: The HTTP `Request-Id` request header is an optional and unofficial HTTP header, used to trace individual HTTP requests from the client to the server and back again. It allows the client and server to correlate each HTTP request. If not provided by the client, the server should generate a unique request ID and include it in the response. schema: {} responses: '200': description: The project site journal has been successfully retrieved. content: application/json: schema: type: object properties: message: type: string example: Success data: $ref: '#/components/schemas/ReadSiteJournalDto' '400': description: Bad request, Invalid input content: application/json: schema: type: object properties: type: type: string example: https://capmoapi.readme.io/reference/errors#bad-request message: type: string example: An error occurred errors: type: array items: type: object properties: code: type: string example: BAD_REQUEST message: type: string example: Bad request '401': description: Unauthorized content: application/json: schema: type: object properties: type: type: string example: https://capmoapi.readme.io/reference/errors#unauthorized message: type: string example: An error occurred errors: type: array items: type: object properties: code: type: string example: UNAUTHORIZED message: type: string example: Unauthorized '403': description: Forbidden content: application/json: schema: type: object properties: type: type: string example: https://capmoapi.readme.io/reference/errors#forbidden message: type: string example: An error occurred errors: type: array items: type: object properties: code: type: string example: FORBIDDEN message: type: string example: Forbidden '404': description: Object not found content: application/json: schema: type: object properties: type: type: string example: https://capmoapi.readme.io/reference/errors#not-found message: type: string example: An error occurred errors: type: array items: type: object properties: code: type: string example: NOT_FOUND message: type: string example: Object not found '500': description: Internal server error content: application/json: schema: type: object properties: type: type: string example: https://capmoapi.readme.io/reference/errors#internal-server-error message: type: string example: An error occurred errors: type: array items: type: object properties: code: type: string example: INTERNAL_SERVER_ERROR message: type: string example: Internal server error security: - CapmoAuth: [] summary: '' tags: - Project Site Journals patch: description: Updates a project site journal. When the properties to be updated are objects, they are completely replaced. This means that attendances, visits or weather observation will always be replaced in case of an update. operationId: updateSiteJournal parameters: - name: projectId required: true in: path description: The unique identifier of the project. schema: example: 123e4567-e89b-12d3-a456-426614174000 type: string - name: siteJournalId required: true in: path description: The unique identifier of the site journal. schema: example: 123e4567-e89b-12d3-a456-426614174000 type: string - name: Request-Id in: header description: The HTTP `Request-Id` request header is an optional and unofficial HTTP header, used to trace individual HTTP requests from the client to the server and back again. It allows the client and server to correlate each HTTP request. If not provided by the client, the server should generate a unique request ID and include it in the response. schema: {} requestBody: required: true description: The data required to update a project site journal. content: application/json: schema: $ref: '#/components/schemas/UpdateSiteJournalDto' responses: '200': description: The project site journal has been successfully updated. content: application/json: schema: type: object properties: message: type: string example: Success data: $ref: '#/components/schemas/ReadSiteJournalDto' '400': description: Bad request, Invalid input content: application/json: schema: type: object properties: type: type: string example: https://capmoapi.readme.io/reference/errors#bad-request message: type: string example: An error occurred errors: type: array items: type: object properties: code: type: string example: BAD_REQUEST message: type: string example: Bad request '401': description: Unauthorized content: application/json: schema: type: object properties: type: type: string example: https://capmoapi.readme.io/reference/errors#unauthorized message: type: string example: An error occurred errors: type: array items: type: object properties: code: type: string example: UNAUTHORIZED message: type: string example: Unauthorized '403': description: Forbidden content: application/json: schema: type: object properties: type: type: string example: https://capmoapi.readme.io/reference/errors#forbidden message: type: string example: An error occurred errors: type: array items: type: object properties: code: type: string example: FORBIDDEN message: type: string example: Forbidden '404': description: Object not found content: application/json: schema: type: object properties: type: type: string example: https://capmoapi.readme.io/reference/errors#not-found message: type: string example: An error occurred errors: type: array items: type: object properties: code: type: string example: NOT_FOUND message: type: string example: Object not found '500': description: Internal server error content: application/json: schema: type: object properties: type: type: string example: https://capmoapi.readme.io/reference/errors#internal-server-error message: type: string example: An error occurred errors: type: array items: type: object properties: code: type: string example: INTERNAL_SERVER_ERROR message: type: string example: Internal server error security: - CapmoAuth: [] summary: '' tags: - Project Site Journals delete: description: This endpoint deletes a project site journal and all its associated entries (company attendances, visits, weather observations). operationId: deleteSiteJournal parameters: - name: projectId required: true in: path description: The unique identifier of the project. schema: example: 123e4567-e89b-12d3-a456-426614174000 type: string - name: siteJournalId required: true in: path description: The unique identifier of the site journal. schema: example: 123e4567-e89b-12d3-a456-426614174000 type: string - name: Request-Id in: header description: The HTTP `Request-Id` request header is an optional and unofficial HTTP header, used to trace individual HTTP requests from the client to the server and back again. It allows the client and server to correlate each HTTP request. If not provided by the client, the server should generate a unique request ID and include it in the response. schema: {} responses: '200': description: The project site journal has been successfully deleted. '400': description: Bad request, Invalid input content: application/json: schema: type: object properties: type: type: string example: https://capmoapi.readme.io/reference/errors#bad-request message: type: string example: An error occurred errors: type: array items: type: object properties: code: type: string example: BAD_REQUEST message: type: string example: Bad request '401': description: Unauthorized content: application/json: schema: type: object properties: type: type: string example: https://capmoapi.readme.io/reference/errors#unauthorized message: type: string example: An error occurred errors: type: array items: type: object properties: code: type: string example: UNAUTHORIZED message: type: string example: Unauthorized '403': description: Forbidden content: application/json: schema: type: object properties: type: type: string example: https://capmoapi.readme.io/reference/errors#forbidden message: type: string example: An error occurred errors: type: array items: type: object properties: code: type: string example: FORBIDDEN message: type: string example: Forbidden '404': description: Object not found content: application/json: schema: type: object properties: type: type: string example: https://capmoapi.readme.io/reference/errors#not-found message: type: string example: An error occurred errors: type: array items: type: object properties: code: type: string example: NOT_FOUND message: type: string example: Object not found '500': description: Internal server error content: application/json: schema: type: object properties: type: type: string example: https://capmoapi.readme.io/reference/errors#internal-server-error message: type: string example: An error occurred errors: type: array items: type: object properties: code: type: string example: INTERNAL_SERVER_ERROR message: type: string example: Internal server error security: - CapmoAuth: [] summary: '' tags: - Project Site Journals components: schemas: SiteJournalCustomTextDto: type: object properties: text: type: string nullable: true description: Free-form text content for this custom text entry. example: Foundation work completed on the east wing. required: - text SiteJournalVisitDto: type: object properties: started_at: type: string nullable: true example: '11:00' description: The start time (HH:mm) of a specific project stakeholder visit. ended_at: type: string nullable: true example: '12:00' description: The end time (HH:mm) of a specific project stakeholder visit. visitor_id: type: string nullable: true example: 123e4567-e89b-12d3-a456-426614174000 description: The unique identifier (UUID) of the contact person who visited. qualification: type: string nullable: true enum: - CONSTRUCTION_WORKER - SITE_MANAGER - SKILLED_WORKER - HELPER - ASSISTANT_WORKER - FOREMAN - FITTER - ASSEMBLY_SUPERVISOR - SENIOR_SITE_MANAGER - SENIOR_FITTER - SENIOR_FOREMAN - FOREMAN_CONSTRUCTION - PROJECT_MANAGER - PROJECT_PLANNER - SUPERVISOR - MASTER_FOREMAN - OTHER example: CONSTRUCTION_WORKER description: The job title/qualification of the visitor. required: - started_at - ended_at - visitor_id - qualification PaginatedOutputDto: type: object properties: after: type: string example: null count: type: number example: 1 total: type: number example: 1 required: - after - count - total CreateSiteJournalDto: type: object properties: source_id: type: string description: The unique identifier of the source. This is a user-generated string. You can use this to link the person to a resource in an external system. example: 123e4567-e89b-12d3-a456-426614174000 date: type: string description: The date of the site journal in ISO format (YYYY-MM-DD). example: '2025-01-13' visits: description: Records the time intervals of visits. type: array items: $ref: '#/components/schemas/SiteJournalVisitDto' weather_observation: type: object description: The description of the weather for the given day. company_attendances: description: Describes the attendance, namely how many people and which company they belong. type: array items: $ref: '#/components/schemas/SiteJournalCompanyAttendanceDto' custom_texts: description: Free-form custom text entries. type: array items: $ref: '#/components/schemas/SiteJournalCustomTextDto' required: - date UpdateSiteJournalDto: type: object properties: source_id: type: string description: The unique identifier of the source. This is a user-generated string. You can use this to link the person to a resource in an external system. example: 123e4567-e89b-12d3-a456-426614174000 date: type: string description: The date of the site journal in ISO format (YYYY-MM-DD). example: '2025-01-13' visits: description: Records the time intervals of visits. type: array items: $ref: '#/components/schemas/SiteJournalVisitDto' weather_observation: type: object description: The description of the weather for the given day. company_attendances: description: Describes the attendance, namely how many people and which company they belong. type: array items: $ref: '#/components/schemas/SiteJournalCompanyAttendanceDto' custom_texts: description: Free-form custom text entries. type: array items: $ref: '#/components/schemas/SiteJournalCustomTextDto' SiteJournalWorkerEntryDto: type: object properties: id: type: string example: 123e4567-e89b-12d3-a456-426614174000 description: The unique identifier (UUID) of the worker entry. started_at: type: string nullable: true example: 08:00 description: The start time (HH:mm) of the worker entry. ended_at: type: string nullable: true example: '17:00' description: The end time (HH:mm) of the worker entry. duration: type: number nullable: true example: 480 description: Duration in minutes. worker_id: type: string nullable: true example: 123e4567-e89b-12d3-a456-426614174000 description: The unique identifier (UUID) of the worker (contact book person). qualification: type: string nullable: true enum: - CONSTRUCTION_WORKER - SITE_MANAGER - SKILLED_WORKER - HELPER - ASSISTANT_WORKER - FOREMAN - FITTER - ASSEMBLY_SUPERVISOR - SENIOR_SITE_MANAGER - SENIOR_FITTER - SENIOR_FOREMAN - FOREMAN_CONSTRUCTION - PROJECT_MANAGER - PROJECT_PLANNER - SUPERVISOR - MASTER_FOREMAN - OTHER example: CONSTRUCTION_WORKER description: The qualification of the worker. required: - id - started_at - ended_at - duration - worker_id - qualification ReadSiteJournalDto: type: object properties: source_id: type: string description: The unique identifier of the source. This is a user-generated string. You can use this to link the person to a resource in an external system. example: 123e4567-e89b-12d3-a456-426614174000 id: type: string example: 123e4567-e89b-12d3-a456-426614174000 description: The unique identifier of the site journal. date: type: string description: The date of the site journal in ISO format (YYYY-MM-DD). example: '2025-01-13' project_id: type: string description: The unique identifier of the project. example: adc99411-eaa2-11e9-11ed-efee563cda11 weather_observation: type: object description: The description of the weather for the given day. visits: description: Records the time interval of the visit. type: array items: type: string company_attendances: description: Describes the attendance, namely how many people and which company they belong to. type: array items: type: string custom_texts: description: Free-form custom text entries for this site journal. type: array items: $ref: '#/components/schemas/SiteJournalCustomTextDto' required: - id - date - project_id - weather_observation - visits - company_attendances - custom_texts SiteJournalCompanyAttendanceDto: type: object properties: company_id: type: string example: 123e4567-e89b-12d3-a456-426614174000 description: The company unique identifier (UUID) associated with the attendees. headcount: type: number nullable: true example: 5 description: A positive number representing the number of attendees. Can be null. description: type: string nullable: true example: Arrived late due to traffic. description: An optional note or annotation about the attendance. worker_entries: description: Individual worker entries for this company attendance. type: array items: $ref: '#/components/schemas/SiteJournalWorkerEntryDto' required: - company_id - headcount - description securitySchemes: CapmoAuth: type: apiKey in: header name: Authorization description: 'For authentication, use the custom prefix followed by a space and then your API key. Example: "Capmo YOUR_API_KEY".' x-readme: headers: - key: Request-Id value: YOUR_REQUEST_ID