Knowledge

The knowledge store is a domain-scoped key-value store backed by PostgreSQL JSONB. Each entry has a domain, a key, arbitrary JSON data and optional tags.

All endpoints require authentication and builder access (superadmin or a user holding the engineer role). Members reach knowledge content through escalation lookup refs: see Lookups and GET /api/escalations/:id/lookups.

List domains

GET /api/knowledge/domains

Returns all knowledge domains with entry counts and last-updated timestamps.

Example request

curl https://lt.acme.dev/api/knowledge/domains \
  -H "Authorization: Bearer $LT_TOKEN"

Response 200

{
  "domains": [
    { "domain": "screenshot", "count": 3, "latest": "2026-05-09T22:26:51.616Z" },
    { "domain": "config", "count": 1, "latest": "2026-05-08T10:00:00.000Z" }
  ]
}

List entries

GET /api/knowledge/entries

Returns entries within a domain, ordered by last updated.

Query parameters

Parameter	Type	Required	Description
domain	string	Yes	Domain to query
search	string	No	Search by key name or tag (ILIKE partial match)
tags	string	No	Comma-separated tag filter (array overlap)
limit	number	No	Max results (default: 50, max: 200)
offset	number	No	Pagination offset

Example request

curl "https://lt.acme.dev/api/knowledge/entries?domain=screenshot&search=acme&tags=web&limit=50&offset=0" \
  -H "Authorization: Bearer $LT_TOKEN"

Response 200

{
  "entries": [
    {
      "id": "uuid",
      "domain": "screenshot",
      "key": "acme",
      "data": { "2026-05-09": "description..." },
      "tags": ["web"],
      "created_at": "2026-05-09T22:26:51.616Z",
      "updated_at": "2026-05-09T22:26:51.616Z"
    }
  ],
  "total": 1
}

Get entry

GET /api/knowledge/entry

Returns a single knowledge entry by domain and key, or { found: false } when none exists. With version, returns that immutable edition from the version history instead of the live entry.

Query parameters

Parameter	Type	Required	Description
domain	string	Yes	Domain
key	string	Yes	Entry key
version	integer	No	Fetch this immutable edition instead of the live entry

Example request

curl "https://lt.acme.dev/api/knowledge/entry?domain=screenshot&key=acme" \
  -H "Authorization: Bearer $LT_TOKEN"

Response 200

{
  "id": "uuid",
  "domain": "screenshot",
  "key": "acme",
  "data": { "2026-05-09": "The Acme homepage..." },
  "tags": [],
  "created_at": "2026-05-09T22:26:51.616Z",
  "updated_at": "2026-05-09T22:26:51.616Z"
}

List entry versions

GET /api/knowledge/entry/versions

Every data-changing write mints an immutable edition. This lists them newest first, with the current one marked.

Query parameters

Parameter	Type	Required	Description
domain	string	Yes	Domain
key	string	Yes	Entry key

Example request

curl "https://lt.acme.dev/api/knowledge/entry/versions?domain=catalog&key=materials" \
  -H "Authorization: Bearer $LT_TOKEN"

Response 200

{
  "domain": "catalog",
  "key": "materials",
  "versions": [
    { "version": 2, "change_summary": null, "created_at": "...", "is_current": true },
    { "version": 1, "change_summary": null, "created_at": "...", "is_current": false }
  ]
}

Store entry

POST /api/knowledge/entry

Creates or updates a knowledge entry. By default the JSONB data merges at the top level: new keys are added, existing keys are overwritten and absent keys are kept. Set replace: true to replace the data object entirely (required when removing fields).

Request body

Field	Type	Required	Description
domain	string	Yes	Domain
key	string	Yes	Entry key
data	object	Yes	JSONB data (top level must be an object)
tags	string[]	No	Tags are unioned with existing tags on upsert
replace	boolean	No	When true, replaces data entirely instead of merging

Example request

curl -X POST https://lt.acme.dev/api/knowledge/entry \
  -H "Authorization: Bearer $LT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "screenshot",
    "key": "acme",
    "data": { "2026-05-09": "The Acme homepage..." },
    "tags": ["web"],
    "replace": false
  }'

Response 200

{
  "id": "uuid",
  "domain": "screenshot",
  "key": "acme",
  "created": false,
  "updated_at": "2026-05-09T22:26:51.616Z"
}

Set field (nested path)

PUT /api/knowledge/field

Sets a value at a specific JSONB path and leaves sibling fields in place. Use dot notation for nested paths. Creates the entry when it does not exist.

Request body

Field	Type	Required	Description
domain	string	Yes	Domain
key	string	Yes	Entry key
path	string	Yes	Dot-notation path (e.g. acme.holiday, config.retries)
value	any	Yes	Value to set at that path (any JSON type)
tags	string[]	No	Tags to union with existing

Example request

curl -X PUT https://lt.acme.dev/api/knowledge/field \
  -H "Authorization: Bearer $LT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "research",
    "key": "screenshots",
    "path": "acme.holiday",
    "value": "Holiday banner with flowers",
    "tags": ["screenshot"]
  }'

Response 200

{ "id": "uuid", "domain": "research", "key": "screenshots", "created": false, "updated_at": "..." }

Remove field

DELETE /api/knowledge/field

Removes the field at a JSONB path. The entry stays; only the targeted path is deleted.

Query parameters

Parameter	Type	Required	Description
domain	string	Yes	Domain
key	string	Yes	Entry key
path	string	Yes	Dot-notation path to remove

Example request

curl -X DELETE "https://lt.acme.dev/api/knowledge/field?domain=research&key=screenshots&path=acme.legacy_data" \
  -H "Authorization: Bearer $LT_TOKEN"

Response 200

{ "removed": true }

Response 404: { "error": "Field not found" }

Delete entry

DELETE /api/knowledge/entry

Permanently deletes a knowledge entry.

Query parameters

Parameter	Type	Required	Description
domain	string	Yes	Domain
key	string	Yes	Entry key

Example request

curl -X DELETE "https://lt.acme.dev/api/knowledge/entry?domain=screenshot&key=acme" \
  -H "Authorization: Bearer $LT_TOKEN"

Response 200

{ "deleted": true, "domain": "screenshot", "key": "acme" }

Response 404

{ "error": "Entry not found" }