Knowledge Context API

ReferenceAdministratorAutomation authorSecurity

Key points

Kind is not a label: guardrail and policy documents validate direct scripts before execution, while the other kinds only inform the prompt.
Storing a blocking guardrail is an enforcement change, not a documentation change.
A connection imports documents; it does not give a run live access to the provider.
Deleting a document a pipeline requires answers 409 rather than breaking the run.
Disabling a connection stops imports while leaving already-imported documents working.
Resolve a page before importing it: the preview shows exactly which document a URL becomes.
The knowledge-connections paths are compatibility aliases for knowledge-context-connections.

Operations

GET/v1/knowledge-contextsAuthorized

Lists knowledge documents the caller can see.

Notes

Kind is not a label. guardrail and policy documents participate in script validation; the other kinds only inform the prompt.

Parameters

Name	In	Type	Required	Description
`team_path`	query	string	Optional	Restrict to documents owned by one team path.
`kind`	query	string	Optional	Restrict to one document kind.Allowed: architecture, guardrail, policy, adr, guideline, runbook, reference, example

Call it

List knowledge documentsapi-knowledge-context request

curl -s -H "Authorization: Bearer $NOPSAI_TOKEN" "$NOPSAI_URL/v1/knowledge-contexts?kind=guardrail" | jq '.[] | {id, kind, team}'

Result

Documents the caller may see, filtered per caller by AAA.

Responses

200application/json

Knowledge documents.

[{
  "id": "platform/release-notes",
  "kind": "policy",
  "title": "Release notes policy",
  "team": "platform",
  "source": "config_repo",
  "updated_at": "2026-08-18T15:41:02Z"
}]

When it fails

Status	Cause	What to do
503	Authorization is unavailable, so the list cannot be filtered.	Check AAA.
500	The query failed.	Platform fault.

Side effects

None.

Proven by

services/nopsai/knowledge_connections_test.go
services/nopsai/knowledge_context.go
doc/knowledge-context.md

GET/v1/knowledge-contexts/{knowledgeID...}Authorized

Reads one knowledge document.

Parameters

Name	In	Type	Required	Description
`knowledgeID`	path	string	Required	Document identifier. A catch-all segment, so a team-prefixed id with slashes is passed as-is.

Call it

Read a knowledge documentapi-knowledge-context request

curl -s -H "Authorization: Bearer $NOPSAI_TOKEN" "$NOPSAI_URL/v1/knowledge-contexts/platform/release-notes" | jq

Result

The document with its kind, content, and provenance.

Responses

200application/json

The document.

{
  "id": "platform/release-notes",
  "kind": "policy",
  "title": "Release notes policy",
  "team": "platform",
  "source": "config_repo",
  "updated_at": "2026-08-18T15:41:02Z"
}

When it fails

Status	Cause	What to do
400	The identifier is empty or malformed.	Use an id from the list route.
404	No document with that id.	Check the team prefix.
409	The document is mid-import from a provider connection.	Wait for the import to finish and read again.
500	The document could not be loaded.	Platform fault.

Side effects

None.

Proven by

services/nopsai/knowledge_connections_test.go
services/nopsai/knowledge_context.go

PUT/v1/knowledge-contexts/{knowledgeID...}Authorized

Creates or replaces a knowledge document.

Notes

Storing a blocking guardrail is an enforcement change, not a documentation change: scripts under it are validated before they execute.

Parameters

Name	In	Type	Required	Description
`knowledgeID`	path	string	Required	Document identifier to store under.

Call it

Store a policy documentapi-knowledge-context request

curl -sX PUT "$NOPSAI_URL/v1/knowledge-contexts/platform/release-notes" \
  -H "Authorization: Bearer $NOPSAI_TOKEN" \
  -H "Content-Type: application/json" \
  --data @knowledge.json | jq

Result

The stored document, available to the next run that references it.

Replace before running

knowledge.json carries the kind, title, and content.

Responses

200application/json

Document stored.

{
  "id": "platform/release-notes",
  "kind": "policy",
  "title": "Release notes policy",
  "team": "platform",
  "source": "config_repo",
  "updated_at": "2026-08-18T15:41:02Z"
}

When it fails

Status	Cause	What to do
400	An unknown kind or missing content.	Kind must be one of the eight documented values.
404	The owning team does not exist.	Check the team prefix in the identifier.
409	The document is managed by a provider connection.	Edit it at the provider, or detach the connection first.
500	The document could not be stored.	Retry.

Side effects

