openapi: 3.1.0 info: title: ConflictService API version: 1.0.0 security: - WorldMonitorKey: [] - ApiKeyHeader: [] servers: - url: https://api.worldmonitor.app paths: /api/conflict/v1/list-acled-events: get: tags: - ConflictService summary: ListAcledEvents description: ListAcledEvents retrieves ACLED armed-conflict events with country, location, actors, event type and fatalities, filterable by country and inclusive time range. operationId: ListAcledEvents parameters: - name: start in: query description: Start of time range (inclusive), Unix epoch milliseconds. required: false example: "1717200000000" schema: type: string format: int64 - name: end in: query description: End of time range (inclusive), Unix epoch milliseconds. required: false example: "1717200000000" schema: type: string format: int64 - name: page_size in: query description: |- Maximum items per page (1-100). Accepted but currently ignored; no-op until this handler supports the parameter. required: false example: 25 schema: type: integer format: int32 - name: cursor in: query description: |- Cursor for next page. Accepted but currently ignored; no-op until this handler supports the parameter. required: false example: "next-page-token" schema: type: string - name: country in: query description: Optional country filter (ISO 3166-1 alpha-2). required: false example: "US" schema: type: string - name: jmespath in: query description: |- Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath. required: false example: "keys(@)" schema: type: string responses: "200": description: Successful response content: application/json: example: "events": - "actors": - "example" "admin1": "example" "country": "US" "eventType": "all" "fatalities": 1 "id": "example-id" "pagination": "nextCursor": "next-page-token" "totalCount": 1 schema: $ref: '#/components/schemas/ListAcledEventsResponse' "400": description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' "401": description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' "403": description: API access requires an active subscription (the API key's subscription is inactive or expired). headers: X-Billing-Verification: description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`). schema: type: string content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' "429": description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' "503": description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape. headers: Retry-After: description: Seconds to wait before retrying (1-60). schema: type: string X-Billing-Verification: description: Billing-verification state that produced this response (matches the body `code`). schema: type: string X-Validation-Mode: description: Present with value degraded when user API-key validation is temporarily unavailable. schema: type: string X-RateLimit-Mode: description: Present with value degraded when a fail-closed rate-limit dependency is unavailable. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/BillingVerificationError' - $ref: '#/components/schemas/GatewayError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/conflict/v1/list-ucdp-events: get: tags: - ConflictService summary: ListUcdpEvents description: Browse cached, georeferenced UCDP violence events with optional country filtering, event dates and fatality estimates for country-level conflict data analysis. operationId: ListUcdpEvents parameters: - name: start in: query description: |- Start of time range (inclusive), Unix epoch milliseconds. Accepted but currently ignored; no-op until this handler supports the parameter. required: false example: "1717200000000" schema: type: string format: int64 - name: end in: query description: |- End of time range (inclusive), Unix epoch milliseconds. Accepted but currently ignored; no-op until this handler supports the parameter. required: false example: "1717200000000" schema: type: string format: int64 - name: page_size in: query description: |- Maximum items per page (1-100). Accepted but currently ignored; no-op until this handler supports the parameter. required: false example: 25 schema: type: integer format: int32 - name: cursor in: query description: |- Cursor for next page. Accepted but currently ignored; no-op until this handler supports the parameter. required: false example: "next-page-token" schema: type: string - name: country in: query description: Optional country filter (ISO 3166-1 alpha-2). required: false example: "US" schema: type: string - name: jmespath in: query description: |- Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath. required: false example: "keys(@)" schema: type: string responses: "200": description: Successful response content: application/json: example: "candidateVersion": "2026-01-15" "events": - "country": "US" "dateEnd": 1717200000000 "dateStart": 1717200000000 "deathsBest": 1 "deathsHigh": 1 "id": "example-id" "pagination": "nextCursor": "next-page-token" "totalCount": 1 schema: $ref: '#/components/schemas/ListUcdpEventsResponse' "400": description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' "401": description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' "403": description: API access requires an active subscription (the API key's subscription is inactive or expired). headers: X-Billing-Verification: description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`). schema: type: string content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' "429": description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' "503": description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape. headers: Retry-After: description: Seconds to wait before retrying (1-60). schema: type: string X-Billing-Verification: description: Billing-verification state that produced this response (matches the body `code`). schema: type: string X-Validation-Mode: description: Present with value degraded when user API-key validation is temporarily unavailable. schema: type: string X-RateLimit-Mode: description: Present with value degraded when a fail-closed rate-limit dependency is unavailable. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/BillingVerificationError' - $ref: '#/components/schemas/GatewayError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/conflict/v1/get-humanitarian-summary: get: tags: - ConflictService summary: GetHumanitarianSummary description: Retrieve a cached HAPI conflict summary for a country, with event counts, fatalities, demonstrations, reference period and update time for humanitarian context. operationId: GetHumanitarianSummary parameters: - name: country_code in: query description: ISO 3166-1 alpha-2 country code (e.g., "YE", "SD", "SO"). required: true example: "AD" schema: type: string enum: - 'AD' - 'AE' - 'AF' - 'AG' - 'AI' - 'AL' - 'AM' - 'AO' - 'AQ' - 'AR' - 'AS' - 'AT' - 'AU' - 'AW' - 'AX' - 'AZ' - 'BA' - 'BB' - 'BD' - 'BE' - 'BF' - 'BG' - 'BH' - 'BI' - 'BJ' - 'BL' - 'BM' - 'BN' - 'BO' - 'BR' - 'BS' - 'BT' - 'BW' - 'BY' - 'BZ' - 'CA' - 'CD' - 'CF' - 'CG' - 'CH' - 'CI' - 'CK' - 'CL' - 'CM' - 'CN' - 'CO' - 'CR' - 'CU' - 'CV' - 'CW' - 'CY' - 'CZ' - 'DE' - 'DJ' - 'DK' - 'DM' - 'DO' - 'DZ' - 'EC' - 'EE' - 'EG' - 'EH' - 'ER' - 'ES' - 'ET' - 'FI' - 'FJ' - 'FK' - 'FM' - 'FO' - 'FR' - 'GA' - 'GB' - 'GD' - 'GE' - 'GG' - 'GH' - 'GI' - 'GL' - 'GM' - 'GN' - 'GQ' - 'GR' - 'GS' - 'GT' - 'GU' - 'GW' - 'GY' - 'HK' - 'HM' - 'HN' - 'HR' - 'HT' - 'HU' - 'ID' - 'IE' - 'IL' - 'IM' - 'IN' - 'IO' - 'IQ' - 'IR' - 'IS' - 'IT' - 'JE' - 'JM' - 'JO' - 'JP' - 'KE' - 'KG' - 'KH' - 'KI' - 'KM' - 'KN' - 'KP' - 'KR' - 'KW' - 'KY' - 'KZ' - 'LA' - 'LB' - 'LC' - 'LI' - 'LK' - 'LR' - 'LS' - 'LT' - 'LU' - 'LV' - 'LY' - 'MA' - 'MC' - 'MD' - 'ME' - 'MF' - 'MG' - 'MH' - 'MK' - 'ML' - 'MM' - 'MN' - 'MO' - 'MP' - 'MR' - 'MS' - 'MT' - 'MU' - 'MV' - 'MW' - 'MX' - 'MY' - 'MZ' - 'NA' - 'NC' - 'NE' - 'NF' - 'NG' - 'NI' - 'NL' - 'NO' - 'NP' - 'NR' - 'NU' - 'NZ' - 'OM' - 'PA' - 'PE' - 'PF' - 'PG' - 'PH' - 'PK' - 'PL' - 'PM' - 'PN' - 'PR' - 'PS' - 'PT' - 'PW' - 'PY' - 'QA' - 'RO' - 'RS' - 'RU' - 'RW' - 'SA' - 'SB' - 'SC' - 'SD' - 'SE' - 'SG' - 'SH' - 'SI' - 'SK' - 'SL' - 'SM' - 'SN' - 'SO' - 'SR' - 'SS' - 'ST' - 'SV' - 'SX' - 'SY' - 'SZ' - 'TC' - 'TD' - 'TF' - 'TG' - 'TH' - 'TJ' - 'TL' - 'TM' - 'TN' - 'TO' - 'TR' - 'TT' - 'TV' - 'TW' - 'TZ' - 'UA' - 'UG' - 'UM' - 'US' - 'UY' - 'UZ' - 'VA' - 'VC' - 'VE' - 'VG' - 'VI' - 'VN' - 'VU' - 'WF' - 'WS' - 'XK' - 'YE' - 'ZA' - 'ZM' - 'ZW' - name: jmespath in: query description: |- Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath. required: false example: "keys(@)" schema: type: string responses: "200": description: Successful response content: application/json: example: "summary": "conflictDemonstrations": 42 "conflictEventsTotal": 1 "conflictFatalities": 1 "conflictPoliticalViolenceEvents": 1 "countryCode": "US" schema: $ref: '#/components/schemas/GetHumanitarianSummaryResponse' "400": description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' "401": description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' "403": description: API access requires an active subscription (the API key's subscription is inactive or expired). headers: X-Billing-Verification: description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`). schema: type: string content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' "429": description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' "503": description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape. headers: Retry-After: description: Seconds to wait before retrying (1-60). schema: type: string X-Billing-Verification: description: Billing-verification state that produced this response (matches the body `code`). schema: type: string X-Validation-Mode: description: Present with value degraded when user API-key validation is temporarily unavailable. schema: type: string X-RateLimit-Mode: description: Present with value degraded when a fail-closed rate-limit dependency is unavailable. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/BillingVerificationError' - $ref: '#/components/schemas/GatewayError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/conflict/v1/list-iran-events: get: tags: - ConflictService summary: ListIranEvents description: ListIranEvents is disabled by default; enable IRAN_EVENTS_ENABLED to return cached LiveUAMap Iran conflict records, otherwise an empty list with scrapedAt zero. operationId: ListIranEvents parameters: - name: jmespath in: query description: |- Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath. required: false example: "keys(@)" schema: type: string responses: "200": description: Successful response content: application/json: example: "events": - "category": "cs.AI" "id": "example-id" "latitude": 40.7128 "locationName": "WorldMonitor Analyst" "longitude": -74.006 "scrapedAt": "1717200000000" schema: $ref: '#/components/schemas/ListIranEventsResponse' "400": description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' "401": description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' "403": description: API access requires an active subscription (the API key's subscription is inactive or expired). headers: X-Billing-Verification: description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`). schema: type: string content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' "429": description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' "503": description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape. headers: Retry-After: description: Seconds to wait before retrying (1-60). schema: type: string X-Billing-Verification: description: Billing-verification state that produced this response (matches the body `code`). schema: type: string X-Validation-Mode: description: Present with value degraded when user API-key validation is temporarily unavailable. schema: type: string X-RateLimit-Mode: description: Present with value degraded when a fail-closed rate-limit dependency is unavailable. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/BillingVerificationError' - $ref: '#/components/schemas/GatewayError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/conflict/v1/get-humanitarian-summary-batch: post: parameters: - name: Idempotency-Key in: header description: Optional client-generated idempotency key. Retrying a POST with the same key and an identical request body replays the original response (only the status, body, and Content-Type are reproduced) instead of re-executing; reusing the key with a different body is rejected with 422. For mutations this avoids duplicating the side effect, while for batch-read POSTs it replays a cached snapshot that can be up to 24 hours stale. Keys are scoped per authenticated caller (falling back to the source IP for unauthenticated endpoints) and retained for 24 hours. required: false example: "4f8b9c2e-1a3d-4b6f-8e0a-2c5d7f9b1e34" schema: type: string minLength: 1 maxLength: 255 pattern: "^[\\x21-\\x7E]{1,255}$" tags: - ConflictService summary: GetHumanitarianSummaryBatch description: Retrieve humanitarian summaries for multiple countries in one request, with country indicators and requested versus fetched counts for coverage comparison. operationId: GetHumanitarianSummaryBatch requestBody: content: application/json: example: "countryCodes": - "US" schema: $ref: '#/components/schemas/GetHumanitarianSummaryBatchRequest' required: true responses: "200": description: Successful response headers: Idempotency-Key: schema: type: string description: The idempotency key echoed from the request. Present only when the client opted into idempotency. Idempotent-Replayed: schema: type: boolean description: true when this response was replayed from an earlier request with the same key, false on the first (original) request. Present only when the client opted into idempotency. content: application/json: example: "fetched": 1 "requested": 1 "results": "exampleKey": "conflictDemonstrations": 42 "conflictEventsTotal": 1 "conflictFatalities": 1 "conflictPoliticalViolenceEvents": 1 "countryCode": "US" schema: $ref: '#/components/schemas/GetHumanitarianSummaryBatchResponse' "400": description: Validation error, invalid Idempotency-Key header, or malformed JSON request body content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - type: object required: - error - message properties: error: type: string message: type: string - $ref: '#/components/schemas/InvalidRequestBodyError' "409": description: A request with this Idempotency-Key is still being processed headers: Idempotency-Key: schema: type: string description: The idempotency key supplied by the client. Retry-After: schema: type: string description: Seconds to wait before retrying the in-flight request. content: application/json: schema: type: object required: - error - message properties: error: type: string message: type: string "422": description: The Idempotency-Key was already used with a different request body headers: Idempotency-Key: schema: type: string description: The idempotency key supplied by the client. content: application/json: schema: type: object required: - error - message properties: error: type: string message: type: string "401": description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' "403": description: API access requires an active subscription (the API key's subscription is inactive or expired). headers: X-Billing-Verification: description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`). schema: type: string content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' "429": description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' "503": description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape. headers: Retry-After: description: Seconds to wait before retrying (1-60). schema: type: string X-Billing-Verification: description: Billing-verification state that produced this response (matches the body `code`). schema: type: string X-Validation-Mode: description: Present with value degraded when user API-key validation is temporarily unavailable. schema: type: string X-RateLimit-Mode: description: Present with value degraded when a fail-closed rate-limit dependency is unavailable. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/BillingVerificationError' - $ref: '#/components/schemas/GatewayError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' components: securitySchemes: WorldMonitorKey: type: apiKey in: header name: X-WorldMonitor-Key description: User-issued WorldMonitor API key. ApiKeyHeader: type: apiKey in: header name: X-Api-Key description: Alias header for the WorldMonitor API key (X-WorldMonitor-Key). schemas: JmespathProjectionError: description: Returned when a REST jmespath projection is invalid or exceeds the expression/output byte limits. properties: _jmespath_error: description: Projection error discriminator and details. type: string original_keys: description: Top-level keys or shape of the unprojected response. items: type: string type: array required: - _jmespath_error - original_keys type: object UnauthorizedError: type: object properties: error: type: string description: Human-readable error message. required: - error description: Returned when the API key is missing, malformed, or lacks current API access. Error: type: object properties: message: type: string description: Error message (e.g., 'user not found', 'database connection failed') description: Error is returned when a handler encounters an error. It contains a simple error message that the developer can customize. BillingVerificationError: type: object description: "Returned with HTTP 503 when paid access cannot be confirmed right now: the billing provider is re-verifying a recently expired subscription, or the entitlement backend is unreachable. Retryable — honor Retry-After." properties: error: type: string description: Human-readable billing-verification failure reason. code: type: string enum: - renewal_verification_pending - renewal_verification_failed - entitlement_verification_unavailable description: Machine-readable billing-verification state, mirrored in the X-Billing-Verification response header. requiredTier: type: integer format: int32 description: Minimum entitlement tier required for this endpoint, when the denial came from a tier gate. required: - error - code InvalidRequestBodyError: type: object description: Returned when a JSON POST request body is empty or malformed. properties: message: type: string description: Invalid request body required: - message GatewayError: type: object description: Returned by gateway infrastructure errors before an RPC handler runs, such as origin, routing, method, authentication, or quota checks. properties: error: oneOf: - type: string - type: object additionalProperties: true description: Gateway error reason or structured gateway failure details. required: - error RateLimitError: type: object description: Returned when a gateway or handler rate limit rejects the request. properties: error: type: string description: Human-readable rate-limit failure reason. required: - error ForbiddenError: type: object properties: error: type: string description: Human-readable entitlement failure reason. code: type: string enum: - subscription_lapsed description: Machine-readable denial code, present when the 403 is a billing-provider-confirmed subscription lapse (mirrored in the X-Billing-Verification response header). requiredTier: type: integer format: int32 description: Minimum entitlement tier required for this endpoint. currentTier: type: integer format: int32 description: Caller entitlement tier when known. planKey: type: string description: Caller plan key when known. required: - error description: Returned when a PRO-gated endpoint denies access because the caller has no resolved authenticated user, entitlements cannot be verified, or the caller lacks the required entitlement tier. FieldViolation: type: object properties: field: type: string description: The field path that failed validation (e.g., 'user.email' for nested fields). For header validation, this will be the header name (e.g., 'X-API-Key') description: type: string description: Human-readable description of the validation violation (e.g., 'must be a valid email address', 'required field missing') required: - field - description description: FieldViolation describes a single validation error for a specific field. ValidationError: type: object properties: violations: type: array items: $ref: '#/components/schemas/FieldViolation' description: List of validation violations required: - violations description: ValidationError is returned when request validation fails. It contains a list of field violations describing what went wrong. ListAcledEventsRequest: type: object properties: start: type: integer format: int64 description: 'Start of time range (inclusive), Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript' end: type: integer format: int64 description: 'End of time range (inclusive), Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript' pageSize: type: integer format: int32 description: |- Maximum items per page (1-100). Accepted but currently ignored; no-op until this handler supports the parameter. cursor: type: string description: |- Cursor for next page. Accepted but currently ignored; no-op until this handler supports the parameter. country: type: string description: Optional country filter (ISO 3166-1 alpha-2). description: ListAcledEventsRequest specifies filters for retrieving ACLED conflict events. ListAcledEventsResponse: type: object properties: events: type: array items: $ref: '#/components/schemas/AcledConflictEvent' pagination: $ref: '#/components/schemas/PaginationResponse' description: ListAcledEventsResponse contains ACLED conflict events matching the request. AcledConflictEvent: type: object properties: id: type: string minLength: 1 description: Unique ACLED event identifier. eventType: type: string description: ACLED event type classification (e.g., "Battles", "Explosions/Remote violence"). country: type: string description: Country where the event occurred. location: $ref: '#/components/schemas/GeoCoordinates' occurredAt: type: integer format: int64 description: 'Time the event occurred, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript' fatalities: type: integer format: int32 description: Reported fatalities from this event. actors: type: array items: type: string description: Named actors involved in the event. source: type: string description: Source article or report. admin1: type: string description: Administrative region within the country. required: - id description: AcledConflictEvent represents an armed conflict event from the ACLED dataset. GeoCoordinates: type: object properties: latitude: type: number maximum: 90 minimum: -90 format: double description: Latitude in decimal degrees (-90 to 90). longitude: type: number maximum: 180 minimum: -180 format: double description: Longitude in decimal degrees (-180 to 180). description: GeoCoordinates represents a geographic location using WGS84 coordinates. PaginationResponse: type: object properties: nextCursor: type: string description: Cursor for fetching the next page. Empty string indicates no more pages. totalCount: type: integer format: int32 description: Total count of items matching the query, if known. Zero if the total is unknown. description: PaginationResponse contains pagination metadata returned alongside list results. ListUcdpEventsRequest: type: object properties: start: type: integer format: int64 description: |- Start of time range (inclusive), Unix epoch milliseconds. Accepted but currently ignored; no-op until this handler supports the parameter.. Warning: Values > 2^53 may lose precision in JavaScript end: type: integer format: int64 description: |- End of time range (inclusive), Unix epoch milliseconds. Accepted but currently ignored; no-op until this handler supports the parameter.. Warning: Values > 2^53 may lose precision in JavaScript pageSize: type: integer format: int32 description: |- Maximum items per page (1-100). Accepted but currently ignored; no-op until this handler supports the parameter. cursor: type: string description: |- Cursor for next page. Accepted but currently ignored; no-op until this handler supports the parameter. country: type: string description: Optional country filter (ISO 3166-1 alpha-2). description: ListUcdpEventsRequest specifies filters for retrieving UCDP violence events. ListUcdpEventsResponse: type: object properties: events: type: array items: $ref: '#/components/schemas/UcdpViolenceEvent' pagination: $ref: '#/components/schemas/PaginationResponse' candidateVersion: type: string description: Monthly candidate release merged in; "+partial" when incomplete, empty when none. description: ListUcdpEventsResponse contains UCDP violence events matching the request. UcdpViolenceEvent: type: object properties: id: type: string minLength: 1 description: Unique UCDP event identifier. dateStart: type: integer format: int64 description: 'Start date of the event, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript' dateEnd: type: integer format: int64 description: 'End date of the event, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript' location: $ref: '#/components/schemas/GeoCoordinates' country: type: string description: Country where the event occurred. sideA: type: string description: Primary party in the conflict (Side A). sideB: type: string description: Secondary party in the conflict (Side B). deathsBest: type: integer format: int32 description: Best estimate of deaths. deathsLow: type: integer format: int32 description: Low estimate of deaths. deathsHigh: type: integer format: int32 description: High estimate of deaths. violenceType: type: string enum: - UCDP_VIOLENCE_TYPE_UNSPECIFIED - UCDP_VIOLENCE_TYPE_STATE_BASED - UCDP_VIOLENCE_TYPE_NON_STATE - UCDP_VIOLENCE_TYPE_ONE_SIDED description: |- UcdpViolenceType represents the UCDP violence classification. Maps to existing TS union: 'state-based' | 'non-state' | 'one-sided'. sourceOriginal: type: string description: Original source of the event report. hasPreciseLocation: type: boolean description: True when UCDP identifies a specific event location (where_prec 1). locationName: type: string description: Name of the location represented by the event coordinates. required: - id description: UcdpViolenceEvent represents a georeferenced violence event from the UCDP dataset. GetHumanitarianSummaryRequest: type: object properties: countryCode: type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code (e.g., "YE", "SD", "SO"). required: - countryCode description: GetHumanitarianSummaryRequest specifies which country to retrieve the humanitarian summary for. GetHumanitarianSummaryResponse: type: object properties: summary: $ref: '#/components/schemas/HumanitarianCountrySummary' description: GetHumanitarianSummaryResponse contains the humanitarian summary for the requested country. HumanitarianCountrySummary: type: object properties: countryCode: type: string description: ISO 3166-1 alpha-2 country code. countryName: type: string description: Country name. conflictEventsTotal: type: integer format: int32 description: Total conflict events in the reference period. conflictPoliticalViolenceEvents: type: integer format: int32 description: Political-violence category events only. conflictFatalities: type: integer format: int32 description: Political-violence category fatalities only. referencePeriod: type: string description: Reference period start date (YYYY-MM-DD). conflictDemonstrations: type: integer format: int32 description: Number of demonstration events. updatedAt: type: integer format: int64 description: 'Last data update time, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript' description: HumanitarianCountrySummary represents HAPI conflict event counts for a country. ListIranEventsRequest: type: object ListIranEventsResponse: type: object properties: events: type: array items: $ref: '#/components/schemas/IranEvent' scrapedAt: type: string format: int64 IranEvent: type: object properties: id: type: string title: type: string category: type: string sourceUrl: type: string latitude: type: number format: double longitude: type: number format: double locationName: type: string timestamp: type: string format: int64 severity: type: string GetHumanitarianSummaryBatchRequest: type: object properties: countryCodes: type: array items: type: string maxItems: 25 minItems: 1 description: ISO 3166-1 alpha-2 country codes (e.g., "YE", "SD"). Max 25. maxItems: 25 minItems: 1 description: GetHumanitarianSummaryBatchRequest looks up humanitarian summaries for multiple countries. GetHumanitarianSummaryBatchResponse: type: object properties: results: type: object additionalProperties: $ref: '#/components/schemas/HumanitarianCountrySummary' description: Map of country_code -> humanitarian summary for found countries. fetched: type: integer format: int32 description: Number of countries successfully fetched. requested: type: integer format: int32 description: Number of countries requested. description: GetHumanitarianSummaryBatchResponse contains humanitarian summaries for the requested countries. ResultsEntry: type: object properties: key: type: string value: $ref: '#/components/schemas/HumanitarianCountrySummary'