---
title: "Publish (upsert) a KB note from an external source"
method: POST
path: "/api/v4/workspaces/{workspace}/notes/sync"
tags: ["Knowledge Base"]
---

# Publish (upsert) a KB note from an external source

`POST /api/v4/workspaces/{workspace}/notes/sync`

Upsert a note identified by its sourceKind/source/sourceId. The content is the full markdown note with YAML frontmatter. dryRun=true validates without writing. Requires workspace admin. Synced notes become read-only in the CRUD API.

## Path parameters

- `workspace` string, required

## Request body

- NoteSyncRequestV4 — Publish (upsert) a KB note from an external source. Content is the full markdown note with YAML frontmatter.
  - `sourceKind` string — Origin type, e.g. "git"
  - `source` string, required — Origin/collection (e.g. repo URL)
  - `sourceId` string, required — Stable id within the source (e.g. file path)
  - `sourceRef` string, nullable — Version pointer (e.g. commit)
  - `sourceMetadata` object, nullable
  - `content` string, required — Markdown note with YAML frontmatter
  - `dryRun` boolean — Validate only; write nothing

## Response `200`

Sync result

- NoteSyncResponseV4 — Result of a note sync (upsert) operation.
  - `status` string — created | updated | unchanged | rejected
  - `applied` boolean
  - `ok` boolean
  - `noteId` string, nullable
  - `diagnostics` NoteDiagnosticV4[]
    - `level` string — "error" | "warning"
    - `code` string
    - `field` string, nullable
    - `message` string

---

[API](https://skmtc.dev/runwhen/apis/runwhen-platform-api.md) · [All operations](https://skmtc.dev/runwhen/apis/runwhen-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/runwhen/runwhen-platform-api/revisions/9d1a64d4b1c1/schema)