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 Health——200 HealthResponse
GET /healthGet Health——200 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 yet—BootstrapRequest200 LoginResponse
GET /api/auth/configGet Auth Config——200 AuthConfigResponse
POST /api/auth/loginLogin—LoginRequest200 LoginResponse
POST /api/auth/logoutLogout——204
GET /api/auth/meGet Current User Profile——200 UserResponse
GET /api/auth/oidc/{slug}/callbackOidc Callback Getcode, state—302
POST /api/auth/oidc/{slug}/callbackUsed by IdPs configured with response_mode=form_post——302
POST /api/auth/oidc/{slug}/link/startOidc Link Start——302
GET /api/auth/oidc/{slug}/loginOidc Loginreturn_to—302
POST /api/auth/refreshRotate refresh token, check family reuse, issue new pair——200 LoginResponse
POST /api/auth/registerAlways 403 — self-service registration is not exposed over the API——200

Current user ​

The caller's own identities and query history.

OperationPurposeParametersRequestResponse
GET /api/me/identitiesList My Identities——200 IdentityListResponse
DELETE /api/me/identities/{identity_id}Unlink My Identity——204

Personal access tokens ​

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

OperationPurposeParametersRequestResponse
GET /api/admin/users/{user_id}/tokensAdmin List User Tokens——200 TokenListResponse
POST /api/admin/users/{user_id}/tokens/revoke-allMass-revoke every active PAT for a target user—RevokeAllRequest200 RevokeAllResponse
GET /api/me/tokensList My Tokens——200 TokenListResponse
POST /api/me/tokensCreate My Token—CreateTokenRequest201 CreateTokenResponse
DELETE /api/me/tokens/{token_id}Revoke My Token——204
POST /api/me/tokens/{token_id}/rotateAtomically revoke an existing token and mint a replacement——201 CreateTokenResponse

Repositories ​

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

OperationPurposeParametersRequestResponse
GET /api/reposList Repositoriespage, per_page, search, status—200 RepositoryListResponse
POST /api/reposCreate Repository—CreateRepositoryRequest202 RepositoryResponse
POST /api/repos/uploadCreate a new repository sourced from an uploaded zip archive—form data202 RepositoryResponse
GET /api/repos/{host}/{owner}/{name}Get Repository——200 RepositoryResponse
PATCH /api/repos/{host}/{owner}/{name}Update Repository—UpdateRepositoryRequest200 RepositoryResponse
DELETE /api/repos/{host}/{owner}/{name}Delete Repository——204
GET /api/repos/{host}/{owner}/{name}/files/{source_file_id}Get Repository Source File——200 SourceFileResponse
GET /api/repos/{host}/{owner}/{name}/files/{source_file_id}/rangeGet Repository Source File Rangestart, end—200 SourceFileRangeResponse
GET /api/repos/{host}/{owner}/{name}/graphGet Repository Graphview, node_type, language, module, search, depth, limit—200 GraphListResponse
GET /api/repos/{host}/{owner}/{name}/graph/nodes/by-qn/{qualified_name}Resolve a code node by its qualified_name for the current repo——200 GraphNodeDetailResponse
POST /api/repos/{host}/{owner}/{name}/graph/nodes/checkCheck Repository Graph Nodes—GraphNodesCheckRequest200 GraphNodesCheckResponse
GET /api/repos/{host}/{owner}/{name}/graph/nodes/{node_id}Get Repository Graph Node——200 GraphNodeDetailResponse
POST /api/repos/{host}/{owner}/{name}/reindexReindex Repository——202 RepoReindexResponse
POST /api/repos/{host}/{owner}/{name}/runs/{run_id}/cancelForce-cancel a wedged QUEUED/RUNNING repo_sync_runs row——200 RepoSyncRunResponse
POST /api/repos/{host}/{owner}/{name}/uploadReplace the persisted archive for a zip-source repository—form data202 RepoReindexResponse
POST /api/repos/{host}/{owner}/{name}/webhookTrigger Repository Webhookx-cograph-webhook-secret—202 RepoWebhookTriggerResponse

Generated wiki ​

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

OperationPurposeParametersRequestResponse
GET /api/repos/{host}/{owner}/{name}/wikiGet Wiki Tree——200 WikiTreeResponse
GET /api/repos/{host}/{owner}/{name}/wiki/{slug}Get Wiki Page——200 WikiPageResponse
POST /api/repos/{host}/{owner}/{name}/wiki/{slug}/repair-citationsRepair Wiki Page Citations——200 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 repo——200 DocTreeResponse
GET /api/repos/{host}/{owner}/{name}/docs/{slug}Return a single doc page by slug——200 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, search—200 RepoDocumentListResponse
GET /api/repos/{host}/{owner}/{name}/documents/{document_id}Get Repository Document——200 RepoDocumentDetailResponse

Retrieval ​

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

OperationPurposeParametersRequestResponse
POST /api/retrieveRetrieve—RetrievalRequest200 RetrievalResponse

Source routing ​

Which repository or collection likely holds the answer.

