> ## 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. # Create Knowledge entry > Create a new Knowledge entry with its first version. The `externalId` + `provider` pair must be unique for the tenant (409 if a duplicate exists). GovWorx generates a stable `referenceId` for every item in every content list and echoes them back in the response. **Store all `referenceId` values** — they are required to update existing items in place on future append calls. Section ownership is declared via a single top-level `apiControl` object. Each flag defaults to false (GovWorx-owned) when absent or when `apiControl` is omitted entirely. Flags are immutable after creation — delete and recreate to change them. If `publish` is true (default), the created version is immediately published and available to GovWorx runtime consumers. ## OpenAPI ````yaml https://app.govworx.net/u/api-docs post /api/v1/external/knowledge 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: post: tags: - Knowledge summary: Create Knowledge entry description: >- Create a new Knowledge entry with its first version. The `externalId` + `provider` pair must be unique for the tenant (409 if a duplicate exists). GovWorx generates a stable `referenceId` for every item in every content list and echoes them back in the response. **Store all `referenceId` values** — they are required to update existing items in place on future append calls. Section ownership is declared via a single top-level `apiControl` object. Each flag defaults to false (GovWorx-owned) when absent or when `apiControl` is omitted entirely. Flags are immutable after creation — delete and recreate to change them. If `publish` is true (default), the created version is immediately published and available to GovWorx runtime consumers. operationId: createKnowledge requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateExternalKnowledgeRequestDto' required: true responses: '201': description: >- Knowledge entry created. The first version is always version 1, with description 'Created via external API'. If publish=true (default) the version is immediately active. Response includes all GovWorx-generated referenceIds — store them for future appends. content: '*/*': schema: $ref: '#/components/schemas/ExternalKnowledgeDetailDto' '400': description: >- Validation error — missing required fields, unsupported knowledgeType, or interview on a non-interview type. content: '*/*': schema: $ref: '#/components/schemas/ErrorInfo' example: info: At least one of `interview` or `actions` is required '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 '409': description: >- A Knowledge entry with this externalId already exists for this provider in the tenant. content: '*/*': schema: $ref: '#/components/schemas/ErrorInfo' example: info: >- A Knowledge entry with externalId 'apco-card-cardiac-arrest-adult' already exists for provider 'APCO' in this tenant components: schemas: CreateExternalKnowledgeRequestDto: type: object description: >- Create a new Knowledge entry along with its first version. Provide at least one of `interview` or `actions`. properties: name: type: string description: >- Human-readable name for the Knowledge entry (e.g., the guide card title). example: Cardiac Arrest - Adult description: type: string description: Optional description shown in the GovWorx UI. example: APCO standard protocol for adult cardiac arrest. knowledgeType: type: string default: GUIDE_CARD description: >- Classification of the Knowledge entry. Defaults to GUIDE_CARD. Only GUIDE_CARD and INSTRUCTION_CARD are supported; any other value is rejected. GUIDE_CARD carries interview + action content; INSTRUCTION_CARD carries action content only. enum: - GUIDE_CARD - INSTRUCTION_CARD example: GUIDE_CARD provider: type: string description: >- Identifier of the organization authoring this Knowledge entry. Common values include APCO, PowerPhone, IAED, or a tenant-internal name for in-house authoring. example: APCO maxLength: 255 minLength: 0 externalId: type: string description: >- Partner-supplied identifier. Stored verbatim and unique per provider/tenant. Used to look up the GovWorx internal id and for idempotency on retries. example: apco-card-cardiac-arrest-adult maxLength: 255 minLength: 0 externalVersion: type: string description: >- Partner-supplied version label for this submission. Free-form short string; stored alongside the version for traceability. example: v1.0 maxLength: 64 minLength: 0 publish: type: boolean default: 'true' description: >- If true (default), publishes the created version immediately so it becomes available to runtime consumers. apiControl: $ref: '#/components/schemas/KnowledgeApiControl' description: >- Declares which sections of this Knowledge entry are owned by the external API. All flags default to false (GovWorx-controlled) when absent. Flags are immutable after creation — to change ownership, delete and recreate the entry. See `KnowledgeApiControl` for per-flag details. isAllCallers: type: boolean default: 'false' description: >- If true, marks this entry as the tenant's all-callers guide card (single per tenant). Default false. interview: $ref: '#/components/schemas/AssistDigestV3' description: >- Interview (question list) content. Required for GUIDE_CARD; not supported on INSTRUCTION_CARD. At least one of `interview` or `actions` must be present. GovWorx generates a stable `referenceId` (`q-{8 hex}`) for every question — the response echoes these back. Store them; echo them on future appends to update existing questions in place. Ownership of the question list is declared via the top-level `apiControl.questions` flag. actions: $ref: '#/components/schemas/ActionSetDigest' description: >- Action set content for the guide card or instruction card. At least one of `interview` or `actions` must be present. GovWorx generates stable `referenceId`s for every item (`si-`, `ca-`, `sms-`, `dt-` prefixes) — the response echoes these back. Store them; echo them on future appends to update existing items. Per-sub-section ownership is declared via the top-level `apiControl` flags. required: - externalId - externalVersion - name - provider ExternalKnowledgeDetailDto: type: object description: Detail view of a Knowledge entry, including its version list. properties: id: type: integer format: int64 description: GovWorx internal Knowledge id. Use this in subsequent API calls. example: 12345 name: type: string description: Human-readable name of the Knowledge entry. example: Cardiac Arrest - Adult description: type: string description: Optional description shown in the GovWorx UI. source: type: string description: >- Source of the entry. API_IMPORT indicates it was loaded via this API. example: API_IMPORT provider: type: string description: >- Identifier of the organization that authored this Knowledge entry. Common values include APCO, PowerPhone, IAED, or a tenant-internal name for in-house authoring. example: APCO knowledgeType: type: string description: Classification of the Knowledge entry. enum: - GUIDE_CARD - INSTRUCTION_CARD - POLICY - MEMO_BRIEFING - TRAINING - GENERAL_KNOWLEDGE - NON_EMERGENCY_LINE_ABILITY example: GUIDE_CARD externalId: type: string description: Partner-supplied identifier if one was provided on create. example: apco-card-cardiac-arrest-adult publishedVersion: type: integer format: int32 description: >- Version number of the currently published version, or null if none is published. example: 3 createdAt: type: string format: date-time description: >- UTC timestamp when this entry was created (i.e., when GovWorx received and stored the first version). updatedAt: type: string format: date-time description: >- UTC timestamp when this entry was last modified — a new version was added, the published version changed, or metadata was updated. versions: type: array description: >- All versions for this Knowledge entry, including their interview and action content. items: $ref: '#/components/schemas/ExternalKnowledgeVersionDetailDto' 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' 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. 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. ````