Skip to content

REST reference

Every endpoint the backend exposes: 138 operations across 106 paths, generated from the application's own OpenAPI schema so it cannot drift from the code.

See REST API for authentication, error shapes, a worked request and response, and how the interactive schema is exposed.

Request bodies are documented in full at the bottom of this page. The response column names a model rather than listing its fields: a response is read as it arrives, and the 182 response models would be bulk nobody navigates. Where a response shape matters before you call — the retrieval envelope in particular — it is shown on the page for that feature.

Reading the tables

A * marks a required parameter. Path parameters are omitted from the parameters column because they are visible in the path, and the Authorization, X-CSRF-Token and Idempotency-Key headers are omitted because they are cross-cutting rather than per-operation.

A in the request column means the schema declares no body. Usually that is because there is none — POST /api/repos/{…}/reindex needs no payload. On the upload, OIDC-callback and webhook routes it means something different: the handler reads the raw body itself instead of declaring a model, so the schema cannot describe a shape that does exist. Each of those is documented on the page for its feature.

The response column is the status the schema declares, which is not always the only one a caller sees: an endpoint that rejects every request still declares a success status, and the purpose column says so where that happens. Error shapes are on REST API.

Health

Liveness. Mounted twice so probes need not know the API prefix.

OperationPurposeParametersRequestResponse
GET /api/healthGet Health200 HealthResponse
GET /healthGet Health200 HealthResponse

Authentication

Session lifecycle: config, first-admin bootstrap, register, login, logout, refresh — plus the OIDC login, callback and account-linking routes.

OperationPurposeParametersRequestResponse
POST /api/auth/bootstrapCreate the first admin when no admin exists yetBootstrapRequest200 LoginResponse
GET /api/auth/configGet Auth Config200 AuthConfigResponse
POST /api/auth/loginLoginLoginRequest200 LoginResponse
POST /api/auth/logoutLogout204
GET /api/auth/meGet Current User Profile200 UserResponse
GET /api/auth/oidc/{slug}/callbackOidc Callback Getcode, state302
POST /api/auth/oidc/{slug}/callbackUsed by IdPs configured with response_mode=form_post302
POST /api/auth/oidc/{slug}/link/startOidc Link Start302
GET /api/auth/oidc/{slug}/loginOidc Loginreturn_to302
POST /api/auth/refreshRotate refresh token, check family reuse, issue new pair200 LoginResponse
POST /api/auth/registerAlways 403 — self-service registration is not exposed over the API200

Current user

The caller's own identities and query history.

OperationPurposeParametersRequestResponse
GET /api/me/identitiesList My Identities200 IdentityListResponse
DELETE /api/me/identities/{identity_id}Unlink My Identity204

Personal access tokens

Mint, list, rotate and revoke tokens for REST and MCP.

OperationPurposeParametersRequestResponse
GET /api/admin/users/{user_id}/tokensAdmin List User Tokens200 TokenListResponse
POST /api/admin/users/{user_id}/tokens/revoke-allMass-revoke every active PAT for a target userRevokeAllRequest200 RevokeAllResponse
GET /api/me/tokensList My Tokens200 TokenListResponse
POST /api/me/tokensCreate My TokenCreateTokenRequest201 CreateTokenResponse
DELETE /api/me/tokens/{token_id}Revoke My Token204
POST /api/me/tokens/{token_id}/rotateAtomically revoke an existing token and mint a replacement201 CreateTokenResponse

Repositories

Create, configure, index and delete repositories, including zip upload.

