openapi: 3.1.0 info: title: SanctionsService API version: 1.0.0 security: - WorldMonitorKey: [] - ApiKeyHeader: [] servers: - url: https://api.worldmonitor.app paths: /api/sanctions/v1/list-sanctions-pressure: get: tags: - SanctionsService summary: ListSanctionsPressure description: ListSanctionsPressure returns OFAC SDN and Consolidated designations plus Canada SEMA entries, with country and program pressure and new additions. operationId: ListSanctionsPressure parameters: - name: max_items in: query description: Maximum number of recent sanctions entries to include. required: false example: 1 schema: type: integer format: int32 - 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: "aircraftCount": 1 "consolidatedCount": 1 "countries": - "aircraftCount": 1 "countryCode": "US" "countryName": "US" "entryCount": 1 "newEntryCount": 1 "datasetDate": "1717200000000" "entries": - "countryCodes": - "US" "countryNames": - "US" "effectiveAt": "1717200000000" "entityType": "SANCTIONS_ENTITY_TYPE_ENTITY" "id": "example-id" schema: $ref: '#/components/schemas/ListSanctionsPressureResponse' "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/sanctions/v1/lookup-sanction-entity: get: tags: - SanctionsService summary: LookupSanctionEntity description: |- LookupSanctionEntity screens the seeded OFAC SDN, OFAC Consolidated, Canada SEMA and US Consolidated Screening List export-control lists by name, up to 10 retained aliases per entity, or an exact IMO identifier. operationId: LookupSanctionEntity parameters: - name: q in: query description: Search a name, up to 10 retained aliases per entity, or an exact IMO identifier (2-200 characters). required: false example: "example" schema: type: string - name: max_results in: query description: Maximum number of matching sanctioned entities to return. required: false example: 1 schema: type: integer format: int32 - 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: "results": - "countryCodes": - "US" "entityType": "all" "id": "example-id" "name": "WorldMonitor Analyst" "programs": - "example" "source": "example" "total": 1 schema: $ref: '#/components/schemas/LookupSanctionEntityResponse' "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' 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. ListSanctionsPressureRequest: type: object properties: maxItems: type: integer format: int32 description: Maximum number of recent sanctions entries to include. description: ListSanctionsPressureRequest retrieves recent OFAC sanctions pressure state. ListSanctionsPressureResponse: type: object properties: entries: type: array items: $ref: '#/components/schemas/SanctionsEntry' countries: type: array items: $ref: '#/components/schemas/CountrySanctionsPressure' programs: type: array items: $ref: '#/components/schemas/ProgramSanctionsPressure' fetchedAt: type: string format: int64 datasetDate: type: string format: int64 totalCount: type: integer format: int32 sdnCount: type: integer format: int32 consolidatedCount: type: integer format: int32 newEntryCount: type: integer format: int32 vesselCount: type: integer format: int32 aircraftCount: type: integer format: int32 semaCount: type: integer format: int32 description: Number of Canadian SEMA designations represented in this snapshot. semaError: type: string description: Present when the SEMA source failed while other sanctions data remained available. unattributed: $ref: '#/components/schemas/UnattributedSanctionsPressure' flagRegistries: type: array items: $ref: '#/components/schemas/FlagRegistrySanctionsPressure' regulationTargets: type: array items: $ref: '#/components/schemas/CountrySanctionsPressure' description: ListSanctionsPressureResponse contains normalized OFAC pressure summaries and recent entries. SanctionsEntry: type: object properties: id: type: string name: type: string entityType: type: string enum: - SANCTIONS_ENTITY_TYPE_UNSPECIFIED - SANCTIONS_ENTITY_TYPE_ENTITY - SANCTIONS_ENTITY_TYPE_INDIVIDUAL - SANCTIONS_ENTITY_TYPE_VESSEL - SANCTIONS_ENTITY_TYPE_AIRCRAFT description: SanctionsEntityType classifies the designated party. countryCodes: type: array items: type: string countryNames: type: array items: type: string programs: type: array items: type: string sourceLists: type: array items: type: string effectiveAt: type: string format: int64 isNew: type: boolean note: type: string parentCountryCodes: type: array items: type: string description: |- Direct linked-parent countries for addressless entities. These are not address/nationality evidence and do not feed country risk counts. parentCountryNames: type: array items: type: string description: SanctionsEntry is a normalized OFAC sanctions designation. CountrySanctionsPressure: type: object properties: countryCode: type: string countryName: type: string entryCount: type: integer format: int32 newEntryCount: type: integer format: int32 vesselCount: type: integer format: int32 description: |- Assets with a direct country association only. Zero does not mean this country has no sanctioned vessels; flag counts are in flagRegistries. aircraftCount: type: integer format: int32 description: |- Assets with a direct country association only; registry counts are in ListSanctionsPressureResponse.flagRegistries, not this field. description: CountrySanctionsPressure summarizes designation volume and recent additions by country. ProgramSanctionsPressure: type: object properties: program: type: string entryCount: type: integer format: int32 newEntryCount: type: integer format: int32 description: ProgramSanctionsPressure summarizes designation volume and recent additions by OFAC program. UnattributedSanctionsPressure: type: object properties: entryCount: type: integer format: int32 vesselCount: type: integer format: int32 aircraftCount: type: integer format: int32 FlagRegistrySanctionsPressure: type: object properties: countryCode: type: string countryName: type: string vesselCount: type: integer format: int32 newVesselCount: type: integer format: int32 aircraftCount: type: integer format: int32 description: Zero in snapshots written before aircraft registries were counted. newAircraftCount: type: integer format: int32 description: |- FlagRegistrySanctionsPressure counts sanctioned vessels by flag and sanctioned aircraft by the state of registry in their tail number. The response lists at most 12 registries, ordered by new vessels and aircraft, then all vessels and aircraft, so an omitted registry may still register sanctioned assets. Older snapshots return none. LookupSanctionEntityRequest: type: object properties: q: type: string description: Search a name, up to 10 retained aliases per entity, or an exact IMO identifier (2-200 characters). maxResults: type: integer format: int32 description: Maximum number of matching sanctioned entities to return. description: LookupSanctionEntityRequest screens the seeded OFAC SDN, OFAC Consolidated, Canada SEMA and US CSL index. LookupSanctionEntityResponse: type: object properties: results: type: array items: $ref: '#/components/schemas/SanctionEntityMatch' total: type: integer format: int32 source: type: string description: |- Comma-separated lists searched; "seeded" when q is rejected before lookup; "unavailable" when no valid index records are available. description: |- LookupSanctionEntityResponse contains seeded matches ranked by token-set Jaro-Winkler score. A match is a lead to confirm with the issuing agency, not legal advice. SanctionEntityMatch: type: object properties: id: type: string name: type: string entityType: type: string countryCodes: type: array items: type: string programs: type: array items: type: string description: SanctionEntityMatch is a compact entity match from the lookup index.