---
title: "Apply Knowledge Run"
method: POST
path: "/api/v1/internal/knowledge/apply-run"
tags: ["internal", "internal-knowledge"]
---

# Apply Knowledge Run

`POST /api/v1/internal/knowledge/apply-run`

Apply one populate-knowledge run atomically (all-or-nothing).

Writes are confined to the request's workspace; every mutation carries the
run's provenance in its audit metadata, and a run-marker audit row advances
the refresh cursor. Any invalid item rolls back the whole run.

## Request body

- AdminKnowledgeApplyRunRequest — One populate-knowledge run, applied atomically to a single workspace. The item shapes (with title/content caps) are the domain run models; the audit actor is the authenticated internal caller, so the payload carries no admin id.
  - `workspace_id` string, uuid, required
  - `provenance` KnowledgeRunProvenance, required — Provenance stamped into every audit row a knowledge run writes. ``meetings_through`` is the refresh cursor: the latest source meeting a run ingested. A later run reads it back (``KnowledgeRunCursor``) to research only newer material.
    - `source` string
    - `run_at` string, date-time, required
    - `meetings_through` string, date-time, required
  - `creates` KnowledgeRunCreate[]
    - `scope` 'user' | 'workspace', required
    - `owner_id` string, uuid, required
    - `title` string, required
    - `content` string, required
  - `updates` KnowledgeRunUpdate[]
    - `entry_id` string, uuid, required
    - `title` string, required
    - `content` string, required
  - `deletes` KnowledgeRunDelete[]
    - `entry_id` string, uuid, required

## Response `200`

Successful Response

- AdminKnowledgeApplyRunResponse — What an applied run changed, plus the run-marker audit row's id.
  - `created` KnowledgeEntryResponse[], required
    - `id` string, uuid, required
    - `scope` 'user' | 'workspace' | 'project', required — Tier a knowledge entry applies to. Resolution is additive and ordered ``user -> workspace -> project`` — precedence is ordering only, not override (no shadowing in v1). "System" knowledge is the agent's existing system prompt — a separate, pre-existing mechanism that does not live in this table — so there is no ``system`` scope here. Project scope (MAIA-2547) is ambient: paths never name a project; the run's project id scopes reads and writes.
    - `user_id` string, uuid, nullable
    - `workspace_id` string, uuid, nullable
    - `project_id` string, uuid, nullable
    - `title` string, required
    - `content` string, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `is_core` boolean, required — Whether this is the reserved always-injected core entry (MAIA-2833).
  - `updated` KnowledgeEntryResponse[], required
    - `id` string, uuid, required
    - `scope` 'user' | 'workspace' | 'project', required — Tier a knowledge entry applies to. Resolution is additive and ordered ``user -> workspace -> project`` — precedence is ordering only, not override (no shadowing in v1). "System" knowledge is the agent's existing system prompt — a separate, pre-existing mechanism that does not live in this table — so there is no ``system`` scope here. Project scope (MAIA-2547) is ambient: paths never name a project; the run's project id scopes reads and writes.
    - `user_id` string, uuid, nullable
    - `workspace_id` string, uuid, nullable
    - `project_id` string, uuid, nullable
    - `title` string, required
    - `content` string, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `is_core` boolean, required — Whether this is the reserved always-injected core entry (MAIA-2833).
  - `deleted_ids` string[], required
  - `run_marker_id` string, uuid, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/maia-analytics/apis/maia-api.md) · [All operations](https://skmtc.net/maia-analytics/apis/maia-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/maia-analytics/maia-api/revisions/964b64b122c8/schema)