OperationPurposeParametersRequestResponse
GET /api/reposList Repositoriespage, per_page, search, status200 RepositoryListResponse
POST /api/reposCreate RepositoryCreateRepositoryRequest202 RepositoryResponse
POST /api/repos/uploadCreate a new repository sourced from an uploaded zip archiveform data202 RepositoryResponse
GET /api/repos/{host}/{owner}/{name}Get Repository200 RepositoryResponse
PATCH /api/repos/{host}/{owner}/{name}Update RepositoryUpdateRepositoryRequest200 RepositoryResponse
DELETE /api/repos/{host}/{owner}/{name}Delete Repository204
GET /api/repos/{host}/{owner}/{name}/files/{source_file_id}Get Repository Source File200 SourceFileResponse
GET /api/repos/{host}/{owner}/{name}/files/{source_file_id}/rangeGet Repository Source File Rangestart, end200 SourceFileRangeResponse
GET /api/repos/{host}/{owner}/{name}/graphGet Repository Graphview, node_type, language, module, search, depth, limit200 GraphListResponse
GET /api/repos/{host}/{owner}/{name}/graph/nodes/by-qn/{qualified_name}Resolve a code node by its qualified_name for the current repo200 GraphNodeDetailResponse
POST /api/repos/{host}/{owner}/{name}/graph/nodes/checkCheck Repository Graph NodesGraphNodesCheckRequest200 GraphNodesCheckResponse
GET /api/repos/{host}/{owner}/{name}/graph/nodes/{node_id}Get Repository Graph Node200 GraphNodeDetailResponse
POST /api/repos/{host}/{owner}/{name}/reindexReindex Repository202 RepoReindexResponse
POST /api/repos/{host}/{owner}/{name}/runs/{run_id}/cancelForce-cancel a wedged QUEUED/RUNNING repo_sync_runs row200 RepoSyncRunResponse
POST /api/repos/{host}/{owner}/{name}/uploadReplace the persisted archive for a zip-source repositoryform data202 RepoReindexResponse
POST /api/repos/{host}/{owner}/{name}/webhookTrigger Repository Webhookx-cograph-webhook-secret202 RepoWebhookTriggerResponse

Generated wiki

Read the generated page tree and individual pages; repair stale citations.

OperationPurposeParametersRequestResponse
GET /api/repos/{host}/{owner}/{name}/wikiGet Wiki Tree200 WikiTreeResponse
GET /api/repos/{host}/{owner}/{name}/wiki/{slug}Get Wiki Page200 WikiPageResponse
POST /api/repos/{host}/{owner}/{name}/wiki/{slug}/repair-citationsRepair Wiki Page Citations200 WikiCitationRepairResponse

Repository docs (rendered)

The repository's own in-tree markdown, rendered as pages.

OperationPurposeParametersRequestResponse
GET /api/repos/{host}/{owner}/{name}/docsReturn nested doc tree for a repo200 DocTreeResponse
GET /api/repos/{host}/{owner}/{name}/docs/{slug}Return a single doc page by slug200 DocPageResponse

Repository documents (indexed rows)

The document rows behind the rendered tree above — one per indexed file.

OperationPurposeParametersRequestResponse
GET /api/repos/{host}/{owner}/{name}/documentsList Repository Documentspage, per_page, search200 RepoDocumentListResponse
GET /api/repos/{host}/{owner}/{name}/documents/{document_id}Get Repository Document200 RepoDocumentDetailResponse

Retrieval

Hybrid search — the REST mirror of the MCP retrieve tool.

OperationPurposeParametersRequestResponse
POST /api/retrieveRetrieveRetrievalRequest200 RetrievalResponse

Source routing

Which repository or collection likely holds the answer.

OperationPurposeParametersRequestResponse
POST /api/routeRoute EndpointRouteRequest200 RouteResponse

Markdown collections

Uploaded document corpora: CRUD, upload, search, embedding and jobs.

