DocsPublic API
Docs/Developer API·Last reviewed

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.

IssuesId