Write endpoints

Before you write

• Writing needs the right to change work in the project. If your workspace role or your role in the project is Viewer, every write is refused with 403. See People and roles.
• Send the body as JSON, with Content-Type: application/json.
• A write answers 201 Created. Its message says what happened in a sentence, and its other fields give what your program needs next.
• Writes are made under your name. Proposals, claims and linked pull requests also show in What happened on the job, with your name and your program’s name.

Propose a change

Proposes a new title or description for a job. The job doesn’t change. Its owner is asked to accept, edit or dismiss the proposal.

Body

title string, optional

The title you propose, up to 300 characters. Leave it out to keep the title.

description string, optional

The description you propose, in Markdown, up to 8,000 characters. Leave it out to keep the description.

rationale string, optional

Why you propose it. The person deciding sees it, so say what you found.

Send a title, a description, or both.

Answer

message string

What happened, in a sentence.

proposalId integer

The proposal’s ID.

Example

curl -X POST \
  "https://app.arbituro.com/api/v1/projects/WEB/jobs/WEB-12/proposals" \
  -H "Authorization: Bearer $ARBITURO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "Downloading an invoice PDF on iOS Safari answers 404, because the PDF is sent with the wrong content type. Desktop browsers are fine.",
  "rationale": "The cause is known now. Jo found it while fixing the download."
}'

{
  "message": "Proposed. WEB-12 is unchanged; the proposal is waiting on a person to accept, edit or dismiss it.",
  "proposalId": 482
}

Refusals

400

Nothing was proposed, or a title or description is too long.

409

A proposal is already waiting on the job. It has to be decided before another is raised.

Claim a criterion is met

Records evidence that one acceptance criterion is met, and asks the person who decides it. The criterion stays undecided until they decide, with your evidence in front of them.

Only criteria a person decides can be claimed. A criterion a CI check decides is settled by the check, on a pull request linked to the job. One that a message settles is settled when the message is sent.

Body

clause string, required

The criterion’s text, or enough of its start to pick out one criterion.

evidence string, required

What you checked and what it showed. The person deciding reads it first. Up to 2,000 characters are kept.

Answer

message string

What happened, in a sentence.

clause string

The criterion’s full text.

decider string

Who decides it, by name.

Example

curl -X POST \
  "https://app.arbituro.com/api/v1/projects/WEB/jobs/WEB-12/claims" \
  -H "Authorization: Bearer $ARBITURO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "clause": "A download completes",
  "evidence": "Downloaded invoice 1042 in Safari on iOS 18.1 against staging, and the PDF opened. Run: https://ci.example.com/runs/812"
}'

{
  "message": "Recorded against \"A download completes on iOS Safari.\". The clause is still undecided — Jo Park ticks it.",
  "clause": "A download completes on iOS Safari.",
  "decider": "Jo Park"
}

Refusals

400

No evidence, no criterion named, or text that matches more than one criterion.

404

No criterion on the job starts with that text.

409

The criterion is decided by a CI check, automatically, or by a message being sent. The message says what settles it instead.

Post a note

Adds a note to the job under your name. People you @mention who can open the job are told, as they would be for a note you wrote in Arbituro. Mentioning an agent doesn’t start it.

Body

body string, required

The note, in Markdown, up to 8,000 characters.

Answer

message string

What happened, in a sentence.

noteId integer

The note’s ID.

Example

curl -X POST \
  "https://app.arbituro.com/api/v1/projects/WEB/jobs/WEB-12/notes" \
  -H "Authorization: Bearer $ARBITURO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "body": "The fix is on staging, ready to check on a phone."
}'

{
  "message": "Posted on WEB-12.",
  "noteId": 9140
}

Refusals

400

The note is empty, or too long.

File a job

Files a new job in the project’s backlog under your name. It has no owner, no agent and no acceptance criteria, and nothing starts on it until a person picks it up.

Body

title string, required

What needs doing, as a short title.

description string, optional

What the job is, in Markdown. Say what you found and why it matters.

Answer

message string

What happened, in a sentence.

key string

The new job’s key.

title string

Its title.

The Location header gives the new job’s path, such as /api/v1/projects/WEB/jobs/WEB-31.

Example

curl -X POST \
  "https://app.arbituro.com/api/v1/projects/WEB/jobs" \
  -H "Authorization: Bearer $ARBITURO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Retry a failed invoice download",
  "description": "A download that fails on a slow connection leaves the customer with nothing. Retry once before showing an error."
}'

{
  "message": "Created WEB-31: \"Retry a failed invoice download\" (in the backlog).",
  "key": "WEB-31",
  "title": "Retry a failed invoice download"
}

Refusals

400

The title is missing.

Link a pull request

Puts a pull request on the job, so the job shows it with its state and its CI checks. Arbituro reads the pull request from GitHub and writes nothing there. A criterion that a CI check decides is then settled by that check on this pull request, and nothing else about the job changes.

The pull request has to be in a GitHub repository linked to the job’s project, and Arbituro’s GitHub app has to be able to see it. See Link repositories to a project.

Body

url string, required

The pull request’s github.com address, such as https://github.com/acme/web/pull/41.

Answer

message string

What happened, in a sentence.

pullRequest string

The pull request as GitHub names it, such as acme/web#41.

url string

Its address.

Example

curl -X POST \
  "https://app.arbituro.com/api/v1/projects/WEB/jobs/WEB-12/pull-requests" \
  -H "Authorization: Bearer $ARBITURO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://github.com/acme/web/pull/41"
}'

{
  "message": "Linked acme/web#41 to WEB-12. The job shows it with its state and CI; nothing else about the job changed, and its done-when still waits on a person.",
  "pullRequest": "acme/web#41",
  "url": "https://github.com/acme/web/pull/41"
}

Refusals

400

The address isn’t a github.com pull request’s, such as an issue’s address.

404

Arbituro’s GitHub app can’t see the pull request.

409

The pull request is already on the job, the project has no linked repository, the repository isn’t one the project can reach, or GitHub isn’t available.

503

GitHub didn’t answer, so nothing was linked. Try again shortly.