A guardrail or policy document changes what scripts are allowed to run for pipelines that reference it.
Editing a GitOps-managed document creates drift until it is pushed or discarded.
Writes an audit record.

Proven by

services/nopsai/knowledge_connections_test.go
services/nopsai/knowledge_context.go
doc/knowledge-context.md

POST/v1/knowledge-contexts/{knowledgeID...}Authorized

Runs an action against one knowledge document, such as refreshing it from its provider.

Parameters

Name	In	Type	Required	Description
`knowledgeID`	path	string	Required	Document identifier.

Call it

Refresh a document from its providerapi-knowledge-context request

curl -sX POST "$NOPSAI_URL/v1/knowledge-contexts/platform/release-notes" \
  -H "Authorization: Bearer $NOPSAI_TOKEN" \
  -H "Content-Type: application/json" \
  --data @action.json | jq

Result

The document after the action. Which actions apply depends on whether it is connection-backed.

Replace before running

action.json names the action, for example a refresh from the connected provider.

Responses

200application/json

The document after the action.

{
  "id": "platform/release-notes",
  "kind": "policy",
  "title": "Release notes policy",
  "team": "platform",
  "source": "config_repo",
  "updated_at": "2026-08-18T15:41:02Z"
}

When it fails

Status	Cause	What to do
400	An unknown action, or one that does not apply to this document.	A locally authored document cannot be refreshed from a provider.
404	No document with that id.	Confirm the id.
500	The action failed.	Retry; a provider refresh makes a real call.

Side effects

A refresh replaces the stored content from the provider and records the import.

Proven by

services/nopsai/knowledge_context_external_sync_test.go
services/nopsai/knowledge_context.go

DELETE/v1/knowledge-contexts/{knowledgeID...}Authorized

Deletes a knowledge document.

Parameters

Name	In	Type	Required	Description
`knowledgeID`	path	string	Required	Document to delete.

Call it

Delete a knowledge documentapi-knowledge-context request

curl -sX DELETE -H "Authorization: Bearer $NOPSAI_TOKEN" "$NOPSAI_URL/v1/knowledge-contexts/platform/release-notes" -w "%{http_code}\n"

Result

204, unless it is required by a pipeline that references it.

Responses

204

Document deleted.

When it fails

Status	Cause	What to do
400	The identifier is empty.	Name the document.
404	No document with that id.	It may already be deleted.
409	The document is provider-managed or still required.	Detach the connection, or remove the `required: true` reference from the pipelines that need it.
500	The delete failed.	Retry.

Side effects

A pipeline that references the document with required: true fails until the reference is removed.
Writes an audit record.

Proven by

services/nopsai/knowledge_connections_test.go
services/nopsai/knowledge_context.go

GET/v1/knowledge-context-connectionsAuthorized

Lists provider connections.

Notes

A connection is a link to an external wiki. It imports documents; it does not give a run live access to the provider.

Parameters

Name	In	Type	Required	Description
`team_path`	query	string	Optional	Restrict to one team’s connections.

Call it

List provider connectionsapi-knowledge-context request

curl -s -H "Authorization: Bearer $NOPSAI_TOKEN" "$NOPSAI_URL/v1/knowledge-context-connections" | jq '.[] | {id, provider, disabled}'

Result

Each connection with its provider and base URL. The credential is a reference, never a value.

Responses

200application/json

Connections visible to the caller.

[{
  "id": "platform/confluence",
  "team": "platform",
  "name": "confluence",
  "display_name": "Confluence",
  "provider": "confluence",
  "base_url": "https://wiki.example.com",
  "credential_ref": "platform/confluence",
  "disabled": false
}]

When it fails

Status	Cause	What to do
503	Authorization is unavailable.	Check AAA.
500	The query failed.	Platform fault.

Side effects

None.

Proven by

services/nopsai/knowledge_connections_test.go
services/nopsai/knowledge_connections.go

POST/v1/knowledge-context-connectionsAuthorized

Creates a provider connection.

Call it

Connect a wikiapi-knowledge-context request

curl -sX POST "$NOPSAI_URL/v1/knowledge-context-connections" \
  -H "Authorization: Bearer $NOPSAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"team":"platform","name":"confluence","provider":"confluence","base_url":"https://wiki.example.com","credential_ref":"platform/confluence"}' | jq -r .id

Result

The connection id. Test it before importing anything.

Responses

201application/json

Connection created.

