Agent access
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/apiSend credentials as a bearer token:
Authorization: Bearer YOUR_SCOPED_TOKENCore resource groups
| Resource | Typical purpose | Minimum scope |
|---|---|---|
/retrieval/search | Permission-aware hybrid search and explanations | search:read |
/retrieval/answer | Cited answers over visible evidence | search:read |
/documents/:id | Read one permitted document by stable ID | knowledge:read |
/documents/:id/original-link | Request a short-lived authenticated original link | knowledge:read |
/graph/* | Inspect or traverse visible document relations | knowledge:read |
/knowledge/* | Work with permitted internal workspaces and files | knowledge:read or knowledge:write |
Administrative endpoints require their matching administration scopes. Do not issue broad administration scopes to search-only agents.
Errors and limits
401means the credential is missing, expired, or invalid.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.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.