Read endpoints

Every read answers 200 with JSON. A project you can’t open gets 404, as does a job that isn’t there. See Errors and limits.

List jobs

Lists a project’s jobs in the order your team set, unfinished ones unless you ask for others. It answers with 50 at a time, or as many as limit asks for, up to 100.

Query parameters

status string, optional

A status’s name in this project, such as In progress, or one of open (the default: every unfinished job), not-started, underway, finished, dropped and all.

owner string, optional

Only the jobs this person owns, by name. none gives the jobs nobody owns.

partOf string, optional

Only the jobs that are part of this job, by its key.

untouchedDays integer, optional

Only the jobs nothing has happened on for at least this many days.

limit integer, optional

How many jobs to answer with, from 1 to 100. The default is 50.

after string, optional

The next key from the page before, to read the page after it.

Answer

jobs array

The jobs on this page, each with the fields below.

more integer

How many more jobs the filters match after this page.

next string or null

The key to pass as after for the next page, or null on the last page.

Each job

key string

The job’s key, such as WEB-12.

title string

The job’s title.

type string

Story, Task, Bug or Spike.

status string

The status as the project names it. In a project with no statuses of its own, open, finished or dropped.

statusKind string or null

NotStarted, Underway, Finished or Dropped. null in a project with no statuses of its own.

owner string or null

The owner’s name, or null when nobody owns the job.

agent string or null

The name of the agent assigned to the job.

starts, due day or null

The job’s start and due days.

priority string or null

Low, Medium, High or Critical.

parts integer

How many jobs are part of this one.

partsFinished integer

How many of those are finished.

partOf string or null

The key of the job this one is part of.

shapeMet integer or null

How many of three things hold: the job has an objective, it has acceptance criteria, and no question on it is open. null when that hasn’t been worked out for the job.

untouchedDays integer or null

Days since anything happened on the job. null where that doesn’t apply.

waiting string or null

Who the job is waiting on and for what, in a few words. null when it waits on nobody.

Example

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

{
  "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"
}

To read every page, pass each answer’s next as after until next is null. A status the project doesn’t have is refused with 400, and the message lists the project’s own statuses.

Get a job

Reads one job in full: its description, its acceptance criteria with the state of each and who or what decides each one, and what has been spent on it.

Answer

The job has the fields List jobs gives, except shapeMet, untouchedDays and waiting, and these:

finished, dropped boolean

Whether the job is finished, or dropped.

comments integer

How many notes are on the job.

description string or null

The description, in Markdown.

information array

Questions asked on the job, each with question and answer. The answer is null until someone gives one.

doneWhen array

The acceptance criteria, in order, each with the fields below. The job is finished when every one is met. An empty list means nobody has agreed yet what finished means.

spentCredits integer

Credits spent on the job so far.

budgetCredits integer or null

The job’s credit limit, or null when it has none.

Each acceptance criterion

text string

What has to be true.

state string

Unknown while undecided, Passing when met, Failing when not met, and Waived when set aside.

decidedBy string

How the criterion is decided. See the values below.

decider string or null

The person who decides it, when the criterion names one.

check string or null

The name of the CI check that decides it, when one does.

due day or null

The day it should be decided by.

The values of decidedBy match the ways a criterion can be decided, as Acceptance criteria describes:

Person

The person in decider decides it.

Owner

It names nobody, so whoever judges the job decides it: the job’s owner, unless judging was handed to someone else.

Check

The CI check in check decides it, on a pull request linked to the job.

Automatic

It is checked automatically, with no named check.

Send

An approved message settles it when the message is sent.

Example

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

{
  "key": "WEB-12",
  "title": "Fix the invoice download on iOS Safari",
  "type": "Bug",
  "status": "In progress",
  "statusKind": "Underway",
  "finished": false,
  "dropped": false,
  "starts": "2026-10-26",
  "due": "2026-11-06",
  "priority": "High",
  "partOf": null,
  "owner": "Sam Reyes",
  "agent": null,
  "parts": 0,
  "partsFinished": 0,
  "comments": 2,
  "description": "Downloading an invoice PDF on iOS Safari answers 404. Desktop browsers are fine.",
  "information": [
    {
      "question": "Does the Android app have the same problem?",
      "answer": "No, only Safari on iOS."
    }
  ],
  "doneWhen": [
    {
      "text": "A download completes on iOS Safari.",
      "state": "Unknown",
      "decidedBy": "Person",
      "decider": "Jo Park",
      "check": null,
      "due": "2026-11-04"
    },
    {
      "text": "The build passes.",
      "state": "Passing",
      "decidedBy": "Check",
      "decider": null,
      "check": "build",
      "due": null
    },
    {
      "text": "Support knows the fix is live.",
      "state": "Unknown",
      "decidedBy": "Send",
      "decider": null,
      "check": null,
      "due": null
    }
  ],
  "spentCredits": 0,
  "budgetCredits": null
}

