{"openapi":"3.1.0","info":{"title":"Spaecify","version":"1.0.0","description":"Document real AEC processes into structured, reviewable ProcessSpecs. The same operations are available as MCP tools at /mcp. Approval of a candidate only happens on the review page, never through the API."},"servers":[{"url":"https://spaecify.com"}],"security":[{"bearer":[]},{"oauth":["fsc"]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"A personal key from the Connect page, or an OAuth access token."},"oauth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://spaecify.com/oauth/authorize","tokenUrl":"https://spaecify.com/oauth/token","refreshUrl":"https://spaecify.com/oauth/token","scopes":{"fsc":"Act as you, within your role"}}}}}},"paths":{"/v1/work":{"get":{"operationId":"list_work","summary":"First call","description":"First call. Lists what you are assigned to document, with readiness, open questions and review comments, and any candidates waiting for your review.","parameters":[],"responses":{"200":{"description":"Success"},"401":{"description":"Missing or invalid token"},"403":{"description":"Not allowed for this person or key"},"404":{"description":"Not found"},"409":{"description":"Conflict, such as a stale revision"},"422":{"description":"Invalid arguments"}}}},"/v1/workflows/{workflow_id}/context":{"get":{"operationId":"get_context","summary":"Everything needed before editing one workflow: draft body, revision, readiness blockers with paths, assignment, pending candidate, comments, artifacts and members.","description":"Everything needed before editing one workflow: draft body, revision, readiness blockers with paths, assignment, pending candidate, comments, artifacts and members.","parameters":[{"name":"workflow_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"401":{"description":"Missing or invalid token"},"403":{"description":"Not allowed for this person or key"},"404":{"description":"Not found"},"409":{"description":"Conflict, such as a stale revision"},"422":{"description":"Invalid arguments"}}}},"/v1/schemas/process-spec/v1":{"get":{"operationId":"get_schema","summary":"The ProcessSpec JSON Schema v1, for validating before you send.","description":"The ProcessSpec JSON Schema v1, for validating before you send.","parameters":[],"responses":{"200":{"description":"Success"},"401":{"description":"Missing or invalid token"},"403":{"description":"Not allowed for this person or key"},"404":{"description":"Not found"},"409":{"description":"Conflict, such as a stale revision"},"422":{"description":"Invalid arguments"}}}},"/v1/workflows/{workflow_id}/draft":{"post":{"operationId":"save_draft","summary":"The core write: apply id-based operations to the draft atomically","description":"The core write: apply id-based operations to the draft atomically. A stale expected_revision returns 409 with the current revision and the sections changed since. Missing fields and dangling references are warnings here and blockers at submission. Questions are raised and answered through ops, so an answer and its edits land together.","parameters":[{"name":"workflow_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8},"description":"Unique per intended write. Reuse it only to retry the same write."}],"responses":{"200":{"description":"Success"},"401":{"description":"Missing or invalid token"},"403":{"description":"Not allowed for this person or key"},"404":{"description":"Not found"},"409":{"description":"Conflict, such as a stale revision"},"422":{"description":"Invalid arguments"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expected_revision":{"type":"integer","minimum":0,"maximum":9007199254740991},"ops":{"minItems":1,"maxItems":200,"type":"array","items":{"anyOf":[{"oneOf":[{"type":"object","properties":{"op":{"type":"string","const":"upsert"},"section":{"type":"string","enum":["inputs","outputs","intermediates","steps","constraints","exceptions","references","examples","assumptions"]},"item":{"type":"object","properties":{"id":{"type":"string","pattern":"^[A-Za-z0-9_.-]{1,64}$"}},"required":["id"],"additionalProperties":{}}},"required":["op","section","item"],"additionalProperties":false},{"type":"object","properties":{"op":{"type":"string","const":"remove"},"section":{"type":"string","enum":["inputs","outputs","intermediates","steps","constraints","exceptions","references","examples","assumptions"]},"id":{"type":"string","pattern":"^[A-Za-z0-9_.-]{1,64}$"}},"required":["op","section","id"],"additionalProperties":false},{"type":"object","properties":{"op":{"type":"string","const":"set"},"path":{"type":"string","maxLength":200},"value":{}},"required":["op","path","value"],"additionalProperties":false},{"type":"object","properties":{"op":{"type":"string","const":"raise_question"},"item":{"type":"object","properties":{"id":{"type":"string","pattern":"^[A-Za-z0-9_.-]{1,64}$"},"text":{"type":"string","minLength":1,"maxLength":20000},"context":{"type":"string","maxLength":2000},"blocking":{"default":false,"type":"boolean"}},"required":["text"],"additionalProperties":false}},"required":["op","item"],"additionalProperties":false}]},{"type":"object","properties":{"op":{"type":"string","const":"answer_question"},"id":{"type":"string","pattern":"^[A-Za-z0-9_.-]{1,64}$"},"answer":{"type":"string","minLength":1,"maxLength":20000},"follow_up_ops":{"default":[],"maxItems":100,"type":"array","items":{"oneOf":[{"type":"object","properties":{"op":{"type":"string","const":"upsert"},"section":{"type":"string","enum":["inputs","outputs","intermediates","steps","constraints","exceptions","references","examples","assumptions"]},"item":{"type":"object","properties":{"id":{"type":"string","pattern":"^[A-Za-z0-9_.-]{1,64}$"}},"required":["id"],"additionalProperties":{}}},"required":["op","section","item"],"additionalProperties":false},{"type":"object","properties":{"op":{"type":"string","const":"remove"},"section":{"type":"string","enum":["inputs","outputs","intermediates","steps","constraints","exceptions","references","examples","assumptions"]},"id":{"type":"string","pattern":"^[A-Za-z0-9_.-]{1,64}$"}},"required":["op","section","id"],"additionalProperties":false},{"type":"object","properties":{"op":{"type":"string","const":"set"},"path":{"type":"string","maxLength":200},"value":{}},"required":["op","path","value"],"additionalProperties":false},{"type":"object","properties":{"op":{"type":"string","const":"raise_question"},"item":{"type":"object","properties":{"id":{"type":"string","pattern":"^[A-Za-z0-9_.-]{1,64}$"},"text":{"type":"string","minLength":1,"maxLength":20000},"context":{"type":"string","maxLength":2000},"blocking":{"default":false,"type":"boolean"}},"required":["text"],"additionalProperties":false}},"required":["op","item"],"additionalProperties":false}]}}},"required":["op","id","answer"],"additionalProperties":false}]}},"note":{"type":"string","maxLength":500},"confirm_large_removal":{"type":"boolean"}},"required":["expected_revision","ops"]}}}}}},"/v1/workflows/{workflow_id}/artifacts/reference":{"post":{"operationId":"reference_artifact","summary":"Register a resource without uploading it, such as a project path, a Grasshopper definition on a network drive or an internal tool","description":"Register a resource without uploading it, such as a project path, a Grasshopper definition on a network drive or an internal tool. Cite it in the spec as the returned ref.","parameters":[{"name":"workflow_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8},"description":"Unique per intended write. Reuse it only to retry the same write."}],"responses":{"200":{"description":"Success"},"401":{"description":"Missing or invalid token"},"403":{"description":"Not allowed for this person or key"},"404":{"description":"Not found"},"409":{"description":"Conflict, such as a stale revision"},"422":{"description":"Invalid arguments"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":300},"kind":{"type":"string","enum":["document","dataset","template","script","model","reference"]},"locator":{"type":"string","minLength":1,"maxLength":2000},"description":{"type":"string","maxLength":2000},"digest":{"type":"string","maxLength":20000,"description":"Your summary of the file, in plain language, for people who don't open it"},"purpose":{"type":"string","enum":["procedure","sample_input","sample_output","past_job","standard","tool","decision","failure_case","clarification","other"],"description":"Why the file is here: procedure (how it is done today), sample_input, sample_output, past_job (what came in and went out on a real job), standard (spec, code, supplier catalogue), tool (script, definition, template), decision (email, minutes, register showing who decided), failure_case (NCR, rejected submittal, clash report), clarification (sketch or markup answering a question), other"},"target":{"type":"string","maxLength":80,"description":"The item it is about, such as \"constraints.c1\" or \"questions.q2\". Omit for the whole process."}},"required":["name","kind","locator"]}}}}}},"/v1/workflows/{workflow_id}/candidates":{"post":{"operationId":"submit_candidate","summary":"Freeze the draft into a review candidate and notify the reviewer","description":"Freeze the draft into a review candidate and notify the reviewer. Returns the candidate id and hash, or a 422 listing every blocker with its path.","parameters":[{"name":"workflow_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8},"description":"Unique per intended write. Reuse it only to retry the same write."}],"responses":{"200":{"description":"Success"},"401":{"description":"Missing or invalid token"},"403":{"description":"Not allowed for this person or key"},"404":{"description":"Not found"},"409":{"description":"Conflict, such as a stale revision"},"422":{"description":"Invalid arguments"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"string","minLength":1,"maxLength":5000}},"required":["summary"]}}}}}},"/v1/focus":{"put":{"operationId":"set_focus","summary":"Move this person's open browser sessions to a screen: work, workflow (entity_id is a workflow id) or review (entity_id is a candidate id).","description":"Move this person's open browser sessions to a screen: work, workflow (entity_id is a workflow id) or review (entity_id is a candidate id).","parameters":[],"responses":{"200":{"description":"Success"},"401":{"description":"Missing or invalid token"},"403":{"description":"Not allowed for this person or key"},"404":{"description":"Not found"},"409":{"description":"Conflict, such as a stale revision"},"422":{"description":"Invalid arguments"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"screen":{"type":"string","enum":["work","workflow","review"]},"entity_id":{"type":"string","minLength":1,"maxLength":100},"session_id":{"type":"string","minLength":1,"maxLength":100}},"required":["screen"]}}}}}},"/v1/activity":{"post":{"operationId":"report_activity","summary":"Add one human-readable line to the timeline, such as 'reading the supplier spec'.","description":"Add one human-readable line to the timeline, such as 'reading the supplier spec'.","parameters":[],"responses":{"200":{"description":"Success"},"401":{"description":"Missing or invalid token"},"403":{"description":"Not allowed for this person or key"},"404":{"description":"Not found"},"409":{"description":"Conflict, such as a stale revision"},"422":{"description":"Invalid arguments"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":500},"workflow_id":{"type":"string","minLength":1,"maxLength":100}},"required":["text"]}}}}}},"/v1/events":{"get":{"operationId":"get_events","summary":"Catch up on what happened since a sequence number, including reviewer decisions.","description":"Catch up on what happened since a sequence number, including reviewer decisions.","parameters":[{"name":"since_seq","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"workflow_id","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":100}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500}}],"responses":{"200":{"description":"Success"},"401":{"description":"Missing or invalid token"},"403":{"description":"Not allowed for this person or key"},"404":{"description":"Not found"},"409":{"description":"Conflict, such as a stale revision"},"422":{"description":"Invalid arguments"}}}},"/v1/projects":{"post":{"operationId":"create_project","summary":"Create a project.","description":"Create a project.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8},"description":"Unique per intended write. Reuse it only to retry the same write."}],"responses":{"200":{"description":"Success"},"401":{"description":"Missing or invalid token"},"403":{"description":"Not allowed for this person or key"},"404":{"description":"Not found"},"409":{"description":"Conflict, such as a stale revision"},"422":{"description":"Invalid arguments"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"code":{"type":"string","minLength":1,"maxLength":50},"description":{"type":"string","maxLength":2000}},"required":["name","code"]}}}}}},"/v1/workflows":{"post":{"operationId":"create_workflow","summary":"Create a workflow and its empty draft","description":"Create a workflow and its empty draft. The reviewer can be anyone in the project who isn't a viewer, including one of its experts.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8},"description":"Unique per intended write. Reuse it only to retry the same write."}],"responses":{"200":{"description":"Success"},"401":{"description":"Missing or invalid token"},"403":{"description":"Not allowed for this person or key"},"404":{"description":"Not found"},"409":{"description":"Conflict, such as a stale revision"},"422":{"description":"Invalid arguments"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"type":"string","minLength":1,"maxLength":100},"name":{"type":"string","minLength":1,"maxLength":200},"summary":{"type":"string","maxLength":5000},"reviewer_member_id":{"type":"string","minLength":1,"maxLength":100},"due_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["project_id","name","reviewer_member_id"]}}}}}},"/v1/workflows/{workflow_id}/assignments":{"post":{"operationId":"assign_expert","summary":"Assign an expert to a workflow","description":"Assign an expert to a workflow. The expert is emailed and can accept, decline or hand part of it on. Refused for a viewer or if scopes overlap an open assignment. Omit scope_sections for the whole spec.","parameters":[{"name":"workflow_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8},"description":"Unique per intended write. Reuse it only to retry the same write."}],"responses":{"200":{"description":"Success"},"401":{"description":"Missing or invalid token"},"403":{"description":"Not allowed for this person or key"},"404":{"description":"Not found"},"409":{"description":"Conflict, such as a stale revision"},"422":{"description":"Invalid arguments"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"member_id":{"type":"string","minLength":1,"maxLength":100},"scope_sections":{"type":"array","items":{"type":"string","enum":["inputs","outputs","intermediates","steps","constraints","exceptions","references","examples","assumptions","glossary"]}},"instructions":{"type":"string","maxLength":5000},"due_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["member_id"]}}}}}},"/v1/candidates":{"get":{"operationId":"list_candidates","summary":"Pending and decided candidates with hash and readiness, for the workflows you manage, review or work on.","description":"Pending and decided candidates with hash and readiness, for the workflows you manage, review or work on.","parameters":[{"name":"workflow_id","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":100}}],"responses":{"200":{"description":"Success"},"401":{"description":"Missing or invalid token"},"403":{"description":"Not allowed for this person or key"},"404":{"description":"Not found"},"409":{"description":"Conflict, such as a stale revision"},"422":{"description":"Invalid arguments"}}}},"/v1/candidates/{candidate_id}":{"get":{"operationId":"get_candidate","summary":"The review package: readable procedure, consolidated diff against the current version, readiness, evidence and questions.","description":"The review package: readable procedure, consolidated diff against the current version, readiness, evidence and questions.","parameters":[{"name":"candidate_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"401":{"description":"Missing or invalid token"},"403":{"description":"Not allowed for this person or key"},"404":{"description":"Not found"},"409":{"description":"Conflict, such as a stale revision"},"422":{"description":"Invalid arguments"}}}},"/v1/candidates/{candidate_id}/request-changes":{"post":{"operationId":"request_changes","summary":"Send a candidate back with comments","description":"Send a candidate back with comments. Only the workflow's reviewer can do this. artifact_ids point the expert at files already on the process, such as the schedule QA accepted. There is no approve tool, because approval only happens on the review page.","parameters":[{"name":"candidate_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8},"description":"Unique per intended write. Reuse it only to retry the same write."}],"responses":{"200":{"description":"Success"},"401":{"description":"Missing or invalid token"},"403":{"description":"Not allowed for this person or key"},"404":{"description":"Not found"},"409":{"description":"Conflict, such as a stale revision"},"422":{"description":"Invalid arguments"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"candidate_hash":{"type":"string","pattern":"^[0-9a-f]{64}$"},"comments":{"type":"string","minLength":1,"maxLength":10000},"artifact_ids":{"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":100}}},"required":["candidate_hash","comments"]}}}}}},"/v1/members":{"get":{"operationId":"list_members","summary":"Members of your organization and their roles, with the member ids used by assign_expert and delegate_work.","description":"Members of your organization and their roles, with the member ids used by assign_expert and delegate_work.","parameters":[],"responses":{"200":{"description":"Success"},"401":{"description":"Missing or invalid token"},"403":{"description":"Not allowed for this person or key"},"404":{"description":"Not found"},"409":{"description":"Conflict, such as a stale revision"},"422":{"description":"Invalid arguments"}}}},"/v1/workflows/{workflow_id}/comments":{"get":{"operationId":"list_comments","summary":"Comments people left on the workflow, each on one item (target such as steps.s1) or on the whole process (target general)","description":"Comments people left on the workflow, each on one item (target such as steps.s1) or on the whole process (target general). Read them and address them in the draft.","parameters":[{"name":"workflow_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"401":{"description":"Missing or invalid token"},"403":{"description":"Not allowed for this person or key"},"404":{"description":"Not found"},"409":{"description":"Conflict, such as a stale revision"},"422":{"description":"Invalid arguments"}}},"post":{"operationId":"add_comment","summary":"Comment on one item of the workflow (target such as steps.s1, inputs.model) or on the whole process (target general)","description":"Comment on one item of the workflow (target such as steps.s1, inputs.model) or on the whole process (target general). Everyone working on it is told.","parameters":[{"name":"workflow_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8},"description":"Unique per intended write. Reuse it only to retry the same write."}],"responses":{"200":{"description":"Success"},"401":{"description":"Missing or invalid token"},"403":{"description":"Not allowed for this person or key"},"404":{"description":"Not found"},"409":{"description":"Conflict, such as a stale revision"},"422":{"description":"Invalid arguments"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"target":{"type":"string","maxLength":80},"body":{"type":"string","minLength":1,"maxLength":5000}},"required":["body"]}}}}}},"/v1/workflows/{workflow_id}/questions":{"post":{"operationId":"ask_question","summary":"For the reviewer or a manager: ask the expert a question","description":"For the reviewer or a manager: ask the expert a question. It is added to the draft as an open question, and the expert is emailed. Blocking questions must be answered before submission.","parameters":[{"name":"workflow_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8},"description":"Unique per intended write. Reuse it only to retry the same write."}],"responses":{"200":{"description":"Success"},"401":{"description":"Missing or invalid token"},"403":{"description":"Not allowed for this person or key"},"404":{"description":"Not found"},"409":{"description":"Conflict, such as a stale revision"},"422":{"description":"Invalid arguments"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":5000},"blocking":{"type":"boolean"},"context":{"type":"string","maxLength":2000}},"required":["text"]}}}}}},"/v1/workflows/{workflow_id}/history":{"get":{"operationId":"get_history","summary":"Who changed what: the saved revisions of a draft, newest first, each with its author and the items it changed, plus the candidates submitted from it.","description":"Who changed what: the saved revisions of a draft, newest first, each with its author and the items it changed, plus the candidates submitted from it.","parameters":[{"name":"workflow_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Success"},"401":{"description":"Missing or invalid token"},"403":{"description":"Not allowed for this person or key"},"404":{"description":"Not found"},"409":{"description":"Conflict, such as a stale revision"},"422":{"description":"Invalid arguments"}}}},"/v1/assignments/{assignment_id}/response":{"post":{"operationId":"respond_assignment","summary":"Accept or decline an assignment","description":"Accept or decline an assignment. Declining removes it and tells the person who asked; give a reason.","parameters":[{"name":"assignment_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"401":{"description":"Missing or invalid token"},"403":{"description":"Not allowed for this person or key"},"404":{"description":"Not found"},"409":{"description":"Conflict, such as a stale revision"},"422":{"description":"Invalid arguments"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"decision":{"type":"string","enum":["accept","decline"]},"reason":{"type":"string","maxLength":1000}},"required":["decision"]}}}}}},"/v1/workflows/{workflow_id}/delegations":{"post":{"operationId":"delegate_work","summary":"Hand some of your sections to someone else: a member (member_id) or a new person invited by email (email and name)","description":"Hand some of your sections to someone else: a member (member_id) or a new person invited by email (email and name). Your own scope shrinks to match.","parameters":[{"name":"workflow_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8},"description":"Unique per intended write. Reuse it only to retry the same write."}],"responses":{"200":{"description":"Success"},"401":{"description":"Missing or invalid token"},"403":{"description":"Not allowed for this person or key"},"404":{"description":"Not found"},"409":{"description":"Conflict, such as a stale revision"},"422":{"description":"Invalid arguments"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"scope_sections":{"minItems":1,"type":"array","items":{"type":"string","enum":["inputs","outputs","intermediates","steps","constraints","exceptions","references","examples","assumptions","glossary"]}},"member_id":{"type":"string","minLength":1,"maxLength":100},"email":{"type":"string","maxLength":320,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"name":{"type":"string","maxLength":200},"instructions":{"type":"string","maxLength":5000},"due_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["scope_sections"]}}}}}},"/v1/artifacts/{artifact_id}/annotations":{"post":{"operationId":"annotate_artifact","summary":"Add boxes with notes to an uploaded screenshot (x, y, w, h are fractions 0 to 1 of its width and height), and/or a digest: your summary of the file, shown next to it on the website","description":"Add boxes with notes to an uploaded screenshot (x, y, w, h are fractions 0 to 1 of its width and height), and/or a digest: your summary of the file, shown next to it on the website. Replaces earlier annotations.","parameters":[{"name":"artifact_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"401":{"description":"Missing or invalid token"},"403":{"description":"Not allowed for this person or key"},"404":{"description":"Not found"},"409":{"description":"Conflict, such as a stale revision"},"422":{"description":"Invalid arguments"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"annotations":{"maxItems":50,"type":"array","items":{"type":"object","properties":{"x":{"type":"number","minimum":0,"maximum":1},"y":{"type":"number","minimum":0,"maximum":1},"w":{"type":"number","minimum":0,"maximum":1},"h":{"type":"number","minimum":0,"maximum":1},"note":{"type":"string","minLength":1,"maxLength":1000}},"required":["x","y","w","h","note"]},"description":"Boxes on the image, as fractions of its width and height, each with a note"},"digest":{"type":"string","maxLength":20000,"description":"Your summary of the file, in plain language, for people who don't open it"}},"required":[]}}}}}},"/v1/workflows/{workflow_id}/requests":{"post":{"operationId":"request_document","summary":"Ask a named person in the organization for a document: a supplier letter, a calc sheet, an issued schedule, the QA checklist","description":"Ask a named person in the organization for a document: a supplier letter, a calc sheet, an issued schedule, the QA checklist. Say why it is needed and, with target, which item it is for. Blocking requests must be accepted before submission. If the person is not yet working on the process, the request is only drafted: a person must press Send on the website, because text you read could name anyone.","parameters":[{"name":"workflow_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8},"description":"Unique per intended write. Reuse it only to retry the same write."}],"responses":{"200":{"description":"Success"},"401":{"description":"Missing or invalid token"},"403":{"description":"Not allowed for this person or key"},"404":{"description":"Not found"},"409":{"description":"Conflict, such as a stale revision"},"422":{"description":"Invalid arguments"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"member_id":{"type":"string","minLength":1,"maxLength":100},"title":{"type":"string","minLength":1,"maxLength":300},"details":{"type":"string","maxLength":5000},"purpose":{"type":"string","enum":["procedure","sample_input","sample_output","past_job","standard","tool","decision","failure_case","clarification","other"],"description":"Why the file is here: procedure (how it is done today), sample_input, sample_output, past_job (what came in and went out on a real job), standard (spec, code, supplier catalogue), tool (script, definition, template), decision (email, minutes, register showing who decided), failure_case (NCR, rejected submittal, clash report), clarification (sketch or markup answering a question), other"},"target":{"type":"string","maxLength":80,"description":"The item it is about, such as \"constraints.c1\" or \"questions.q2\". Omit for the whole process."},"blocking":{"type":"boolean"},"due_at":{"description":"A date such as 2026-11-20","type":"string","maxLength":40}},"required":["member_id","title"]}}}}}},"/v1/workflows/{workflow_id}/requests/starter-pack":{"post":{"operationId":"request_starter_pack","summary":"For a manager: ask each expert on the process (or one member) for the kick-off documents: the current procedure, one input, one correct output and one past job","description":"For a manager: ask each expert on the process (or one member) for the kick-off documents: the current procedure, one input, one correct output and one past job. Requests that already exist are skipped.","parameters":[{"name":"workflow_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8},"description":"Unique per intended write. Reuse it only to retry the same write."}],"responses":{"200":{"description":"Success"},"401":{"description":"Missing or invalid token"},"403":{"description":"Not allowed for this person or key"},"404":{"description":"Not found"},"409":{"description":"Conflict, such as a stale revision"},"422":{"description":"Invalid arguments"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"member_id":{"type":"string","minLength":1,"maxLength":100},"blocking":{"type":"boolean"}},"required":[]}}}}}},"/v1/requests":{"get":{"operationId":"list_requests","summary":"Document requests","description":"Document requests. With workflow_id: every request on that process. Without: the documents people asked of you (with the item they are for) and the ones you asked for that are still open.","parameters":[{"name":"workflow_id","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":100}}],"responses":{"200":{"description":"Success"},"401":{"description":"Missing or invalid token"},"403":{"description":"Not allowed for this person or key"},"404":{"description":"Not found"},"409":{"description":"Conflict, such as a stale revision"},"422":{"description":"Invalid arguments"}}}},"/v1/requests/{request_id}/provide":{"post":{"operationId":"provide_document","summary":"For the person a document was asked of: add the file (base64, 2 MB or less) or the path where it is kept (locator), with a short note","description":"For the person a document was asked of: add the file (base64, 2 MB or less) or the path where it is kept (locator), with a short note. Only you can, only for a request made to you, and you see nothing else of the process. Larger files: POST /v1/requests/{id}/files as multipart, or the request page on the website.","parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8},"description":"Unique per intended write. Reuse it only to retry the same write."}],"responses":{"200":{"description":"Success"},"401":{"description":"Missing or invalid token"},"403":{"description":"Not allowed for this person or key"},"404":{"description":"Not found"},"409":{"description":"Conflict, such as a stale revision"},"422":{"description":"Invalid arguments"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":300},"kind":{"type":"string","enum":["document","dataset","template","script","model","reference"]},"mime":{"type":"string","minLength":1,"maxLength":200},"content_base64":{"type":"string","maxLength":3000000,"pattern":"^[A-Za-z0-9+/=\\s]*$"},"locator":{"type":"string","maxLength":2000},"digest":{"type":"string","maxLength":20000,"description":"Your summary of the file, in plain language, for people who don't open it"},"note":{"type":"string","maxLength":2000}},"required":["name"]}}}}}},"/v1/requests/{request_id}/decision":{"post":{"operationId":"decide_request","summary":"For the person who asked (or a manager): accept the document that was sent, return it with a reason (wrong revision, a draft instead of the issued one), or cancel the request","description":"For the person who asked (or a manager): accept the document that was sent, return it with a reason (wrong revision, a draft instead of the issued one), or cancel the request. Check the file against what was asked before accepting.","parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8},"description":"Unique per intended write. Reuse it only to retry the same write."}],"responses":{"200":{"description":"Success"},"401":{"description":"Missing or invalid token"},"403":{"description":"Not allowed for this person or key"},"404":{"description":"Not found"},"409":{"description":"Conflict, such as a stale revision"},"422":{"description":"Invalid arguments"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"decision":{"type":"string","enum":["accept","return","cancel"]},"reason":{"type":"string","maxLength":2000}},"required":["decision"]}}}}}},"/v1/keys/{agent_key_id}":{"delete":{"operationId":"revoke_key","summary":"Revoke one of your own agent keys","description":"Revoke one of your own agent keys. Admins can revoke any key in the organization.","parameters":[{"name":"agent_key_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"401":{"description":"Missing or invalid token"},"403":{"description":"Not allowed for this person or key"},"404":{"description":"Not found"},"409":{"description":"Conflict, such as a stale revision"},"422":{"description":"Invalid arguments"}}}}}}