OperationPurposeParametersRequestResponse
GET /api/md-collectionsList Md Collectionspage, per_page, search200 MdCollectionListResponse
POST /api/md-collectionsCreate Md CollectionCreateMdCollectionRequest201 MdCollectionDetailResponse
GET /api/md-collections/-/jobsList All Md Jobslimit, status200 MdGlobalJobListResponse
POST /api/md-collections/-/jobs/{job_id}/retryRetry Md Job200 MdJobResponse
GET /api/md-collections/{collection_id}Get Md Collectionpage, per_page, search200 MdCollectionDetailResponse
PATCH /api/md-collections/{collection_id}Update Md CollectionUpdateMdCollectionRequest200 MdCollectionDetailResponse
DELETE /api/md-collections/{collection_id}Delete Md Collection204
POST /api/md-collections/{collection_id}/documentsUpload Md Document201 MdDocumentUploadResponse
POST /api/md-collections/{collection_id}/documents/batchUpload Md Document BatchMdDocumentBatchUploadRequest201 MdDocumentBatchUploadResponse
GET /api/md-collections/{collection_id}/documents/{document_id}Get Md Document200 MdDocumentDetailResponse
DELETE /api/md-collections/{collection_id}/documents/{document_id}Delete Md Document204
GET /api/md-collections/{collection_id}/documents/{document_id}/chunksList Md Document Chunks200 MdChunkListResponse
GET /api/md-collections/{collection_id}/embed-statusGet Md Collection Embed Status200 MdEmbedStatusResponse
GET /api/md-collections/{collection_id}/jobsList Md Collection Jobslimit200 MdJobListResponse
POST /api/md-collections/{collection_id}/re-embedReembed Md Collection200 MdJobResponse
POST /api/md-collections/{collection_id}/searchSearch Md CollectionMdCollectionSearchRequest200 MdCollectionSearchResponse

Pipeline jobs

Sync batches, per-step jobs, retry and cancel.

OperationPurposeParametersRequestResponse
GET /api/jobsList Jobsstep, status, repo_id, batch_id, search, page, per_page200 SyncJobListResponse
GET /api/jobs/batchesReturn all batches (non-paginated), sorted newest-first by started_atkind200 SyncBatchListResponse
GET /api/jobs/batches/{batch_id}Get Batch200 SyncBatchDetailResponse
GET /api/jobs/statsGet Statsdays200 SyncStatsResponse
GET /api/jobs/{job_id}Get Job200 SyncJobResponse
POST /api/jobs/{job_id}/cancelCancel a queued or running job200 SyncJobResponse
POST /api/jobs/{job_id}/retryRequeue a failed job200 SyncJobResponse

Query logs

Usage analytics for admins, and self-service history.

OperationPurposeParametersRequestResponse
GET /api/admin/query-logsAdmin List Query Logspage, per_page, user_id, repository_id, tool_name, status, zero_results, q, since, until200 QueryLogPage
GET /api/admin/query-logs/statsAdmin Query Logs Statssince, until, top_n200 QueryLogStats
GET /api/admin/query-logs/stats/timeseriesBucketed query counts + token/cost sums for the usage chartsince, until, bucket200 UsageTimeseries
GET /api/admin/query-logs/stats/usersPer-user activity over the window — INCLUDING silent userssince, until200 UserUsageStats
GET /api/me/query-logsMe List Query Logspage, per_page, repository_id, tool_name, status, q, since, until200 QueryLogPage
DELETE /api/me/query-logsDrop every query_log row belonging to the caller200 ForgetResponse

Administration

One router tag covers the whole admin surface: users, groups and their repository/collection grants, git hosts and clone credentials, identity providers, SCIM clients and the SCIM event log.

