DocsWriting with the API
Docs/Developer API·Last reviewed

Writing with the API

The API writes the way the app does: the same rules, numbering, notifications and refusals. This page covers what each write does and how to retry safely. To read data back, see the paging article.

Posting

A defect posted with the API behaves like one entered in the app. It is numbered like any other, people are notified as they would be, and the same refusals apply. Only project_id and description are required.

The answer is the defect as GET /v1/defects/{defectId} returns it, and its address is in the Location header. A company or project that does not take defects through the API answers 409 create_not_available, and details says why.

curl https://api.issuesid.com/v1/defects \
  -H "Authorization: Bearer $ISSUESID_API_KEY" \
  -H "Idempotency-Key: create-tile-0001" \
  -H "Content-Type: application/json" \
  -d "{\"project_id\": \"$PROJECT_ID\",
       \"description\": \"Cracked tile at the lift lobby\"}"

Defaults

Left out, priority is medium, type is defect and due_date is three days after the defect was opened. Send due_date as null for no fix-by day. The day is a calendar day as YYYY-MM-DD, in the company's time zone, which GET /v1/company returns.

If the company requires a location on every defect, location_id is required too.

Edits

Edit a defect with PATCH /v1/defects/{defectId}. It alters only the fields you send and keeps every field you leave out. You can edit description, priority, type, custom_type_id, due_date, location_id and external_ids. A request that asks for what the defect already is alters nothing, notifies no one, and answers with the same ETag.

Trade lines

Issue a defect to a trade with POST /v1/defects/{defectId}/issued-to and a trade_id from GET /v1/trades. The defect gets a line for that trade, and the defect follows its lines as it does in the app. Send notify_trade as false to skip the email to the trade. Your own staff are still told. Issuing a trade that already has an open line alters nothing.

A defect can be issued to at most 11 trades. A twelfth answers 409 action_not_available with the detail issued_to_limit_reached.

Removal

Remove a trade with DELETE /v1/defects/{defectId}/issued-to/{tradeId}. Every line the defect has for that trade goes, and the defect follows the lines that are left. Each line goes on its own, so a retry is safe: it removes whatever is left. Removing a trade that has no line alters nothing.

Deadlines

The trade's due_date is three days after the defect was opened if you leave it out, and null means no fix-by day.

Actions

Close a defect with POST /v1/defects/{defectId}/close and reopen it with POST /v1/defects/{defectId}/reopen. Neither takes a body. Closing does what a manager pressing Close in the app does: every trade line is closed with the defect, and closed_at is set. Reopening opens the lines again and never resets the progress a trade recorded. Closing a closed defect, or reopening one that is not closed, alters nothing.

Only a key for all projects can close or reopen. A key for a list of projects gets 403 forbidden.

A company can require a root cause before a defect is closed. If the defect has none, the answer is 409 action_not_available with the detail root_cause_required, because the API cannot set a root cause yet. Close it in the app instead.

Staff notes

Send a note with POST /v1/defects/{defectId}/notes and a body of plain text, from one visible character to 10,000. A note sent with the API is always staff only: only the company's own people see it, and nobody outside the company is emailed. There is no audience field, and any other key in the request is refused with 422 unknown_field.

Text such as @Jane Smith stays plain text. It tags no one, gives no one access to the defect and sends no mention, though the company's staff are told about the note as they are for one written in the app.

Photos

A photo goes up in three steps.

  1. 01Send POST /v1/defects/{defectId}/photos with file_name, content_type and size_bytes, the exact size of the file. The answer holds photo_id, upload_url, upload_method, upload_headers and upload_expires_at.
  2. 02Send the file's bytes to upload_url with upload_method and the upload_headers exactly as given, and exactly size_bytes bytes as the body. Do it before upload_expires_at: the link lasts 15 minutes.
  3. 03Send POST /v1/defects/{defectId}/photos/{photoId}/confirm, using the photo_id from step 1.

Until it is confirmed the photo does not exist: it is not listed and does not appear on the defect. Send captured_at in step 1 when you know when the photo was taken.

The types are image/jpeg, image/png, image/webp, image/heic and image/heif, from 1 byte up to 26,214,400 bytes (25 MB).

Checks

At confirm the API checks the type, the size and the first bytes of the file. This is a best effort check of the file as it is then, and it runs once. The upload link stays writable until it expires, so confirm only after the upload has finished.

If the file has not arrived, the answer is 409 upload_missing and nothing is written: finish the upload, then confirm again. If it arrived but is not what you declared, the answer is 422 upload_rejected, and its detail is one of size_mismatch, too_large, type_mismatch or content_mismatch. The file and its upload record are removed, so start again from step 1.

Confirming a photo that is already confirmed alters nothing and answers the same, so a retry is safe. A defect can hold at most 50 unconfirmed uploads from the last 24 hours. Past that, the answer is 409 action_not_available with the detail upload_limit_reached.

Idempotency

Send Idempotency-Key on a POST, with a value of 1 to 255 printable ASCII characters that you choose, such as a fresh UUID for each request. If a call times out, send the same key and the same request again. You get the first answer back with Idempotent-Replayed: true, and nothing is done twice. A repeated photo request returns the same photo_id with a freshly signed upload_url.

The same key with a different request is refused with 422 idempotency_key_reused. A request that is still running answers 409 idempotency_in_progress with Retry-After: wait, then send it again. Keys are kept for 24 hours.

A refusal that the same request would get again is stored and replayed too, for 24 hours. That covers create_not_available, action_not_available, external_id_conflict, validation_failed, forbidden, not_found and upload_rejected. A failure that describes a moment is not stored, so the same key runs again after precondition_failed, upload_missing, a 503 or a 500.

After fixing the cause of a refusal, send a fresh Idempotency-Key. The old key replays the refusal for 24 hours.

Conflicts

Every read or write that returns a defect carries its ETag. Send it back in If-Match on an edit, a close, a reopen or a trade line edit, and the defect is written only if nobody else has edited it. If it was edited since, nothing is written and the answer is 412 precondition_failed, carrying the current ETag. Read the defect again, then decide.

If-Match: * means any current version, and a list of ETags separated by commas is accepted. Notes and photos take no If-Match, but one moves the defect's ETag.

Retryable 503

A 503 temporarily_unavailable with Retry-After means nothing was written. It happens when a write collided with another edit in flight, and when a defect is posted and the API could not check whether the project takes defects through the API. The same request normally works a moment later, so wait for Retry-After and send it again.

External ids

Keep your own ids on a defect with external_ids, a list of pairs of system and id. system is a short lower case name you choose for your own system, with letters, digits, _ and -, up to 40 characters. id is your id for it, 1 to 200 characters. A defect holds at most 10 pairs and each system once.

Find a defect by a pair with GET /v1/defects?external_system=&external_id=, sending both. A pair is unique per system in a company. If another defect already holds it, the answer is 409 external_id_conflict, so a retry that is unsure whether the first call worked can look the defect up by its id.

When you edit, external_ids is merged system by system. A system with an id sets or replaces it, a system with an id of null removes it, and a system you do not list is kept.

Key limits

What a key may write depends on its access and its projects.

  • →A read only key gets 403 forbidden on every write.
  • →A read and write key for a list of projects opens defects in those projects and nowhere else. It edits a defect and its trade lines only if its own API user opened it, and it cannot close or reopen. It can post a note or a photo on any defect it can reach.
  • →A read and write key for all projects has a manager's rights over the defects it can reach, including close and reopen.

A company admin sets a key's access and projects when making it, in Settings > Public API.

Every endpoint, parameter, header and response is in the API reference.

IssuesId