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"
    }
  ]
}

Full-text search

Match notes on their literal words rather than their meaning. Use it when you know the term you are looking for — a column name, an identifier, a piece of jargon — where semantic search would return things that are merely related.

GET /knowledge/context/fts

Parameter	In	Required	Default	Description
`q`	query	yes	—	The query, in web-search syntax: quoted phrases, `OR`, and `-` to exclude.
`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	`20`	Maximum results (1–100).

curl -G "$BASE_URL/knowledge/context/fts" \
  --data-urlencode 'q="sorcery family" -deprecated' \
  --data-urlencode "scope=ontology" \
  --data-urlencode "scope_id=$ONTOLOGY_ID" \
  -H "Authorization: Bearer $TOKEN"

Standing rules

Rules are the subset of notes that the assistant is expected to honour on every request, rather than retrieve when relevant — “always filter out test accounts”, “prefer the orders_v2 table”. This endpoint returns the ones in force.

GET /knowledge/context/rules

Parameter	In	Required	Default	Description
`ontology_id`	query	no	—	Include this ontology’s rules alongside the global ones. Omit for global rules only.

curl -G "$BASE_URL/knowledge/context/rules" \
  --data-urlencode "ontology_id=$ONTOLOGY_ID" \
  -H "Authorization: Bearer $TOKEN"

{
  "status": "success",
  "message": "User rules retrieved",
  "data": {
    "count": 1,
    "rules": [
      {
        "id": "note_9a1b...",
        "scope": "ontology",
        "activation": "always",
        "title": "Exclude test accounts",
        "text": "Never include accounts whose id starts with TEST_."
      }
    ]
  }
}

If you are building your own assistant on top of Prometheux, fetch these once per session and apply them to every request — that is what the built-in assistant does. They are the user’s standing instructions, so ignoring them is visible to the user as the assistant forgetting what it was told.

Links between notes

Notes can be linked to each other and to the things they describe — a concept, an ontology, a data source. A link is an edge: a typed, directed triple of source node, relation, and destination node. Edges are what makes a note about customer_churn show up on that concept’s Context tab. Edges are created two ways: deliberately, through the endpoint below, or implicitly, by writing a [[wikilink]] in a note’s text. The distinction is recorded in created_by — a wikilink edge is tied to its text anchor and disappears when the link text does, while a user edge lives on its own.

List edges

GET /knowledge/context/edges

Parameter	In	Required	Default	Description
`node_type`	query	no	—	`note`, `concept`, `ontology`, or `datasource`.
`node_id`	query	no	—	The node whose edges to list.

Returns edges in both directions, so backlinks are included. With no node filter it returns every edge in the workspace — which is how the notes page draws its graph view, and more than you want for anything else.

Create an edge

POST /knowledge/context/edges

Parameter	In	Required	Default	Description
`src_type`, `src_id`	body	yes	—	The source node.
`dst_type`, `dst_id`	body	yes	—	The destination node.
`relation`	body	no	`relates_to`	The relation name.
`created_by`	body	no	`user`	`user` or `wikilink`.

curl -X POST "$BASE_URL/knowledge/context/edges" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "src_type": "note",
    "src_id": "note_c3d4...",
    "dst_type": "concept",
    "dst_id": "28b8678395e:customer_churn",
    "relation": "describes"
  }'

Creating an edge that already exists is not an error — the existing edge is returned with 200, so repeating the call is safe.

A concept node’s ID is <ontology_id>:<predicate_name>, not the concept’s UUID.

Delete an edge

DELETE /knowledge/context/edges/{edge_id}

Notes attached to something

Returns the active notes linked to one non-note node, in either direction — everything the concept Context tab shows, in a single request rather than an edge listing followed by a fetch per note.

GET /knowledge/context/attached

Parameter	In	Required	Default	Description
`node_type`	query	yes	—	`concept`, `ontology`, or `datasource`.
`node_id`	query	yes	—	The node ID. Concepts use `<ontology_id>:<predicate_name>`.

curl -G "$BASE_URL/knowledge/context/attached" \
  --data-urlencode "node_type=concept" \
  --data-urlencode "node_id=28b8678395e:customer_churn" \
  -H "Authorization: Bearer $TOKEN"

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" } }

From notes to concepts

Two read-only endpoints that help turn written knowledge into Vadalog. Neither creates anything: both hand back the material for a concept, which you then author with POST /concepts/{ontology_id}/save.

Extract concept candidates from a document

Runs an extraction pass over a document already ingested with /knowledge/context/from-file and returns the concepts it suggests — each with a name, a description, and the snippet it came from — checked against the concepts the project already has.

POST /knowledge/context/extract-concepts

Parameter	In	Required	Default	Description
`document_id`	body	yes	—	The `document_id` returned by the ingestion endpoint.
`ontology_id`	body	no	—	The project to check existing concepts against.

curl -X POST "$BASE_URL/knowledge/context/extract-concepts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "document_id": "doc_e5f6...", "ontology_id": "28b8678395e" }'

The document must be ingested first — this endpoint works from stored chunks, not from a file path. Extraction is an LLM pass, so expect it to take seconds, not milliseconds.

Promote a note to a concept

Returns one note’s text alongside the project’s existing predicates, so a concept can be written from it with the names it should join against already in hand.

POST /knowledge/context/{note_id}/promote

Parameter	In	Required	Default	Description
`note_id`	path	yes	—	The note’s UUID.
`ontology_id`	body	yes	—	The project the concept would live in.

An unknown note ID returns 404; a note that holds nothing a concept could be built from returns 400.

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

Full-text search

Standing rules

Links between notes

List edges

Create an edge

Delete an edge

Notes attached to something

Ingestion

Ingest a file as context

Auto-seed from data sources

From notes to concepts

Extract concept candidates from a document

Promote a note to a concept

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

​Full-text search

​Standing rules

​Links between notes

​List edges

​Create an edge

​Delete an edge

​Notes attached to something

​Ingestion

​Ingest a file as context

​Auto-seed from data sources

​From notes to concepts

​Extract concept candidates from a document

​Promote a note to a concept

​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

Full-text search

Standing rules

Links between notes

List edges

Create an edge

Delete an edge

Notes attached to something

Ingestion

Ingest a file as context

Auto-seed from data sources

From notes to concepts

Extract concept candidates from a document

Promote a note to a concept

Project document

Render project document