> ## Documentation Index > Fetch the complete documentation index at: https://www.worldmonitor.app/docs/llms.txt > Use this file to discover all available pages before exploring further. # SearchIntelHistory > SearchIntelHistory searches the durable historical intelligence store (convex/intelHistory.ts) by semantic similarity to a free-text query. The handler embeds the query, so each cache miss costs one embeddings call — the route carries its own fail-closed rate policy. Premium-gated. PRO-gated. Requires entitlement tier >= 1. ## OpenAPI ````yaml /api/IntelligenceService.openapi.yaml post /api/intelligence/v1/search-intel-history openapi: 3.1.0 info: title: IntelligenceService API version: 1.0.0 servers: - url: https://api.worldmonitor.app security: - WorldMonitorKey: [] - ApiKeyHeader: [] paths: /api/intelligence/v1/search-intel-history: post: tags: - IntelligenceService summary: SearchIntelHistory description: |- SearchIntelHistory searches the durable historical intelligence store (convex/intelHistory.ts) by semantic similarity to a free-text query. The handler embeds the query, so each cache miss costs one embeddings call — the route carries its own fail-closed rate policy. Premium-gated. PRO-gated. Requires entitlement tier >= 1. operationId: SearchIntelHistory 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}$ requestBody: content: application/json: example: country: US domain: conflict from: 1 limit: 25 query: supply chain risk to: 1 schema: $ref: '#/components/schemas/SearchIntelHistoryRequest' 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: partial: true query: supply chain risk records: - category: cs.AI country: US domain: example id: example-id ingestedAt: 1717200000000 upstreamUnavailable: true schema: $ref: '#/components/schemas/SearchIntelHistoryResponse' '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' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '403': description: PRO entitlement access denied. content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '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 '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' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' security: - WorldMonitorKey: [] - ApiKeyHeader: [] - BearerAuth: [] components: schemas: SearchIntelHistoryRequest: type: object properties: query: type: string maxLength: 500 minLength: 2 description: >- Free-text search query, e.g. "artillery strikes near Kharkiv". Embedded with the same model and normalization the seed writer used, so query and stored vectors are comparable. domain: type: string pattern: ^(conflict|military|energy)?$ description: Restrict to one producing domain. Empty searches every domain. country: type: string pattern: ^([A-Z]{2})?$ description: >- Restrict to one ISO 3166-1 alpha-2 country. Empty searches every country. from: type: integer minimum: 0 format: int64 description: >- Earliest occurred_at to consider, Unix epoch milliseconds, inclusive. 0 or omitted means no lower bound.. Warning: Values > 2^53 may lose precision in JavaScript to: type: integer minimum: 0 format: int64 description: |- Latest occurred_at to consider, Unix epoch milliseconds, inclusive. 0 or omitted means no upper bound.. Warning: Values > 2^53 may lose precision in JavaScript limit: type: integer maximum: 64 minimum: 0 format: int32 description: >- Maximum matches to return. Defaults to 20 server-side when omitted or <= 0; the handler caps it at 64, the SEARCH_MAX_LIMIT the Convex action clamps to (convex/intelHistory.ts). required: - query description: |- SearchIntelHistoryRequest asks for stored historical intelligence events semantically similar to a free-text query. The handler embeds `query` and runs a vector search over convex/intelHistory.ts; the optional filters narrow the candidate set before ranking. SearchIntelHistoryResponse: type: object properties: records: type: array items: $ref: '#/components/schemas/IntelHistoryRecord' query: type: string description: >- Echo of the search query, so a caller multiplexing requests can pair a response back to its input. partial: type: boolean description: True when a bounded candidate window may omit further matches. upstreamUnavailable: type: boolean description: |- True when the embedding provider or the history store could not be reached. The gateway reads this flag out of the body and switches the response to Cache-Control: no-store, so a transient outage is never pinned as a false-empty result for the tier's full TTL. description: |- SearchIntelHistoryResponse returns the matching historical events, most similar first. 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. 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 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. ForbiddenError: type: object properties: error: type: string description: Human-readable entitlement failure reason. 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. 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. 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 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 IntelHistoryRecord: type: object properties: id: type: string description: >- Opaque stable handle for the stored event (a Convex document id). Useful for de-duplicating across calls; not resolvable through any public route. domain: type: string description: |- Producing domain, e.g. "conflict", "military", "energy". Matches the domain filter accepted by the three RPCs. resource: type: string description: |- Seeder-level resource that produced the event, e.g. "acled-events". Finer-grained than domain and not part of any request filter. country: type: string description: >- ISO 3166-1 alpha-2 country code. Empty when the event is not attributable to a single country. category: type: string description: >- Producer-supplied event category, e.g. "battle". Free-form per domain; empty when the producer did not classify the event. title: type: string description: Event headline. Always present. summary: type: string description: Longer description. Empty when the producer had none. sourceUrl: type: string description: >- Canonical link to the underlying report. Empty when the producer had none. occurredAt: type: integer format: int64 description: >- When the event happened, Unix epoch milliseconds. This is the field the timeline orders by and the from/to filters bound.. Warning: Values > 2^53 may lose precision in JavaScript ingestedAt: type: integer format: int64 description: >- When WorldMonitor stored the event, Unix epoch milliseconds. Distinct from occurred_at for backfills, and the field retention ages rows out by.. Warning: Values > 2^53 may lose precision in JavaScript score: type: number format: double description: >- Cosine similarity against the request's query vector, in [-1, 1]. Higher is closer. Always 0 on GetIntelTimeline, which ranks by time and has no query vector to score against. description: |- IntelHistoryRecord is one durable historical intelligence event (#5694). Seeders append the events they publish to the Convex `intelHistory` table (convex/intelHistory.ts) after each run; every read path — chronological (GetIntelTimeline) and semantic (SearchIntelHistory, GetSimilarEvents) — returns this same projection, so a caller can hold one record shape. Defined in its own file because all three RPCs reuse it, matching the satellite.proto convention. 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. 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). BearerAuth: type: http scheme: bearer description: >- Bearer token: a Clerk-issued JWT for browser session flows, passed as Authorization: Bearer . ````