API Overview

Conventions, authentication, error handling, and common patterns for the Cognova REST API.

Base URL

All API endpoints are served under the /api prefix.

https://your-cognova-instance.com/api/tasks

Content Type

Requests and responses use JSON. Set the Content-Type header for requests with a body:

Content-Type: application/json

Most endpoints require an authenticated session. Cognova uses cookie-based sessions managed by BetterAuth. After signing in via /api/auth/sign-in/email, the server sets a session cookie that is sent automatically on subsequent requests.

For programmatic access (CLI tools, scripts), you can authenticate with an API token instead:

X-API-Token: <your-token>

Set the COGNOVA_API_TOKEN environment variable on the server to enable token authentication.

Public Endpoints

These paths do not require authentication:

Path	Purpose
`/api/auth/*`	Sign-up, sign-in, sign-out
`/api/health`	Health check
`/api/documents/:id/public`	Public document viewer

All other /api/* routes return 401 Unauthorized if no valid session or API token is provided.

Response Format

Success

All successful responses wrap the result in a data field:

{
  "data": { "id": "abc-123", "title": "My Task" }
}

List endpoints return an array:

{
  "data": [
    { "id": "abc-123", "title": "Task One" },
    { "id": "def-456", "title": "Task Two" }
  ]
}

Errors

Errors follow a consistent shape:

{
  "statusCode": 400,
  "statusMessage": "Bad Request",
  "message": "Task title is required"
}

Status Codes

Code	Meaning
`200`	OK -- request succeeded
`201`	Created -- resource created
`400`	Bad Request -- invalid input or validation failure
`401`	Unauthorized -- missing or invalid session
`403`	Forbidden -- insufficient permissions
`404`	Not Found -- resource does not exist
`500`	Server Error -- unexpected failure
`503`	Service Unavailable -- database not configured

Soft Deletes

Tasks, projects, and documents use soft deletes. When you DELETE a resource, it sets a deletedAt timestamp rather than removing the row.

Default behavior: soft-deleted resources are excluded from list endpoints.
Include deleted: pass ?includeDeleted=true to include them.
Restore: POST /api/{resource}/{id}/restore clears the deletedAt field (available for tasks and documents).

Agent deletion is a hard delete. Deleting an agent permanently removes it and cascades to all associated runs.

Filtering

List endpoints accept query parameters for filtering. Common parameters:

Parameter	Type	Description
`includeDeleted`	`boolean`	Include soft-deleted resources
`search`	`string`	Full-text search on title/content
`projectId`	`string`	Filter by project

Endpoint-specific filters are documented on each resource page.

Type Reference

All TypeScript interfaces for request/response shapes are defined in shared/types/. See the Database Schema page for the full type definitions -- they are not duplicated in this reference.

Production Checklist

Security hardening and operational best practices for production deployments.

Authentication