API docs by Redocly

AgentOps API (0.1.0)

Download OpenAPI specification:

License: MIT OR Apache-2.0

REST API for the merged agentops-server process — composes routes from agentops-api, docbrain-api (nested under /docbrain), and agentops-heavy-api (accounts/auth, team management, repository connection/indexing, search, and webhooks) onto one Axum router, one port.

Three auth models coexist depending on the route group:

  • Session auth (sessionAuth): a Bearer token from POST /auth/login or POST /auth/signup, used by the web UI and anything acting as a specific user.
  • API key auth (apiKeyAuth): a Bearer token from agentops api-key generate / POST /auth/api-keys, used by CLI/MCP/service callers.
  • Webhook signature (no Bearer token): /webhooks/* routes verify an HMAC signature header instead — see each route's description.

Most /repos/* and /search/* routes accept either a session or an API key (sessionOrApiKey); the tenant resolves from the session if present, else from a tenant/org request field.

Health

Liveness check

Responses

Response samples

Content type
application/json
{
  • "status": "ok"
}

Auth

Signup, login, sessions, API keys, 2FA, profile, first-run infra config.

Whether this instance has any account yet, and whether signup is open

Unauthenticated — lets the frontend default to the Signup tab on a fresh instance and hide it once gated.

Responses

Response samples

Content type
application/json
{
  • "has_accounts": true,
  • "signup_open": true
}

Write first-run infra config (.env) — first-run only

Unauthenticated (there's no session yet on a brand-new instance), but deliberately first-run only: 403s once any account already exists, so an anonymous caller can't rewrite a running instance's secrets. Writes .env in the server process's working directory; the caller must restart the process for it to take effect (no hot-reload).

Request Body schema: application/json
required
secrets_master_key
required
string

64 hex chars (32 bytes) — generate with openssl rand -hex 32.

database_url
string

postgres:// connection string for the code-graph store; omit for SQLite.

addr
string
access_mode
string
Enum: "advisor" "full"
signup_mode
string
Enum: "open" "first-user-only"
anthropic_api_key
string
linear_api_key
string
github_app_id
string
github_app_private_key
string
github_webhook_secret
string
qdrant_url
string

Responses

Request samples

Content type
application/json
{
  • "secrets_master_key": "string",
  • "database_url": "string",
  • "addr": "0.0.0.0:8420",
  • "access_mode": "advisor",
  • "signup_mode": "open",
  • "anthropic_api_key": "string",
  • "linear_api_key": "string",
  • "github_app_id": "string",
  • "github_app_private_key": "string",
  • "github_webhook_secret": "string",
  • "qdrant_url": "string"
}

Response samples

Content type
application/json
{
  • "ok": true
}

Create an account

Always mints a brand-new tenant for the new user. Once AGENTOPS_SIGNUP_MODE=first-user-only (the default for self-host deployments) and any account already exists, this requires a valid invite_token — see POST /invites/accept for how an invited user actually joins the inviting org afterward (signup alone never redeems the invite).

Request Body schema: application/json
required
email
required
string <email>
password
required
string
first_name
required
string
last_name
required
string
invite_token
string

Proves this signup is invite-driven; required once AGENTOPS_SIGNUP_MODE=first-user-only and an account already exists. Does not itself join the inviting org — see POST /invites/accept.

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "password": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "invite_token": "string"
}

Response samples

Content type
application/json
{
  • "user": {
    },
  • "session_token": "string"
}

Log in with email/password

If the account has 2FA enabled, returns a 202 challenge instead of a session — complete it via POST /auth/login/2fa.

Request Body schema: application/json
required
email
required
string <email>
password
required
string

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "user": {
    },
  • "session_token": "string"
}

Complete a 2FA login challenge

Request Body schema: application/json
required
challenge_token
required
string
code
required
string

Responses

Request samples

Content type
application/json
{
  • "challenge_token": "string",
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "user": {
    },
  • "session_token": "string"
}

Revoke the presented session

Authorizations:
sessionAuth

Responses

Get the current user

Authorizations:
sessionAuth

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "email": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "tenant": "string",
  • "avatar_url": "string",
  • "handle": "string",
  • "bio": "string",
  • "location": "string",
  • "theme_pref": "string",
  • "default_search_scope": "string",
  • "show_gotcha_callouts": true,
  • "graph_layout_algorithm": "string",
  • "two_factor_enabled": true,
  • "onboarding_completed": true
}

Update profile fields

Every field optional — omitted means "leave unchanged".

Authorizations:
sessionAuth
Request Body schema: application/json
first_name
string
last_name
string
handle
string
bio
string
location
string

Responses

Request samples

Content type
application/json
{
  • "first_name": "string",
  • "last_name": "string",
  • "handle": "string",
  • "bio": "string",
  • "location": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "email": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "tenant": "string",
  • "avatar_url": "string",
  • "handle": "string",
  • "bio": "string",
  • "location": "string",
  • "theme_pref": "string",
  • "default_search_scope": "string",
  • "show_gotcha_callouts": true,
  • "graph_layout_algorithm": "string",
  • "two_factor_enabled": true,
  • "onboarding_completed": true
}

Update display preferences

Authorizations:
sessionAuth
Request Body schema: application/json
theme_pref
string
default_search_scope
string
show_gotcha_callouts
boolean
graph_layout_algorithm
string

Responses

Request samples

Content type
application/json
{
  • "theme_pref": "string",
  • "default_search_scope": "string",
  • "show_gotcha_callouts": true,
  • "graph_layout_algorithm": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "email": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "tenant": "string",
  • "avatar_url": "string",
  • "handle": "string",
  • "bio": "string",
  • "location": "string",
  • "theme_pref": "string",
  • "default_search_scope": "string",
  • "show_gotcha_callouts": true,
  • "graph_layout_algorithm": "string",
  • "two_factor_enabled": true,
  • "onboarding_completed": true
}

Change password

Revokes every other session on success — the request that proved it knows the new password doesn't lock itself out.

Authorizations:
sessionAuth
Request Body schema: application/json
required
current_password
required
string
new_password
required
string

Responses

Request samples

Content type
application/json
{
  • "current_password": "string",
  • "new_password": "string"
}

Response samples

Content type
application/json
{
  • "updated": true
}

Mark the /welcome onboarding checklist done

Idempotent — safe to call more than once (e.g. re-clicking "Continue to dashboard").

Authorizations:
sessionAuth

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "email": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "tenant": "string",
  • "avatar_url": "string",
  • "handle": "string",
  • "bio": "string",
  • "location": "string",
  • "theme_pref": "string",
  • "default_search_scope": "string",
  • "show_gotcha_callouts": true,
  • "graph_layout_algorithm": "string",
  • "two_factor_enabled": true,
  • "onboarding_completed": true
}

List active sessions

Authorizations:
sessionAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Revoke every session except the current one

Authorizations:
sessionAuth

Responses

Response samples

Content type
application/json
{
  • "revoked": 0
}

Revoke a specific session

Authorizations:
sessionAuth
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
{
  • "revoked": true
}

List this user's API keys

Authorizations:
sessionAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new API key

The raw key is returned exactly once, in this response — only its prefix is ever visible again.

Authorizations:
sessionAuth
Request Body schema: application/json
required
name
required
string

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "key_prefix": "string",
  • "last_used_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "key": "string"
}

Revoke an API key

Authorizations:
sessionAuth
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
{
  • "revoked": true
}

Begin 2FA enrollment

Authorizations:
sessionAuth

Responses

Response samples

Content type
application/json
{
  • "secret": "string",
  • "otpauth_uri": "string",
  • "qr_data_uri": "string"
}

Confirm 2FA enrollment with a code

Authorizations:
sessionAuth
Request Body schema: application/json
required
code
required
string

Responses

Request samples

Content type
application/json
{
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "backup_codes": [
    ]
}

Disable 2FA

Authorizations:
sessionAuth
Request Body schema: application/json
required
password
required
string

Responses

Request samples

Content type
application/json
{
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "disabled": true
}

Regenerate 2FA backup codes

Authorizations:
sessionAuth
Request Body schema: application/json
required
password
required
string

Responses

Request samples

Content type
application/json
{
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "backup_codes": [
    ]
}

Team

Org/role/member/invite management, repo-access matrix, audit log.

Get org summary (name, member count, caller's role/owner status)

Authorizations:
sessionAuth

Responses

Response samples

Content type
application/json
{
  • "tenant": "string",
  • "name": "string",
  • "member_count": 0,
  • "role": "string",
  • "is_owner": true
}

Rename the organization

Owner-only — used by the /welcome onboarding checklist's workspace-setup item.

Authorizations:
sessionAuth
Request Body schema: application/json
required
name
required
string

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "name": "string"
}

List org members

Authorizations:
sessionAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Change a member's role and/or status

Demoting/removing another active admin requires being the Owner; the org can never end up with zero active admins.

Authorizations:
sessionAuth
path Parameters
user_id
required
integer
Request Body schema: application/json
role
string
status
string

Responses

Request samples

Content type
application/json
{
  • "role": "string",
  • "status": "string"
}

Remove a member

Authorizations:
sessionAuth
path Parameters
user_id
required
integer

Responses

List the fixed role matrix, live per-role counts, and custom roles

Authorizations:
sessionAuth

Responses

Response samples

Content type
application/json
{
  • "roles": [
    ],
  • "matrix": [
    ],
  • "custom_roles": [
    ]
}

Create a custom role cloned from a fixed one

Authorizations:
sessionAuth
Request Body schema: application/json
required
label
required
string
cloned_from
required
string
capabilities
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "label": "string",
  • "cloned_from": "string",
  • "capabilities": [
    ]
}

Update a custom role's capabilities

Authorizations:
sessionAuth
path Parameters
role_key
required
string
Request Body schema: application/json
capabilities
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "capabilities": [
    ]
}

Delete a custom role

Authorizations:
sessionAuth
path Parameters
role_key
required
string

Responses

Transfer org ownership to another active admin

Authorizations:
sessionAuth
Request Body schema: application/json
required
to_user_id
required
integer

Responses

Request samples

Content type
application/json
{
  • "to_user_id": 0
}

Owner-only, irreversible cascade delete of the organization

Deletes every repo connection, credential, docbrain data, and team row for the tenant except the audit log.

Authorizations:
sessionAuth
Request Body schema: application/json
required
confirm_tenant
required
string

Must exactly match the caller's own tenant — type-to-confirm safety check.

Responses

Request samples

Content type
application/json
{
  • "confirm_tenant": "string"
}

List pending invites

Authorizations:
sessionAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create an invite

No email is sent — the response includes the raw token so the caller can build a copyable /invite/{token} link.

Authorizations:
sessionAuth
Request Body schema: application/json
required
email
required
string <email>
role
required
string
note
string

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "role": "string",
  • "note": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "email": "string",
  • "role": "string",
  • "note": "string",
  • "status": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "token": "string"
}

Resend an invite (returns the same or a refreshed token)

Authorizations:
sessionAuth
path Parameters
id
required
integer

Responses

Revoke a pending invite

Authorizations:
sessionAuth
path Parameters
id
required
integer

Responses

Get the per-member, per-repo access matrix

Authorizations:
sessionAuth

Responses

Response samples

Content type
application/json
{
  • "repos": [
    ],
  • "members": [
    ],
  • "access": [
    ]
}

Save repo-access overrides

Only member/viewer rows are override-editable; a diff for an admin or billing row is silently ignored.

Authorizations:
sessionAuth
Request Body schema: application/json
required
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "changes": [
    ]
}

List org audit log entries

Authorizations:
sessionAuth
query Parameters
since
string <date-time>
limit
integer

Responses

Response samples

Content type
application/json
[
  • { }
]

Accept an invite and switch the caller's active tenant

Authorizations:
sessionAuth
Request Body schema: application/json
required
token
required
string

Responses

Request samples

Content type
application/json
{
  • "token": "string"
}

Response samples

Content type
application/json
{
  • "tenant": "string",
  • "role": "string"
}

Preview an invite before signing in

Public — the token itself is the secret. Used by the unauthenticated invite landing page.

path Parameters
token
required
string

Responses

Response samples

Content type
application/json
{
  • "tenant": "string",
  • "org_name": "string",
  • "email": "string",
  • "role": "string"
}

Integrations

Per-user and org-wide third-party credential vault.

List org-wide integration credentials (metadata only, never secrets)

Authorizations:
sessionAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Store/update an org-wide credential for a provider

Authorizations:
sessionAuth
path Parameters
provider
required
string
Request Body schema: application/json
required
auth_type
required
string
secret
required
string
refresh_token
string
expires_at
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "auth_type": "string",
  • "secret": "string",
  • "refresh_token": "string",
  • "expires_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "provider": "string",
  • "auth_type": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Remove an org-wide credential

Authorizations:
sessionAuth
path Parameters
provider
required
string

Responses

Begin an OAuth flow for a provider (not yet implemented for any provider)

Authorizations:
sessionAuth
path Parameters
provider
required
string

Responses

OAuth callback for a provider (not yet implemented for any provider)

Authorizations:
sessionAuth
path Parameters
provider
required
string

Responses

List this user's personal integration credentials

Authorizations:
sessionAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Store/update a personal credential for a provider

Authorizations:
sessionAuth
path Parameters
provider
required
string

Responses

Remove a personal credential

Authorizations:
sessionAuth
path Parameters
provider
required
string

Responses

Repositories

Connecting, verifying, and indexing repos (SSH or GitHub App).

Connect a repo via SSH deploy key

Generates a keypair and returns the public half — add it as a read-only Deploy Key on the repo, then verify.

Authorizations:
sessionOrApiKey
Request Body schema: application/json
required
tenant
string

Required on the API-key path; ignored on the session path (derived from the session).

repo_id
required
string
repo_url
required
string

Responses

Request samples

Content type
application/json
{
  • "tenant": "string",
  • "repo_id": "string",
  • "repo_url": "string"
}

Response samples

Content type
application/json
{
  • "connection": {
    },
  • "instructions": "string"
}

List connected repos

Authorizations:
sessionOrApiKey
query Parameters
tenant
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Verify a repo connection (attempts a real fetch)

Authorizations:
sessionOrApiKey
path Parameters
id
required
string
query Parameters
tenant
string

Responses

Start (or queue) indexing for a connected repo

Authorizations:
sessionOrApiKey
path Parameters
id
required
string

Responses

Poll indexing job status

Authorizations:
sessionOrApiKey
path Parameters
id
required
string
query Parameters
tenant
string

Responses

Retry a failed indexing job

Authorizations:
sessionOrApiKey
path Parameters
id
required
string
query Parameters
tenant
string

Responses

Regenerate the SSH deploy keypair for a connection

Authorizations:
sessionOrApiKey
path Parameters
id
required
string
query Parameters
tenant
string

Responses

Get the GitHub App installation URL

Authorizations:
sessionOrApiKey

Responses

GitHub App installation OAuth callback

Responses

List repos available under a GitHub App installation

Authorizations:
sessionOrApiKey
path Parameters
id
required
string

Responses

Connect a repo from a GitHub App installation (no SSH key needed)

Authorizations:
sessionOrApiKey
path Parameters
id
required
string
Request Body schema: application/json
repo_full_name
string

Responses

Request samples

Content type
application/json
{
  • "repo_full_name": "string"
}

Search & Graph

Code-graph nodes/edges, semantic + docs search, curation.

Embed and index a scanned repo's graph for semantic search

Requires Qdrant to be configured (AGENTOPS_QDRANT_URL) — 503s otherwise.

Authorizations:
sessionOrApiKey
Request Body schema: application/json
required
path
required
string

Responses

Request samples

Content type
application/json
{
  • "path": "string"
}

Response samples

Content type
application/json
{
  • "indexed": 0
}

Semantic search over an indexed repo

Authorizations:
sessionOrApiKey
query Parameters
path
required
string
q
required
string
top_k
integer
Default: 5

Responses

Response samples

Content type
application/json
{
  • "results": [
    ]
}

Embed and index docbrain doc content for a library slug

Authorizations:
sessionOrApiKey
Request Body schema: application/json
required
slug
required
string
org
string

Which tenant's docbrain store to read from.

Responses

Request samples

Content type
application/json
{
  • "slug": "string",
  • "org": "string"
}

Response samples

Content type
application/json
{
  • "indexed": 0
}

Semantic search scoped to docbrain doc content

Authorizations:
sessionOrApiKey
query Parameters
slug
required
string
q
required
string
top_k
integer
Default: 5

Responses

Response samples

Content type
application/json
{
  • "results": [
    ]
}

Locally consolidate/fine-tune a small model on a repo's curated notes

Authorizations:
sessionOrApiKey
Request Body schema: application/json
required
path
required
string

Responses

Request samples

Content type
application/json
{
  • "path": "string"
}

Response samples

Content type
application/json
{
  • "attempted": true,
  • "promoted": true,
  • "examples_used": 0,
  • "candidate_score": 0,
  • "baseline_score": 0
}

List graph nodes

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
[
  • { }
]

List scanned repos (same data as `agentops repos`)

Authorizations:
apiKeyAuth

Responses

Re-scan a repo by name

Authorizations:
apiKeyAuth
path Parameters
name
required
string

Responses

Get a graph node's detail

Authorizations:
apiKeyAuth
path Parameters
name
required
string
id
required
string

Responses

Set a Gotcha/Decision node's curation state (bucket, reason, prominence)

Authorizations:
apiKeyAuth
path Parameters
name
required
string
id
required
string
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Get a node's local subgraph (neighbors within N hops)

Authorizations:
apiKeyAuth
path Parameters
name
required
string
id
required
string

Responses

Get the whole-repo graph view

Authorizations:
apiKeyAuth
path Parameters
name
required
string

Responses

Reinforce a Hebbian References edge (recency/co-access weighting)

Authorizations:
apiKeyAuth
path Parameters
name
required
string
id
required
string

Responses

Get generated documentation for a repo

Authorizations:
apiKeyAuth
path Parameters
name
required
string

Responses

Recent scan/note/curation activity across repos

Authorizations:
apiKeyAuth

Responses

Hybrid (dense + lexical + graph-expanded) local search

Authorizations:
apiKeyAuth
query Parameters
q
required
string
path
string

Responses

List Gotcha nodes across repos, for the curation dashboard

Authorizations:
apiKeyAuth

Responses

Tools

MCP tool-calling over REST (agentops-api's and docbrain-api's tool tables).

List agentops-api's MCP-style tool table

Authorizations:
apiKeyAuth

Responses

Call a tool by name (agentops-api's table)

Authorizations:
apiKeyAuth
path Parameters
name
required
string
Request Body schema: application/json
object

Tool-specific arguments — see GET /tools for each tool's input schema.

Responses

Request samples

Content type
application/json
{ }

List docbrain-api's MCP-style tool table

Authorizations:
apiKeyAuth

Responses

Call a docbrain tool by name (e.g. register_library, scrape_library, search_docs)

Authorizations:
apiKeyAuth
path Parameters
name
required
string
Request Body schema: application/json
object

Tool-specific arguments — see GET /docbrain/tools for each tool's input schema.

Responses

Request samples

Content type
application/json
{ }

Remote MCP transport (Streamable HTTP, stateless mode) for a server-hosted instance

The network-reachable counterpart to the stdio agentops-mcp-server binary — what agentops connect --remote <server-url> points a team member's coding tool at instead of a local stdio server. Speaks plain MCP JSON-RPC 2.0 (initialize, tools/list, tools/call) over a single endpoint, one JSON response per POST (no SSE upgrade — this server has no server-initiated push). Only exposes agentops-mcp's tool set (scan/notes/local search) — each tool takes its own path argument, which here must name a connected repo (its RepoConnection id or repo_url, from GET /repos) belonging to the caller's tenant, never a literal filesystem path. A JSON-RPC notification (no id) gets 202 Accepted with no body.

Authorizations:
sessionOrPersonalApiKey
Request Body schema: application/json
required
jsonrpc
required
string
Value: "2.0"
id
any

Omit for a notification (gets 202, no response body).

method
required
string
Enum: "initialize" "tools/list" "tools/call"
params
object

For tools/call: { name: string, arguments: { path: , ... } }

Responses

Request samples

Content type
application/json
{
  • "jsonrpc": "2.0",
  • "id": null,
  • "method": "initialize",
  • "params": { }
}

Libraries

docbrain's tracked third-party libraries.

List libraries with real ingested (scraped) content

Registered-but-never-scraped libraries (e.g. auto-discovered from a manifest) are filtered out here — use the list_libraries MCP tool for the full registry.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "libraries": [
    ]
}

Get a library's detail, including where it's used

Authorizations:
apiKeyAuth
path Parameters
slug
required
string

Responses

Response samples

Content type
application/json
{
  • "library": {
    },
  • "used_in": [
    ]
}

Webhooks

GitHub App and Linear inbound webhooks (HMAC-verified, no Bearer auth).

GitHub App webhook receiver

No Bearer auth — verified via the X-Hub-Signature-256 HMAC header instead. 501s if no GitHub App is configured for this deployment.

Responses

Linear webhook receiver

No Bearer auth — HMAC-signature verified instead.

Responses

Linear

Session-authed Linear task sync, separate from the Linear webhook.

List Linear auto-kickoff enrollments

Authorizations:
sessionAuth

Responses

Enroll a Linear team in auto-kickoff (auto-creating an agentops task per new Linear issue)

Authorizations:
sessionAuth

Responses

Disable auto-kickoff for a Linear team

Authorizations:
sessionAuth
path Parameters
team_id
required
string

Responses

Push an agentops task's status to its linked Linear issue

Authorizations:
sessionAuth
path Parameters
task_id
required
string

Responses

Post an LLM-generated summary of a task's activity to its Linear issue

Authorizations:
sessionAuth
path Parameters
task_id
required
string

Responses