Knowledge

Knowledge is what the agent is told before it starts. Findings are the output of a run; knowledge is the input to every run after it. An entry written once applies to everything that follows.

The knowledge entry object

Entry types

A closed set, because the type decides how the entry is presented to the agent. "Accepted risks" and "testing rules" read very differently in a run instruction, and free-form tags would make that grouping meaningless.

manual versus internal

manual entries are yours. internal entries are written by the agent from its own notes after a run. Both feed the next run identically — the distinction is provenance and editability: an internal entry cannot be edited or replaced, only deleted. Attempting to update one returns 409 knowledge_entry_not_editable.

List entries

GET /knowledge · scope knowledge:read · role viewer

curl "https://api.vulnix.dev/knowledge?source=manual" \
  -H "Authorization: Bearer $VULNIX_TOKEN"

{ "entries": [] }

Create an entry

POST /knowledge · scope knowledge:write · role admin · returns 201

curl -X POST https://api.vulnix.dev/knowledge \
  -H "Authorization: Bearer $VULNIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entry_type": "business_logic",
    "description": "Tenancy is enforced on the X-Org header, not the JWT. A member of org A presented with org B in that header must get 403, never data.",
    "domain_ids": ["01M2NMSF7GJY6KMMKZJ0EA0N47"]
  }'

Returns the created entry. An unknown entry_type, a blank description, or one over the limit returns 422 invalid_knowledge_entry.

Update an entry

PATCH /knowledge/{entry_id} · scope knowledge:write · role admin

Takes the same body as create. Returns the updated entry.

404 knowledge_entry_not_found for an unknown id; 409 knowledge_entry_not_editable for an internal entry.

Delete an entry

DELETE /knowledge/{entry_id} · scope knowledge:write · role admin · returns 204

No response body. Works for both manual and internal entries — deleting is how you retract something the agent concluded and got wrong.