Documentation

API

Read your organisation’s settings and data, and set up its configuration, with an API key. Made for Claude Code and scripts.

API keys

An admin creates a key in the control panel under Settings → API keys, with a name, an expiry and the access it gets:

  • Read: settings, members, roles, connections (never their secrets), outside MCP servers, routines and their runs, reviews (not the findings), the call log, usage, budgets, credit and invoices.
  • Read and write: also changes the configuration: members and their roles, connections and their tokens, outside MCP servers, routines, login domains and single sign-on, Slack, retention, currency, spend caps, the log stream and the fallback for members without an own account.

The key is shown once; Gunnie.ai keeps only a hash of it. A key acts as the admin who created it and stops working when that admin is removed, turned off or no longer an admin, when it expires, or when any admin revokes it. Every change made with a key is listed with the key: the endpoint, the outcome and when, never what was sent.

Some things stay with a person in the browser, whatever the key: approving or rejecting changes, approval policies, the emergency stop, temporary admin rights, payments, buying credit, turning on an outside server’s tools, running a routine now, API keys themselves, and Gunnie.ai’s own platform pages.

Using the API

Send the key as a bearer token to https://app.gunnie.ai. Bodies are JSON. A key works only in its own organisation.

curl -H "Authorization: Bearer $gunnie_api_key" https://app.gunnie.ai/api/members

curl -X PATCH -H "Authorization: Bearer $gunnie_api_key" -H "Content-Type: application/json" \
  -d '{"days": 90}' https://app.gunnie.ai/api/retention

GET https://app.gunnie.ai/api/reference describes every endpoint below as JSON, with the JSON Schema of each request body, so an agent can read it first. Which fields and tokens each system needs is in systems in GET /api/connections.

The same endpoints as an OpenAPI 3.1 document: https://app.gunnie.ai/api/openapi.json. Import it in Postman, Insomnia or any OpenAPI tool, or generate a client from it. Each operation says the key it needs in x-gunnie-scope.

A key may make 120 requests a minute; above that the answer is 429 with a Retry-After header. Errors are JSON with error and error_description: invalid_api_key (unknown, revoked or expired), read_only_key, not_available_with_api_key, key_owner_inactive and browser_login_required.

Setting up with Claude Code

Put a write key in an environment variable, never in a repository, and ask Claude Code to set things up, for example:

Read https://app.gunnie.ai/api/reference. Then, with the key in $gunnie_api_key, connect our Jira at https://example.atlassian.net
for projects APP and WEB, invite the people in team.csv as developers, and keep records for 90 days.
Show me each change before you make it.

Revoke the key when the setup is done, or give it a short expiry. Use a read key for reports and checks.

Endpoints

