Context Layer

The Context Layer is the AI agent’s knowledge base. It stores context notes — discrete facts, preferences, observations, and document chunks — that the agent retrieves at inference time to reason over your data. Notes are scoped either global (workspace-wide) or ontology (tied to a single ontology via a scope_id).

This note scope model (global | ontology + scope_id) is specific to the Context Layer. A note scoped to ontology with a given scope_id is only retrieved when the agent operates on that same ontology. The scope_id is the ontology ID — the same identifier you pass to the AI Agent chat endpoint.

All paths are relative to the base URL and require authentication. All responses use the standard envelope.

The platform also ships an onboarding interview wizard that populates context notes interactively. Those endpoints (GET /knowledge/interview/template, POST /knowledge/interview) are UI-internal and not documented here.

Note fields

Every context note has these fields:

Field	Description
`id`	Note UUID.
`scope`	`global` or `ontology`.
`scope_id`	The ontology ID when `scope` is `ontology`; `null` for `global`.
`kind`	One of `fact`, `preference`, `observation`, `document_chunk`.
`title`	Short label (≤ 120 chars). Auto-derived from the first line of `text` when omitted.
`text`	The note content. Markdown is allowed.
`activation`	How the note enters context — `retrieved` (default), `always`, or `on_demand`. See below.
`source`	Originator: `user`, `agent_writer`, or `import`.
`created_at`	ISO-8601 timestamp.
`use_count`	How many times the note has been retrieved.
`superseded_by`	UUID of the note that replaced this one, or `null`. Superseded notes are excluded from listing and retrieval.

Activation

activation controls how a note enters the agent’s context:

Value	Behavior
`retrieved` (default)	Added to a semantic pool and surfaced only when relevant to the message.
`always`	Injected into the system prompt on every message (a standing rule).
`on_demand`	The title is always listed; the body is fetched only when the agent asks for it.

Notes with activation of always or on_demand enter the system prompt, so on create/update they are passed through a safety screen. If rejected, the request returns 400 with a message like Rule rejected by screening: <reason>. retrieved notes are never screened.

Context notes

List notes

Return active context notes for the given scope, optionally filtered by kind or activation.

GET /knowledge/context

Parameter	In	Required	Default	Description
`scope`	query	yes	—	`global` or `ontology`.
`scope_id`	query	no	—	The ontology ID. Required when `scope` is `ontology`; omit for `global`.
`kinds`	query	no	—	Comma-separated list of kinds to include (e.g. `fact,preference`). Omit to return all.
`activation`	query	no	—	Filter to a single activation (`retrieved`, `always`, or `on_demand`).

curl "$BASE_URL/knowledge/context?scope=ontology&scope_id=$ONTOLOGY_ID" \
  -H "Authorization: Bearer $TOKEN"

{
  "status": "success",
  "message": "Context notes listed",
  "data": [
    {
      "id": "note_a1b2...",
      "scope": "ontology",
      "scope_id": "28b8678395e",
      "kind": "fact",
      "title": "Composite key on orders",
      "text": "The `orders` table has a composite primary key on (order_id, tenant_id).",
      "activation": "retrieved",
      "source": "user",
      "use_count": 3,
      "superseded_by": null,
      "created_at": "2026-06-20T09:15:00+00:00"
    }
  ]
}

Create a note

Write a single context note into the knowledge base.

POST /knowledge/context

Parameter	In	Required	Default	Description
`scope`	body	yes	—	`global` or `ontology`.
`scope_id`	body	conditional	—	The ontology ID. Required when `scope` is `ontology`; must be absent/`null` for `global`.
`kind`	body	yes	—	One of `fact`, `preference`, `observation`, `document_chunk`.
`text`	body	yes	—	The note content (non-empty).
`title`	body	no	derived	Short label (≤ 120 chars). Auto-derived from the first line of `text` when omitted.
`activation`	body	no	`"retrieved"`	`retrieved`, `always`, or `on_demand`. Non-`retrieved` values are screened (see above).
`source`	body	no	`"user"`	`user`, `agent_writer`, or `import`.
`supersedes`	body	no	`[]`	List of note IDs this note replaces. Superseded notes are excluded from future retrieval.

