Public API
The IssuesId API lets your own software read and write your company's projects, defects, forms and diary over HTTPS. This page shows how to use it: who switches it on, what a key is, how to sign in and a first call.
Answers
- →Who switches it on: IssuesId does, one company at a time, on request.
- →Who makes keys: a company admin, in Settings > Public API.
- →Is there a sandbox: no. Use a test project in your own company, or ask us.
- →Is there a try-it console: no, by design. The reference is for reading, and your own code or curl makes the calls.
- →Where to call it:
https://api.issuesid.com/v1, over HTTPS.
Until a company is switched on, every call answers 403 api_not_enabled.
Keys
Each key is read only, or read and write, and it reaches either all projects or a list of projects. Each key acts as its own named API user, so changes made with a key show in the app as "API: " followed by the key name.
- →A read only key can look at data and never change it. Any write is refused with 403
forbidden. - →A read and write key for all projects has a manager's rights over defects.
- →A read and write key for a list of projects opens defects in those projects, and edits only the defects it opened. It cannot close or reopen a defect.
- →A key for a list of projects cannot read filed forms or job checklists. Those calls answer 403
forbidden, not an empty list.
A key looks like iid_live_... followed by its id and secret.
A key is shown once, straight after it is created. If it is lost, a company admin creates a replacement.
Key management
A company admin creates, rotates and revokes keys in Settings > Public API, with Create key, Rotate key and Revoke key. A manager or user cannot make or change a key, so ask your company admin for one.
Rotating makes a new key with the same name, access and projects. The old key keeps working for the overlap the admin chooses, so you can switch your software over without a gap.
Revoking takes effect at once: anything using the key stops working straight away, and it can't be undone.
Signing in
Send the key in the Authorization header as a bearer token, in the form Authorization: Bearer iid_live_.... That is the only place a key is accepted. A key in the query string is refused with 400 credential_in_query.
A missing, malformed, unknown, expired or revoked key gets 401 unauthorized.
The base URL is https://api.issuesid.com/v1, over HTTPS only. Call it from a server, not from a web page in a browser: the API sends no browser cross-origin permissions, and a key in page code is a key anyone can read.
First call
Three calls show that the key works. GET /v1/me says which key, company and projects the request is for. GET /v1/projects lists the projects the key can see. GET /v1/defects?limit=50 lists the first 50 defects.
A failed call answers with an error object holding code, message and request_id. Branch on code, never on message, and quote the request_id if you contact support.
In curl:
curl https://api.issuesid.com/v1/me \
-H "Authorization: Bearer $ISSUESID_API_KEY"
curl https://api.issuesid.com/v1/projects \
-H "Authorization: Bearer $ISSUESID_API_KEY"
curl "https://api.issuesid.com/v1/defects?limit=50" \
-H "Authorization: Bearer $ISSUESID_API_KEY"In Node 20 or later:
const base = "https://api.issuesid.com/v1";
const headers = {
Authorization: `Bearer ${process.env.ISSUESID_API_KEY}`,
};
async function get(path) {
const res = await fetch(base + path, { headers });
const body = await res.json();
if (!res.ok) {
const { code, request_id } = body.error;
throw new Error(`${res.status} ${code} ${request_id}`);
}
return body;
}
console.log(await get("/me"));
console.log(await get("/projects"));
console.log(await get("/defects?limit=50"));In Python 3:
import json
import os
import urllib.error
import urllib.request
BASE = "https://api.issuesid.com/v1"
KEY = os.environ["ISSUESID_API_KEY"]
def get(path):
req = urllib.request.Request(
BASE + path,
headers={"Authorization": "Bearer " + KEY},
)
try:
with urllib.request.urlopen(req) as res:
return json.load(res)
except urllib.error.HTTPError as err:
e = json.load(err)["error"]
raise SystemExit(f"{err.code} {e['code']} {e['request_id']}")
print(get("/me"))
print(get("/projects"))
print(get("/defects?limit=50"))The Node snippet is an ES module, so save it as a .mjs file. The /v1/me answer looks like this, with example ids:
{
"key": {
"name": "Head office sync",
"prefix": "iid_live_...",
"access": "read_write",
"project_scope": "all",
"project_ids": []
},
"company": {
"id": "00000000-0000-0000-0000-000000000000",
"name": "Example Co"
},
"actor": {
"id": "00000000-0000-0000-0000-000000000000",
"name": "API: Head office sync"
},
"rate_limits": {
"reads_per_minute": 600,
"writes_per_minute": 120
}
}project_ids is empty when the key reaches every project. Every list answers with data, next_cursor and as_of.
Next, read the paging article to keep a copy current, and the writing article to send writes.
Every endpoint, parameter and response is in the API reference. The same contract is available as the OpenAPI spec and a Postman collection.