docs/api/SanctionsService.openapi.yaml
Rama main · réplica de lectura del repositorio original.
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.