OperationPurposeParametersRequestResponse
POST /api/routeRoute Endpoint—RouteRequest200 RouteResponse

Markdown collections ​

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

OperationPurposeParametersRequestResponse
GET /api/md-collectionsList Md Collectionspage, per_page, search—200 MdCollectionListResponse
POST /api/md-collectionsCreate Md Collection—CreateMdCollectionRequest201 MdCollectionDetailResponse
GET /api/md-collections/-/jobsList All Md Jobslimit, status—200 MdGlobalJobListResponse
POST /api/md-collections/-/jobs/{job_id}/retryRetry Md Job——200 MdJobResponse
GET /api/md-collections/{collection_id}Get Md Collectionpage, per_page, search—200 MdCollectionDetailResponse
PATCH /api/md-collections/{collection_id}Update Md Collection—UpdateMdCollectionRequest200 MdCollectionDetailResponse
DELETE /api/md-collections/{collection_id}Delete Md Collection——204
POST /api/md-collections/{collection_id}/documentsUpload Md Document——201 MdDocumentUploadResponse
POST /api/md-collections/{collection_id}/documents/batchUpload Md Document Batch—MdDocumentBatchUploadRequest201 MdDocumentBatchUploadResponse
GET /api/md-collections/{collection_id}/documents/{document_id}Get Md Document——200 MdDocumentDetailResponse
DELETE /api/md-collections/{collection_id}/documents/{document_id}Delete Md Document——204
GET /api/md-collections/{collection_id}/documents/{document_id}/chunksList Md Document Chunks——200 MdChunkListResponse
GET /api/md-collections/{collection_id}/embed-statusGet Md Collection Embed Status——200 MdEmbedStatusResponse
GET /api/md-collections/{collection_id}/jobsList Md Collection Jobslimit—200 MdJobListResponse
POST /api/md-collections/{collection_id}/re-embedReembed Md Collection——200 MdJobResponse
POST /api/md-collections/{collection_id}/searchSearch Md Collection—MdCollectionSearchRequest200 MdCollectionSearchResponse

Pipeline jobs ​

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

OperationPurposeParametersRequestResponse
GET /api/jobsList Jobsstep, status, repo_id, batch_id, search, page, per_page—200 SyncJobListResponse
GET /api/jobs/batchesReturn all batches (non-paginated), sorted newest-first by started_atkind—200 SyncBatchListResponse
GET /api/jobs/batches/{batch_id}Get Batch——200 SyncBatchDetailResponse
GET /api/jobs/statsGet Statsdays—200 SyncStatsResponse
GET /api/jobs/{job_id}Get Job——200 SyncJobResponse
POST /api/jobs/{job_id}/cancelCancel a queued or running job——200 SyncJobResponse
POST /api/jobs/{job_id}/retryRequeue a failed job——200 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, until—200 QueryLogPage
GET /api/admin/query-logs/statsAdmin Query Logs Statssince, until, top_n—200 QueryLogStats
GET /api/admin/query-logs/stats/timeseriesBucketed query counts + token/cost sums for the usage chartsince, until, bucket—200 UsageTimeseries
GET /api/admin/query-logs/stats/usersPer-user activity over the window — INCLUDING silent userssince, until—200 UserUsageStats
GET /api/me/query-logsMe List Query Logspage, per_page, repository_id, tool_name, status, q, since, until—200 QueryLogPage
DELETE /api/me/query-logsDrop every query_log row belonging to the caller——200 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 Hosts——200 GitHostListResponse
POST /api/admin/git-hostsCreate Git Host—CreateGitHostRequest201 GitHostView
PATCH /api/admin/git-hosts/{host_id}Update Git Host—UpdateGitHostRequest200 GitHostView
DELETE /api/admin/git-hosts/{host_id}Delete Git Host——204
GET /api/admin/git-hosts/{host_id}/credentialsList Credentials——200 CredentialListResponse
POST /api/admin/git-hosts/{host_id}/credentialsCreate Credential—CreateCredentialRequest201 CredentialView
PATCH /api/admin/git-hosts/{host_id}/credentials/{credential_id}Update Credential—UpdateCredentialRequest200 CredentialView
DELETE /api/admin/git-hosts/{host_id}/credentials/{credential_id}Delete Credential——204
POST /api/admin/git-hosts/{host_id}/credentials/{credential_id}/testTest Credential—TestCredentialRequest200 CredentialTestResult
GET /api/admin/git-hosts/{host_id}/webhook-deliveriesList Webhook Deliverieslimit—200 WebhookDeliveryListResponse
GET /api/admin/groupsList Groups——200 GroupListResponse
POST /api/admin/groupsCreate Group—CreateGroupRequest201 GroupResponse
PATCH /api/admin/groups/{group_id}Update Group—UpdateGroupRequest200 GroupResponse
DELETE /api/admin/groups/{group_id}Delete Group——204
GET /api/admin/groups/{group_id}/collectionsList Collection Grants——200 CollectionGrantListResponse
POST /api/admin/groups/{group_id}/collectionsPut Collection Grant—PutCollectionGrantRequest200 CollectionGrantResponse
DELETE /api/admin/groups/{group_id}/collections/{collection_id}Delete Collection Grant——204
GET /api/admin/groups/{group_id}/membersList Members——200 GroupMembersResponse
POST /api/admin/groups/{group_id}/membersIdempotent bulk member-add—AddMembersRequest200 AddMembersResponse
DELETE /api/admin/groups/{group_id}/members/{user_id}Remove Member——204
GET /api/admin/groups/{group_id}/repositoriesList Repository Grants——200 RepositoryGrantListResponse
POST /api/admin/groups/{group_id}/repositoriesUpsert a (group, repository) grant—PutRepositoryGrantRequest200 RepositoryGrantResponse
DELETE /api/admin/groups/{group_id}/repositories/{repository_id}Delete Repository Grant——204
GET /api/admin/identity-providersList Identity Providers——200 IdentityProviderListResponse
POST /api/admin/identity-providersCreate Identity Provider—CreateIdentityProviderRequest201 IdentityProviderView
PATCH /api/admin/identity-providers/{provider_id}Update Identity Provider—UpdateIdentityProviderRequest200 IdentityProviderView
DELETE /api/admin/identity-providers/{provider_id}Delete Identity Provider——204
POST /api/admin/identity-providers/{provider_id}/testProbe the IdP discovery + JWKS endpoints with the configured client——200 IdentityProviderTestResponse
GET /api/admin/repos/{host}/{owner}/{name}/webhookGet Repository Webhook Config——200 RepoWebhookConfigResponse
GET /api/admin/scim-clientsList Scim Clients——200 SCIMClientListResponse
POST /api/admin/scim-clientsCreate Scim Client—CreateSCIMClientRequest201 SCIMClientCreated
DELETE /api/admin/scim-clients/{client_id}Revoke Scim Client——204
POST /api/admin/scim-clients/{client_id}/rotateRotate Scim Client——201 SCIMClientCreated
GET /api/admin/scim-eventsList Scim Eventsclient_id, target_user_id, status, since, limit—200 SCIMEventListResponse
GET /api/admin/usersList Users——200 AdminUserListResponse
POST /api/admin/usersCreate User—CreateUserRequest201 AdminUserResponse
PATCH /api/admin/users/{user_id}Update User—UpdateUserRequest200 AdminUserResponse
DELETE /api/admin/users/{user_id}Delete User——204
POST /api/admin/users/{user_id}/disableDisable User—DisableUserRequest204
POST /api/admin/users/{user_id}/enableEnable User——204

