> ## 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. # Look up Knowledge by externalId > Resolve a partner-supplied externalId to its GovWorx internal id. externalId is passed as a query parameter (not a path segment) because it is stored verbatim and may contain '/', which does not round-trip through a route path. externalId is only unique per (tenant, provider) — pass `provider` to disambiguate if more than one provider has used the same externalId for this tenant (409 if omitted and ambiguous). Returns the matching entry or 404 if none exists for the tenant. Token must have the 'View Knowledge' or 'Manage Knowledge' permission. ## OpenAPI ````yaml https://app.govworx.net/u/api-docs get /api/v1/external/knowledge/by-external-id 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: Media Ingest description: External media ingest — SRT radio traffic - 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/by-external-id: get: tags: - Knowledge summary: Look up Knowledge by externalId description: >- Resolve a partner-supplied externalId to its GovWorx internal id. externalId is passed as a query parameter (not a path segment) because it is stored verbatim and may contain '/', which does not round-trip through a route path. externalId is only unique per (tenant, provider) — pass `provider` to disambiguate if more than one provider has used the same externalId for this tenant (409 if omitted and ambiguous). Returns the matching entry or 404 if none exists for the tenant. Token must have the 'View Knowledge' or 'Manage Knowledge' permission. operationId: lookupByExternalId parameters: - name: externalId in: query description: >- Partner-supplied externalId to resolve. Sent as a query parameter so ids containing '/' round-trip safely. required: true schema: type: string - name: provider in: query description: >- Disambiguates when more than one provider has used this externalId for the tenant. required: false schema: type: string responses: '200': description: Match found content: '*/*': schema: $ref: '#/components/schemas/ExternalKnowledgeDto' '404': description: No entry with this externalId exists for the tenant content: '*/*': schema: $ref: '#/components/schemas/ExternalKnowledgeDto' '409': description: >- Multiple providers have used this externalId for the tenant — pass `provider` to disambiguate. content: '*/*': schema: $ref: '#/components/schemas/ErrorInfo' example: info: >- Multiple Knowledge entries have externalId 'card-1' across different providers. Pass `provider` to disambiguate. components: schemas: ExternalKnowledgeDto: type: object description: Summary of a Knowledge entry. 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. ErrorInfo: type: object properties: info: type: string ````