MethodPathKeyWhat it does
GET/api/meReadThe admin the key acts as, the organisation, its tools, currency and emergency stop state.
GET/api/setupReadThe setup checklist: what is done and what is next.
GET/api/modulesReadThe add-ons in the organisation’s plan.
GET/api/rolesReadRoles, the tools each may use, and members per role.
GET/api/membersReadMembers with their role and status.
POST/api/membersWriteAdd a member: email, role, and send_invite to email them. Body
PATCH/api/members/:idWriteChange a member’s role, or turn their access off or on (disabled). Body
DELETE/api/members/:idWriteRemove a member.
POST/api/members/:id/inviteWriteEmail a member their invitation again.
GET/api/connectionsReadConnections, their last check, and per system the fields and secrets it needs (systems).
PUT/api/connections/:systemWriteConnect or change a system: baseUrl, settings and secrets as its spec in GET /api/connections names them. Secrets are never returned. Body
DELETE/api/connections/:systemWriteDisconnect a system and remove its secrets.
POST/api/connections/:system/testWriteTest a saved connection.
POST/api/connections/:system/choicesWriteThe choices for a setting that the system lists, such as projects, before saving. Body
POST/api/connections/:system/keyWriteGenerate or rotate a connection’s SSH key; returns the public half.
PUT/api/connections/:system/personal-dataWriteThe roles that see this system’s personal data in full. Body
GET/api/webhooksWriteEach connected system’s webhook address and signing secret. Write keys only.
GET/api/issues/statusesReadThe issue tracker’s statuses, for routine triggers.
GET/api/upstreamReadOutside MCP servers, their status and limits.
GET/api/upstream/:server/toolsReadAn outside server’s tools, their flags and whether each is on.
GET/api/upstream/:server/tools/:tool/changeReadBoth copies of a tool whose text changed since it was approved.
POST/api/upstream/discoverWriteWhat an outside server at a URL asks for to sign in. Body
POST/api/upstreamWriteAdd an outside MCP server: name, url and auth. Body
PUT/api/upstream/:serverWriteChange an outside server’s address or sign-in. Body
POST/api/upstream/:server/refreshWriteList an outside server’s tools again.
DELETE/api/upstream/:server/loginsWriteSign every member out of an outside server.
DELETE/api/upstream/:serverWriteRemove an outside server.
GET/api/routinesReadRoutines with their trigger, scope, budget and this month’s spend.
GET/api/routines/skillsReadThe skills a routine can run, with what each needs.
GET/api/routines/:id/runsReadA routine’s latest runs.
GET/api/routines/:id/runs/:runId/resultReadA run’s report.
GET/api/routines/:id/estimateReadWhat a routine is expected to cost per month.
POST/api/routinesWriteCreate a routine: name, trigger, skill, scope, output and budget. Body
PUT/api/routines/:idWriteChange a routine; the same fields as creating one. Body
POST/api/routines/:id/enableWriteTurn a routine on.
POST/api/routines/:id/disableWriteTurn a routine off.
DELETE/api/routines/:idWriteRemove a routine.
GET/api/reviewsReadCode reviews: who, when, status and cost. Not the findings.
GET/api/skillsReadThe organisation’s own skills and the routines that use them.
GET/api/usageReadUsage per member and tool.
GET/api/usage.csvReadUsage as CSV.
GET/api/budgetReadThe review budget and what was spent this month.
GET/api/valueReadTime saved, as the value page shows it.
GET/api/callsReadThe call log: who, which tool, when, outcome, duration. Never arguments or answers.
GET/api/calls/countsReadCall counts per status for a filter.
GET/api/calls/clientsReadThe assistants that called tools.
GET/api/calls.csvReadThe call log as CSV.
GET/api/activityReadThe live feed: calls, runs and approvals.
GET/api/statsReadCalls per day and per tool.
GET/api/actionsReadWrite actions waiting for approval, and decided ones. Deciding is only in the browser.
GET/api/actions/:idReadOne write action and its approvals.
GET/api/retentionReadHow long records are kept.
PATCH/api/retentionWriteSet how long records are kept: days, 7 to 365. Body
GET/api/currencyReadThe organisation’s currency.
PATCH/api/currencyWriteSet the currency: EUR or USD. Body
GET/api/spend-capsReadMonthly spend caps for the organisation and per member.
PUT/api/spend-caps/:kind/:subjectWriteSet or clear a monthly cap (monthly_eur, null clears). Body
GET/api/claude-routeReadWhich Claude account the organisation’s runs use.
GET/api/login-settingsReadLogin domains, Microsoft login and single sign-on.
PUT/api/login-settingsWriteSet the login domains and whether Microsoft login is on. Body
POST/api/login-settings/domains/:domain/verifyWriteCheck a login domain’s DNS record.
PUT/api/login-settings/ssoWriteSet single sign-on with Microsoft Entra ID. Body
DELETE/api/login-settings/ssoWriteRemove single sign-on.
GET/api/slackReadThe Slack workspace and the routines’ channel.
GET/api/slack/channelsReadThe Slack channels the app can post in.
PUT/api/slack/channelWriteSet the routines’ Slack channel. Body
DELETE/api/slack/channelWriteClear the routines’ Slack channel.
POST/api/slack/testWritePost a test message in the channel.
GET/api/slack/peopleReadPeople to tag in Slack who have no matching email address.
PUT/api/slack/peopleWriteAdd or change a person to tag: display_name, email, slack_user_id. Body
DELETE/api/slack/people/:idWriteRemove a person to tag.
GET/api/admin/log-streamReadThe log stream to your SIEM.
PUT/api/admin/log-streamWriteSet the log stream’s address, header and on or off. Body
POST/api/admin/log-stream/rotateWriteMake a new signing secret; returned this once.
POST/api/admin/log-stream/testWriteSend a test delivery.
GET/api/admin/accountsReadMembers’ own accounts per system, and the fallback.
PUT/api/admin/accounts/fallbackWriteWhat a member without an own account gets: refuse or service_reads. Body
GET/api/governance-reportReadThe monthly governance report settings.
GET/api/governance-report/previewReadA preview of the next governance report.
GET/api/creditReadPrepaid credit and recent movements.
GET/api/credit/auto-top-upReadAutomatic top-up: the setting and recent top-ups.
GET/api/billingReadPlan, billing details and payment method.
GET/api/billing/invoicesReadInvoices.
GET/api/billing/invoices/:id/pdfReadAn invoice as PDF.

Request bodies

