Authentication

All API requests require authentication. Gnoll supports cookie-based auth (for the web UI) and API key auth (for scripts, agents, and integrations).

API Key Authentication

The recommended method for programmatic access. API keys are passed via the Authorization header:

Authorization: Bearer gkey_your_key_here

Store your key securely. The full key is only shown once at creation time. If lost, delete the key and create a new one.

API keys are authorized by scopes. Each scope grants access to specific resources and actions:

Scope	Grants Access To
`issues:read`	List and view issues
`issues:write`	Create, update, close, reopen, delete issues
`deps:read`	View dependencies and dependency graph
`deps:write`	Add and remove dependencies
`comments:read`	List and view comments
`comments:write`	Create and delete comments
`epics:read`	View epic-specific data
`epics:write`	Manage epic relationships
`labels:read`	List labels and categories
`labels:write`	Create, update, delete labels; attach/detach from issues
`search:read`	Full-text search
`events:read`	View activity events
`dashboard:read`	View dashboard statistics

API keys can be restricted to specific projects. When a key is project-scoped, it can only access issues within those projects.

Set the active project context using a cookie:

Cookie: ProjectId=your_project_id

Or the key's project restrictions will be applied automatically.

All API responses are JSON. Successful responses return the data directly. Error responses follow this format:

{
  "error": "Description of what went wrong",
  "code": "ERROR_CODE",
  "status": 400
}

List endpoints support pagination with these query parameters:

Parameter	Default	Description
`page`	1	Page number (1-based)
`pageSize`	25	Items per page (max 100)

Paginated responses include:

{
  "items": [...],
  "totalCount": 142,
  "page": 1,
  "pageSize": 25,
  "totalPages": 6
}

All API endpoints are prefixed with /api/v1/. For example:

GET https://your-instance.com/api/v1/issues