Read a job’s notes

Reads the notes people and agents left on a job, oldest first. It answers with the first 100.

Answer

A notes array, each note with these fields:

id integer

The note’s ID.

at time

When it was written.

author string

Who wrote it, by name.

authorKind string

Human for a person, or Agent for an agent.

body string

The note, in Markdown.

Example

curl "https://app.arbituro.com/api/v1/projects/WEB/jobs/WEB-12/notes" \
  -H "Authorization: Bearer $ARBITURO_API_KEY"

{
  "notes": [
    {
      "id": 9131,
      "at": "2026-10-28T23:12:44Z",
      "author": "Sam Reyes",
      "authorKind": "Human",
      "body": "Reproduced on iOS 18. Desktop Safari is fine."
    },
    {
      "id": 9134,
      "at": "2026-10-29T02:40:03Z",
      "author": "Jo Park",
      "authorKind": "Human",
      "body": "The PDF is sent with the wrong content type. The fix is in acme/web#41."
    }
  ]
}

Read a job’s history

Reads what changed on a job and who changed it, newest first.

Query parameters

limit integer, optional

How many changes to answer with, from 1 to 50. The default is 20.

Answer

An entries array, each change with these fields:

at time

When the change was made.

change string

Created, Updated, or Scheduled for a change to the job’s dates.

by string

Who made the change, by name.

source string

The part of Arbituro the change came through.

fields array

Each field that changed, with field, and its old and new values as text in from and to. A value longer than 80 characters is shortened.

Example

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

{
  "entries": [
    {
      "at": "2026-10-29T02:41:10Z",
      "change": "Updated",
      "by": "Jo Park",
      "source": "WorkItemsController",
      "fields": [
        {
          "field": "Title",
          "from": "Invoice download broken",
          "to": "Fix the invoice download on iOS Safari"
        }
      ]
    }
  ]
}

Search a project

Searches a project’s jobs, their history and the documents published to its agents, and answers with the best 8 matches. Search before you propose or file anything, to see whether it is already settled.

Query parameters

q string, required

What to look for. Only the first 500 characters are used.

scope string, optional

all, the default, searches everything. vault searches only the documents published to the project’s agents.

Answer

A results array, best first, each result with these fields:

rank integer

Its place in the results, from 1.

kind string

What kind of record it is, such as work-item for a job or vault-document for a published document.

key string or null

The record’s key, when it has one.

title string

The record’s title.

subtitle string or null

A few words more, such as a job’s type.

snippet string

The passage that matched.

updatedAt time

When the record last changed.

vault object or null

For a published document: cite, the handle agents cite it by; trust, which is current, stale, superseded or retired; and supersededBy, the key of the document that replaces it, when someone named one.

Example

curl "https://app.arbituro.com/api/v1/projects/WEB/search?q=invoice%20download" \
  -H "Authorization: Bearer $ARBITURO_API_KEY"

{
  "results": [
    {
      "rank": 1,
      "kind": "work-item",
      "key": "WEB-12",
      "title": "Fix the invoice download on iOS Safari",
      "subtitle": "Bug",
      "snippet": "Downloading an invoice PDF on iOS Safari answers 404. Desktop browsers are fine.",
      "updatedAt": "2026-10-29T02:41:10Z",
      "vault": null
    }
  ]
}

A search with no q is refused with 400.

What happened

Reads a project’s recent activity, newest first: jobs filed and changed, notes, runs, decisions and approvals, a line each. It answers with the latest 30 lines. Name a job to see only its activity.

Query parameters

job string, optional

A job’s key, to see only that job’s activity.

Answer

lines array

The activity, newest first, each with the fields below.

total integer

How many lines there are in all.

Each line

at time

When it happened.

line string

What happened, in a sentence that names who did it.

job string or null

The key of the job it happened on, or null for the project itself.

Example

curl "https://app.arbituro.com/api/v1/projects/WEB/what-happened?job=WEB-12" \
  -H "Authorization: Bearer $ARBITURO_API_KEY"

{
  "lines": [
    {
      "at": "2026-10-29T02:40:03Z",
      "line": "Jo Park: The PDF is sent with the wrong content type. The fix is in acme/web#41.",
      "job": "WEB-12"
    },
    {
      "at": "2026-10-28T23:12:44Z",
      "line": "Sam Reyes: Reproduced on iOS 18. Desktop Safari is fine.",
      "job": "WEB-12"
    },
    {
      "at": "2026-10-28T23:05:31Z",
      "line": "Sam Reyes created this job",
      "job": "WEB-12"
    }
  ],
  "total": 3
}