> ## 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. # Upload Incident > Upload a new incident to the system. Token must have 'Manage Events' permission. System will only upload incident once, using the sysId to prevent duplicates. **Important**: Do NOT include the 'id' field in your request - use 'sysId' to identify incidents from your source system. By default, timestamps are assumed to be in UTC and will be converted to the tenant's local timezone. Set convertFromUtc=false if your timestamps are already in local time. ## OpenAPI ````yaml https://app.govworx.net/u/api-docs put /api/v1/external/incident 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/incident: put: tags: - Incident summary: Upload Incident description: >- Upload a new incident to the system. Token must have 'Manage Events' permission. System will only upload incident once, using the sysId to prevent duplicates. **Important**: Do NOT include the 'id' field in your request - use 'sysId' to identify incidents from your source system. By default, timestamps are assumed to be in UTC and will be converted to the tenant's local timezone. Set convertFromUtc=false if your timestamps are already in local time. operationId: uploadIncident parameters: - name: convertFromUtc in: query required: false schema: type: boolean default: true requestBody: content: application/json: schema: $ref: '#/components/schemas/IncidentDto' required: true responses: '200': description: OK components: schemas: IncidentDto: type: object description: Incident data transfer object for creating or updating incidents properties: sysId: type: string description: >- Unique system identifier from your source CAD system. This is used to prevent duplicate incidents. example: INC-2026-001234 number: type: string description: Incident number or call sign displayed to users example: 26-001234 caseNumber: type: string description: Case report number if assigned to the incident example: CR-2026-9876 priority: type: string description: Priority level of the incident as assigned by CAD example: Priority 1 incidentType: type: string description: Incident type / problem nature / call type classification example: Medical Emergency - Cardiac Arrest callerNumber: type: string description: The primary caller's phone number example: 555-123-4567 callerName: type: string description: The primary caller's name example: John Smith agency: type: string description: Agency identifier responding to or handling the incident example: CITY-FIRE-01 agencyType: type: string description: Type of agency (e.g., Fire, Police, EMS, Aeromedical) example: Fire dispatchQueueAt: type: string format: date-time description: > Timestamp when the incident was added to the dispatch queue. Subject to timezone conversion based on convertFromUtc parameter (defaults to UTC). example: '2026-01-06T10:30:00Z' incidentDate: type: string format: date-time description: > Date and time when the incident was created in the CAD system. Subject to timezone conversion based on convertFromUtc parameter (defaults to UTC). Used as fallback for callPickupTime/callReceivedTime if those are missing. example: '2026-01-06T10:25:00Z' disposition: type: string description: Final disposition or outcome of the incident example: Transport to Hospital location: type: string description: Address or location description of the incident example: 123 latitude: type: string description: Latitude coordinate of the incident location (decimal degrees) example: 40.7128 longitude: type: string description: Longitude coordinate of the incident location (decimal degrees) example: -74.006 callPosition: type: string description: > The position/workstation that the call taker who received the call was sitting in. Used for call audio matching and analytics. example: Position-01 callTakerId: type: string description: > The personnel ID of the call taker. This field gets mapped to the user's Personnel ID in the system to associate users with events example: CT-456 callTakerName: type: string description: Name of the call taker who handled the incident example: Jane Doe callSource: type: string description: > Information about how the incident was initiated. Typically indicates channels such as Admin Line, E911, Field Initiated, etc. example: E911 initialIncidentType: type: string description: | Initial incident type as reported when call was first received. May differ from final incidentType if call was reclassified. example: Chest Pain initialLocation: type: string description: > Initial location as reported when call was first received. May differ from final location if address was updated during the incident. example: 123 additionalContext: type: string description: Additional context, comments, or narrative about the incident example: >- Caller reports patient experiencing chest pain and shortness of breath for 30 minutes responseArea: type: string description: | Geographic response area, jurisdiction, beat, or ORI code. Used for routing and organizational purposes. example: Beat-3-Downtown radioChannel: type: string description: Radio channel assigned for communications on this incident example: FIRE-TAC-1 callReceivedTime: type: string format: date-time description: > Time the call was received by the system. Required for matching call audio. Subject to timezone conversion (defaults to UTC). If both callReceivedTime and callPickupTime are missing, both will be populated from incidentDate. Can be the earliest timestamp indicating the call taker has begun creating a CAD incident. example: '2026-01-06T10:23:00Z' callPickupTime: type: string format: date-time description: > Time the call was answered/picked up. Required for matching call audio. Subject to timezone conversion (defaults to UTC). If not provided, this will be auto-populated from callReceivedTime if available, otherwise from incidentDate if both callPickupTime and callReceivedTime are missing. Can be the earliest timestamp indicating the call taker has begun creating a CAD incident. example: '2026-01-06T10:23:15Z' callHangupTime: type: string format: date-time description: | Time the call ended/hung up. Required for matching call audio. Subject to timezone conversion (defaults to UTC). example: '2026-01-06T10:28:00Z' closedAt: type: string format: date-time description: | Timestamp when the incident was closed in the CAD system. Subject to timezone conversion (defaults to UTC). example: '2026-01-06T11:45:00Z' notes: type: array description: | List of notes/comments associated with the incident. Timestamps are subject to timezone conversion. items: $ref: '#/components/schemas/IncidentNote' responders: type: array description: | List of responders/units assigned to the incident. Timestamps are subject to timezone conversion. items: $ref: '#/components/schemas/IncidentResponder' additionalPersonnel: type: array description: > List of additional personnel involved in the incident (e.g., secondary call takers, dispatchers). Each entry includes personnelId, name, and role. items: $ref: '#/components/schemas/IncidentAdditionalPersonnel' relatedSysId: type: string description: > System ID (sysId) of a related or parent incident for linking incidents together. Used to establish relationships between incidents (e.g., duplicate calls, related events). example: INC-2026-001233 trainingCad: type: boolean description: > Flag indicating this is a training/simulation CAD incident. When true, the sysId will be prefixed to isolate it from real incidents and the incident will be routed through the training matching pipeline. example: false required: - callTakerId - closedAt - incidentDate - incidentType - number - sysId IncidentNote: type: object properties: noteId: type: string note: type: string noteBy: type: string noteAt: type: string format: date-time IncidentResponder: type: object properties: personnelId: type: string personnelFirstName: type: string personnelLastName: type: string unitName: type: string dispatchedBy: type: string dispatchedAt: type: string format: date-time enrouteAt: type: string format: date-time arrivedAt: type: string format: date-time clearedAt: type: string format: date-time IncidentAdditionalPersonnel: type: object properties: personnelId: type: string name: type: string type: type: string ````