{
  "id": "platform/confluence",
  "team": "platform",
  "name": "confluence",
  "display_name": "Confluence",
  "provider": "confluence",
  "base_url": "https://wiki.example.com",
  "credential_ref": "platform/confluence",
  "disabled": false
}

When it fails

Status	Cause	What to do
400	An unknown provider, a missing base URL, or an unresolvable credential.	The message names the field.

Side effects

Creates a link the platform can import from.
Writes an audit record.

Proven by

services/nopsai/knowledge_connections_test.go
services/nopsai/knowledge_connections_gitops_test.go
services/nopsai/knowledge_connections.go

GET/v1/knowledge-context-connections/{connectionID...}Authorized

Reads one provider connection.

Notes

The identifier is a catch-all segment, so a team-prefixed id with slashes needs no encoding.

Parameters

Name	In	Type	Required	Description
`connectionID`	path	string	Required	Connection identifier, including its team prefix.

Call it

Read a connectionapi-knowledge-context request

curl -s -H "Authorization: Bearer $NOPSAI_TOKEN" "$NOPSAI_URL/v1/knowledge-context-connections/platform/confluence" | jq

Result

Provider, base URL, scopes, and configuration.

Responses

200application/json

The connection.

{
  "id": "platform/confluence",
  "team": "platform",
  "name": "confluence",
  "display_name": "Confluence",
  "provider": "confluence",
  "base_url": "https://wiki.example.com",
  "credential_ref": "platform/confluence",
  "disabled": false
}

Side effects

None.

Proven by

services/nopsai/knowledge_connections_test.go
services/nopsai/knowledge_connections.go

PUT/v1/knowledge-context-connections/{connectionID...}Authorized

Replaces a provider connection.

Parameters

Name	In	Type	Required	Description
`connectionID`	path	string	Required	Connection to replace.

Call it

Replace a connectionapi-knowledge-context request

curl -sX PUT "$NOPSAI_URL/v1/knowledge-context-connections/platform/confluence" \
  -H "Authorization: Bearer $NOPSAI_TOKEN" \
  -H "Content-Type: application/json" \
  --data @connection.json | jq

Result

The stored connection. Documents already imported keep their content.

Replace before running

A PUT replaces the whole document; omitted fields are cleared.

Responses

200application/json

Connection stored.

{
  "id": "platform/confluence",
  "team": "platform",
  "name": "confluence",
  "display_name": "Confluence",
  "provider": "confluence",
  "base_url": "https://wiki.example.com",
  "credential_ref": "platform/confluence",
  "disabled": false
}

When it fails

Status	Cause	What to do
400	An invalid provider, URL, or credential reference.	The message names the field.

Side effects

Changes where future imports read from.
Writes an audit record.

Proven by

services/nopsai/knowledge_connections_test.go
services/nopsai/knowledge_connections.go

PATCH/v1/knowledge-context-connections/{connectionID...}Authorized

Partially updates a provider connection.

Notes

Disable rather than delete while investigating: the imported documents keep working while the link is paused.

Parameters

Name	In	Type	Required	Description
`connectionID`	path	string	Required	Connection to update.

Call it

Disable a connectionapi-knowledge-context request

curl -sX PATCH "$NOPSAI_URL/v1/knowledge-context-connections/platform/confluence" \
  -H "Authorization: Bearer $NOPSAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"disabled":true}' | jq '{id, disabled}'

Result

Imports stop; documents already imported stay available to runs.

Responses

200application/json

Connection updated.

{
  "id": "platform/confluence",
  "team": "platform",
  "name": "confluence",
  "display_name": "Confluence",
  "provider": "confluence",
  "base_url": "https://wiki.example.com",
  "credential_ref": "platform/confluence",
  "disabled": false
}

When it fails

Status	Cause	What to do
400	A supplied field is invalid.	The message names the field.

Side effects

Disabling stops imports without removing imported documents.
Writes an audit record.

Proven by

services/nopsai/knowledge_connections_test.go
services/nopsai/knowledge_connections.go

DELETE/v1/knowledge-context-connections/{connectionID...}Authorized

Deletes a provider connection.

Parameters

Name	In	Type	Required	Description
`connectionID`	path	string	Required	Connection to delete.

Call it

Delete a connectionapi-knowledge-context request

curl -sX DELETE -H "Authorization: Bearer $NOPSAI_TOKEN" "$NOPSAI_URL/v1/knowledge-context-connections/platform/confluence" -w "%{http_code}\n"

Result

204, unless documents imported through it still depend on it.

Responses

204

Connection deleted.

When it fails

