Contexts

Contexts are structured knowledge bundles that Chao reasons over. A Context can contain documents, live connector snapshots, prior chain outputs, web pages, or notes. Users curate Contexts. Agents consume them. Chao synthesizes them into grounded responses.

Status: Planned (Phase 1, Milestone M1.2)

Endpoints

Method	Path	Description	Auth	Rate Limit
POST	/contexts	Create a Context	JWT + Entitlement	30/min
GET	/contexts	List user Contexts	JWT	60/min
GET	/contexts/:id	Get a Context + sources	JWT	60/min
PATCH	/contexts/:id	Update name/visibility	JWT	30/min
DELETE	/contexts/:id	Delete a Context	JWT	30/min
POST	/contexts/:id/sources	Add a source (upload, URL, connector)	JWT	30/min
DELETE	/contexts/:id/sources/:sourceId	Remove a source	JWT	30/min
POST	/contexts/:id/refresh	Trigger manual refresh	JWT	10/min
POST	/contexts/:id/search?q=	Semantic search within Context	JWT	60/min

Context Source Types

Type	Description	Refresh
document	PDF, Markdown, CSV, HTML file	Manual re-upload
connector_snapshot	Current Notion page, GitHub issues list	Configurable interval
chain_output	Output of a chain execution	On chain completion
web	Live fetch of a URL	On-demand or scheduled
note	Free-text written directly	Manual

Create Context

Request

Field	Type	Required	Description
name	string	Yes	Context name
visibility	string	No	One of: private, workspace, org. Default: private

Add Source

Request

Field	Type	Required	Description
type	string	Yes	One of: document, connector_snapshot, web, note
content	string	Conditional	Required for note type
url	string	Conditional	Required for web type
connectorId	string	Conditional	Required for connector_snapshot type
refreshIntervalMinutes	number	No	Auto-refresh interval (connector/web sources)

Semantic Search

Request

Param	Type	Required	Description
q	string	Yes	Search query
topK	number	No	Max results (default: 5)

Response

{
  "data": [
    {
      "content": "The product spec mentions...",
      "sourceId": "src-123",
      "sourceType": "document",
      "relevanceScore": 0.92
    }
  ]
}