> ## Documentation Index > Fetch the complete documentation index at: https://developers.govworx.ai/llms.txt > Use this file to discover all available pages before exploring further. # Append Knowledge version > Add a new immutable version to an existing API-managed Knowledge entry. The version number is assigned automatically (previous + 1). **API-owned sections** (where the `apiControl` flag was set to true on create): Send the updated content. Full-overwrite semantics apply — whatever you send becomes the new version's content. Omitting a list, sending null, or sending `[]` sets that section to empty. Echo a `referenceId` from the previous version to update that item; omit the `referenceId` to add a new item. Supplying an unknown `referenceId` is rejected (400). **GovWorx-owned sections** (where the `apiControl` flag was false on create): Do NOT send content for these sections. GovWorx automatically carries the previous version's content forward. Sending content for a GovWorx-owned section is rejected (400). **Flag immutability:** `apiControl` is set once at creation — you do not need to resend it on append. Omitting it is recommended; the stored flags are used automatically. If you do include it, each flag must match the value set on create (400 if different). If `publish` is true (default), the new version is immediately published, replacing the previously published version. If the Knowledge entry has no previously published version, the new version becomes the first published one. ## OpenAPI ````yaml https://app.govworx.net/u/api-docs post /api/v1/external/knowledge/{knowledgeId}/versions openapi: 3.1.0 info: title: GovWorx Data API description: Interfaces to access data produced and organized by GovWorx Applications. termsOfService: http://swagger.io/terms/ version: '1.0' servers: - url: https://app.govworx.net security: [] tags: - name: TRAIN description: Training Phase and Enrollment Records - name: Audit Log Export description: Programmatically pull audit records into your SIEM solution - name: Knowledge description: >- Push and version guide cards and instruction cards into GovWorx from external systems (e.g., APCO, PowerPhone, IAED). ## Concepts **Knowledge entry:** A guide card or instruction card identified by a GovWorx-internal `id` and your partner-supplied `externalId`. Each entry carries one or more immutable versions. **Version:** An immutable snapshot of the guide card content created by `POST /` (create) or `POST /{knowledgeId}/versions` (append). Only one version is published (active) at a time. **Section ownership (`apiControl`):** A single top-level `apiControl` object on each request declares which sections are owned by the API and which are managed within GovWorx. API-owned sections are fully overwritten on every append. GovWorx-owned sections are editable inside GovWorx and carried forward automatically — do not include their content in append payloads. Flags are set once at creation and are immutable between versions. ## referenceId lifecycle GovWorx assigns a stable `referenceId` to every item in every content list on create. These identifiers are echoed back in the create/append response. **Store them.** On future appends, echo a `referenceId` to update the existing item in place. Omit the `referenceId` to add a new item (a fresh id is generated). Supplying an unknown `referenceId` — one not present in the previous version — is rejected (400). Reference id formats: `q-{8 hex}` (questions), `si-{8 hex}` (spoken instructions), `ca-{8 hex}` (CAD actions), `sms-{8 hex}` (SMS messages), `dt-{8 hex}` (dispatch triggers). ## Authentication All endpoints require a bearer token with the `Manage Knowledge` permission. - name: Incident description: Upload a new Incident to the system - name: MCP Resources description: MCP Resource endpoints for external integrations - name: Quality Assurance description: QA evaluation and feedback report endpoints - name: Users description: User Records externalDocs: description: GovWorx Developer Docs url: https://api.govworx.ai paths: /api/v1/external/knowledge/{knowledgeId}/versions: post: tags: - Knowledge summary: Append Knowledge version description: >- Add a new immutable version to an existing API-managed Knowledge entry. The version number is assigned automatically (previous + 1). **API-owned sections** (where the `apiControl` flag was set to true on create): Send the updated content. Full-overwrite semantics apply — whatever you send becomes the new version's content. Omitting a list, sending null, or sending `[]` sets that section to empty. Echo a `referenceId` from the previous version to update that item; omit the `referenceId` to add a new item. Supplying an unknown `referenceId` is rejected (400). **GovWorx-owned sections** (where the `apiControl` flag was false on create): Do NOT send content for these sections. GovWorx automatically carries the previous version's content forward. Sending content for a GovWorx-owned section is rejected (400). **Flag immutability:** `apiControl` is set once at creation — you do not need to resend it on append. Omitting it is recommended; the stored flags are used automatically. If you do include it, each flag must match the value set on create (400 if different). If `publish` is true (default), the new version is immediately published, replacing the previously published version. If the Knowledge entry has no previously published version, the new version becomes the first published one. operationId: appendVersion parameters: - name: knowledgeId in: path description: GovWorx internal Knowledge id returned from the create endpoint. required: true schema: type: integer format: int64 example: 12345 requestBody: content: application/json: schema: $ref: '#/components/schemas/AppendExternalKnowledgeVersionRequestDto' required: true responses: '201': description: >- Version appended. Response includes the full new version with all GovWorx-generated referenceIds. content: '*/*': schema: $ref: '#/components/schemas/ExternalKnowledgeVersionDetailDto' '400': description: >- Validation error — GovWorx-owned section content supplied, unknown referenceId, flag immutability violation, or unsupported digest type for this knowledge type. content: '*/*': schema: $ref: '#/components/schemas/ErrorInfo' examples: GovWorx-owned section supplied: description: GovWorx-owned section supplied value: info: >- The `spokenInstructions` section is not API-controlled and is managed within GovWorx. Remove `spokenInstructions` from the request. Unknown referenceId: description: Unknown referenceId value: info: >- Unknown referenceId 'si-deadbeef' on API-controlled spoken instructions. Updates must echo a GovWorx-generated referenceId from the previous version; omit the referenceId to add a new item. Flag immutability: description: Flag immutability value: info: >- The `spokenInstructions` setting cannot change between versions (currently true). Delete the Knowledge entry and recreate it to change which sections the API manages. '401': description: Missing or invalid bearer token. content: '*/*': schema: $ref: '#/components/schemas/ErrorInfo' example: info: Authentication required '403': description: Token does not have the Manage Knowledge permission. content: '*/*': schema: $ref: '#/components/schemas/ErrorInfo' example: info: Access denied — Manage Knowledge permission required '404': description: Knowledge entry not found, or the entry is not API-managed. content: '*/*': schema: $ref: '#/components/schemas/ErrorInfo' example: info: Versions can only be appended to API-managed Knowledge entries '409': description: >- A concurrent request appended the same version number — retry the request. content: '*/*': schema: $ref: '#/components/schemas/ErrorInfo' example: info: >- A concurrent append created version 3 for this Knowledge entry. Retry the request to append the next version. components: schemas: AppendExternalKnowledgeVersionRequestDto: type: object description: >- Append a new immutable version to an existing Knowledge entry. Provide at least one of `interview` or `actions`. properties: name: type: string description: >- Optional updated name for the Knowledge entry. When supplied, replaces the existing name. example: Cardiac Arrest - Adult (Updated) maxLength: 255 minLength: 0 description: type: string description: >- Optional description. When supplied, updates both the Knowledge entry's top-level description and the new version's description. When omitted, the Knowledge description is unchanged and the version description defaults to 'Appended via external API'. example: Updated chest-compression rate per Q1 2026 guidelines. isAllCallers: type: boolean default: 'false' description: >- If true, marks this entry as the tenant's all-callers guide card (single per tenant). Omit to leave the existing value unchanged. externalVersion: type: string description: >- Optional partner-supplied version label. Free-form short string; stored but not used for ordering or lookup. example: v1.2.0 maxLength: 64 minLength: 0 publish: type: boolean default: 'true' description: >- If true (default), publishes the new version immediately, replacing the previously published version. apiControl: $ref: '#/components/schemas/KnowledgeApiControl' description: >- Optional. Ownership flags are set once at creation and are immutable — you do not need to resend them on every append. If omitted (recommended), the stored flags are used automatically. If supplied, each provided flag must match the value set on create (400 if different). To change ownership, delete the entry and recreate it. interview: $ref: '#/components/schemas/AssistDigestV3' description: >- Interview content for the new version. **API-owned questions (`apiControl.questions = true`):** Send the full `questionList`. Echo a `referenceId` to update an existing question; omit it to add a new one. Unknown ids → 400. Omitting / null / `[]` results in an empty question list (full overwrite). **GovWorx-owned questions (`apiControl.questions = false`):** Omit `questionList`; it is carried forward automatically. Sending it is rejected (400). actions: $ref: '#/components/schemas/ActionSetDigest' description: >- Action set content for the new version. For each API-owned sub-section (flag = true): send the updated list; echo a `referenceId` to update, omit to add new. Omit / null / `[]` = empty (full overwrite). For each GovWorx-owned sub-section (flag = false): omit that list entirely — it is carried forward automatically. Sending it is rejected (400). ExternalKnowledgeVersionDetailDto: type: object description: >- Full detail of a Knowledge version, including its normalized interview and action content. All `referenceId` values in the returned content are GovWorx-generated stable identifiers. Store these ids — they must be echoed in future append requests to update existing items in place. properties: version: type: integer format: int32 description: >- Monotonic version number, unique per Knowledge id. Use this in version-scoped routes. example: 3 externalVersion: type: string description: Optional partner-supplied version label. example: v1.2.0 isPublished: type: boolean description: >- True if this version is the currently published version for the Knowledge entry. description: type: string description: >- Optional description of this version, as provided on create or append. createdAt: type: string format: date-time description: >- UTC timestamp when this version was created (i.e., when GovWorx received and stored the payload). publishedAt: type: string format: date-time description: >- UTC timestamp when this version was last published (made active), or null if never published. apiControl: $ref: '#/components/schemas/KnowledgeApiControl' description: >- The active API ownership flags for this version. Echoes what was declared on create and is immutable between versions. Use this to confirm which sections are API-controlled vs GovWorx-controlled. interview: $ref: '#/components/schemas/AssistDigestV3' description: >- Interview (question list) content for this version with all GovWorx-generated `referenceId`s populated. Null if this knowledge type does not carry interview content. actions: $ref: '#/components/schemas/ActionSetDigest' description: >- Action set content for this version with all GovWorx-generated `referenceId`s populated across spoken instructions (`si-`), CAD actions (`ca-`), SMS messages (`sms-`), and dispatch triggers (`dt-`). Null if no action content exists for this version. ErrorInfo: type: object properties: info: type: string KnowledgeApiControl: type: object description: >- Centralized per-section API ownership flags for this Knowledge entry. Declares which sections are owned by the external API (API-controlled) and which are managed within GovWorx (GovWorx-controlled). All flags default to false (GovWorx-controlled) when absent or null. **Flags are set once at creation and are immutable.** You do not need to send `apiControl` on append — omitting it is the recommended approach and the stored flags are used automatically. If you do include it, each flag must match the creation value (400 if different). To change ownership of any section, delete the Knowledge entry and recreate it. properties: questions: type: boolean default: 'false' description: >- If true, the `questionList` (including all conditional sub-questions) and the `intent` field are owned by the API. Each append fully overwrites — omitting, null, or `[]` → empty. If false (default), interview questions are editable in GovWorx and must not be included in appends. incidentType: type: boolean default: 'false' description: >- Reserved for future use — must be false or omitted. Incident type assignment from the API payload is not yet supported; incident types are always carried forward from the previous version and remain editable in GovWorx regardless of this flag. spokenInstructions: type: boolean default: 'false' description: >- If true, the `spokenInstructions` list and the `purpose` field are owned by the API. Each append fully overwrites. If false (default), spoken instructions are editable in GovWorx. cadActions: type: boolean default: 'false' description: >- If true, the `cadActions` list is owned by the API. Each append fully overwrites. If false (default), CAD actions are editable in GovWorx. smsMessages: type: boolean default: 'false' description: >- If true, the `smsMessages` list is owned by the API. Each append fully overwrites. If false (default), SMS messages are editable in GovWorx. dispatchTriggers: type: boolean default: 'false' description: >- If true, the `dispatchTriggers` list is owned by the API. Each append fully overwrites. If false (default), dispatch triggers are editable in GovWorx. AssistDigestV3: type: object description: >- Structured interview content for a guide card: the questions a calltaker asks the caller and the reference content shown alongside them. properties: id: type: string description: >- Stable identifier within the document, assigned by the author or generator. name: type: string description: Display name of the guide card. example: Cardiac Arrest - Adult intent: type: string description: Short statement of when this guide card applies. example: Caller reports an unresponsive adult with no pulse. service: type: string description: >- Optional service category (e.g., MEDICAL, FIRE, LAW). Used internally for routing. example: MEDICAL isRoot: type: boolean description: >- True if this is the entry-point guide card for the protocol. Default false. questionList: type: array description: Ordered list of interview questions asked by the calltaker. items: $ref: '#/components/schemas/Question' ActionSetDigest: type: object description: >- Action content for a guide card: spoken instructions, CAD actions, and SMS messages. properties: id: type: string description: Stable identifier within the document. name: type: string description: Display name of the action set. example: Cardiac Arrest - Actions purpose: type: string description: >- Short statement of what these actions accomplish. Ownership follows the `spokenInstructions` flag in the Knowledge entry's `apiControl`. spokenInstructions: type: array description: Instructions the calltaker reads aloud to the caller. items: $ref: '#/components/schemas/SpokenInstruction' cadActions: type: array description: Steps the calltaker or dispatcher performs in the CAD system. items: $ref: '#/components/schemas/CADAction' smsMessages: type: array description: SMS messages the calltaker may send to the caller. items: $ref: '#/components/schemas/SMSMessage' dispatchTriggers: type: array description: >- Cues for the calltaker to update CAD priority/code (e.g., dispatch code changes). items: $ref: '#/components/schemas/DispatchTrigger' media: type: array description: >- Media assets (images, videos) referenced by spoken instructions or SMS messages. items: $ref: '#/components/schemas/ActionSetMedia' Question: type: object description: A single interview question. properties: id: type: integer format: int64 description: >- Sequential identifier within the questionList. Assigned by GovWorx on import; partners may omit. referenceId: type: string description: 'Stable identifier for cross-references (format: q-{8 hex chars}).' example: q-1a2b3c4d text: type: string description: The question as it should be asked to the caller. example: Is the patient breathing normally? intent: type: string description: What the calltaker is trying to learn from this question. lowQualityCriteria: type: string description: Description of a poor-quality answer to this question. highQualityCriteria: type: string description: Description of a high-quality answer to this question. evaluatable: type: boolean description: Whether this question can be evaluated/scored. Default true if null. useInAssist: type: boolean description: >- Whether this question is used by the AI assist system. Default true if null. isCritical: type: boolean description: Critical questions weigh heavily in evaluation. Default false. required: type: boolean description: Whether this question must be asked. Default true if null. relatedQuestions: type: array description: Follow-up question groups shown conditionally based on the answer. items: $ref: '#/components/schemas/RelatedQuestionGroup' SpokenInstruction: type: object description: A single spoken instruction read to the caller. properties: referenceId: type: string description: 'Stable identifier (format: si-{8 hex chars}).' example: si-1a2b3c4d instruction: type: string description: The instruction text to read. example: Place the heel of one hand on the center of the chest. sequence: type: integer format: int32 description: Delivery order (0-based). conditionedOn: type: string description: Natural-language condition describing when this instruction applies. referenceMedia: type: string description: >- Reference id of an associated media asset, matching ActionSetMedia.referenceId. evaluatable: type: boolean description: >- Whether this instruction can be evaluated/scored. Default true if null. useInAssist: type: boolean description: >- Whether this instruction is used by the AI assist system. Default true if null. required: type: boolean description: >- Whether this instruction is required to be delivered. Default true if null. isCritical: type: boolean description: >- Critical instructions weigh heavily in evaluation. Default false if null. CADAction: type: object description: A CAD-system action the calltaker or dispatcher performs. properties: referenceId: type: string description: 'Stable identifier (format: ca-{8 hex chars}).' example: ca-1a2b3c4d instruction: type: string description: What to do in CAD. example: Enter call type CARDIAC. role: type: string description: Who performs the action. enum: - CALLTAKER - DISPATCHER example: CALLTAKER conditionedOn: type: string description: Natural-language condition describing when this action applies. sequence: type: integer format: int32 description: Delivery order (0-based). evaluatable: type: boolean description: Whether this action can be evaluated/scored. Default true if null. useInAssist: type: boolean description: >- Whether this action is used by the AI assist system. Default true if null. required: type: boolean description: Whether this action is required. Default true if null. SMSMessage: type: object description: SMS message template that may be sent to the caller. properties: referenceId: type: string description: 'Stable identifier (format: sms-{8 hex chars}).' example: sms-1a2b3c4d message: type: string description: Message body. example: We've dispatched help. Stay on the line. mediaRef: type: string description: >- Reference id of an associated media asset, matching ActionSetMedia.referenceId. conditionedOn: type: string description: >- Natural-language condition describing when this message should be sent. sequence: type: integer format: int32 description: Delivery order (0-based). DispatchTrigger: type: object description: A cue for the calltaker to set/update the CAD dispatch code or priority. properties: referenceId: type: string description: 'Stable identifier (format: dt-{8 hex chars}).' example: dt-1a2b3c4d dispatchCode: type: string description: The CAD dispatch code to apply. example: 29B condition: type: string description: >- Natural-language condition describing when this trigger fires. Null means it fires whenever the guide card becomes active. sequence: type: integer format: int32 description: Delivery order (0-based). ActionSetMedia: type: object description: A media asset referenced by spoken instructions or SMS messages. properties: referenceId: type: string description: >- Stable identifier referenced by SpokenInstruction.referenceMedia or SMSMessage.mediaRef. name: type: string description: Display name. description: type: string description: Short description of the media asset. mediaType: type: string description: Type of media. enum: - IMAGE - VIDEO example: IMAGE url: type: string description: Public URL to the media asset. RelatedQuestionGroup: type: object description: Group of related follow-up questions shown conditionally. properties: id: type: integer format: int64 description: Sequential identifier within the relatedQuestions array. displayCriteria: type: string description: Natural-language condition describing when this group is shown. questionList: description: Questions in this group. ````