Status	Cause	What to do
404	No connection with that id.	It may already be deleted.
409	Documents imported through this connection still reference it.	Detach or delete those documents first.
500	The delete failed.	Retry.

Side effects

Writes an audit record.

Proven by

services/nopsai/knowledge_connections_test.go
services/nopsai/knowledge_connections.go

POST/v1/knowledge-context-connections/{connectionID...}Authorized

Runs an action against a connection addressed by a nested identifier.

Parameters

Name	In	Type	Required	Description
`connectionID`	path	string	Required	Connection identifier.

Call it

Post an action to a connectionapi-knowledge-context request

curl -sX POST "$NOPSAI_URL/v1/knowledge-context-connections/platform/confluence" \
  -H "Authorization: Bearer $NOPSAI_TOKEN" \
  -H "Content-Type: application/json" \
  --data @action.json | jq

Result

The connection after the action.

Replace before running

action.json names the action to run against the connection.

Responses

200application/json

The connection after the action.

{
  "id": "platform/confluence",
  "team": "platform",
  "name": "confluence",
  "display_name": "Confluence",
  "provider": "confluence",
  "base_url": "https://wiki.example.com",
  "credential_ref": "platform/confluence",
  "disabled": false
}

When it fails

Status	Cause	What to do
400	An unknown action or malformed body.	The dedicated `/test` and `/resolve-page` routes cover the common cases.

Side effects

Depends on the action; a provider call may be made.

Proven by

services/nopsai/knowledge_connections_test.go
services/nopsai/knowledge_connections.go

POST/v1/knowledge-context-connections/{connectionID}/testAuthorized

Tests a connection against its provider.

Parameters

Name	In	Type	Required	Description
`connectionID`	path	string	Required	Connection to test.

Call it

Test a connectionapi-knowledge-context request

curl -sX POST -H "Authorization: Bearer $NOPSAI_TOKEN" "$NOPSAI_URL/v1/knowledge-context-connections/$CONNECTION_ID/test" | jq

Result

A real provider call, without importing or storing a document.

Responses

200application/json

The provider answered.

{ "ok": true, "provider": "confluence" }

When it fails

Status	Cause	What to do
400	The connection is incomplete or disabled.	Finish configuring it first.
404	No connection with that id.	Confirm the id.
502	The provider rejected the call or could not be reached.	Usually an expired credential or blocked egress.

Side effects

Makes one real provider call. Stores nothing.

Proven by

services/nopsai/knowledge_connections_test.go
services/nopsai/knowledge_connections.go

POST/v1/knowledge-context-connections/{connectionID}/resolve-pageAuthorized

Resolves a provider page reference to the document it would import.

Notes

Resolve before importing: it shows exactly which document a URL turns into, including its title and page id.

Parameters

Name	In	Type	Required	Description
`connectionID`	path	string	Required	Connection identifier.

Call it

Preview what a page would import asapi-knowledge-context request

curl -sX POST "$NOPSAI_URL/v1/knowledge-context-connections/$CONNECTION_ID/resolve-page" \
  -H "Authorization: Bearer $NOPSAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://wiki.example.com/display/PLAT/Release+policy"}' | jq

Result

The page and the document it maps to — a preview, not an import.

Responses

200application/json

The resolved page.

{
  "external_page_id": "482991",
  "title": "Release policy",
  "url": "https://wiki.example.com/display/PLAT/Release+policy"
}

When it fails

Status	Cause	What to do
400	A missing or unparseable page reference.	Send the provider URL or page id.
404	No connection with that id, or the page does not exist.	Confirm both.
502	The provider could not be reached.	Test the connection.

Side effects

Makes one provider call. Imports nothing.

Proven by

services/nopsai/knowledge_context_external_sync_test.go
services/nopsai/knowledge_connections.go

GET/v1/knowledge-context-connections/{connectionID}/pages/searchAuthorized

Searches pages available through a connection.

Parameters

Name	In	Type	Required	Description
`connectionID`	path	string	Required	Connection identifier.
`q`	query	string	Required	Search text passed to the provider.

Call it

Search a connected wikiapi-knowledge-context request

curl -s -H "Authorization: Bearer $NOPSAI_TOKEN" "$NOPSAI_URL/v1/knowledge-context-connections/$CONNECTION_ID/pages/search?q=release" | jq

Result

Matching pages with their ids, so one can be resolved and imported.

Responses

200application/json

Matching pages.

[
  { "external_page_id": "482991", "title": "Release policy" }
]