LLM runtime ​

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

OperationPurposeParametersRequestResponse
GET /api/admin/llm-runtimeList Assignments——200 AssignmentsResponse
GET /api/admin/llm-runtime/embedding-statusGet Embedding Status——200 EmbeddingStatusView
POST /api/admin/llm-runtime/reembedTrigger Reembed——202 ReembedAcceptedResponse
POST /api/admin/llm-runtime/testProbe (secret + model) without saving — owner only—AssignmentTestRequest200 AssignmentTestResponse
PUT /api/admin/llm-runtime/{role}Upsert Assignment—AssignmentRequest200 AssignmentView
DELETE /api/admin/llm-runtime/{role}Clear Assignment——204

Provider secrets ​

Encrypted provider credentials.

OperationPurposeParametersRequestResponse
GET /api/admin/secretsList Secrets——200 LLMSecretsListResponse
POST /api/admin/secretsCreate Secret—SecretUpsertRequest201 LLMSecretResponse
PUT /api/admin/secrets/{secret_id}Update Secret—SecretUpsertRequest200 LLMSecretResponse
DELETE /api/admin/secrets/{secret_id}Delete Secret——204
POST /api/admin/secrets/{secret_id}/testTest Secret——200 SecretTestResponse

MCP briefing ​

The operator briefing injected into every MCP session.

OperationPurposeParametersRequestResponse
GET /api/admin/mcp/briefingGet Mcp Briefing——200 McpBriefingResponse
PATCH /api/admin/mcp/briefingUpdate Mcp Briefing—McpBriefingPatchRequest200 McpBriefingResponse

Inbound webhooks ​

Push events that trigger a sync.

OperationPurposeParametersRequestResponse
POST /api/webhooks/github/{host_slug}Receive Github Webhook——204

SCIM 2.0 ​

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

OperationPurposeParametersRequestResponse
GET /scim/v2/ResourceTypesGet Resource Types——200
GET /scim/v2/SchemasGet Schemas——200
GET /scim/v2/ServiceProviderConfigGet Service Provider Config——200
GET /scim/v2/UsersList Users——200
POST /scim/v2/UsersCreate User——201
GET /scim/v2/Users/{user_id}Get User——200
PUT /scim/v2/Users/{user_id}Replace User——200
PATCH /scim/v2/Users/{user_id}Patch User——200
DELETE /scim/v2/Users/{user_id}Delete User——204

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.