{ "openapi": "3.0.0", "info": { "title": "BuildPass API", "description": "Approved integrators can connect to the BuildPass API on behalf of builders to build connections between a wide range of construction platforms.", "version": "1.0.0" }, "servers": [ { "url": "https://api.buildpass.global", "description": "Production server" } ], "components": { "securitySchemes": { "OAuth2": { "type": "oauth2", "flows": { "clientCredentials": { "tokenUrl": "https://api.buildpass.global/oauth/token", "scopes": { "read:subcontractors": "Read subcontractors", "write:subcontractors": "Write subcontractors", "read:prequalifications": "Read prequalifications", "write:prequalifications": "Write prequalifications", "read:insurances": "Read insurances", "write:insurances": "Write insurances", "read:contacts": "Read contacts", "read:swms": "Read SWMS", "read:timesheets": "Read timesheets", "read:inductions": "Read inductions", "read:meetings": "Read meetings", "write:meetings": "Write meetings", "read:photos": "Read photos and photo folders", "write:photos": "Create, update, delete, and sync photos and photo folders" } } } } }, "schemas": { "Integration": { "type": "object", "properties": { "type": { "type": "string", "enum": ["PROCORE"], "example": "PROCORE" }, "sourceId": { "type": "string", "example": "1234567890" }, "companyId": { "type": "string", "example": "1234567890" } } }, "Project": { "type": "object", "properties": { "id": { "type": "string", "example": "proj_clgbsb90b001qjy0f0eo1hspp" }, "status": { "type": "string", "enum": ["ARCHIVED", "COMPLETE", "IN_PROGRESS", "UPCOMING"], "example": "UPCOMING" }, "createdAt": { "type": "string", "format": "date-time", "example": "2023-10-03T23:19:35.771Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2023-10-03T23:19:35.771Z" }, "name": { "type": "string", "example": "Downtown Mall Construction" }, "integrations": { "type": "array", "items": { "$ref": "#/components/schemas/Integration" } } } }, "Address": { "type": "object", "properties": { "street": { "type": "string", "example": "123 Fake Street" }, "suburb": { "type": "string", "example": "Springfield" }, "state": { "type": "string", "example": "QLD" }, "postcode": { "type": "string", "example": "4000" }, "country": { "type": "string", "example": "Australia" } } }, "Builder": { "type": "object", "properties": { "id": { "type": "string", "example": "buil_clgbsb90b001qjy0f0eo1hspp" }, "createdAt": { "type": "string", "format": "date-time", "example": "2023-10-03T23:19:35.771Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2023-10-03T23:19:35.771Z" }, "logoUrl": { "type": "string", "nullable": true, "description": "A signed URL for the builder's company logo when one is configured.", "example": "https://bp-signed-assets.example.com/logo.png?X-Amz-Signature=..." }, "name": { "type": "string", "example": "BuildPass Constructions" } } }, "Subcontractor": { "type": "object", "properties": { "id": { "type": "string", "example": "sub_clgbsb90b001qjy0f0eo1hspp" }, "createdAt": { "type": "string", "format": "date-time", "example": "2023-10-03T23:19:35.771Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2023-10-03T23:19:35.771Z" }, "name": { "type": "string", "example": "Andrews Brick Laying" }, "abn": { "type": "string", "example": "98765432100" }, "address": { "$ref": "#/components/schemas/Address" }, "statuses": { "type": "array", "enum": [ "NOT_INVITED", "INVITED", "SWMS_UPLOADED", "INSURANCES_UPLOADED", "SWMS_REVIEWED", "INSURANCES_REVIEWED" ], "example": ["INVITED", "SWMS_UPLOADED"] }, "tags": { "type": "array", "items": { "type": "string" }, "example": ["bricklayer"] }, "integrations": { "type": "array", "items": { "$ref": "#/components/schemas/Integration" } } } }, "PaginationMeta": { "type": "object", "properties": { "totalCount": { "type": "integer", "description": "How many total items there are.", "example": 100 }, "totalPages": { "type": "integer", "description": "How many pages there are based on your offset and limit.", "example": 4 }, "offset": { "type": "integer", "description": "How many items skipped before starting to collect the result set.", "example": 0 }, "limit": { "type": "integer", "description": "How many items you requested to return.", "example": 25 } } }, "PaginatedResponseProject": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "PaginatedResponseSubcontractor": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Subcontractor" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "PaginatedResponseBuilder": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Builder" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "PaginatedResponsePrequalification": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Prequalification" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "PaginatedResponseInsurance": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Insurance" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "PaginatedResponseContact": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "PaginatedResponseSwms": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Swms" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "ErrorResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "fieldName": { "type": "string", "example": "name" }, "message": { "type": "string", "example": "This field is required." } } } } } }, "OAuthErrorResponse": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "invalid_request", "invalid_client", "invalid_grant", "unauthorized_client", "unsupported_grant_type", "invalid_scope" ], "description": "OAuth 2.0 error code as defined in RFC 6749", "example": "invalid_client" }, "error_description": { "type": "string", "description": "Human-readable description of the error", "example": "Invalid client credentials" }, "error_uri": { "type": "string", "description": "Optional URI for more information about the error", "example": "https://tools.ietf.org/html/rfc6749#section-5.2" } }, "required": ["error"] }, "TokenRequest": { "type": "object", "properties": { "client_id": { "type": "string", "description": "Your client ID. Can be provided in request body or via HTTP Basic Authentication.", "example": "your_client_id" }, "client_secret": { "type": "string", "description": "Your client secret. Can be provided in request body or via HTTP Basic Authentication.", "example": "your_client_secret" }, "scope": { "type": "string", "description": "The scopes you want to request access to. Available: `read:builders`, `read:subcontractors`, `read:prequalifications`, `read:insurances`, `read:swms`, `read:timesheets`, `read:contacts`, `read:inductions`, `read:meetings`, `write:meetings`.", "example": "read:builders read:subcontractors read:prequalifications read:insurances" }, "audience": { "type": "string", "description": "The audience for the token (resource server identifier).", "enum": ["https://api.buildpass.global"], "example": "https://api.buildpass.global" }, "grant_type": { "type": "string", "description": "The grant type you want to use. Currently only `client_credentials` is supported.", "enum": ["client_credentials"], "example": "client_credentials" } }, "required": ["scope", "audience", "grant_type"] }, "TokenResponse": { "type": "object", "properties": { "access_token": { "type": "string", "description": "The access token that can be used in the Authorization header to access the API.", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, "token_type": { "type": "string", "description": "The type of token that was issued.", "example": "Bearer" }, "expires_in": { "type": "integer", "description": "The number of seconds until the token expires.", "example": 3600 }, "expires": { "type": "integer", "description": "The number of seconds until the token expires. Deprecated, use expires_in instead.", "example": 3600 }, "scope": { "type": "string", "description": "The scopes that were granted for this token.", "example": "read:builders read:subcontractors" } }, "required": ["access_token", "token_type", "expires_in"] }, "Prequalification": { "type": "object", "properties": { "id": { "type": "string", "example": "prequal_clgbsb90b001qjy0f0eo1hspp" }, "createdAt": { "type": "string", "format": "date-time", "example": "2023-10-03T23:19:35.771Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2023-10-03T23:19:35.771Z" }, "status": { "type": "string", "enum": ["APPROVED", "REJECTED", "WAITING_REVIEW", "SENT"], "example": "WAITING_REVIEW" }, "reviewComments": { "type": "string", "example": "Needs further documentation." } } }, "Insurance": { "type": "object", "properties": { "id": { "type": "string", "example": "doc_clgbsb90b001qjy0f0eo1hspp" }, "createdAt": { "type": "string", "format": "date-time", "example": "2023-10-03T23:19:35.771Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2023-10-03T23:19:35.771Z" }, "expiry": { "type": "string", "format": "date-time", "example": "2023-10-03T23:19:35.771Z" }, "name": { "type": "string", "example": "Safety Certificate" }, "type": { "type": "string", "enum": ["PUBLIC_LIABILITY", "WORK_COVER", "OTHER"] }, "customType": { "type": "string", "example": "SDS" }, "status": { "type": "string", "enum": ["CHANGES_REQUESTED", "REVIEWED", "WAITING_REVIEW"], "example": "WAITING_REVIEW" }, "url": { "type": "string", "format": "uri" } } }, "Contact": { "type": "object", "properties": { "id": { "type": "string", "example": "con_clgbsb90b001qjy0f0eo1hspp" }, "createdAt": { "type": "string", "format": "date-time", "example": "2023-10-03T23:19:35.771Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2023-10-03T23:19:35.771Z" }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "john.doe@example.com" }, "phone": { "type": "string", "example": "+61401123456" }, "isPrimary": { "type": "boolean", "example": true }, "type": { "type": "string", "enum": ["SUBCONTRACTOR", "CLIENT", "SITE_MANAGER", "HSR", "OTHER"], "example": "SUBCONTRACTOR" }, "projectIds": { "type": "array", "items": { "type": "string", "example": "proj_clgbsb90b001qjy0f0eo1hspp" } } } }, "Swms": { "type": "object", "properties": { "id": { "type": "string", "example": "swms_clgbsb90b001qjy0f0eo1hspp", "description": "The ID of the SWMS document" }, "createdAt": { "type": "string", "format": "date-time", "example": "2023-10-03T23:19:35.771Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2023-10-03T23:19:35.771Z" }, "name": { "type": "string", "example": "SWMS Document" }, "status": { "type": "string", "enum": ["REVIEWED", "WAITING_REVIEW", "CHANGES_REQUESTED"], "example": "WAITING_REVIEW" }, "url": { "type": "string", "format": "uri", "example": "https://example.com/swms_document.pdf" } } }, "X-BuildPass-Builder-Id": { "type": "string", "example": "buil_clgbsb90b001qjy0f0eo1hspp", "description": "Call the /builders endpoint to get a builder ID" }, "X-BuildPass-Api-Version": { "type": "string", "example": "v1", "default": "v1", "enum": ["v1"], "description": "What API version to use." }, "Timesheet": { "type": "object", "properties": { "id": { "type": "string", "example": "ts_clgbsb90b001qjy0f0eo1hspp" }, "status": { "type": "string", "enum": ["APPROVED_1", "APPROVED_2", "REJECTED", "WAITING_REVIEW"], "example": "WAITING_REVIEW" }, "createdAt": { "type": "string", "format": "date-time", "example": "2023-10-03T23:19:35.771Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2023-10-03T23:19:35.771Z" }, "date": { "type": "string", "format": "date-time", "example": "2023-10-03T23:19:35.771Z" }, "hours": { "type": "number", "example": 10 }, "notes": { "type": "string", "example": "This is a note" }, "timeType": { "type": "string", "example": "Annual Leave" }, "costCode": { "type": "string", "example": "001 - Foundation" }, "timesheetGroupId": { "type": "string", "example": "tsg_clgbsb90b001qjy0f0eo1hspp" }, "profile": { "type": "object", "properties": { "id": { "type": "string", "example": "pers_clgbsb90b001qjy0f0eo1hspp" }, "fullName": { "type": "string", "example": "John Doe" }, "type": { "type": "string", "example": "worker" } } }, "project": { "type": "object", "properties": { "id": { "type": "string", "example": "project_clgbsb90b001qjy0f0eo1hspp" }, "name": { "type": "string", "example": "Project 1" } } } } }, "PaginatedResponseTimesheet": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Timesheet" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "TimesheetTimeTypes": { "type": "object", "properties": { "data": { "type": "array", "items": { "properties": { "id": { "type": "string", "example": "tstt_1" }, "name": { "type": "string", "example": "Annual Leave" } } } } } }, "TimesheetCostCodes": { "type": "object", "properties": { "data": { "type": "array", "items": { "properties": { "id": { "type": "string", "example": "tscc_clgbsb90b001qjy0f0eo1hspp" }, "code": { "type": "string", "example": "001" }, "description": { "type": "string", "example": "Concrete Foundation" } } } } } }, "Induction": { "type": "object", "properties": { "id": { "type": "string", "example": "ind_clgbsb90b001qjy0f0eo1hspp", "description": "The ID of the induction" }, "identifier": { "type": "number", "nullable": true, "example": 1, "description": "The project-specific identifier for the induction" }, "createdAt": { "type": "string", "format": "date-time", "example": "2023-10-03T23:19:35.771Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2023-10-03T23:19:35.771Z" }, "type": { "type": "string", "enum": ["BUILDER_INDUCTION", "PROJECT_INDUCTION"], "example": "PROJECT_INDUCTION" }, "status": { "type": "string", "enum": ["REVIEWED", "WAITING_REVIEW", "CHANGES_REQUESTED"], "example": "WAITING_REVIEW" }, "project": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "example": "prj_clgbsb90b001qjy0f0eo1hspp" }, "name": { "type": "string", "example": "Downtown Mall Construction" } } }, "worker": { "type": "object", "properties": { "id": { "type": "string", "example": "wkr_clgbsb90b001qjy0f0eo1hspp" }, "fullName": { "type": "string", "example": "John Doe" } } }, "subcontractor": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "example": "sub_clgbsb90b001qjy0f0eo1hspp" }, "name": { "type": "string", "example": "ABC Contractors" } } } } }, "InductionBlock": { "type": "object", "description": "A capture field in the induction form with user-provided data. Display-only fields are excluded.", "properties": { "name": { "type": "string", "example": "Emergency Contact", "description": "The name of the field, defaults to a readable version of the type if not provided" }, "type": { "type": "string", "example": "text", "description": "The type of capture field (text, select, checkbox, signature, dateTime, etc.)" }, "value": { "description": "The value provided by the user", "example": "Jane Doe" } } }, "InductionWithData": { "allOf": [ { "$ref": "#/components/schemas/Induction" }, { "type": "object", "properties": { "data": { "type": "array", "nullable": true, "description": "Array of capture fields with user-provided data from the induction form", "items": { "$ref": "#/components/schemas/InductionBlock" } } } } ] }, "PaginatedResponseInduction": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Induction" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "Meeting": { "type": "object", "properties": { "id": { "type": "string", "example": "extapitoolboxmeeting01" }, "builderId": { "type": "string", "example": "buil_clgbsb90b001qjy0f0eo1hspp" }, "projectId": { "type": "string", "example": "proj_clgbsb90b001qjy0f0eo1hscp" }, "projectName": { "type": "string", "example": "Downtown Mall Construction" }, "projectTimezone": { "type": "string", "nullable": true, "example": "Australia/Brisbane" }, "title": { "type": "string", "example": "External API seeded meeting" }, "name": { "type": "string", "example": "External API seeded meeting" }, "meetingTitle": { "type": "string", "nullable": true, "example": "External API seeded meeting" }, "meetingTypeId": { "type": "string", "nullable": true, "example": null }, "meetingTypeName": { "type": "string", "nullable": true, "example": null }, "date": { "type": "string", "format": "date-time", "example": "2026-01-15T09:00:00.000Z" }, "startAt": { "type": "string", "format": "date-time", "example": "2026-01-15T09:00:00.000Z" }, "scheduledAt": { "type": "string", "format": "date-time", "example": "2026-01-15T09:00:00.000Z" }, "status": { "type": "string", "enum": ["DRAFT", "DISTRIBUTED", "COMPLETED", "RUNNING"], "example": "DISTRIBUTED" }, "meetingStatus": { "type": "string", "enum": ["DRAFT", "DISTRIBUTED", "COMPLETED", "RUNNING"], "example": "DISTRIBUTED" }, "agenda": { "type": "string", "nullable": true, "example": "External API integration test agenda" }, "description": { "type": "string", "nullable": true, "example": "Seeded meeting for External API integration tests" }, "notes": { "type": "string", "nullable": true, "example": "Seeded meeting for External API integration tests" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-01-15T09:00:00.000Z" } } }, "MeetingCreateRequest": { "type": "object", "required": ["title"], "properties": { "title": { "type": "string", "example": "Supasite meeting" }, "projectId": { "type": "string", "example": "proj_clgbsb90b001qjy0f0eo1hscp" }, "startAt": { "type": "string", "format": "date-time", "example": "2026-01-15T09:00:00.000Z" }, "agenda": { "type": "array", "maxItems": 20, "items": { "type": "string" }, "example": ["Review site risks"] }, "notes": { "type": "string", "example": "Started from Supasite" }, "externalSourceId": { "type": "string", "example": "supasite:meeting:user_123:2026-01-15T09:00:00.000Z" }, "sourceApp": { "type": "string", "default": "external", "example": "supasite" } } }, "MeetingUpdateRequest": { "type": "object", "required": ["title"], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^(?!\\s*$).+", "description": "Meeting title (trimmed). Must be non-empty after trimming and no more than 160 characters.", "example": "Concrete Pour Planning" } } }, "MeetingLifecycleResponse": { "type": "object", "properties": { "id": { "type": "string", "example": "extapitoolboxmeeting01" }, "builderId": { "type": "string", "example": "buil_clgbsb90b001qjy0f0eo1hspp" }, "projectId": { "type": "string", "example": "proj_clgbsb90b001qjy0f0eo1hscp" }, "title": { "type": "string", "example": "Concrete Pour Planning" }, "name": { "type": "string", "example": "Concrete Pour Planning" }, "date": { "type": "string", "format": "date-time", "example": "2026-01-15T09:00:00.000Z" }, "status": { "type": "string", "enum": ["DRAFT", "DISTRIBUTED", "RUNNING", "COMPLETED"], "example": "RUNNING" }, "agenda": { "type": "string", "nullable": true, "example": "External API integration test agenda" }, "meetingTitle": { "type": "string", "nullable": true, "example": "External API seeded meeting" }, "notes": { "type": "string", "nullable": true, "example": "Seeded meeting for External API integration tests" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-01-15T09:00:00.000Z" } } }, "MeetingNote": { "type": "object", "properties": { "id": { "type": "string", "example": "mnote_clgbsb90b001qjy0f0eo1hspp" }, "builderId": { "type": "string", "example": "buil_clgbsb90b001qjy0f0eo1hspp" }, "meetingId": { "type": "string", "example": "extapitoolboxmeeting01" }, "authorAdminUserId": { "type": "string", "nullable": true, "example": null }, "source": { "type": "string", "enum": ["MANUAL"], "example": "MANUAL" }, "sourceApp": { "type": "string", "nullable": true, "example": "supasite" }, "sourceDeepLink": { "type": "string", "nullable": true, "example": "buildpass://meetings/extapitoolboxmeeting01/notes/external-note-123" }, "sourceWebLink": { "type": "string", "nullable": true, "example": "https://app.buildpass.com.au/meetings/extapitoolboxmeeting01" }, "externalSourceId": { "type": "string", "nullable": true, "example": "external-note-123" }, "title": { "type": "string", "nullable": true, "example": "Site walk note" }, "summaryMarkdown": { "type": "string", "nullable": true, "example": "Captured decisions from the site walk." }, "detailBlocks": { "type": "array", "nullable": true, "items": { "type": "object", "additionalProperties": true } }, "actionItems": { "nullable": true, "example": [ { "text": "Upload site photos" } ] }, "capturedStartedAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-01-15T12:00:00.000Z" }, "capturedEndedAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-01-15T12:10:00.000Z" }, "archivedAt": { "type": "string", "format": "date-time", "nullable": true, "example": null }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-01-15T12:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-01-15T12:00:00.000Z" } } }, "MeetingNoteUpsertRequest": { "type": "object", "properties": { "externalSourceId": { "type": "string", "example": "external-note-123" }, "sourceApp": { "type": "string", "default": "supasite", "example": "supasite" }, "sourceDeepLink": { "type": "string", "nullable": true, "example": "buildpass://meetings/extapitoolboxmeeting01/notes/external-note-123" }, "sourceWebLink": { "type": "string", "nullable": true, "example": "https://app.buildpass.com.au/meetings/extapitoolboxmeeting01" }, "title": { "type": "string", "nullable": true, "example": "Site walk note" }, "summaryMarkdown": { "type": "string", "nullable": true, "example": "Captured decisions from the site walk." }, "detailBlocks": { "type": "array", "nullable": true, "items": { "type": "object", "additionalProperties": true } }, "actionItems": { "nullable": true, "example": [ { "text": "Upload site photos" } ] }, "capturedStartedAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-01-15T12:00:00.000Z" }, "capturedEndedAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-01-15T12:10:00.000Z" } } }, "MeetingNotePatchRequest": { "type": "object", "properties": { "externalSourceId": { "type": "string", "example": "external-note-123" }, "sourceApp": { "type": "string", "default": "supasite", "example": "supasite" }, "sourceDeepLink": { "type": "string", "nullable": true, "example": "buildpass://meetings/extapitoolboxmeeting01/notes/external-note-123" }, "sourceWebLink": { "type": "string", "nullable": true, "example": "https://app.buildpass.com.au/meetings/extapitoolboxmeeting01" }, "title": { "type": "string", "nullable": true, "example": "Site walk note" }, "summaryMarkdown": { "type": "string", "nullable": true, "example": "Captured decisions from the site walk." }, "detailBlocks": { "type": "array", "nullable": true, "items": { "type": "object", "additionalProperties": true } }, "actionItems": { "nullable": true, "example": [ { "text": "Upload site photos" } ] }, "capturedStartedAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-01-15T12:00:00.000Z" }, "capturedEndedAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-01-15T12:10:00.000Z" } } }, "PaginatedResponseMeeting": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Meeting" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "PaginatedResponseMeetingNote": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MeetingNote" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "Photo": { "type": "object", "properties": { "id": { "type": "string" }, "builderId": { "type": "string", "nullable": true }, "projectId": { "type": "string", "nullable": true }, "folderId": { "type": "string", "nullable": true }, "fileName": { "type": "string" }, "contentType": { "type": "string" }, "key": { "type": "string" }, "fileSize": { "type": "string" }, "description": { "type": "string", "nullable": true }, "photoTakenDate": { "type": "string", "format": "date-time", "nullable": true }, "sortDate": { "type": "string", "format": "date-time", "nullable": true }, "metadata": { "type": "object", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "archivedAt": { "type": "string", "format": "date-time", "nullable": true }, "imageUrl": { "type": "string", "format": "uri", "nullable": true, "description": "Short-lived signed URL for downloading the photo image." } } }, "PhotoFolder": { "type": "object", "properties": { "id": { "type": "string" }, "builderId": { "type": "string" }, "projectId": { "type": "string", "nullable": true }, "parentId": { "type": "string", "nullable": true }, "name": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "PhotoInput": { "type": "object", "required": ["fileName"], "properties": { "projectId": { "type": "string", "example": "proj_ckproject123456789012345678" }, "folderId": { "type": "string" }, "imageAttachment": { "$ref": "#/components/schemas/AttachmentUploadReference" }, "imageUrl": { "type": "string", "format": "uri", "description": "Approved HTTPS URL to import. To import photos from your own image URL hosts, contact BuildPass so those hosts can be reviewed and enabled." }, "fileName": { "type": "string" }, "contentType": { "type": "string", "default": "image/jpeg" }, "capturedAt": { "type": "string", "format": "date-time" }, "description": { "type": "string" }, "externalSourceId": { "type": "string" } } }, "PhotoFolderInput": { "type": "object", "required": ["name"], "properties": { "projectId": { "type": "string", "example": "proj_ckproject123456789012345678" }, "parentId": { "type": "string" }, "name": { "type": "string" } } }, "PhotoGallerySyncInput": { "type": "object", "required": [ "externalSourceId", "sourceApp", "projectId", "folderName", "photos" ], "properties": { "externalSourceId": { "type": "string", "example": "supasite:photo-page:page_123" }, "folderId": { "type": "string", "description": "Existing BuildPass photo folder id for this external source. Omit on first upsert to create a new folder." }, "sourceApp": { "type": "string", "example": "supasite" }, "projectId": { "type": "string", "example": "proj_ckproject123456789012345678" }, "folderName": { "type": "string", "example": "Site walkthrough - 2026-06-11" }, "photos": { "type": "array", "items": { "type": "object", "required": [ "externalSourceId", "fileName", "contentType", "sequenceId" ], "properties": { "externalSourceId": { "type": "string" }, "imageUrl": { "type": "string", "format": "uri", "description": "Approved HTTPS URL import host enabled by BuildPass. Prefer imageAttachment from the attachment upload endpoints." }, "imageAttachment": { "$ref": "#/components/schemas/AttachmentUploadReference" }, "fileName": { "type": "string" }, "contentType": { "type": "string" }, "sequenceId": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "capturedAt": { "type": "string", "format": "date-time" } } } } } }, "PhotoGalleryDeleteInput": { "type": "object", "required": ["externalSourceId", "projectId"], "properties": { "externalSourceId": { "type": "string", "example": "supasite:photo-page:page_123" }, "folderId": { "type": "string", "description": "Existing BuildPass photo folder id for this external source." }, "projectId": { "type": "string", "example": "proj_ckproject123456789012345678" } } }, "PhotoGallerySyncResponse": { "type": "object", "properties": { "folderId": { "type": "string" }, "createdAttachmentIds": { "type": "array", "items": { "type": "string" } }, "skippedExternalSourceIds": { "type": "array", "items": { "type": "string" } }, "failedPhotos": { "type": "array", "items": { "type": "object" } }, "status": { "type": "string", "enum": ["synced", "partial"] } } }, "PhotoGalleryDeleteResponse": { "type": "object", "properties": { "folderId": { "type": "string", "nullable": true }, "deletedFolderId": { "type": "string", "nullable": true }, "deletedAttachmentIds": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": ["deleted"] } } }, "AttachmentUploadReference": { "type": "object", "required": ["key", "type"], "properties": { "key": { "type": "string", "example": "external-uploads/ckbuilder123456789012345678/photo.jpg" }, "regionId": { "type": "string", "nullable": true, "example": "au1" }, "type": { "type": "string", "enum": ["attachment"] } } }, "AttachmentUploadResponse": { "allOf": [ { "$ref": "#/components/schemas/AttachmentUploadReference" }, { "type": "object", "properties": { "imageUrl": { "type": "string", "format": "uri" }, "fileName": { "type": "string" }, "contentType": { "type": "string" }, "fieldName": { "type": "string", "description": "Present on bulk upload responses." } } } ] } } }, "security": [ { "OAuth2": [] } ], "paths": { "/oauth/token": { "post": { "description": "Generate an OAuth token to access the BuildPass API", "operationId": "getOAuthToken", "requestBody": { "description": "Client credentials to obtain OAuth token", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/TokenRequest" } } } }, "responses": { "200": { "description": "Token response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } } }, "400": { "description": "Bad Request - Invalid request parameters or scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthErrorResponse" } } } }, "401": { "description": "Unauthorized - Invalid client credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthErrorResponse" } } } }, "500": { "description": "Internal Server Error" } }, "security": [] } }, "/builders": { "get": { "description": "Get all builders that you are authorised to access", "operationId": "getBuilders", "parameters": [ { "name": "offset", "description": "The number of items to skip before starting to collect the result set", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "example": 0 } }, { "name": "limit", "description": "The number of items to return.", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "example": 25, "maximum": 25 } }, { "name": "X-BuildPass-Api-Version", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/X-BuildPass-Api-Version" } } ], "responses": { "200": { "description": "A list of builders", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponseBuilder" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "OAuth2": [] } ] } }, "/builders/{id}": { "get": { "description": "Get a builder that you are authorised to access", "operationId": "getBuilderById", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "buil_clgbsb90b001qjy0f0eo1hspp" } }, { "name": "X-BuildPass-Api-Version", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/X-BuildPass-Api-Version" } } ], "responses": { "200": { "description": "A builder object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Builder" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "OAuth2": [] } ] } }, "/builders/{id}/projects": { "get": { "description": "Get all projects for a builder", "operationId": "getProjects", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "buil_clgbsb90b001qjy0f0eo1hspp" } }, { "name": "offset", "description": "The number of items to skip before starting to collect the result set", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "example": 0 } }, { "name": "limit", "description": "The number of items to return.", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "example": 25, "maximum": 25 } } ], "responses": { "200": { "description": "A list of projects", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponseProject" } } } } } } }, "/builders/{id}/projects/{projectId}": { "get": { "description": "Get a project for a builder", "operationId": "getProjectById", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "buil_clgbsb90b001qjy0f0eo1hspp" } }, { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "example": "proj_clgbsb90b001qjy0f0eo1hspp" } } ], "responses": { "200": { "description": "A project object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "OAuth2": [] } ] } }, "/builders/{builderId}/projects/{projectId}/inductions": { "get": { "description": "Get all inductions for a project", "operationId": "getProjectInductions", "parameters": [ { "name": "builderId", "description": "The ID of the builder", "in": "path", "required": true, "schema": { "type": "string", "example": "buil_clgbsb90b001qjy0f0eo1hspp" } }, { "name": "projectId", "description": "The ID of the project", "in": "path", "required": true, "schema": { "type": "string", "example": "prj_clgbsb90b001qjy0f0eo1hspp" } }, { "name": "status", "description": "Filter by induction status", "in": "query", "required": false, "schema": { "type": "string", "enum": ["REVIEWED", "WAITING_REVIEW", "CHANGES_REQUESTED"], "example": "WAITING_REVIEW" } }, { "name": "offset", "description": "The number of items to skip before starting to collect the result set", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "example": 0 } }, { "name": "limit", "description": "The number of items to return", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "example": 25, "maximum": 25 } }, { "name": "X-BuildPass-Api-Version", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/X-BuildPass-Api-Version" } } ], "responses": { "200": { "description": "A paginated list of inductions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponseInduction" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "OAuth2": [] } ] } }, "/builders/{builderId}/projects/{projectId}/inductions/{identifierOrId}": { "get": { "description": "Get an induction by identifier (numeric) or ID (ind_ prefix)", "operationId": "getProjectInduction", "parameters": [ { "name": "builderId", "description": "The ID of the builder", "in": "path", "required": true, "schema": { "type": "string", "example": "buil_clgbsb90b001qjy0f0eo1hspp" } }, { "name": "projectId", "description": "The ID of the project", "in": "path", "required": true, "schema": { "type": "string", "example": "prj_clgbsb90b001qjy0f0eo1hspp" } }, { "name": "identifierOrId", "description": "The project-specific identifier (numeric, e.g. 5) or the induction ID (with ind_ prefix, e.g. ind_abc123)", "in": "path", "required": true, "schema": { "type": "string", "example": "5" } }, { "name": "X-BuildPass-Api-Version", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/X-BuildPass-Api-Version" } } ], "responses": { "200": { "description": "An induction object with form data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InductionWithData" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "OAuth2": [] } ] } }, "/subcontractors": { "get": { "description": "Get all subcontractors under a builder", "operationId": "getSubcontractors", "parameters": [ { "name": "offset", "description": "The number of items to skip before starting to collect the result set.", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "example": 0 } }, { "name": "limit", "description": "The number of items to return.", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "example": 25, "maximum": 25 } }, { "name": "projectId", "description": "Filter subcontractors for a specific project", "in": "query", "required": false, "schema": { "type": "string", "example": "proj_clgbsb90b001qjy0f0eo1hspp" } }, { "name": "X-BuildPass-Builder-Id", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/X-BuildPass-Builder-Id" } }, { "name": "X-BuildPass-Api-Version", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/X-BuildPass-Api-Version" } } ], "responses": { "200": { "description": "A list of subcontractors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponseSubcontractor" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "OAuth2": [] } ] } }, "/subcontractors/{id}": { "get": { "description": "Get a subcontractor", "operationId": "getSubcontractorById", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "sub_clgbsb90b001qjy0f0eo1hspp" } }, { "name": "X-BuildPass-Api-Version", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/X-BuildPass-Api-Version" } }, { "name": "projectId", "in": "query", "description": "Filter returned statuses by project", "required": false, "schema": { "type": "string", "example": "proj_clgbsb90b001qjy0f0eo1hspp" } } ], "responses": { "200": { "description": "A subcontractor object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subcontractor" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "OAuth2": [] } ] } }, "/subcontractors/{id}/projects": { "get": { "description": "Get all projects assigned to a subcontractor", "operationId": "getSubcontractorProjects", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "sub_clgbsb90b001qjy0f0eo1hspp" } }, { "name": "offset", "description": "The number of items to skip before starting to collect the result set", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "example": 0 } }, { "name": "limit", "description": "The number of items to return.", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "example": 25, "maximum": 25 } } ], "responses": { "200": { "description": "A list of projects", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponseProject" } } } } } } }, "/subcontractors/{id}/prequalifications": { "get": { "description": "Get all prequalifications for a subcontractor", "operationId": "getPrequalifications", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "sub_clgbsb90b001qjy0f0eo1hspp" } }, { "name": "offset", "description": "The number of items to skip before starting to collect the result set", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "example": 0 } }, { "name": "limit", "description": "The number of items to return.", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "example": 25, "maximum": 25 } }, { "name": "status", "description": "Filter prequalifications by status", "in": "query", "required": false, "schema": { "type": "string", "enum": ["APPROVED", "REJECTED", "WAITING_REVIEW", "SENT"], "example": "WAITING_REVIEW" } }, { "name": "X-BuildPass-Api-Version", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/X-BuildPass-Api-Version" } } ], "responses": { "200": { "description": "A list of prequalifications", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponsePrequalification" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "OAuth2": [] } ] } }, "/subcontractors/{id}/prequalifications/{prequalId}": { "get": { "description": "Get a prequalification for a subcontractor", "operationId": "getPrequalificationById", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "sub_clgbsb90b001qjy0f0eo1hspp" } }, { "name": "prequalId", "in": "path", "required": true, "schema": { "type": "string", "example": "prequal_clgbsb90b001qjy0f0eo1hspp" } }, { "name": "X-BuildPass-Api-Version", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/X-BuildPass-Api-Version" } } ], "responses": { "200": { "description": "A prequalification object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Prequalification" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "OAuth2": [] } ] } }, "/subcontractors/{id}/insurances": { "get": { "description": "Get all insurances for a subcontractor", "operationId": "getInsurances", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "sub_clgbsb90b001qjy0f0eo1hspp" } }, { "name": "offset", "description": "The number of items to skip before starting to collect the result set", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "example": 0 } }, { "name": "limit", "description": "The number of items to return.", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "example": 25, "maximum": 25 } }, { "name": "type", "description": "Filter insurances by type", "in": "query", "required": false, "schema": { "type": "string", "enum": ["PUBLIC_LIABILITY", "WORK_COVER", "OTHER"], "example": "SWMS" } }, { "name": "status", "description": "Filter insurances by status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "CHANGES_REQUESTED", "REVIEWED", "WAITING_REVIEW", "EXPIRED" ], "example": "EXPIRED" } }, { "name": "customType", "description": "Filter insurances by custom type", "in": "query", "required": false, "schema": { "type": "string", "example": "SDS" } }, { "name": "X-BuildPass-Api-Version", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/X-BuildPass-Api-Version" } } ], "responses": { "200": { "description": "A list of insurances", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponseInsurance" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "OAuth2": [] } ] } }, "/subcontractors/{id}/insurances/{insuranceId}": { "get": { "description": "Get a document for a subcontractor", "operationId": "getInsuranceById", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "sub_clgbsb90b001qjy0f0eo1hspp" } }, { "name": "insuranceId", "in": "path", "required": true, "schema": { "type": "string", "example": "doc_clgbsb90b001qjy0f0eo1hspp" } }, { "name": "X-BuildPass-Builder-Id", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/X-BuildPass-Builder-Id" } }, { "name": "X-BuildPass-Api-Version", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/X-BuildPass-Api-Version" } } ], "responses": { "200": { "description": "A document object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Insurance" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "OAuth2": [] } ] } }, "/subcontractors/{id}/contacts": { "get": { "description": "Get all contacts for a subcontractor", "operationId": "getContacts", "parameters": [ { "name": "id", "description": "The ID of the subcontractor", "in": "path", "required": true, "schema": { "type": "string", "example": "sub_clgbsb90b001qjy0f0eo1hspp" } }, { "name": "offset", "description": "The number of items to skip before starting to collect the result set", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "example": 0 } }, { "name": "limit", "description": "The number of items to return.", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "example": 25, "maximum": 25 } }, { "name": "projectId", "description": "Filter contacts by the project they are associated with", "in": "query", "required": false, "schema": { "type": "string", "example": "proj_clgbsb90b001qjy0f0eo1hspp" } }, { "name": "isPrimary", "description": "Filter contacts by whether they are the primary contact", "in": "query", "required": false, "schema": { "type": "string", "enum": ["true", "false"], "example": "true" } }, { "name": "X-BuildPass-Api-Version", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/X-BuildPass-Api-Version" } } ], "responses": { "200": { "description": "A list of contacts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponseContact" } } } } } } }, "/subcontractors/{id}/swms": { "get": { "description": "Get all SWMS documents for a subcontractor", "operationId": "getSwms", "parameters": [ { "name": "id", "description": "The ID of the subcontractor", "in": "path", "required": true, "schema": { "type": "string", "example": "sub_clgbsb90b001qjy0f0eo1hspp" } }, { "name": "offset", "description": "The number of items to skip before starting to collect the result set", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "example": 0 } }, { "name": "limit", "description": "The number of items to return.", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "example": 25, "maximum": 25 } }, { "name": "projectId", "description": "Filter SWMS documents by the project they are associated with", "in": "query", "required": false, "schema": { "type": "string", "example": "proj_clgbsb90b001qjy0f0eo1hspp" } }, { "name": "X-BuildPass-Api-Version", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/X-BuildPass-Api-Version" } } ], "responses": { "200": { "description": "A list of SWMS documents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponseSwms" } } } } } } }, "/subcontractors/{id}/swms/{swmsDocId}": { "get": { "description": "Get a SWMS document for a subcontractor", "operationId": "getSwmsById", "parameters": [ { "name": "id", "description": "The ID of the subcontractor", "in": "path", "required": true, "schema": { "type": "string", "example": "sub_clgbsb90b001qjy0f0eo1hspp" } }, { "name": "swmsDocId", "description": "The ID of the SWMS document", "in": "path", "required": true, "schema": { "type": "string", "example": "swms_clgbsb90b001qjy0f0eo1hspp" } }, { "name": "X-BuildPass-Api-Version", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/X-BuildPass-Api-Version" } } ], "responses": { "200": { "description": "A SWMS document object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Swms" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "OAuth2": [] } ] } }, "/subcontractors/{id}/inductions": { "get": { "description": "Get all inductions for workers associated with a subcontractor", "operationId": "getSubcontractorInductions", "parameters": [ { "name": "id", "description": "The ID of the subcontractor", "in": "path", "required": true, "schema": { "type": "string", "example": "sub_clgbsb90b001qjy0f0eo1hspp" } }, { "name": "projectId", "description": "Filter by project ID", "in": "query", "required": false, "schema": { "type": "string", "example": "prj_clgbsb90b001qjy0f0eo1hspp" } }, { "name": "status", "description": "Filter by induction status", "in": "query", "required": false, "schema": { "type": "string", "enum": ["REVIEWED", "WAITING_REVIEW", "CHANGES_REQUESTED"], "example": "WAITING_REVIEW" } }, { "name": "offset", "description": "The number of items to skip before starting to collect the result set", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "example": 0 } }, { "name": "limit", "description": "The number of items to return", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "example": 25, "maximum": 25 } }, { "name": "X-BuildPass-Api-Version", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/X-BuildPass-Api-Version" } } ], "responses": { "200": { "description": "A paginated list of inductions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponseInduction" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "OAuth2": [] } ] } }, "/timesheets": { "get": { "description": "Get all timesheets for a builder", "operationId": "getTimesheets", "parameters": [ { "name": "projectId", "description": "Filter timesheets by project", "in": "query", "required": false, "schema": { "type": "string", "example": "proj_clgbsb91b001qjy0f0eo1hscp" } }, { "name": "status", "description": "Filter timesheets by status", "in": "query", "required": false, "schema": { "enum": [ "APPROVED_1", "APPROVED_2", "REJECTED", "WAITING_REVIEW" ], "example": "WAITING_REVIEW" } }, { "name": "startDate", "description": "Filter by date range start (ISO format)", "in": "query", "required": false, "schema": { "type": "string", "example": "2023-10-03T23:19:35.771Z" } }, { "name": "endDate", "description": "Filter by date range end (ISO format)", "in": "query", "required": false, "schema": { "type": "string", "example": "2024-10-03T23:19:35.771Z" } }, { "name": "offset", "description": "The number of items to skip before starting to collect the result set", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "example": 0 } }, { "name": "limit", "description": "The number of items to return.", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "example": 25, "maximum": 25 } }, { "name": "X-BuildPass-Builder-Id", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/X-BuildPass-Builder-Id" } }, { "name": "X-BuildPass-Api-Version", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/X-BuildPass-Api-Version" } } ], "responses": { "200": { "description": "A list of timesheets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponseTimesheet" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "OAuth2": [] } ] } }, "/timesheets/{timesheetId}": { "get": { "description": "Get a timesheet by ID", "operationId": "getTimesheetById", "parameters": [ { "name": "timesheetId", "in": "path", "required": true, "schema": { "type": "string", "example": "ts_clgbsb90b001qjy0f0eo1hspp" } }, { "name": "X-BuildPass-Builder-Id", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/X-BuildPass-Builder-Id" } }, { "name": "X-BuildPass-Api-Version", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/X-BuildPass-Api-Version" } } ], "responses": { "200": { "description": "A timesheet object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Timesheet" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "OAuth2": [] } ] } }, "/timesheets/time-types": { "get": { "description": "Get a list of time types configured for a builder", "operationId": "getTimeTypes", "parameters": [ { "name": "X-BuildPass-Builder-Id", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/X-BuildPass-Builder-Id" } }, { "name": "X-BuildPass-Api-Version", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/X-BuildPass-Api-Version" } } ], "responses": { "200": { "description": "A list of timesheet time types", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimesheetTimeTypes" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "OAuth2": [] } ] } }, "/timesheets/cost-codes": { "get": { "description": "Get a list of cost codes configured for a builder", "operationId": "getCostCodes", "parameters": [ { "name": "X-BuildPass-Builder-Id", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/X-BuildPass-Builder-Id" } }, { "name": "X-BuildPass-Api-Version", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/X-BuildPass-Api-Version" } } ], "responses": { "200": { "description": "A list of timesheet cost codes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimesheetCostCodes" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "OAuth2": [] } ] } }, "/builders/{builderId}/meetings": { "get": { "description": "List meetings for a builder", "operationId": "listMeetings", "parameters": [ { "name": "builderId", "in": "path", "required": true, "schema": { "type": "string", "example": "buil_clgbsb90b001qjy0f0eo1hspp" } }, { "name": "from", "description": "Filter meetings from this date-time", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "example": "2026-01-01T00:00:00.000Z" } }, { "name": "to", "description": "Filter meetings until this date-time", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "example": "2026-01-31T23:59:59.999Z" } }, { "name": "status", "description": "Filter by meeting status. Repeat the parameter for multiple values.", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": ["DRAFT", "DISTRIBUTED", "COMPLETED", "RUNNING"] } }, "style": "form", "explode": true }, { "name": "offset", "description": "The number of items to skip before starting to collect the result set", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "example": 0 } }, { "name": "limit", "description": "The number of items to return.", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "example": 25, "maximum": 25 } } ], "responses": { "200": { "description": "A list of meetings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponseMeeting" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "OAuth2": ["read:meetings"] } ] }, "post": { "description": "Create a draft meeting for a builder", "operationId": "createMeeting", "parameters": [ { "name": "builderId", "in": "path", "required": true, "schema": { "type": "string", "example": "buil_clgbsb90b001qjy0f0eo1hspp" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeetingCreateRequest" } } } }, "responses": { "200": { "description": "Created meeting", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Meeting" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "OAuth2": ["write:meetings"] } ] } }, "/builders/{builderId}/meetings/{meetingId}": { "patch": { "description": "Update a meeting", "operationId": "updateMeeting", "parameters": [ { "name": "builderId", "in": "path", "required": true, "schema": { "type": "string", "example": "buil_clgbsb90b001qjy0f0eo1hspp" } }, { "name": "meetingId", "in": "path", "required": true, "schema": { "type": "string", "example": "extapitoolboxmeeting01" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeetingUpdateRequest" } } } }, "responses": { "200": { "description": "Updated meeting", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeetingLifecycleResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "OAuth2": ["write:meetings"] } ] } }, "/builders/{builderId}/meetings/{meetingId}/start": { "post": { "description": "Start a meeting", "operationId": "startMeeting", "parameters": [ { "name": "builderId", "in": "path", "required": true, "schema": { "type": "string", "example": "buil_clgbsb90b001qjy0f0eo1hspp" } }, { "name": "meetingId", "in": "path", "required": true, "schema": { "type": "string", "example": "extapitoolboxmeeting01" } } ], "responses": { "200": { "description": "The started meeting", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeetingLifecycleResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "OAuth2": ["write:meetings"] } ] } }, "/builders/{builderId}/meetings/{meetingId}/end": { "post": { "description": "End a meeting", "operationId": "endMeeting", "parameters": [ { "name": "builderId", "in": "path", "required": true, "schema": { "type": "string", "example": "buil_clgbsb90b001qjy0f0eo1hspp" } }, { "name": "meetingId", "in": "path", "required": true, "schema": { "type": "string", "example": "extapitoolboxmeeting01" } } ], "responses": { "200": { "description": "The ended meeting", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeetingLifecycleResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "OAuth2": ["write:meetings"] } ] } }, "/builders/{builderId}/meetings/{meetingId}/notes": { "get": { "description": "List notes for a meeting", "operationId": "listMeetingNotes", "parameters": [ { "name": "builderId", "in": "path", "required": true, "schema": { "type": "string", "example": "buil_clgbsb90b001qjy0f0eo1hspp" } }, { "name": "meetingId", "in": "path", "required": true, "schema": { "type": "string", "example": "extapitoolboxmeeting01" } }, { "name": "offset", "description": "The number of items to skip before starting to collect the result set", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "example": 0 } }, { "name": "limit", "description": "The number of items to return.", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "example": 25, "maximum": 25 } } ], "responses": { "200": { "description": "A list of meeting notes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponseMeetingNote" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "OAuth2": ["read:meetings"] } ] }, "post": { "description": "Create or update a meeting note by externalSourceId and sourceApp", "operationId": "upsertMeetingNote", "parameters": [ { "name": "builderId", "in": "path", "required": true, "schema": { "type": "string", "example": "buil_clgbsb90b001qjy0f0eo1hspp" } }, { "name": "meetingId", "in": "path", "required": true, "schema": { "type": "string", "example": "extapitoolboxmeeting01" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeetingNoteUpsertRequest" } } } }, "responses": { "200": { "description": "The created or updated meeting note", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeetingNote" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "OAuth2": ["write:meetings"] } ] } }, "/builders/{builderId}/photos": { "get": { "summary": "List photos", "description": "List gallery photos for a builder. Returns signed image URLs.", "tags": ["Photos"], "parameters": [ { "name": "builderId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "folderId", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Photo" } } } } } } } }, "security": [ { "OAuth2": ["read:photos"] } ] }, "post": { "summary": "Create photo", "description": "Create a gallery photo from an uploaded imageAttachment reference, or an approved HTTPS image URL.", "tags": ["Photos"], "parameters": [ { "name": "builderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhotoInput" } } } }, "responses": { "201": { "description": "Photo created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Photo" } } } } }, "security": [ { "OAuth2": ["write:photos"] } ] } }, "/builders/{builderId}/attachments/upload": { "post": { "summary": "Upload attachment", "description": "Upload one attachment file and receive an attachment reference for a later resource create request. Include type=attachment so BuildPass can route the file to the correct storage family. For example, use the returned reference to create a photo.", "tags": ["Attachments"], "parameters": [ { "name": "builderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": ["file", "type"], "properties": { "file": { "type": "string", "format": "binary" }, "type": { "type": "string", "enum": ["attachment"] } } } } } }, "responses": { "201": { "description": "Attachment uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentUploadResponse" } } } } }, "security": [ { "OAuth2": [] } ] } }, "/builders/{builderId}/attachments/bulk-upload": { "post": { "summary": "Bulk upload attachments", "description": "Upload multiple attachment files and receive attachment references for a later resource create or upsert request. Include type=attachment, or per-file type:N=attachment fields, so BuildPass can route each file to the correct storage family. For example, use the returned references to bulk upsert photos.", "tags": ["Attachments"], "parameters": [ { "name": "builderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": ["type"], "properties": { "type": { "type": "string", "enum": ["attachment"], "description": "Upload type to apply to every file." }, "file:0": { "type": "string", "format": "binary" }, "type:0": { "type": "string", "enum": ["attachment"], "description": "Optional upload type for file:0." }, "file:1": { "type": "string", "format": "binary" }, "type:1": { "type": "string", "enum": ["attachment"], "description": "Optional upload type for file:1." } } } } } }, "responses": { "201": { "description": "Attachments uploaded", "content": { "application/json": { "schema": { "type": "object", "properties": { "uploads": { "type": "array", "items": { "$ref": "#/components/schemas/AttachmentUploadResponse" } } } } } } } }, "security": [ { "OAuth2": [] } ] } }, "/builders/{builderId}/photos/{photoId}": { "get": { "summary": "Get photo", "tags": ["Photos"], "parameters": [ { "name": "builderId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "photoId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Photo found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Photo" } } } } }, "security": [ { "OAuth2": ["read:photos"] } ] }, "patch": { "summary": "Update photo", "tags": ["Photos"], "parameters": [ { "name": "builderId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "photoId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "capturedAt": { "type": "string", "format": "date-time" }, "description": { "type": "string", "nullable": true }, "fileName": { "type": "string" }, "folderId": { "type": "string", "nullable": true } } } } } }, "responses": { "200": { "description": "Photo updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Photo" } } } } }, "security": [ { "OAuth2": ["write:photos"] } ] }, "delete": { "summary": "Delete photo", "tags": ["Photos"], "parameters": [ { "name": "builderId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "photoId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Photo archived", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Photo" } } } } }, "security": [ { "OAuth2": ["write:photos"] } ] } }, "/builders/{builderId}/photo-folders": { "get": { "summary": "List photo folders", "tags": ["Photos"], "parameters": [ { "name": "builderId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PhotoFolder" } } } } } } } }, "security": [ { "OAuth2": ["read:photos"] } ] }, "post": { "summary": "Create photo folder", "tags": ["Photos"], "parameters": [ { "name": "builderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhotoFolderInput" } } } }, "responses": { "201": { "description": "Photo folder created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhotoFolder" } } } } }, "security": [ { "OAuth2": ["write:photos"] } ] } }, "/builders/{builderId}/photo-folders/{folderId}": { "get": { "summary": "Get photo folder", "tags": ["Photos"], "parameters": [ { "name": "builderId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "folderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Photo folder found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhotoFolder" } } } } }, "security": [ { "OAuth2": ["read:photos"] } ] }, "patch": { "summary": "Update photo folder", "tags": ["Photos"], "parameters": [ { "name": "builderId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "folderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "parentId": { "type": "string", "nullable": true } } } } } }, "responses": { "200": { "description": "Photo folder updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhotoFolder" } } } } }, "security": [ { "OAuth2": ["write:photos"] } ] }, "delete": { "summary": "Delete photo folder", "tags": ["Photos"], "parameters": [ { "name": "builderId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "folderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Photo folder deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhotoFolder" } } } }, "409": { "description": "Folder is not empty" } }, "security": [ { "OAuth2": ["write:photos"] } ] } }, "/builders/{builderId}/photo-gallery/bulk-upsert": { "post": { "summary": "Bulk upsert photos", "description": "Bulk upsert external photos into a BuildPass photo folder idempotently.", "tags": ["Photos"], "parameters": [ { "name": "builderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhotoGallerySyncInput" } } } }, "responses": { "200": { "description": "Photos synced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhotoGallerySyncResponse" } } } } }, "security": [ { "OAuth2": ["write:photos"] } ] }, "delete": { "summary": "Delete bulk-upserted photos", "description": "Archive photos created for an external photo source and delete the now-empty BuildPass photo folder when possible.", "tags": ["Photos"], "parameters": [ { "name": "builderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhotoGalleryDeleteInput" } } } }, "responses": { "200": { "description": "Photos deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhotoGalleryDeleteResponse" } } } } }, "security": [ { "OAuth2": ["write:photos"] } ] } } } }