{"openapi":"3.1.0","info":{"title":"BuilderComs REST API","version":"1.0.0","description":"Company-protected job/task/message reads and updates. OAuth authorization-code + PKCE tokens must carry authenticated audience/role and verified client_id. Owner authorization of a named integration is required for all calls; Read & write plus active subscription for updates. Discover OAuth via /.well-known/oauth-protected-resource. Owner-managed company REST keys are also accepted as bearer credentials; account-session tokens are not. Includes authenticated incoming update webhooks; not mailbox sync or outgoing customer webhook subscriptions."},"servers":[{"url":"https://web.buildercoms.com/api/public/v1","description":"Production; publish latest API changes before use"}],"paths":{"/connection":{"get":{"summary":"Test company REST key connection","security":[{"CompanyKey":[]}],"parameters":[],"responses":{"200":{"description":"Authorized records","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"data":{"type":"object","additionalProperties":false,"properties":{"connected":{"const":true},"company_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"access_mode":{"type":"string","enum":["read","write"]}},"required":["connected","company_id","name","access_mode"]}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/expired/invalid OAuth token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Grant, subscription, permission or limit denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Missing or inaccessible resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Unsupported method","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Requires application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporary failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/updates":{"post":{"summary":"Receive an incoming job, status, task or reply event","security":[{"OAuthBearer":[]},{"CompanyKey":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"event_id":"123e4567-e89b-42d3-a456-426614174000","event":"job.status_changed","data":{"job_id":"123e4567-e89b-42d3-a456-426614174001","status":"completed"}}}}},"responses":{"200":{"description":"Saved successfully, including retries","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/ActionResult"}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/expired/invalid OAuth token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Grant, subscription, permission or limit denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Missing or inaccessible resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Unsupported method","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Changed retry details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Requires application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporary failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/jobs":{"get":{"summary":"List authorized jobs","security":[{"OAuthBearer":[]},{"CompanyKey":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"before","in":"query","schema":{"type":"string","format":"uuid"},"description":"page.next_cursor; stable descending UUID order, not chronological order"}],"responses":{"200":{"description":"Authorized records","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/JobSummary"}},"page":{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer"},"next_cursor":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["limit","next_cursor"]}},"required":["data","page"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/expired/invalid OAuth token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Grant, subscription, permission or limit denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Missing or inaccessible resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Unsupported method","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Requires application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporary failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a job","security":[{"OAuthBearer":[]},{"CompanyKey":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","format":"uuid"},"description":"New UUID per action; reuse same ID and identical details for retries. Integration-scoped across endpoints."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateJob"},"example":{"address":"123 Test Road","client_name":"Example client"}}}},"responses":{"200":{"description":"Saved successfully, including retries","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/ActionResult"}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/expired/invalid OAuth token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Grant, subscription, permission or limit denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Missing or inaccessible resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Unsupported method","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Changed retry details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Requires application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporary failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/jobs/{job_id}/details":{"patch":{"summary":"Replace job details","security":[{"OAuthBearer":[]},{"CompanyKey":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","format":"uuid"},"description":"New UUID per action; reuse same ID and identical details for retries. Integration-scoped across endpoints."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","maxLength":150},"address":{"type":"string","minLength":1,"maxLength":500},"client_name":{"type":"string","minLength":1,"maxLength":150},"client_email":{"type":"string","maxLength":254,"description":"Email address or empty string"},"client_phone":{"type":"string","maxLength":40},"project_type":{"type":"string","maxLength":100},"description":{"type":"string","maxLength":5000},"start_date":{"type":"string","description":"YYYY-MM-DD or empty string"},"end_date":{"type":"string","description":"YYYY-MM-DD or empty string; not before start_date"},"site_notes":{"type":"string","maxLength":3000},"job_id":{"type":"string","format":"uuid"}},"required":["job_id","name","address","client_name"]},"example":{"job_id":"123e4567-e89b-42d3-a456-426614174001","name":"Framing inspection","address":"123 Test Road","client_name":"Example client"}}}},"responses":{"200":{"description":"Saved successfully, including retries","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/ActionResult"}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/expired/invalid OAuth token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Grant, subscription, permission or limit denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Missing or inaccessible resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Unsupported method","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Changed retry details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Requires application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporary failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/jobs/{job_id}":{"get":{"summary":"Read job details","security":[{"OAuthBearer":[]},{"CompanyKey":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Authorized records","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/Job"}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/expired/invalid OAuth token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Grant, subscription, permission or limit denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Missing or inaccessible resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Unsupported method","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Requires application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporary failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Set job status","security":[{"OAuthBearer":[]},{"CompanyKey":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","format":"uuid"},"description":"New UUID per action; reuse same ID and identical details for retries. Integration-scoped across endpoints."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"status":{"type":"string","enum":["active","completed"]}},"required":["status"]},"example":{"status":"completed"}}}},"responses":{"200":{"description":"Saved successfully, including retries","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/ActionResult"}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/expired/invalid OAuth token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Grant, subscription, permission or limit denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Missing or inaccessible resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Unsupported method","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Changed retry details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Requires application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporary failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/jobs/{job_id}/tasks":{"get":{"summary":"List job tasks","security":[{"OAuthBearer":[]},{"CompanyKey":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"before","in":"query","schema":{"type":"string","format":"uuid"},"description":"page.next_cursor; stable descending UUID order, not chronological order"}],"responses":{"200":{"description":"Authorized records","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Task"}},"page":{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer"},"next_cursor":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["limit","next_cursor"]}},"required":["data","page"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/expired/invalid OAuth token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Grant, subscription, permission or limit denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Missing or inaccessible resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Unsupported method","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Requires application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporary failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a task","security":[{"OAuthBearer":[]},{"CompanyKey":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","format":"uuid"},"description":"New UUID per action; reuse same ID and identical details for retries. Integration-scoped across endpoints."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskInput"},"example":{"title":"Inspect framing","due_date":"2026-11-20"}}}},"responses":{"200":{"description":"Saved successfully, including retries","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/ActionResult"}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/expired/invalid OAuth token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Grant, subscription, permission or limit denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Missing or inaccessible resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Unsupported method","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Changed retry details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Requires application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporary failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/jobs/{job_id}/tasks/{task_id}":{"patch":{"summary":"Replace task title and due date","security":[{"OAuthBearer":[]},{"CompanyKey":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"task_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","format":"uuid"},"description":"New UUID per action; reuse same ID and identical details for retries. Integration-scoped across endpoints."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskInput"},"example":{"title":"Inspect framing","due_date":null}}}},"responses":{"200":{"description":"Saved successfully, including retries","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/ActionResult"}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/expired/invalid OAuth token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Grant, subscription, permission or limit denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Missing or inaccessible resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Unsupported method","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Changed retry details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Requires application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporary failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/jobs/{job_id}/tasks/{task_id}/completion":{"patch":{"summary":"Complete or reopen task","security":[{"OAuthBearer":[]},{"CompanyKey":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"task_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","format":"uuid"},"description":"New UUID per action; reuse same ID and identical details for retries. Integration-scoped across endpoints."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"done":{"type":"boolean"}},"required":["done"]},"example":{"done":true}}}},"responses":{"200":{"description":"Saved successfully, including retries","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/ActionResult"}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/expired/invalid OAuth token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Grant, subscription, permission or limit denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Missing or inaccessible resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Unsupported method","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Changed retry details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Requires application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporary failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/jobs/{job_id}/conversations":{"get":{"summary":"Discover authorized Team channels and Client conversation IDs","security":[{"OAuthBearer":[]},{"CompanyKey":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Authorized records","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Conversation"}}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/expired/invalid OAuth token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Grant, subscription, permission or limit denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Missing or inaccessible resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Unsupported method","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Requires application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporary failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/jobs/{job_id}/messages":{"get":{"summary":"Read conversation roots or exact-thread replies","security":[{"OAuthBearer":[]},{"CompanyKey":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"before","in":"query","schema":{"type":"string","format":"uuid"},"description":"page.next_cursor; stable descending UUID order, not chronological order"},{"name":"audience","in":"query","required":true,"schema":{"type":"string","enum":["team","client"]}},{"name":"channel_id","in":"query","schema":{"type":"string","format":"uuid"},"description":"Team channel; omit for General; forbidden for Client"},{"name":"client_link_id","in":"query","schema":{"type":"string","format":"uuid"},"description":"Required for Client; forbidden for Team"},{"name":"parent_id","in":"query","schema":{"type":"string","format":"uuid"},"description":"Omit for roots; provide root ID for replies"}],"responses":{"200":{"description":"Authorized records","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"page":{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer"},"next_cursor":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["limit","next_cursor"]}},"required":["data","page"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/expired/invalid OAuth token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Grant, subscription, permission or limit denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Missing or inaccessible resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Unsupported method","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Requires application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporary failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Send exact Team or Client message","security":[{"OAuthBearer":[]},{"CompanyKey":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","format":"uuid"},"description":"New UUID per action; reuse same ID and identical details for retries. Integration-scoped across endpoints."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageInput"},"example":{"body":"Inspection complete.","audience":"team","channel_id":null,"client_link_id":null,"parent_id":null}}}},"responses":{"200":{"description":"Saved successfully, including retries","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/ActionResult"}},"required":["data"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/expired/invalid OAuth token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Grant, subscription, permission or limit denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Missing or inaccessible resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Unsupported method","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Changed retry details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Requires application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporary failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"CompanyKey":{"type":"http","scheme":"bearer","bearerFormat":"BuilderComs company REST key","description":"Create in Settings → Developer portal. Shown once, expires after 90 days, owner revocable. Read-only or read/write. Not valid for MCP."},"OAuthBearer":{"type":"http","scheme":"bearer","bearerFormat":"OAuth 2.1 JWT","description":"Authorization-code + PKCE S256; named owner grant. Discover provider metadata through /.well-known/oauth-protected-resource; reuse existing BuilderComs OAuth provider."}},"schemas":{"WebhookEvent":{"oneOf":[{"type":"object","additionalProperties":false,"properties":{"event_id":{"type":"string","format":"uuid"},"event":{"const":"job.created"},"data":{"$ref":"#/components/schemas/CreateJob"}},"required":["event_id","event","data"]},{"type":"object","additionalProperties":false,"properties":{"event_id":{"type":"string","format":"uuid"},"event":{"const":"job.updated"},"data":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","maxLength":150},"address":{"type":"string","minLength":1,"maxLength":500},"client_name":{"type":"string","minLength":1,"maxLength":150},"client_email":{"type":"string","maxLength":254,"description":"Email address or empty string"},"client_phone":{"type":"string","maxLength":40},"project_type":{"type":"string","maxLength":100},"description":{"type":"string","maxLength":5000},"start_date":{"type":"string","description":"YYYY-MM-DD or empty string"},"end_date":{"type":"string","description":"YYYY-MM-DD or empty string; not before start_date"},"site_notes":{"type":"string","maxLength":3000},"job_id":{"type":"string","format":"uuid"}},"required":["job_id","name","address","client_name"]}},"required":["event_id","event","data"]},{"type":"object","additionalProperties":false,"properties":{"event_id":{"type":"string","format":"uuid"},"event":{"const":"job.status_changed"},"data":{"type":"object","additionalProperties":false,"properties":{"job_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active","completed"]}},"required":["job_id","status"]}},"required":["event_id","event","data"]},{"type":"object","additionalProperties":false,"properties":{"event_id":{"type":"string","format":"uuid"},"event":{"const":"task.created"},"data":{"type":"object","additionalProperties":false,"properties":{"job_id":{"type":"string","format":"uuid"},"title":{"type":"string","minLength":1,"maxLength":200},"due_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]}},"required":["job_id","title"]}},"required":["event_id","event","data"]},{"type":"object","additionalProperties":false,"properties":{"event_id":{"type":"string","format":"uuid"},"event":{"const":"task.updated"},"data":{"type":"object","additionalProperties":false,"properties":{"job_id":{"type":"string","format":"uuid"},"task_id":{"type":"string","format":"uuid"},"title":{"type":"string","minLength":1,"maxLength":200},"due_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]}},"required":["job_id","task_id","title"]}},"required":["event_id","event","data"]},{"type":"object","additionalProperties":false,"properties":{"event_id":{"type":"string","format":"uuid"},"event":{"const":"task.completion_changed"},"data":{"type":"object","additionalProperties":false,"properties":{"job_id":{"type":"string","format":"uuid"},"task_id":{"type":"string","format":"uuid"},"done":{"type":"boolean"}},"required":["job_id","task_id","done"]}},"required":["event_id","event","data"]},{"type":"object","additionalProperties":false,"properties":{"event_id":{"type":"string","format":"uuid"},"event":{"const":"message.sent"},"data":{"type":"object","additionalProperties":false,"properties":{"job_id":{"type":"string","format":"uuid"},"body":{"type":"string","minLength":1,"maxLength":10000},"audience":{"type":"string","enum":["team","client"]},"channel_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"client_link_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"parent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["job_id","body","audience"],"description":"Preserve exact Team/Client and parent scope."}},"required":["event_id","event","data"]}],"description":"One event per request. event_id replaces Idempotency-Key; retry with identical event and data. Owner-authorized OAuth or company REST key required."},"CreateJob":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","maxLength":150},"address":{"type":"string","minLength":1,"maxLength":500},"client_name":{"type":"string","minLength":1,"maxLength":150},"client_email":{"type":"string","maxLength":254,"description":"Email address or empty string"},"client_phone":{"type":"string","maxLength":40},"project_type":{"type":"string","maxLength":100},"description":{"type":"string","maxLength":5000},"start_date":{"type":"string","description":"YYYY-MM-DD or empty string"},"end_date":{"type":"string","description":"YYYY-MM-DD or empty string; not before start_date"},"site_notes":{"type":"string","maxLength":3000}},"required":["address","client_name"]},"JobSummary":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"address":{"type":"string"},"client_name":{"type":"string"},"status":{"type":"string"},"created_at":{"type":"string","format":"date-time"}},"required":["id","name","address","client_name","status","created_at"]},"Job":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"address":{"type":"string"},"client_name":{"type":"string"},"status":{"type":"string"},"description":{"type":"string"},"project_type":{"type":"string"},"start_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"end_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"site_notes":{"type":"string"},"created_at":{"type":"string","format":"date-time"}},"required":["id","name","address","client_name","status","description","project_type","start_date","end_date","site_notes","created_at"]},"TaskInput":{"type":"object","additionalProperties":false,"properties":{"title":{"type":"string","minLength":1,"maxLength":200},"due_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]}},"required":["title"]},"Task":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"job_id":{"type":"string","format":"uuid"},"title":{"type":"string","minLength":1,"maxLength":200},"due_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"done":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}},"required":["id","job_id","title","done","due_date","created_at"]},"MessageInput":{"type":"object","additionalProperties":false,"properties":{"body":{"type":"string","minLength":1,"maxLength":10000},"audience":{"type":"string","enum":["team","client"]},"channel_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"client_link_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"parent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["body","audience"],"description":"Client requires client_link_id and no channel_id. Team forbids client_link_id; null channel_id is General. Replies must match root audience/channel/link. Do not include job_id; URL defines it."},"Message":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"job_id":{"type":"string","format":"uuid"},"body":{"type":"string","minLength":1,"maxLength":10000},"audience":{"type":"string","enum":["team","client"]},"channel_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"client_link_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"parent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"author_name":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"edited_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","job_id","body","audience","channel_id","client_link_id","parent_id","author_name","created_at","edited_at"]},"Conversation":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string"},"audience":{"type":"string","enum":["team","client"]},"channel_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"client_link_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["name","audience","channel_id","client_link_id"]},"ActionResult":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["create_job","update_job_details","update_job_status","create_task","update_task","complete_task","send_message"]},"status":{"const":"succeeded"},"action_id":{"type":"string","format":"uuid"},"agent_name":{"type":"string"}},"required":["id","kind","status","action_id","agent_name"]},"Error":{"type":"object","additionalProperties":false,"properties":{"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"path":{"type":"string"},"message":{"type":"string"}},"required":["path","message"]}}},"required":["code","message"]}},"required":["error"]}}}}