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/retentionGET 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
| Method | Path | Key | What it does |
|---|---|---|---|
GET | /api/me | Read | The admin the key acts as, the organisation, its tools, currency and emergency stop state. |
GET | /api/setup | Read | The setup checklist: what is done and what is next. |
GET | /api/modules | Read | The add-ons in the organisation’s plan. |
GET | /api/roles | Read | Roles, the tools each may use, and members per role. |
GET | /api/members | Read | Members with their role and status. |
POST | /api/members | Write | Add a member: email, role, and send_invite to email them. Body |
PATCH | /api/members/:id | Write | Change a member’s role, or turn their access off or on (disabled). Body |
DELETE | /api/members/:id | Write | Remove a member. |
POST | /api/members/:id/invite | Write | Email a member their invitation again. |
GET | /api/connections | Read | Connections, their last check, and per system the fields and secrets it needs (systems). |
PUT | /api/connections/:system | Write | Connect 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/:system | Write | Disconnect a system and remove its secrets. |
POST | /api/connections/:system/test | Write | Test a saved connection. |
POST | /api/connections/:system/choices | Write | The choices for a setting that the system lists, such as projects, before saving. Body |
POST | /api/connections/:system/key | Write | Generate or rotate a connection’s SSH key; returns the public half. |
PUT | /api/connections/:system/personal-data | Write | The roles that see this system’s personal data in full. Body |
GET | /api/webhooks | Write | Each connected system’s webhook address and signing secret. Write keys only. |
GET | /api/issues/statuses | Read | The issue tracker’s statuses, for routine triggers. |
GET | /api/upstream | Read | Outside MCP servers, their status and limits. |
GET | /api/upstream/:server/tools | Read | An outside server’s tools, their flags and whether each is on. |
GET | /api/upstream/:server/tools/:tool/change | Read | Both copies of a tool whose text changed since it was approved. |
POST | /api/upstream/discover | Write | What an outside server at a URL asks for to sign in. Body |
POST | /api/upstream | Write | Add an outside MCP server: name, url and auth. Body |
PUT | /api/upstream/:server | Write | Change an outside server’s address or sign-in. Body |
POST | /api/upstream/:server/refresh | Write | List an outside server’s tools again. |
DELETE | /api/upstream/:server/logins | Write | Sign every member out of an outside server. |
DELETE | /api/upstream/:server | Write | Remove an outside server. |
GET | /api/routines | Read | Routines with their trigger, scope, budget and this month’s spend. |
GET | /api/routines/skills | Read | The skills a routine can run, with what each needs. |
GET | /api/routines/:id/runs | Read | A routine’s latest runs. |
GET | /api/routines/:id/runs/:runId/result | Read | A run’s report. |
GET | /api/routines/:id/estimate | Read | What a routine is expected to cost per month. |
POST | /api/routines | Write | Create a routine: name, trigger, skill, scope, output and budget. Body |
PUT | /api/routines/:id | Write | Change a routine; the same fields as creating one. Body |
POST | /api/routines/:id/enable | Write | Turn a routine on. |
POST | /api/routines/:id/disable | Write | Turn a routine off. |
DELETE | /api/routines/:id | Write | Remove a routine. |
GET | /api/reviews | Read | Code reviews: who, when, status and cost. Not the findings. |
GET | /api/skills | Read | The organisation’s own skills and the routines that use them. |
GET | /api/usage | Read | Usage per member and tool. |
GET | /api/usage.csv | Read | Usage as CSV. |
GET | /api/budget | Read | The review budget and what was spent this month. |
GET | /api/value | Read | Time saved, as the value page shows it. |
GET | /api/calls | Read | The call log: who, which tool, when, outcome, duration. Never arguments or answers. |
GET | /api/calls/counts | Read | Call counts per status for a filter. |
GET | /api/calls/clients | Read | The assistants that called tools. |
GET | /api/calls.csv | Read | The call log as CSV. |
GET | /api/activity | Read | The live feed: calls, runs and approvals. |
GET | /api/stats | Read | Calls per day and per tool. |
GET | /api/actions | Read | Write actions waiting for approval, and decided ones. Deciding is only in the browser. |
GET | /api/actions/:id | Read | One write action and its approvals. |
GET | /api/retention | Read | How long records are kept. |
PATCH | /api/retention | Write | Set how long records are kept: days, 7 to 365. Body |
GET | /api/currency | Read | The organisation’s currency. |
PATCH | /api/currency | Write | Set the currency: EUR or USD. Body |
GET | /api/spend-caps | Read | Monthly spend caps for the organisation and per member. |
PUT | /api/spend-caps/:kind/:subject | Write | Set or clear a monthly cap (monthly_eur, null clears). Body |
GET | /api/claude-route | Read | Which Claude account the organisation’s runs use. |
GET | /api/login-settings | Read | Login domains, Microsoft login and single sign-on. |
PUT | /api/login-settings | Write | Set the login domains and whether Microsoft login is on. Body |
POST | /api/login-settings/domains/:domain/verify | Write | Check a login domain’s DNS record. |
PUT | /api/login-settings/sso | Write | Set single sign-on with Microsoft Entra ID. Body |
DELETE | /api/login-settings/sso | Write | Remove single sign-on. |
GET | /api/slack | Read | The Slack workspace and the routines’ channel. |
GET | /api/slack/channels | Read | The Slack channels the app can post in. |
PUT | /api/slack/channel | Write | Set the routines’ Slack channel. Body |
DELETE | /api/slack/channel | Write | Clear the routines’ Slack channel. |
POST | /api/slack/test | Write | Post a test message in the channel. |
GET | /api/slack/people | Read | People to tag in Slack who have no matching email address. |
PUT | /api/slack/people | Write | Add or change a person to tag: display_name, email, slack_user_id. Body |
DELETE | /api/slack/people/:id | Write | Remove a person to tag. |
GET | /api/admin/log-stream | Read | The log stream to your SIEM. |
PUT | /api/admin/log-stream | Write | Set the log stream’s address, header and on or off. Body |
POST | /api/admin/log-stream/rotate | Write | Make a new signing secret; returned this once. |
POST | /api/admin/log-stream/test | Write | Send a test delivery. |
GET | /api/admin/accounts | Read | Members’ own accounts per system, and the fallback. |
PUT | /api/admin/accounts/fallback | Write | What a member without an own account gets: refuse or service_reads. Body |
GET | /api/governance-report | Read | The monthly governance report settings. |
GET | /api/governance-report/preview | Read | A preview of the next governance report. |
GET | /api/credit | Read | Prepaid credit and recent movements. |
GET | /api/credit/auto-top-up | Read | Automatic top-up: the setting and recent top-ups. |
GET | /api/billing | Read | Plan, billing details and payment method. |
GET | /api/billing/invoices | Read | Invoices. |
GET | /api/billing/invoices/:id/pdf | Read | An 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
| Field | Type | Required | Limits |
|---|---|---|---|
email | string (email) | Yes | at most 320 characters |
role | string | Yes | 1 to 64 characters |
send_invite | boolean | No | default false |
PATCH /api/members/:id
| Field | Type | Required | Limits |
|---|---|---|---|
role | string | No | 1 to 64 characters |
disabled | boolean | No |
PUT /api/connections/:system
| Field | Type | Required | Limits |
|---|---|---|---|
baseUrl | string | Yes | 1 to 500 characters |
settings | object of names to values | Yes | |
secrets | object of names to values | No | default {} |
tokenExpiresAt | string, or null | No |
POST /api/connections/:system/choices
| Field | Type | Required | Limits |
|---|---|---|---|
baseUrl | string | No | 1 to 500 characters |
settings | object of names to values | No | default {} |
secrets | object of names to values | No | default {} |
PUT /api/connections/:system/personal-data
| Field | Type | Required | Limits |
|---|---|---|---|
roles | list of string | Yes | at most 20 items |
POST /api/upstream/discover
| Field | Type | Required | Limits |
|---|---|---|---|
url | string | Yes | at most 2000 characters |
POST /api/upstream
| Field | Type | Required | Limits |
|---|---|---|---|
name | string | Yes | |
url | string | Yes | at 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
| Field | Type | Required | Limits |
|---|---|---|---|
name | string | Yes | |
url | string | Yes | at 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
| Field | Type | Required | Limits |
|---|---|---|---|
name | string | Yes | 1 to 100 characters |
trigger | { type: "schedule", days, times } or { type: "pull_request" } or { type: "jira_status", statuses } or { type: "slack_alert", channel, senders } | Yes | |
skill | one of code-review, prerefinement, team-estimation, release-notes, ready-check, standup, release-risk, qa-precheck, autonomous-dev, scraper-watch, server-alert, watch, catalog-health | Yes | |
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 } | No | default {"slack":false,"post_review":false,"jira_handoff":false,"review_status":false} |
budget | number | Yes | at most 1000 |
PUT /api/routines/:id
| Field | Type | Required | Limits |
|---|---|---|---|
name | string | Yes | 1 to 100 characters |
trigger | { type: "schedule", days, times } or { type: "pull_request" } or { type: "jira_status", statuses } or { type: "slack_alert", channel, senders } | Yes | |
skill | one of code-review, prerefinement, team-estimation, release-notes, ready-check, standup, release-risk, qa-precheck, autonomous-dev, scraper-watch, server-alert, watch, catalog-health | Yes | |
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 } | No | default {"slack":false,"post_review":false,"jira_handoff":false,"review_status":false} |
budget | number | Yes | at most 1000 |
PATCH /api/retention
| Field | Type | Required | Limits |
|---|---|---|---|
days | integer | Yes | 7 to 365 |
PATCH /api/currency
| Field | Type | Required | Limits |
|---|---|---|---|
currency | one of EUR, USD | Yes |
PUT /api/spend-caps/:kind/:subject
| Field | Type | Required | Limits |
|---|---|---|---|
monthly_eur | number, or null | Yes |
PUT /api/login-settings
| Field | Type | Required | Limits |
|---|---|---|---|
domains | list of string | Yes | at most 20 items |
microsoft | boolean | Yes |
PUT /api/login-settings/sso
| Field | Type | Required | Limits |
|---|---|---|---|
entraTenantId | string (uuid) | Yes | |
clientId | string (uuid) | Yes | |
clientSecret | string | Yes | 8 to 500 characters |
PUT /api/slack/channel
| Field | Type | Required | Limits |
|---|---|---|---|
channelId | string | Yes | |
channelName | string | No | at most 80 characters |
PUT /api/slack/people
| Field | Type | Required | Limits |
|---|---|---|---|
display_name | string | Yes | 2 to 100 characters |
email | string (email), or null | No | |
slack_user_id | string | Yes |
PUT /api/admin/log-stream
| Field | Type | Required | Limits |
|---|---|---|---|
url | string | Yes | 9 to 2000 characters |
enabled | boolean | Yes | |
header_name | string, or null | No | |
header_value | string | No | at most 4000 characters |
PUT /api/admin/accounts/fallback
| Field | Type | Required | Limits |
|---|---|---|---|
fallback | one of refuse, service_reads | Yes |