OperationPurposeParametersRequestResponse
GET /api/admin/git-hostsList Git Hosts200 GitHostListResponse
POST /api/admin/git-hostsCreate Git HostCreateGitHostRequest201 GitHostView
PATCH /api/admin/git-hosts/{host_id}Update Git HostUpdateGitHostRequest200 GitHostView
DELETE /api/admin/git-hosts/{host_id}Delete Git Host204
GET /api/admin/git-hosts/{host_id}/credentialsList Credentials200 CredentialListResponse
POST /api/admin/git-hosts/{host_id}/credentialsCreate CredentialCreateCredentialRequest201 CredentialView
PATCH /api/admin/git-hosts/{host_id}/credentials/{credential_id}Update CredentialUpdateCredentialRequest200 CredentialView
DELETE /api/admin/git-hosts/{host_id}/credentials/{credential_id}Delete Credential204
POST /api/admin/git-hosts/{host_id}/credentials/{credential_id}/testTest CredentialTestCredentialRequest200 CredentialTestResult
GET /api/admin/git-hosts/{host_id}/webhook-deliveriesList Webhook Deliverieslimit200 WebhookDeliveryListResponse
GET /api/admin/groupsList Groups200 GroupListResponse
POST /api/admin/groupsCreate GroupCreateGroupRequest201 GroupResponse
PATCH /api/admin/groups/{group_id}Update GroupUpdateGroupRequest200 GroupResponse
DELETE /api/admin/groups/{group_id}Delete Group204
GET /api/admin/groups/{group_id}/collectionsList Collection Grants200 CollectionGrantListResponse
POST /api/admin/groups/{group_id}/collectionsPut Collection GrantPutCollectionGrantRequest200 CollectionGrantResponse
DELETE /api/admin/groups/{group_id}/collections/{collection_id}Delete Collection Grant204
GET /api/admin/groups/{group_id}/membersList Members200 GroupMembersResponse
POST /api/admin/groups/{group_id}/membersIdempotent bulk member-addAddMembersRequest200 AddMembersResponse
DELETE /api/admin/groups/{group_id}/members/{user_id}Remove Member204
GET /api/admin/groups/{group_id}/repositoriesList Repository Grants200 RepositoryGrantListResponse
POST /api/admin/groups/{group_id}/repositoriesUpsert a (group, repository) grantPutRepositoryGrantRequest200 RepositoryGrantResponse
DELETE /api/admin/groups/{group_id}/repositories/{repository_id}Delete Repository Grant204
GET /api/admin/identity-providersList Identity Providers200 IdentityProviderListResponse
POST /api/admin/identity-providersCreate Identity ProviderCreateIdentityProviderRequest201 IdentityProviderView
PATCH /api/admin/identity-providers/{provider_id}Update Identity ProviderUpdateIdentityProviderRequest200 IdentityProviderView
DELETE /api/admin/identity-providers/{provider_id}Delete Identity Provider204
POST /api/admin/identity-providers/{provider_id}/testProbe the IdP discovery + JWKS endpoints with the configured client200 IdentityProviderTestResponse
GET /api/admin/repos/{host}/{owner}/{name}/webhookGet Repository Webhook Config200 RepoWebhookConfigResponse
GET /api/admin/scim-clientsList Scim Clients200 SCIMClientListResponse
POST /api/admin/scim-clientsCreate Scim ClientCreateSCIMClientRequest201 SCIMClientCreated
DELETE /api/admin/scim-clients/{client_id}Revoke Scim Client204
POST /api/admin/scim-clients/{client_id}/rotateRotate Scim Client201 SCIMClientCreated
GET /api/admin/scim-eventsList Scim Eventsclient_id, target_user_id, status, since, limit200 SCIMEventListResponse
GET /api/admin/usersList Users200 AdminUserListResponse
POST /api/admin/usersCreate UserCreateUserRequest201 AdminUserResponse
PATCH /api/admin/users/{user_id}Update UserUpdateUserRequest200 AdminUserResponse
DELETE /api/admin/users/{user_id}Delete User204
POST /api/admin/users/{user_id}/disableDisable UserDisableUserRequest204
POST /api/admin/users/{user_id}/enableEnable User204

LLM runtime

Per-role model assignment, embedding state and provider tests.

OperationPurposeParametersRequestResponse
GET /api/admin/llm-runtimeList Assignments200 AssignmentsResponse
GET /api/admin/llm-runtime/embedding-statusGet Embedding Status200 EmbeddingStatusView
POST /api/admin/llm-runtime/reembedTrigger Reembed202 ReembedAcceptedResponse
POST /api/admin/llm-runtime/testProbe (secret + model) without saving — owner onlyAssignmentTestRequest200 AssignmentTestResponse
PUT /api/admin/llm-runtime/{role}Upsert AssignmentAssignmentRequest200 AssignmentView
DELETE /api/admin/llm-runtime/{role}Clear Assignment204

Provider secrets

Encrypted provider credentials.