curl -X POST "$BASE_URL/knowledge/context" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "ontology",
    "scope_id": "28b8678395e",
    "kind": "preference",
    "title": "Default build level",
    "text": "Prefer level-150 builds unless the user asks otherwise.",
    "activation": "retrieved"
  }'

{
  "status": "success",
  "message": "Context note created",
  "data": {
    "id": "note_c3d4...",
    "scope": "ontology",
    "scope_id": "28b8678395e",
    "kind": "preference",
    "title": "Default build level",
    "text": "Prefer level-150 builds unless the user asks otherwise.",
    "activation": "retrieved",
    "source": "user",
    "use_count": 0,
    "superseded_by": null,
    "created_at": "2026-06-25T11:00:00+00:00"
  }
}

On the free tier, creating notes consumes the embedding quota. When it is exhausted the endpoint returns 402 with code: "..._LIMIT_REACHED".

Get a note

Retrieve a single context note by ID.

GET /knowledge/context/{note_id}

Parameter	In	Required	Default	Description
`note_id`	path	yes	—	Context note UUID.

curl "$BASE_URL/knowledge/context/note_c3d4..." \
  -H "Authorization: Bearer $TOKEN"

Update a note

Partially update a context note in place (the note keeps its ID). Only fields present in the request body are modified. Omitting scope/scope_id leaves them unchanged; passing them explicitly (even as null) overwrites them.

PATCH /knowledge/context/{note_id}

Parameter	In	Required	Default	Description
`note_id`	path	yes	—	Context note UUID.
`text`	body	no	—	Replacement note content.
`title`	body	no	—	Replacement title (non-empty; ≤ 120 chars).
`kind`	body	no	—	Replacement kind.
`activation`	body	no	—	Change activation. Setting `always`/`on_demand` (or editing the text of a note that is already one of those) triggers the safety screen.
`scope`	body	no	—	Move the note to a different scope (`global` or `ontology`).
`scope_id`	body	no	—	Move to a different ontology. Pass `null` with `scope: "global"` to clear the binding.

curl -X PATCH "$BASE_URL/knowledge/context/note_c3d4..." \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Prefer level-125 (meta PvP) builds unless the user asks otherwise." }'

Delete a note

Permanently delete a context note.

DELETE /knowledge/context/{note_id}

Parameter	In	Required	Default	Description
`note_id`	path	yes	—	Context note UUID.

curl -X DELETE "$BASE_URL/knowledge/context/note_c3d4..." \
  -H "Authorization: Bearer $TOKEN"

{
  "status": "success",
  "message": "Context note deleted",
  "data": null
}

Search

Semantic search

Run a vector similarity search over context notes. Returns notes ranked by semantic relevance to the query string, each annotated with a similarity score.

POST /knowledge/context/search

Parameter	In	Required	Default	Description
`scope`	query	yes	—	`global` or `ontology`.
`scope_id`	query	no	—	The ontology ID. Required when `scope` is `ontology`.
`kinds`	query	no	—	Comma-separated kind filter.
`top_k`	query	no	`10`	Maximum number of results to return (1–100).
`query`	body	yes	—	The natural-language search string to embed and match against.

curl -X POST "$BASE_URL/knowledge/context/search?scope=ontology&scope_id=$ONTOLOGY_ID&top_k=5" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "query": "spell family requirement floors" }'

{
  "status": "success",
  "message": "Context notes searched",
  "data": [
    {
      "id": "note_c3d4...",
      "kind": "fact",
      "title": "Death family requirements",
      "text": "The Death sorcery family caps at INT 42 / FAI 30.",
      "score": 0.91,
      "activation": "retrieved",
      "source": "user"
    }
  ]
}

Ingestion

Ingest a file as context

Parse and chunk an already-uploaded file into context notes. The file must first be uploaded via POST /data/files/upload, which returns a disk/<name> path to pass here. The ingestion pipeline extracts text, splits it into chunks, embeds each chunk, and persists them as document_chunk notes tied back to a shared document_id. If the embedding service is unavailable the file is still stored as a single un-vectorized note.

