API reference
Use the authenticated REST surface for search, documents, originals, graph traversal, and administration.
The REST API uses the same tenant, role, source-ACL, and sensitive-data checks as the product interface and MCP server. Use OAuth for interactive clients and a scoped API key for service integrations.
Base URL
https://your-coglake.example/api/coglakeSend credentials as a bearer token:
Authorization: Bearer YOUR_SCOPED_TOKENCore resource groups
| Method and resource | Purpose | Minimum scope |
|---|---|---|
POST /retrieval/search | Search visible knowledge | search:read |
POST /retrieval/answer | Cited answers over visible evidence | search:read |
GET /documents/catalog | Paginated visible document catalog | knowledge:read |
GET /documents/:id | Read a permitted document | knowledge:read |
GET /documents/:id/original-link | Request a temporary authenticated original link | knowledge:read |
Administrative endpoints require their matching administration scopes. Do not issue broad administration scopes to search-only agents.
Read-only examples
Replace the host and token with your own installation and scoped credential. Keep the token in your client's secret storage, not in a shared script or URL.
POST /api/coglake/retrieval/search
Authorization: Bearer YOUR_SCOPED_TOKEN
Content-Type: application/json
{"query":"onboarding","profile":"exact","limit":5}GET /api/coglake/documents/catalog
Authorization: Bearer YOUR_SCOPED_TOKENCatalog responses contain documents and nextCursor. If nextCursor is not null,
send it unchanged as the URL-encoded after parameter on the next catalog request.
Keep the same optional connectorId filter. An empty page with a next cursor is
not the end. A catalog is a view of synchronized content, not a live provider listing.
Encode an entire document ID when inserting it into a URL path; IDs can contain slashes and non-ASCII characters. Do not build an original-file URL yourself. Use the returned link and the required authentication, and request a new link if it expires.
For a schema-discoverable tool interface, prefer MCP. This page covers the public knowledge workflow, not private application internals.
Errors and limits
401means the credential is missing, expired, or invalid.402means a subscription or entitlement is required; role changes do not fix it.403means the caller, role, source ACL, or data policy denies the action.404is also used when revealing the existence of a hidden object would disclose information.409reports stable quota or lifecycle conflicts.- File/validation errors identify unsupported input or exceeded limits; inspect the safe error message before retrying.
429includes a retry boundary when a request budget is exhausted.
Direct document IDs never bypass authorization. Original files are delivered through the authenticated API rather than exposing object-storage credentials.
For agent tooling and OAuth discovery, continue with API and MCP connection.