OperationPurposeParametersRequestResponse
GET /api/admin/secretsList Secrets200 LLMSecretsListResponse
POST /api/admin/secretsCreate SecretSecretUpsertRequest201 LLMSecretResponse
PUT /api/admin/secrets/{secret_id}Update SecretSecretUpsertRequest200 LLMSecretResponse
DELETE /api/admin/secrets/{secret_id}Delete Secret204
POST /api/admin/secrets/{secret_id}/testTest Secret200 SecretTestResponse

MCP briefing

The operator briefing injected into every MCP session.

OperationPurposeParametersRequestResponse
GET /api/admin/mcp/briefingGet Mcp Briefing200 McpBriefingResponse
PATCH /api/admin/mcp/briefingUpdate Mcp BriefingMcpBriefingPatchRequest200 McpBriefingResponse

Inbound webhooks

Push events that trigger a sync.

OperationPurposeParametersRequestResponse
POST /api/webhooks/github/{host_slug}Receive Github Webhook204

SCIM 2.0

User provisioning. Mounted at /scim/v2, outside the API prefix.

OperationPurposeParametersRequestResponse
GET /scim/v2/ResourceTypesGet Resource Types200
GET /scim/v2/SchemasGet Schemas200
GET /scim/v2/ServiceProviderConfigGet Service Provider Config200
GET /scim/v2/UsersList Users200
POST /scim/v2/UsersCreate User201
GET /scim/v2/Users/{user_id}Get User200
PUT /scim/v2/Users/{user_id}Replace User200
PATCH /scim/v2/Users/{user_id}Patch User200
DELETE /scim/v2/Users/{user_id}Delete User204

Request bodies

The fields of every JSON request model above, so a call can be constructed from this page alone. Enum-valued fields show their members; Modes and lifecycles explains what each member means.

AddMembersRequest

FieldTypeRequiredDefault
user_idsuuid[]yes

Rejects unknown fields.

AssignmentRequest

FieldTypeRequiredDefault
secret_iduuidyes
model_namestringyes
reasoning_effortstringno
embedding_dimintegerno
extra_paramsobjectno

Rejects unknown fields.

AssignmentTestRequest

FieldTypeRequiredDefault
rolestringyes
secret_iduuidyes
model_namestringyes
reasoning_effortstringno

Rejects unknown fields.

BootstrapRequest

FieldTypeRequiredDefault
setup_tokenstringyes
emailemailyes
passwordstringyes
namestringnoAdmin

CreateCredentialRequest

FieldTypeRequiredDefault
labelstringyes
tokenstringyes
is_defaultbooleannofalse
webhook_secretstringno

Rejects unknown fields.

CreateGitHostRequest

FieldTypeRequiredDefault
slugstringyes
display_namestringyes
kindstringnogithub
base_urlstringyes
api_urlstringyes
git_hoststringyes
enabledbooleannotrue

Rejects unknown fields.

CreateGroupRequest

FieldTypeRequiredDefault
namestringyes
descriptionstringno
oidc_provider_iduuidno
oidc_group_namestringno

Rejects unknown fields.

CreateIdentityProviderRequest

FieldTypeRequiredDefault
slugstringyes
display_namestringyes
kindstringnooidc
issuer_urlstringyes
client_idstringyes
client_secretstringno
scopesstring[]no
response_modestringnoquery
groups_claimstringno
domain_allowliststring[]no
auto_provisionbooleannotrue
auto_link_on_verified_emailbooleannofalse
admin_group_modestringnoignore
admin_groupsstring[]no
enabledbooleannotrue

Rejects unknown fields.

CreateMdCollectionRequest

FieldTypeRequiredDefault
namestringyes
descriptionstringno
visibilityprivate | public | admin_onlynoprivate

CreateRepositoryRequest

FieldTypeRequiredDefault
git_urlstringyes
branchstringno
namestringno
sync_schedulemanual | hourly | daily | weekly | webhookno
visibilitypublic | admin_onlyno
host_iduuidno

Rejects unknown fields.

CreateSCIMClientRequest

FieldTypeRequiredDefault
provider_iduuidyes
namestringyes
scopesstring[]no