POST /knowledge/context/from-file

Parameter	In	Required	Default	Description
`scope`	body	no	`"global"`	`global` or `ontology`.
`scope_id`	body	no	—	The ontology ID. Required when `scope` is `ontology`.
`file_path`	body	yes	—	The `disk/<name>` path returned by the file-upload endpoint.

curl -X POST "$BASE_URL/knowledge/context/from-file" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "ontology",
    "scope_id": "28b8678395e",
    "file_path": "disk/data_dictionary_v3.pdf"
  }'

{
  "status": "success",
  "message": "File ingested as context notes",
  "data": {
    "document_id": "doc_e5f6...",
    "filename": "data_dictionary_v3.pdf",
    "chunk_count": 14,
    "persisted": 14,
    "scope": "ontology",
    "scope_id": "28b8678395e"
  }
}

Returns 422 Unprocessable Entity when the file is readable but no text can be extracted — the most common cause is a scanned PDF without an OCR layer.

Auto-seed from data sources

Profile connected data sources and automatically write observation notes into the Context Layer. The platform inspects schemas, samples, and statistics for each source and uses the LLM to generate structured observations. This endpoint returns a streaming NDJSON response. Each line is a JSON object with a type field describing the event.

POST /knowledge/auto-seed

Parameter	In	Required	Default	Description
`scope`	body	no	`"ontology"`	`global` or `ontology`.
`scope_id`	body	no	—	The ontology ID. Required when `scope` is `ontology`.
`datasource_ids`	body	no	—	Array of data source IDs to profile. Omit to profile all connected sources.

curl -X POST "$BASE_URL/knowledge/auto-seed" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "ontology",
    "scope_id": "28b8678395e",
    "datasource_ids": ["ds_aaa", "ds_bbb"]
  }'

Each NDJSON line follows this shape:

// Source profiling started
{ "type": "source_started", "data": { "datasource_id": "ds_aaa", "name": "prod_warehouse" } }

// A note was written to the Context Layer
{ "type": "note_written", "data": { "note_id": "note_g7h8...", "kind": "observation", "text": "..." } }

// All sources processed
{ "type": "done", "data": { "notes_written": 12 } }

// Error (stream remains open; partial results may have been written)
{ "type": "error", "data": { "error": "Connection to ds_bbb timed out" } }

Project document

Render project document

Return a combined document view for a project: an LLM-generated natural-language summary alongside the full executable Vadalog program assembled from all concepts. The summary is cached and is automatically invalidated when concepts or context notes change. Pass refresh=true to force regeneration regardless of the cache state.

GET /knowledge/ontology/{ontology_id}/text

Parameter	In	Required	Default	Description
`ontology_id`	path	yes	—	The ontology ID.
`refresh`	query	no	`false`	Bypass the summary cache and regenerate unconditionally.

curl "$BASE_URL/knowledge/ontology/$ONTOLOGY_ID/text" \
  -H "Authorization: Bearer $TOKEN"

{
  "status": "success",
  "message": "Project document rendered",
  "data": {
    "summary": "This project computes monthly revenue by region...",
    "vadalog_text": "@input(\"orders\").\n@output(\"revenue_by_region\").\nrevenue_by_region(R, sum<V>) <- orders(_, R, V, _).",
    "cached": true,
    "generated_at": "2026-06-24T08:30:00+00:00"
  }
}

Introduction

Get Started

Platform

Integrations

Examples

Vadalog Reference

Resources

Note fields

Activation

Context notes

List notes

Create a note

Get a note

Update a note

Delete a note

Search

Semantic search

Ingestion

Ingest a file as context

Auto-seed from data sources

Project document

Render project document

​Note fields

​Activation

​Context notes

​List notes

​Create a note

​Get a note

​Update a note

​Delete a note

​Search

​Semantic search

​Ingestion

​Ingest a file as context

​Auto-seed from data sources

​Project document

​Render project document

Note fields

Activation

Context notes

List notes

Create a note

Get a note

Update a note

Delete a note

Search

Semantic search

Ingestion

Ingest a file as context

Auto-seed from data sources

Project document

Render project document