Skip to content

API & AI-tool access (MCP)

QStack has a REST API and an MCP endpoint so scripts and AI assistants can search, read, and drive quality workflows on your behalf.

There are two ways in, and they suit different tools:

  • A personal API token, for the REST API and for developer tools that let you paste a header — Claude Code, Codex, Cursor and similar.
  • Connecting an assistant, for hosted assistants such as Claude.ai and ChatGPT, which have no place to paste a header. You add your organisation's address as a connector, approve it once on a consent page, and it is listed under Connected assistants where you can disconnect it again.

Both are scoped the way the web app is: they see exactly what their owner sees, in their owner's organisation only.

Both are switched off until your organisation turns them on

An administrator enables the REST API and AI assistant access separately, in Organisation settings. Until then every request is refused, whatever token it carries. They are separate switches because they carry different risks — see What leaves the system.

The token acts as you

Anything done with your token is recorded in the audit trail under your name, marked as having come through the API rather than from you at a keyboard. Treat the token like your password: don't share it, don't commit it to a repository, and revoke it if it may have leaked. Reader-role accounts stay read-only through the API too.

A token can never sign anything

Approving a document or a record needs a signature from you, in person, every time. No script and no assistant can approve on your behalf — the system refuses it, whatever the token is allowed to do.

Getting a token

Generate your own from the navbar: open your avatar menu and choose API token, then Generate token. The page shows the key to copy, and lets you Regenerate (the old key stops working immediately) or Revoke it at any time.

A few things worth knowing:

  • Tokens expire. The page shows the expiry date; generate a new one when it passes.
  • Tokens are read-only by default. Tick Allow this token to change records when generating if your script or assistant needs to move things through a workflow. Leave it off for anything that only reads.
  • Your account must be linked to a person record. Everything a token does is attributed to the person behind it, so there are no service accounts — a shared or unattended identity cannot hold a token. If your account is not linked, ask an administrator.
  • The page shows when the token was last used. A token you do not recognise having been used is worth revoking.

What leaves the system

The API and MCP return the structured fields of a record: numbers, titles, statuses, dates, owners, classifications and file hashes. They deliberately do not return record bodies, extracted or OCR'd document text, complaint narratives, investigation summaries, or direct links to stored files.

That matters most for MCP. When an assistant reads your data, what it reads reaches whichever model provider is behind that assistant — so an administrator should treat that provider as a sub-processor under their own data-protection arrangements before enabling it.

If you need the full text of a document or record, open it in QStack. Files are served through the application so their integrity is verified on the way out; the API does not hand out storage links that would skip that check.

The REST API

The API lives at /api/v1/ on your organisation's usual QStack address, and authenticates with a Bearer header:

curl -H "Authorization: Bearer $TOKEN" \
  "https://<your-org-address>/api/v1/documents/?status=effective&q=gowning"

Available resources: documents, records, deviations, capas, changes, complaints, vendors, audits, people, and training-requirements. Each supports listing (with ?status= and ?q= filters), detail by id, and — where the object has a lifecycle — a POST …/<id>/transition/ action that moves it through the same guarded workflow as the web UI.

Interactive API documentation

The full OpenAPI reference is served by the app itself (log in first, or send your Bearer token):

  • /api/v1/docs/ — browsable Swagger documentation of every endpoint, with request and response shapes and a try-it-out console.
  • /api/v1/schema/ — the raw OpenAPI schema, for code generators and AI tools.

Connecting an AI assistant (MCP)

The MCP endpoint is at /mcp on your organisation's usual QStack address.

Hosted assistants (Claude.ai, ChatGPT)

Add https://<your-org-address>/mcp as a connector in the assistant. It will send you to QStack to log in, then show a consent page naming the assistant and what it is asking for. Approve it and the connection is live.

Manage connections from your avatar menu under Connected assistants: it lists every assistant connected to your account, when, and whether it can write. Disconnect cuts one off immediately. Organisation administrators can see every connection in the organisation from the same page.

Assistants read only, unless your organisation says otherwise

A connected assistant can read by default. Writing needs three things: the assistant asked for write access, you approved it on the consent page, and an administrator has switched on Let connected AI assistants write in organisation settings. That switch is off until somebody turns it on, because machine-generated entries land in the audit trail your organisation has to review. Your own role still applies on top: a Reader's assistant cannot write, whatever it was granted.

Developer tools (Claude Code, Codex, Cursor)

These accept a pasted header, so they use your personal API token:

claude mcp add --transport http qstack \
  https://<your-org-address>/mcp \
  --header "Authorization: Bearer $TOKEN"

A personal token writes if you ticked Allow this token to change records when you generated it — the organisation's assistant-write switch does not apply to it, because a token is you, not a third party.

The tools

Tool What it does
search One search across all modules — the same cross-module search as the reporting page
list_objects List a resource with status/text filters
get_object Fetch one object with all its fields
transition_workflow Move an object through its lifecycle (e.g. send a draft document for review)
create_record_type Create a new internal-form record type as a draft, with the field schema written for you
list_load_datatypes List what can be bulk-loaded or exported
describe_load_template The column spec for a loader sheet
build_load_template Generate a blank loader sheet to fill in
start_load Dry-run a bulk load and report per-row warnings — creates nothing
commit_load Commit a planned load, leaving it awaiting attestation
export_datatype Export everything of one type to a sheet that re-imports cleanly

Record types are created as drafts, never published

create_record_type writes the draft and stops. Publishing a version freezes a controlled artefact that every record pins forever, so a person does it in the app, under their own identity. The tool returns the link.

Bulk load and export need an elevated role

The last five tools need an Admin/Owner account or an active Quality role — the same gate as the bulk-load wizard in the app. commit_load leaves the batch awaiting attestation: a Quality role holder signs the true-copy attestation in the app, and no tool can do that.

Tip

Ask things like "find every open deviation mentioning line 3" or "send the gowning SOP draft for review" — the assistant searches, reads, and transitions through the same role gates that apply to you in the browser.

Arguments are checked strictly

Tool arguments are validated before anything runs, and a misspelt or mistyped one comes back as a clear error rather than being ignored. If an assistant gets something wrong it is told exactly what, and usually corrects itself.

What the API deliberately cannot do

Electronic signatures are never collected through the API. Signing always requires a fresh interactive ceremony in the browser (see Electronic signatures) — an automation or AI assistant can move a record to the point of signature, but a person must sign.