{ "openapi": "3.1.1", "info": { "title": "Arbituro API", "description": "A workspace's jobs, as a program reads and writes them. Every operation names a project, and the project chooses the workspace among the ones the caller is in. Reads give a job's contract — its done-when clauses, each with its state and who decides it. Writes raise decisions and leave notes; none of them ticks a clause, approves anything or moves a job. Every call acts as the person whose token it carries, and is on the record.", "version": "1" }, "servers": [ { "url": "https://app.arbituro.com/" } ], "paths": { "/api/v1/projects/{project}/jobs": { "get": { "tags": [ "PublicApiRead" ], "summary": "List a project's jobs", "description": "A project's jobs in the order people set, one line each. Unfinished jobs unless `status` says otherwise; 50 at a time, the next page by `after`.", "operationId": "list_jobs", "parameters": [ { "name": "project", "in": "path", "description": "The project's key, e.g. FLAIR.", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "A status's name, or one of: open (the default: every unfinished job), not-started, underway, finished, dropped, all.", "schema": { "type": "string" } }, { "name": "owner", "in": "query", "description": "Only the jobs this person owns, by name. Pass \"me\" for the person you act for, or \"none\" for the jobs nobody owns.", "schema": { "type": "string" } }, { "name": "partOf", "in": "query", "description": "Only the jobs that are part of this job, by its key, e.g. FLAIR-3.", "schema": { "type": "string" } }, { "name": "untouchedDays", "in": "query", "description": "Only the jobs nothing has happened on for at least this many days.", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "limit", "in": "query", "description": "How many jobs to return, up to 100. Defaults to 50.", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "after", "in": "query", "description": "The key the last page ended on, to read the page after it.", "schema": { "type": "string" } } ], "responses": { "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } }, "post": { "tags": [ "PublicApiWrite" ], "summary": "File a job", "description": "File a new job in a project. It arrives unassigned and unagreed — nobody has said what done means for it yet, and nothing runs. For work you found that nobody has written down.", "operationId": "create_job", "parameters": [ { "name": "project", "in": "path", "description": "The project's key, e.g. FLAIR.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateJobRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreateJobRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateJobRequest" } } }, "required": true }, "responses": { "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAnswer" } } } } } } }, "/api/v1/projects/{project}/jobs/{job}": { "get": { "tags": [ "PublicApiRead" ], "summary": "Get a job in full", "description": "One job: its description, the done-when clauses that define completion and the state each is in, who decides each, who it is assigned to, the job it is part of, how many parts it has, and what has been spent.", "operationId": "get_job", "parameters": [ { "name": "project", "in": "path", "description": "The project's key, e.g. FLAIR.", "required": true, "schema": { "type": "string" } }, { "name": "job", "in": "path", "description": "The job's key, e.g. FLAIR-12.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/api/v1/projects/{project}/jobs/{job}/notes": { "get": { "tags": [ "PublicApiRead" ], "summary": "Read a job's conversation", "description": "What people and agents have said about one job, oldest first.", "operationId": "list_comments", "parameters": [ { "name": "project", "in": "path", "description": "The project's key, e.g. FLAIR.", "required": true, "schema": { "type": "string" } }, { "name": "job", "in": "path", "description": "The job's key, e.g. FLAIR-12.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } }, "post": { "tags": [ "PublicApiWrite" ], "summary": "Post a note", "description": "Leave a note on a job, as yourself. It appears under your name in the job's conversation and tells the people you @mention who can open the job. Naming an agent starts nothing.", "operationId": "post_note", "parameters": [ { "name": "project", "in": "path", "description": "The project's key, e.g. FLAIR.", "required": true, "schema": { "type": "string" } }, { "name": "job", "in": "path", "description": "The job's key, e.g. FLAIR-12.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostNoteRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/PostNoteRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/PostNoteRequest" } } }, "required": true }, "responses": { "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteAnswer" } } } } } } }, "/api/v1/projects/{project}/jobs/{job}/history": { "get": { "tags": [ "PublicApiRead" ], "summary": "Read a job's history", "description": "What changed on one job and who changed it, most recent first.", "operationId": "job_history", "parameters": [ { "name": "project", "in": "path", "description": "The project's key, e.g. FLAIR.", "required": true, "schema": { "type": "string" } }, { "name": "job", "in": "path", "description": "The job's key, e.g. FLAIR-12.", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "How many entries to return, up to 50. Defaults to 20.", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/api/v1/projects/{project}/search": { "get": { "tags": [ "PublicApiRead" ], "summary": "Search a project", "description": "One project's existing work, history and published vault documents. Search before proposing anything, to find whether the question has already been settled.", "operationId": "search", "parameters": [ { "name": "project", "in": "path", "description": "The project's key, e.g. FLAIR.", "required": true, "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Specific terms to find in this project's existing work and history.", "schema": { "type": "string" } }, { "name": "scope", "in": "query", "description": "\"all\" (default) searches every kind of record. \"vault\" searches only the project's published, curated documents.", "schema": { "type": "string", "default": "all" } } ], "responses": { "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/api/v1/projects/{project}/what-happened": { "get": { "tags": [ "PublicApiRead" ], "summary": "What happened", "description": "The record of what has happened in a project recently — decisions, runs, approvals and changes, as one timeline, newest first. Catch up before working, or find out how something came to be the way it is.", "operationId": "what_happened", "parameters": [ { "name": "project", "in": "path", "description": "The project's key, e.g. FLAIR.", "required": true, "schema": { "type": "string" } }, { "name": "job", "in": "query", "description": "Narrow to one job by its key, e.g. FLAIR-12. Omit for the whole project.", "schema": { "type": "string" } } ], "responses": { "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/api/v1/projects/{project}/jobs/{job}/proposals": { "post": { "tags": [ "PublicApiWrite" ], "summary": "Propose a change to a job", "description": "Propose a change to a job's title or description. Changes nothing: it raises a proposal on the job owner's queue, and they accept, edit or dismiss it in one press. On a job whose first look is under way (`firstLook` on the job) it stops that look, and the job's shape is then the proposer's to propose.", "operationId": "propose_job_update", "parameters": [ { "name": "project", "in": "path", "description": "The project's key, e.g. FLAIR.", "required": true, "schema": { "type": "string" } }, { "name": "job", "in": "path", "description": "The job's key, e.g. FLAIR-12.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposeJobUpdateRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProposeJobUpdateRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/ProposeJobUpdateRequest" } } }, "required": true }, "responses": { "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalAnswer" } } } } } } }, "/api/v1/projects/{project}/jobs/{job}/claims": { "post": { "tags": [ "PublicApiWrite" ], "summary": "Claim a done-when is met", "description": "Record that you believe one of a job's done-when clauses is now met, with your evidence. This does not tick the clause — a person decides that — it attaches your finding so they decide holding it. A clause a check or a send decides is refused.", "operationId": "claim_done", "parameters": [ { "name": "project", "in": "path", "description": "The project's key, e.g. FLAIR.", "required": true, "schema": { "type": "string" } }, { "name": "job", "in": "path", "description": "The job's key, e.g. FLAIR-12.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimDoneRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ClaimDoneRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/ClaimDoneRequest" } } }, "required": true }, "responses": { "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimAnswer" } } } } } } }, "/api/v1/projects/{project}/jobs/{job}/pull-requests": { "post": { "tags": [ "PublicApiWrite" ], "summary": "Link a pull request", "description": "Put the pull request opened for a job on that job, so the job shows the work: its title, its state and its CI. The pull request must be in a GitHub repository bound to the job's project. This changes nothing in GitHub and decides nothing here.", "operationId": "link_pull_request", "parameters": [ { "name": "project", "in": "path", "description": "The project's key, e.g. FLAIR.", "required": true, "schema": { "type": "string" } }, { "name": "job", "in": "path", "description": "The job's key, e.g. FLAIR-12.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkPullRequestRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/LinkPullRequestRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/LinkPullRequestRequest" } } }, "required": true }, "responses": { "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PullRequestAnswer" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } } } } }, "/api/v1/projects/{project}/jobs/{job}/results": { "post": { "tags": [ "PublicApiWrite" ], "summary": "File a job's result", "description": "File the document a job asks for, as Markdown, when its expected result is a document, a one-page memo or a slide deck. It becomes the job's result in that shape, under your name; filing again replaces it with the next version. It is checked as it is filed and refused with what to fix. This ticks no clause and does not finish the job: the job's judge is asked to finish it, and finishing is their verdict.", "operationId": "file_result", "parameters": [ { "name": "project", "in": "path", "description": "The project's key, e.g. FLAIR.", "required": true, "schema": { "type": "string" } }, { "name": "job", "in": "path", "description": "The job's key, e.g. FLAIR-12.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileResultRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FileResultRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/FileResultRequest" } } }, "required": true }, "responses": { "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResultAnswer" } } } } } } } }, "components": { "schemas": { "ClaimAnswer": { "required": [ "message", "clause", "decider" ], "type": "object", "properties": { "message": { "type": "string" }, "clause": { "type": "string" }, "decider": { "type": "string", "description": "Who decides the clause, by name." } } }, "ClaimDoneRequest": { "required": [ "clause", "evidence" ], "type": "object", "properties": { "clause": { "type": "string", "description": "The clause's text, or enough of its beginning to identify it uniquely." }, "evidence": { "type": "string", "description": "What you checked and what you found. This is the evidence a person reads before deciding." } } }, "CreateJobRequest": { "required": [ "title", "description" ], "type": "object", "properties": { "title": { "type": "string", "description": "Short, imperative title." }, "description": { "type": [ "null", "string" ], "description": "What the job is, as markdown. Say what you found and why it matters." } } }, "FileResultRequest": { "required": [ "markdown" ], "type": "object", "properties": { "markdown": { "type": "string", "description": "The whole result, as Markdown. In a slide deck, a `---` line with a blank line above it starts the next slide, and each slide opens with its heading." }, "title": { "type": [ "null", "string" ], "description": "What to call it. Omit to use the job's title." } } }, "JobAnswer": { "required": [ "message", "key", "title" ], "type": "object", "properties": { "message": { "type": "string" }, "key": { "type": "string" }, "title": { "type": "string" } } }, "LinkPullRequestRequest": { "required": [ "url" ], "type": "object", "properties": { "url": { "type": "string", "description": "The pull request's address, e.g. https://github.com/acme/api/pull/41." } } }, "NoteAnswer": { "required": [ "message", "noteId" ], "type": "object", "properties": { "message": { "type": "string" }, "noteId": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } }, "PostNoteRequest": { "required": [ "body" ], "type": "object", "properties": { "body": { "type": "string", "description": "The note, as markdown." } } }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": [ "null", "string" ] }, "title": { "type": [ "null", "string" ] }, "status": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "detail": { "type": [ "null", "string" ] }, "instance": { "type": [ "null", "string" ] } } }, "ProposalAnswer": { "required": [ "message", "proposalId" ], "type": "object", "properties": { "message": { "type": "string" }, "proposalId": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } }, "ProposedClause": { "required": [ "text" ], "type": "object", "properties": { "text": { "type": "string", "description": "What is true when this part of the job is done, in one sentence." }, "check": { "type": [ "null", "string" ], "description": "The exact name of the CI check that decides it, e.g. test, when one does. Omit for a clause a person decides." } } }, "ProposeJobUpdateRequest": { "required": [ "title", "description", "rationale" ], "type": "object", "properties": { "title": { "type": [ "null", "string" ], "description": "The title you propose. Omit to leave the title alone." }, "description": { "type": [ "null", "string" ], "description": "The description you propose, as markdown. Omit to leave the description alone." }, "rationale": { "type": [ "null", "string" ], "description": "Why you are proposing this. Shown to the person deciding, so say what you found rather than what you changed." }, "doneWhen": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/ProposedClause" }, "description": "Done-when clauses to add, at most five. Each is added beside the job's own when a person accepts it; none is changed or removed." } } }, "PullRequestAnswer": { "required": [ "message", "pullRequest", "url" ], "type": "object", "properties": { "message": { "type": "string" }, "pullRequest": { "type": "string" }, "url": { "type": "string" } } }, "Refusal": { "required": [ "message" ], "type": "object", "properties": { "message": { "type": "string", "description": "Why, in a sentence. The same sentence a coding agent is told over MCP." } } }, "ResultAnswer": { "required": [ "message", "title", "version", "judge" ], "type": "object", "properties": { "message": { "type": "string" }, "title": { "type": "string" }, "version": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Which version of the job's result this is; filing again makes the next.", "format": "int32" }, "judge": { "type": [ "null", "string" ], "description": "Who is asked to finish the job, by name. Null where nobody judges it and everyone who can change the project is asked." } } } }, "securitySchemes": { "bearer": { "type": "http", "description": "Either a token WorkOS issued for this API — its audience is this door's own URL, as the discovery document at /.well-known/oauth-protected-resource/api/v1 names it; a token for the workspace app or for an MCP endpoint is refused here, and this one is refused there — or an API key a person made in Settings, under Connections, which acts as them in the one workspace it was made for.", "scheme": "bearer", "bearerFormat": "JWT" } } }, "security": [ { "bearer": [ ] } ], "tags": [ { "name": "PublicApiRead" }, { "name": "PublicApiWrite" } ] }