# REST API (company API keys) (https://systemhub.com/docs/rest-api)

> Part of systemHUB Docs · Connect: Settings → AI Gateway in systemHUB · Auth: OAuth (scoping is workspace-level today — see Getting started) · MCP tools: 60 · Full corpus: https://systemhub.com/llms-full.txt

Use this page when a **program** needs systemHUB with no person present: a nightly audit, a sync to another tool, a report on a schedule. If a person is talking to their AI, use the [MCP server](/docs/getting-started) instead. It is easier to use and it is what the rest of these docs describe.

| | MCP server | REST API with a company API key |
|---|---|---|
| Built for | A person's AI client (Claude, ChatGPT, Gemini CLI) | Scripts, cron jobs, integrations |
| Sign-in | OAuth, per person, token lasts 180 days | A company API key, until you revoke it |
| What you call | The MCP tools in the [tool reference](/docs/tool-reference) | HTTP endpoints under `https://api.systemhub.com` |
| Acts as | The person who connected | The user the key is linked to |

The two are separate. A key does not give you the MCP tools and an MCP token does not work as a key.

## Create a key

Create the key in systemHUB under **Settings → Company → API Keys**. When you create it you choose:

- **The user it acts as.** The key has exactly that user's permissions and the documents they can see. Anything that user can't open, the key can't open.
- **The permission groups** (System, Policy, Training, Item / Folder and others). A call outside the groups you picked is refused.
- **An expiry date** (optional).

The full key is shown once, when you create it. It starts with `shk_`. Store it like a password and never put it in an email, a ticket or a repository.

> **Every successful call is logged** under **Settings → Company → API Key Logs**: method, endpoint, key name, user and time. The log survives revoking or deleting the key. Refused calls (`401`, `403`) are **not** logged, so a blank log does not mean nobody tried.

Revoking a key takes effect on the next call.

## Make a call

One header does the work:

```
GET https://api.systemhub.com/api-item/policies/tree
x-systemhub-api-key: shk_...
```

- **Base URL:** `https://api.systemhub.com`. Your workspace address (`yourcompany.systemhub.com`) is the web app and will not answer API calls.
- **Header name:** exactly `x-systemhub-api-key`, sent as its own header. Not `Authorization`, not `Bearer`.
- **No company header needed.** The key itself tells the API which workspace it belongs to.
- **Send a normal User-Agent.** Some HTTP libraries send a default User-Agent that our edge blocks with a `403`. If every call fails the same way, try setting one.

## Read endpoints

All `GET`. Replace `{section}` with `systems`, `policies` or `trainings`.

| Endpoint | Returns |
|---|---|
| `/api-item/{section}/tree` | The whole folder structure for that section that the key's user can see, in one response, with each folder's `children` nested inside it. |
| `/api-item/{section}/{id}` | One document, with its body, Overview and notes nested under `document`. Returns `403` if the key's user can't open it. |

Each node in the tree has an `id`, `title`, `type` (`1` folder, `2` document) and `state` (0 grey draft, 1 orange needs review, 2 red overdue, 3 green approved, 4 purple archived). For an audit, walk the tree and fetch each document by `id`.

> **The tree is not paged.** It comes back whole, so its size grows with the library: about 70KB for a library of around 400 documents. Plan for that if your tool has a response limit.

## Read-only keys

The permission groups you tick on a key include **read and write** for that area. Ticking "Policy" lets the key read and change policies. There is no read-only tick box.

**To make a key read-only, link it to a user on a Reader seat.** A key can never do more than its user, and a Reader can't create, edit, move or share anything. Tested on production on 13 Nov 2026: a Reader's key could read and every write was refused with `403`. Then tick only the groups the job needs (for an audit of policies and systems: Policy, System and Item / Folder).

If the job is an audit of the whole library, the Reader also needs access to every folder you want audited. See [Roles & seats](/docs/concepts/roles-and-seats) for how access is granted.

## Errors

| Response | What it means | What to do |
|---|---|---|
| `403` `Company not found` | **The key header didn't reach the API.** A request with no key looks like this. | Check the header name is exactly `x-systemhub-api-key`, you're calling `api.systemhub.com` and nothing in between (a proxy, gateway or HTTP tool) strips custom headers. |
| `401` `Invalid API key` | The header arrived but the key is wrong, incomplete or deleted. | Copy the full key again, including `shk_`. |
| `401` after a key used to work | The key was revoked or has expired. | Create a new key. |
| `403` `Forbidden resource` | The key's user can't open that document or do that action (a Reader trying to write, for example), or the key's groups don't include that section. | Give the user access, or add the group to the key. For a read-only key this is the expected answer to any write. |
| `403` "API keys cannot manage other API keys." | You called a key-management endpoint with a key. | Manage keys in the app. |
| `429` "Too many attempts" | Too many key lookups from your address in a short time. | Slow down and retry later. |

## What a key can't do yet

- **Writes made with a key aren't marked as automated** in a document's activity log. They look like edits made in the app by the key's user. See [Errors & limits](/docs/concepts/errors-and-limits).
- **There is no full endpoint reference yet.** This page covers reading the folder structure and single documents for systems, policies and trainings, which is what most unattended jobs need. If you need something else, email support@systemology.com and tell us what you're building.

Next: **[Errors & limits →](/docs/concepts/errors-and-limits)**