Rejects unknown fields.

CreateTokenRequest

FieldTypeRequiredDefault
namestringyes
scopesstring[]yes
expires_atdate-timeno

Rejects unknown fields.

CreateUserRequest

FieldTypeRequiredDefault
emailemailyes
passwordstringyes
namestringno
roleowner | admin | usernouser

Rejects unknown fields.

DisableUserRequest

FieldTypeRequiredDefault
reasonstringno

Rejects unknown fields.

GraphNodesCheckRequest

FieldTypeRequiredDefault
node_idsuuid[]yes

LoginRequest

FieldTypeRequiredDefault
emailstringyes
passwordstringyes

McpBriefingPatchRequest

FieldTypeRequiredDefault
contentstringyes

Rejects unknown fields.

MdCollectionSearchRequest

FieldTypeRequiredDefault
querystringyes
top_kintegerno10

MdDocumentBatchItem

FieldTypeRequiredDefault
source_keystringyes
titlestringno
contentstringyes

MdDocumentBatchUploadRequest

FieldTypeRequiredDefault
documentsobject[]yes
upload_job_iduuidno
upload_totalintegerno
upload_finalbooleannofalse

PutCollectionGrantRequest

FieldTypeRequiredDefault
collection_iduuidyes
levelread | writeyes

Rejects unknown fields.

PutRepositoryGrantRequest

FieldTypeRequiredDefault
repository_iduuidyes
levelread | writeyes

Rejects unknown fields.

RetrievalIncludeRequest

FieldTypeRequiredDefault
chunksbooleannotrue
graphbooleannofalse
scoresbooleannofalse

RetrievalRequest

FieldTypeRequiredDefault
querystringyes
repository_iduuidno
stores(ast | code | ast_summary | repo_doc)[]no
top_kintegerno10
snippet_charsintegerno600
as_ofdate-timeno
sincedate-timeno
untildate-timeno
includeobjectno

RevokeAllRequest

FieldTypeRequiredDefault
reasonstringnoadmin

Rejects unknown fields.

RouteRequest

FieldTypeRequiredDefault
querystringyes
top_kintegerno3

SecretUpsertRequest

FieldTypeRequiredDefault
namestringyes
api_urlstringyes
api_keystringno

Rejects unknown fields.

TestCredentialRequest

FieldTypeRequiredDefault
tokenstringno

Rejects unknown fields.

UpdateCredentialRequest

FieldTypeRequiredDefault
labelstringno
tokenstringno
is_defaultbooleanno
webhook_secretstringno
clear_webhook_secretbooleannofalse

Rejects unknown fields.

UpdateGitHostRequest

FieldTypeRequiredDefault
display_namestringno
base_urlstringno
api_urlstringno
git_hoststringno
enabledbooleanno

Rejects unknown fields.

UpdateGroupRequest

FieldTypeRequiredDefault
namestringno
descriptionstringno
oidc_provider_iduuidno
oidc_group_namestringno

Rejects unknown fields.

UpdateIdentityProviderRequest

FieldTypeRequiredDefault
display_namestringno
issuer_urlstringno
client_idstringno
client_secretstringno
scopesstring[]no
response_modestringno
groups_claimstringno
domain_allowliststring[]no
auto_provisionbooleanno
auto_link_on_verified_emailbooleanno
admin_group_modestringno
admin_groupsstring[]no
enabledbooleanno

Rejects unknown fields.

UpdateMdCollectionRequest

FieldTypeRequiredDefault
namestringno
descriptionstringno
visibilityprivate | public | admin_onlyno

UpdateRepositoryRequest

FieldTypeRequiredDefault
sync_schedulemanual | hourly | daily | weekly | webhookno
visibilitypublic | admin_onlyno
log_queriesbooleanno

Rejects unknown fields.

UpdateUserRequest

FieldTypeRequiredDefault
namestringno
roleowner | admin | userno
passwordstringno

Rejects unknown fields.

Documents Cograph 0.1.0 · Apache-2.0 · pre-1.0, so APIs and migrations may change.