When it fails

Status	Cause	What to do
400	A missing search term.	Send `q`.
404	No connection with that id.	Confirm the id.
502	The provider search failed.	Test the connection.

Side effects

Makes one provider call.

Proven by

services/nopsai/knowledge_connections_test.go
services/nopsai/knowledge_connections.go

GET/v1/knowledge-connectionsAuthorized

Compatibility path for listing provider connections.

Notes

Same handler as /v1/knowledge-context-connections; prefer that form.

POST/v1/knowledge-connectionsAuthorized

Compatibility path for creating a provider connection.

Notes

Same handler as the knowledge-context-connections form.

GET/v1/knowledge-connections/{connectionID...}Authorized

Compatibility path for reading a connection.

Notes

Same handler as the knowledge-context-connections form.

PUT/v1/knowledge-connections/{connectionID...}Authorized

Compatibility path for replacing a connection.

Notes

Same handler as the knowledge-context-connections form.

PATCH/v1/knowledge-connections/{connectionID...}Authorized

Compatibility path for partially updating a connection.

Notes

Same handler as the knowledge-context-connections form.

POST/v1/knowledge-connections/{connectionID...}Authorized

Compatibility path for connection actions.

Notes

Same handler as the knowledge-context-connections form.

DELETE/v1/knowledge-connections/{connectionID...}Authorized

Compatibility path for deleting a connection.

Notes

Same handler as the knowledge-context-connections form.

POST/v1/knowledge-connections/{connectionID}/testAuthorized

Compatibility path for testing a connection.

Notes

Same handler as the knowledge-context-connections form.

GET/v1/knowledge-connections/{connectionID}/pagesAuthorized

Lists pages available through a connection.

Notes

Browsing is the alternative to searching when you do not know the page title yet. Neither imports anything.

Parameters

Name	In	Type	Required	Description
`connectionID`	path	string	Required	Connection identifier.
`limit`	query	integer	Optional	How many pages to return.

Call it

Browse a connected wikiapi-knowledge-context request

curl -s -H "Authorization: Bearer $NOPSAI_TOKEN" "$NOPSAI_URL/v1/knowledge-connections/$CONNECTION_ID/pages" | jq

Result

Pages the connection exposes, for picking one to resolve and import.

Responses

200application/json

Available pages.

[
  { "external_page_id": "482991", "title": "Release policy" }
]

When it fails

Status	Cause	What to do
404	No connection with that id.	List the connections.
502	The provider could not be reached.	Test the connection.

Side effects

Makes one provider call.

Proven by

services/nopsai/knowledge_connections_test.go
services/nopsai/knowledge_connections.go

POST/v1/knowledge-connections/{connectionID}/resolve-pageAuthorized

Compatibility path for resolving a provider page.

Notes

Same handler as the knowledge-context-connections form.

How it works

The two halves answer different questions. A knowledge document is content the platform governs and merges into an LLM task context. A connection is a link to somewhere that content lives, used at import time only — so revoking a connection never removes what a run already depends on.

Guardrail and policy documents are the reason this area belongs in a security review. They participate in script validation, which means adding one narrows what pipelines under it may execute, and removing one widens it.

Import in three steps rather than one: search for the page, resolve it to see the document it becomes, then import. Each step makes exactly one provider call and stores nothing until the last.

Implementation evidence

services/nopsai/knowledge_context.go
Document storage, kinds, and lifecycle.
services/nopsai/knowledge_connections.go
Provider connections, test, resolve, and search.
doc/knowledge-context.md
Document kinds, merging, GitOps layout, and access checks.

Platform

Use cases

Resources

Company

Knowledge Context API

Key points

Operations

Notes

Parameters

Call it

Responses

When it fails

Side effects

Proven by

Parameters

Call it

Responses

When it fails

Side effects

Proven by

Notes

Parameters

Call it

Responses

When it fails

Side effects

Proven by

Parameters

Call it

Responses

When it fails

Side effects

Proven by

Parameters

Call it

Responses

When it fails

Side effects

Proven by

Notes

Parameters

Call it

Responses

When it fails

Side effects

Proven by

Call it

Responses

When it fails

Side effects

Proven by

Notes

Parameters

Call it

Responses

Side effects

Proven by

Parameters

Call it

Responses

When it fails

Side effects

Proven by

Notes

Parameters

Call it

Responses

When it fails

Side effects

Proven by

Parameters

Call it

Responses

When it fails

Side effects

Proven by

Parameters

Call it

Responses

When it fails