The fields each endpoint that takes a body accepts. A field that is not required may be left out. Settings and secrets of a connection depend on the system: see systems in GET /api/connections.

POST /api/members

FieldTypeRequiredLimits
emailstring (email)Yesat most 320 characters
rolestringYes1 to 64 characters
send_invitebooleanNodefault false

PATCH /api/members/:id

FieldTypeRequiredLimits
rolestringNo1 to 64 characters
disabledbooleanNo

PUT /api/connections/:system

FieldTypeRequiredLimits
baseUrlstringYes1 to 500 characters
settingsobject of names to valuesYes
secretsobject of names to valuesNodefault {}
tokenExpiresAtstring, or nullNo

POST /api/connections/:system/choices

FieldTypeRequiredLimits
baseUrlstringNo1 to 500 characters
settingsobject of names to valuesNodefault {}
secretsobject of names to valuesNodefault {}

PUT /api/connections/:system/personal-data

FieldTypeRequiredLimits
roleslist of stringYesat most 20 items

POST /api/upstream/discover

FieldTypeRequiredLimits
urlstringYesat most 2000 characters

POST /api/upstream

FieldTypeRequiredLimits
namestringYes
urlstringYesat most 2000 characters
auth{ kind: "bearer", token } or { kind: "header", header, value } or { kind: "oauth", client_id, client_secret, scopes, microsoft }Yes

PUT /api/upstream/:server

FieldTypeRequiredLimits
namestringYes
urlstringYesat most 2000 characters
auth{ kind: "bearer", token } or { kind: "header", header, value } or { kind: "oauth", client_id, client_secret, scopes, microsoft }Yes

POST /api/routines

FieldTypeRequiredLimits
namestringYes1 to 100 characters
trigger{ type: "schedule", days, times } or { type: "pull_request" } or { type: "jira_status", statuses } or { type: "slack_alert", channel, senders }Yes
skillone of code-review, prerefinement, team-estimation, release-notes, ready-check, standup, release-risk, qa-precheck, autonomous-dev, scraper-watch, server-alert, watch, catalog-healthYes
scope{ repositories, projects, limit, urls, base_branch, label, run_cap, ticket_cap, attempts, max_points, tickets, release, ticket_statuses, target_branches, visual_check, preview_urls, checks, completeness, project }Yes
output{ slack, post_review, jira_handoff, review_status, status_key }Nodefault {"slack":false,"post_review":false,"jira_handoff":false,"review_status":false}
budgetnumberYesat most 1000

PUT /api/routines/:id

FieldTypeRequiredLimits
namestringYes1 to 100 characters
trigger{ type: "schedule", days, times } or { type: "pull_request" } or { type: "jira_status", statuses } or { type: "slack_alert", channel, senders }Yes
skillone of code-review, prerefinement, team-estimation, release-notes, ready-check, standup, release-risk, qa-precheck, autonomous-dev, scraper-watch, server-alert, watch, catalog-healthYes
scope{ repositories, projects, limit, urls, base_branch, label, run_cap, ticket_cap, attempts, max_points, tickets, release, ticket_statuses, target_branches, visual_check, preview_urls, checks, completeness, project }Yes
output{ slack, post_review, jira_handoff, review_status, status_key }Nodefault {"slack":false,"post_review":false,"jira_handoff":false,"review_status":false}
budgetnumberYesat most 1000

PATCH /api/retention

FieldTypeRequiredLimits
daysintegerYes7 to 365

PATCH /api/currency

FieldTypeRequiredLimits
currencyone of EUR, USDYes

PUT /api/spend-caps/:kind/:subject

FieldTypeRequiredLimits
monthly_eurnumber, or nullYes

PUT /api/login-settings

FieldTypeRequiredLimits
domainslist of stringYesat most 20 items
microsoftbooleanYes

PUT /api/login-settings/sso

FieldTypeRequiredLimits
entraTenantIdstring (uuid)Yes
clientIdstring (uuid)Yes
clientSecretstringYes8 to 500 characters

PUT /api/slack/channel

FieldTypeRequiredLimits
channelIdstringYes
channelNamestringNoat most 80 characters

PUT /api/slack/people

FieldTypeRequiredLimits
display_namestringYes2 to 100 characters
emailstring (email), or nullNo
slack_user_idstringYes

PUT /api/admin/log-stream

FieldTypeRequiredLimits
urlstringYes9 to 2000 characters
enabledbooleanYes
header_namestring, or nullNo
header_valuestringNoat most 4000 characters

PUT /api/admin/accounts/fallback

FieldTypeRequiredLimits
fallbackone of refuse, service_readsYes