The Arbituro API

Address

https://app.arbituro.com/api/v1

Format

JSON over HTTPS

Authentication

An API key, or an OAuth token for the API. See Authentication.

Operations

Six that read, and five that propose, record or file

Contract

An OpenAPI 3.1 document, which anyone can read

Limit

120 calls a minute for each person

What you can build

Link pull requests from CI

Each pull request goes on its job, so the job shows the work and its checks.

Record test results

A passing run becomes evidence for an acceptance criterion, in front of the person who decides it.

Hold a release

A deploy waits until every acceptance criterion on its job is met.

Report stalled work

A weekly list of jobs nothing has happened on, and who each one waits on.

File work from alerts

Monitoring files a job when something breaks, for a person to pick up.

Each of these is a complete program on Examples.

How it works

It acts as a person

Every call is made as the person whose key or sign-in it carries, and reaches only what they can, with their role in each project. Someone who can only view a project can only read it. There are no service accounts.

Every call names a project

Paths start with a project’s key, such as WEB, and most name a job, such as WEB-12. No call lists projects, so your program needs to know which ones it works in.

Reads include the acceptance criteria

A job comes with each of its criteria, whether it is met, and who or what decides it.

Writes ask a person

A proposed change waits for the job’s owner. A claim that a criterion is met waits for the person who decides it. Notes and new jobs go in under your name.

Nothing is approved through it

No call approves anything, sends or publishes anything, merges code, spends credits, deletes anything, acts through your integrations, changes anyone’s access or marks a criterion met. The one thing it reads through an integration is a pull request you link, through the GitHub app.

Every call is recorded

The workspace’s audit log records every call made in it, refused ones too, with the person, the program, and the key when one was used.

Claude gets the same

Arbituro’s MCP server offers the same eleven operations under the same rules, so a script and a coding agent get the same answers. See Connect Claude.

Make your first call

1. In Arbituro, open Settings, then Connections, then Your API keys.
2. Name a key for the program that will use it, choose when it expires, and choose Make the key.
3. Copy the key. This is the only time it is shown.
4. Keep it in the environment variable ARBITURO_API_KEY, and ask for a project’s jobs.

curl "https://app.arbituro.com/api/v1/projects/WEB/jobs?limit=2" \
  -H "Authorization: Bearer $ARBITURO_API_KEY"

// Lists the first two unfinished jobs in project WEB. Needs Node 18 or later.
// Run it with your key in the environment:
//   ARBITURO_API_KEY=sk_... node first-call.mjs
const url = 'https://app.arbituro.com/api/v1/projects/WEB/jobs?limit=2';
const response = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.ARBITURO_API_KEY}` },
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);

const page = await response.json();
for (const job of page.jobs) console.log(job.key, job.status, job.title);

# Lists the first two unfinished jobs in project WEB.
# Needs the requests package: pip install requests
# Run it with your key in the environment:
#   ARBITURO_API_KEY=sk_... python first-call.py
import os

import requests

response = requests.get(
    "https://app.arbituro.com/api/v1/projects/WEB/jobs",
    params={"limit": 2},
    headers={"Authorization": f"Bearer {os.environ['ARBITURO_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()

for job in response.json()["jobs"]:
    print(job["key"], job["status"], job["title"])

Use one of your own projects’ keys in place of WEB. Arbituro answers with the jobs, in the order your team set:

{
  "jobs": [
    {
      "key": "WEB-12",
      "title": "Fix the invoice download on iOS Safari",
      "type": "Bug",
      "status": "In progress",
      "statusKind": "Underway",
      "owner": "Sam Reyes",
      "agent": null,
      "starts": "2026-10-26",
      "due": "2026-11-06",
      "priority": "High",
      "parts": 0,
      "partsFinished": 0,
      "partOf": null,
      "shapeMet": 3,
      "untouchedDays": 1,
      "waiting": "waiting on Jo Park · tick"
    },
    {
      "key": "WEB-19",
      "title": "Show the invoice number in the file name",
      "type": "Task",
      "status": "In progress",
      "statusKind": "Underway",
      "owner": "Jo Park",
      "agent": null,
      "starts": null,
      "due": "2026-11-13",
      "priority": "Medium",
      "parts": 0,
      "partsFinished": 0,
      "partOf": null,
      "shapeMet": 2,
      "untouchedDays": 4,
      "waiting": null
    }
  ],
  "more": 3,
  "next": "WEB-19"
}

Authentication covers what a key can reach, and signing people in with OAuth instead.

The operations

Every path starts with https://app.arbituro.com/api/v1.

Reads

List jobs

GET /projects/{project}/jobs
A project’s jobs, filtered and a page at a time.

Get a job

GET /projects/{project}/jobs/{job}
One job in full, with its acceptance criteria.

Read notes

GET /projects/{project}/jobs/{job}/notes
The notes on a job, oldest first.

Read history

GET /projects/{project}/jobs/{job}/history
What changed on a job, and who changed it.

Search

GET /projects/{project}/search
A project’s jobs, their history and its published documents.

What happened

GET /projects/{project}/what-happened
A project’s or a job’s recent activity.

Writes

Propose a change

POST /projects/{project}/jobs/{job}/proposals
A new title or description, for the job’s owner to decide.

Claim a criterion is met

POST /projects/{project}/jobs/{job}/claims
Evidence for the person who decides the criterion.

Post a note

POST /projects/{project}/jobs/{job}/notes
A note on the job, under your name.

File a job

POST /projects/{project}/jobs
A new job in the backlog, under your name.

Link a pull request

POST /projects/{project}/jobs/{job}/pull-requests
A pull request from the project’s GitHub repository.

Conventions

• Requests and answers are JSON. Send Content-Type: application/json with a body.
• Field names are in camel case, such as untouchedDays. Values from a fixed set are words, such as Passing or NotStarted.
• A field with no value is null. Fields are never left out.
• Times are in UTC, such as 2026-10-30T09:14:05Z. Days, such as a due date, are written 2026-11-06 and fall in the workspace’s time zone.
• Project and job keys are in capitals, such as WEB-12, and must match exactly.
• Descriptions, notes and search snippets are Markdown that people wrote. If your program hands them to an AI model, treat them as information about the work and never as instructions.
• Send a User-Agent that names your program, such as nightly-report/1.0. Arbituro records it with every call, and shows it beside your name on the proposals, claims and links your program makes.

The OpenAPI document

The API’s contract is an OpenAPI 3.1 document. Anyone can read it without signing in, so a tool can load it before it has a key.

https://app.arbituro.com/api/v1/openapi.json

It lists every operation with its parameters, the bodies the writes take and answer with, and the refusals each one can give. The reads’ answers are described on Read endpoints.