{ "openapi": "3.0.3", "info": { "title": "sanctions.tr API", "version": "1.0.0", "description": "Normalized sanctions search and tenant-scoped audit reports for approved API accounts. API keys must be stored only in customer backend systems." }, "servers": [ { "url": "https://api.sanctions.tr", "description": "Production" } ], "tags": [ { "name": "Search", "description": "Sanctions search with API keys." }, { "name": "Search Logs", "description": "Tenant-scoped search audit reports." }, { "name": "API Key Logs", "description": "Tenant-scoped API key access reports." } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "`Authorization: Bearer ` for tenant reporting endpoints." }, "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Public API key. Recommended usage: `x-api-key: sak_...`." }, "apiKeyAuthorization": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Alternative usage: `Authorization: ApiKey `." } }, "schemas": { "EntityType": { "type": "string", "enum": [ "person", "company", "vessel", "aircraft", "other" ], "description": "Supported entity type for a search request or result." }, "SearchResponse": { "allOf": [ { "$ref": "#/components/schemas/Status" }, { "type": "object", "description": "Public arama sonucu. `results` skor sırasına göre döner.", "properties": { "total": { "type": "integer", "description": "Total records matching the filters." }, "page": { "type": "integer", "description": "One-based page number." }, "pageSize": { "type": "integer", "description": "Requested or returned records per page." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResultItem" }, "description": "Candidate results ordered by score." }, "meta": { "type": "object", "nullable": true, "properties": { "institutionId": { "type": "string", "nullable": true, "description": "Authenticated tenant institution id." }, "apiKeyId": { "type": "string", "nullable": true, "description": "API key that made the request or is used as a filter." }, "normalizedQuery": { "type": "object", "description": "Normalized query used by the search engine." }, "sourceScope": { "type": "object", "description": "Requested or effective source scope." }, "searchedCollections": { "type": "array", "items": { "type": "string" }, "description": "Collections checked by the search engine." }, "searchableFields": { "type": "array", "items": { "type": "string" }, "description": "Fields evaluated by the search engine." }, "matchingStrategy": { "type": "object", "description": "Matching strategy applied to the request." }, "limitPolicy": { "$ref": "#/components/schemas/LimitPolicy", "description": "Usage policy applied to the request." }, "requestedSources": { "type": "array", "items": { "type": "string" }, "description": "Sources requested by the caller." }, "effectiveSources": { "type": "array", "items": { "type": "string" }, "description": "Sources searched after access policy is applied." } }, "description": "Normalized query, source and policy context." } } } ], "description": "Ranked search results and the effective search scope." }, "Status": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Whether the operation completed successfully." } }, "description": "Success state shared by public API response envelopes." }, "SearchResultItem": { "type": "object", "properties": { "entity": { "$ref": "#/components/schemas/EntityRecord", "description": "Matched normalized primary record." }, "sanctions": { "type": "array", "items": { "$ref": "#/components/schemas/SanctionRecord" }, "description": "Sanctions records associated with the entity." }, "aliases": { "type": "array", "items": { "$ref": "#/components/schemas/AliasRecord" }, "description": "Alternate names associated with the entity." }, "addresses": { "type": "array", "items": { "$ref": "#/components/schemas/AddressRecord" }, "description": "Addresses associated with the entity." }, "identifiers": { "type": "array", "items": { "$ref": "#/components/schemas/IdentifierRecord" }, "description": "Typed identifiers for a POST request." }, "score": { "type": "number", "minimum": 0, "maximum": 100, "description": "Explainable match score clamped to the 0-100 range." }, "rawScore": { "type": "number", "description": "Total match score before clamping." }, "matchQuality": { "$ref": "#/components/schemas/MatchQuality", "description": "Match quality derived from the score." }, "scoreDetails": { "type": "array", "items": { "$ref": "#/components/schemas/ScoreDetail" }, "description": "Fields and reasons that contributed to the score." }, "matchedFields": { "type": "array", "items": { "type": "string" }, "example": [ "primaryName", "identifier" ], "description": "Fields that matched the request." }, "explanation": { "$ref": "#/components/schemas/SearchExplanation", "description": "Field, collection and source-scope explanation for the match." } }, "description": "One candidate result with related records and explainable matching signals." }, "EntityRecord": { "type": "object", "properties": { "entityId": { "type": "string", "description": "Stable normalized entity id across source records." }, "type": { "$ref": "#/components/schemas/EntityType", "description": "Entity or identifier type." }, "primaryName": { "type": "string", "description": "Canonical primary name for the entity." }, "names": { "type": "array", "items": { "type": "string" }, "description": "Normalized names including the primary name." }, "gender": { "type": "string", "nullable": true, "description": "Optional gender value for person records." }, "birthDates": { "type": "array", "items": { "type": "string" }, "description": "Birth date values reported by official sources." }, "birthPlaces": { "type": "array", "items": { "type": "string" }, "description": "Birth place values reported by official sources." }, "nationalities": { "type": "array", "items": { "type": "string" }, "description": "Nationality values reported by official sources." }, "countries": { "type": "array", "items": { "type": "string" }, "description": "Country values associated with the entity." }, "pep": { "type": "boolean", "description": "Whether the record carries a PEP signal; this is not a legal conclusion." } }, "description": "Normalized person, organization, vessel, aircraft or other primary record." }, "SanctionRecord": { "type": "object", "properties": { "entityId": { "type": "string", "description": "Stable normalized entity id across source records." }, "source": { "type": "string", "description": "Canonical sanctions data source." }, "program": { "type": "string", "nullable": true, "description": "Sanctions program reported by the source." }, "regime": { "type": "string", "nullable": true, "description": "Sanctions regime reported by the source." }, "measures": { "type": "array", "items": { "type": "string" }, "description": "Measures or restrictions reported by the source." }, "listedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Date and time the source reports the record as listed." }, "modifiedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Last modification time reported by the source." }, "referenceId": { "type": "string", "description": "Official list or source record reference." } }, "description": "Official sanctions-list record associated with an entity." }, "AliasRecord": { "type": "object", "properties": { "entityId": { "type": "string", "description": "Stable normalized entity id across source records." }, "name": { "type": "string", "description": "Legal name, display name or known alias to search." }, "quality": { "type": "string", "enum": [ "primary", "aka", "low" ], "description": "Alias quality reported by the source." } }, "description": "Normalized alternate name associated with an entity." }, "AddressRecord": { "type": "object", "properties": { "entityId": { "type": "string", "description": "Stable normalized entity id across source records." }, "address": { "type": "string", "nullable": true, "description": "Free-text address reported by the source." }, "city": { "type": "string", "nullable": true, "description": "Address city." }, "region": { "type": "string", "nullable": true, "description": "Address region or administrative area." }, "country": { "type": "string", "nullable": true, "description": "Entity, identifier or address country." }, "postalCode": { "type": "string", "nullable": true, "description": "Address postal code." } }, "description": "Address associated with an entity by an official source." }, "IdentifierRecord": { "type": "object", "properties": { "entityId": { "type": "string", "description": "Stable normalized entity id across source records." }, "type": { "type": "string", "description": "Entity or identifier type." }, "value": { "type": "string", "description": "Identifier value." }, "country": { "type": "string", "nullable": true, "description": "Entity, identifier or address country." } }, "description": "Identity or registration number associated with an entity by an official source." }, "MatchQuality": { "type": "string", "enum": [ "very_strong", "strong", "medium", "weak", "none" ], "description": "Operational quality label derived from the numeric score." }, "ScoreDetail": { "type": "object", "properties": { "field": { "type": "string", "example": "primaryName", "description": "Field that matched, failed validation or contributed to the score." }, "score": { "type": "number", "example": 70, "description": "Explainable match score clamped to the 0-100 range." }, "reason": { "type": "string", "example": "exact_primary_name", "description": "Stable machine-readable reason for a score contribution." } }, "description": "Contribution of one field to the explainable matching score." }, "SearchExplanation": { "type": "object", "properties": { "matchedFields": { "type": "array", "items": { "type": "string" }, "description": "Fields that matched the request." }, "scoreDetails": { "type": "array", "items": { "$ref": "#/components/schemas/ScoreDetail" }, "description": "Fields and reasons that contributed to the score." }, "collectionsChecked": { "type": "array", "items": { "type": "object", "properties": { "collection": { "type": "string", "enum": [ "Entity", "Sanction", "Alias", "Identifier", "Address", "Source" ], "description": "Normalized collection that was checked." }, "fields": { "type": "array", "items": { "type": "string" }, "description": "Fields checked in the collection." }, "matched": { "type": "boolean", "description": "Whether the collection contributed to the match." } } }, "description": "Collections and fields checked by the search engine." }, "sourceScope": { "oneOf": [ { "type": "string", "enum": [ "all" ] }, { "type": "array", "items": { "type": "string" } } ], "description": "Requested or effective source scope." }, "matchedSources": { "type": "array", "items": { "type": "string" }, "description": "Canonical sources that matched." }, "references": { "type": "array", "items": { "$ref": "#/components/schemas/SanctionSummary" }, "description": "Limited official-source references." } }, "description": "Fields and sources that explain why a candidate matched." }, "SanctionSummary": { "type": "object", "properties": { "source": { "type": "string", "description": "Canonical sanctions data source." }, "program": { "type": "string", "nullable": true, "description": "Sanctions program reported by the source." }, "regime": { "type": "string", "nullable": true, "description": "Sanctions regime reported by the source." }, "referenceId": { "type": "string", "nullable": true, "description": "Official list or source record reference." }, "listedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Date and time the source reports the record as listed." } }, "description": "Limited official-source reference used in explanations." }, "LimitPolicy": { "type": "object", "properties": { "unlimited": { "type": "boolean", "default": true, "description": "Whether daily and monthly count limits are disabled." }, "dailyLimit": { "type": "integer", "nullable": true, "description": "Daily successful-request limit." }, "monthlyLimit": { "type": "integer", "nullable": true, "description": "Monthly successful-request limit." }, "maxPageSize": { "type": "integer", "default": 100, "description": "Maximum page size allowed by policy." }, "allowedSources": { "type": "array", "items": { "type": "string", "enum": [ "OFAC", "MASAK", "EU_RESTRICTED", "UK_HMT", "UN_CONSOLIDATED" ] }, "description": "Sources allowed by the key or institution policy." } }, "description": "Usage and source policy applied to an API key or institution." }, "ErrorResponse": { "type": "object", "required": [ "status", "code", "message" ], "properties": { "status": { "type": "boolean", "example": false, "description": "Whether the operation completed successfully." }, "code": { "type": "string", "description": "Stable code for programmatic error handling.", "enum": [ "validation_error", "missing_api_key", "invalid_api_key", "inactive_account", "unapproved_account", "access_restricted", "source_scope", "page_size_limit", "daily_limit", "monthly_limit", "rate_limit_exceeded", "service_unavailable", "internal_error" ], "example": "validation_error" }, "message": { "type": "string", "description": "Human-readable status or error message." }, "details": { "type": "array", "description": "Field-level validation details.", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Field that matched, failed validation or contributed to the score." }, "message": { "type": "string", "description": "Human-readable status or error message." }, "allowed": { "type": "array", "items": { "type": "string" }, "description": "Accepted values for the field." } } } } }, "description": "Machine-readable error envelope used by public API failures." }, "SearchQuery": { "type": "object", "required": [ "name" ], "description": "Normalized search request accepted as query parameters or a JSON body.", "example": { "name": "AEROCARIBBEAN AIRLINES", "type": "company", "sources": [ "OFAC" ], "page": 1, "pageSize": 10 }, "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 160, "description": "Legal name, display name or known alias to search.", "example": "AEROCARIBBEAN AIRLINES" }, "type": { "allOf": [ { "$ref": "#/components/schemas/EntityType" } ], "description": "Entity or identifier type." }, "gender": { "type": "string", "description": "Optional gender value for person records." }, "birthDate": { "type": "string", "pattern": "^\\d{4}(-\\d{2}(-\\d{2})?)?$", "description": "Birth date filter in YYYY, YYYY-MM or YYYY-MM-DD format." }, "nationality": { "type": "string", "description": "Nationality filter for person records." }, "country": { "type": "string", "description": "Entity, identifier or address country." }, "source": { "type": "string", "enum": [ "OFAC", "MASAK", "EU_RESTRICTED", "UK_HMT", "UN_CONSOLIDATED", "OFAC_SDN", "OFAC_ALT", "EU", "UK", "UN" ], "description": "Canonical sanctions data source." }, "sources": { "type": "array", "items": { "type": "string", "enum": [ "OFAC", "MASAK", "EU_RESTRICTED", "UK_HMT", "UN_CONSOLIDATED", "OFAC_SDN", "OFAC_ALT", "EU", "UK", "UN" ] }, "description": "Canonical data sources included in the search." }, "identifier": { "type": "string", "description": "Single identifier value for a GET request." }, "identifiers": { "type": "array", "items": { "$ref": "#/components/schemas/SearchIdentifier" }, "description": "Typed identifiers for a POST request." }, "page": { "type": "integer", "minimum": 1, "default": 1, "description": "One-based page number." }, "pageSize": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "description": "Requested or returned records per page." } } }, "SearchIdentifier": { "type": "object", "properties": { "type": { "type": "string", "example": "passport", "description": "Entity or identifier type." }, "value": { "type": "string", "example": "AA123456", "description": "Identifier value." } }, "description": "Typed identifier supplied with a search request." }, "PaginatedSearchLogs": { "allOf": [ { "$ref": "#/components/schemas/Status" }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SearchLogResponse" }, "description": "Records in this page." }, "pagination": { "$ref": "#/components/schemas/Pagination", "description": "Pagination metadata." } } } ], "description": "Paginated tenant search audit records." }, "SearchLogResponse": { "allOf": [ { "$ref": "#/components/schemas/Status" }, { "type": "object", "properties": { "_id": { "type": "string", "description": "Audit record id." }, "institutionId": { "type": "string", "description": "Authenticated tenant institution id." }, "apiKeyId": { "type": "string", "nullable": true, "description": "API key that made the request or is used as a filter." }, "userId": { "type": "string", "nullable": true, "description": "Tenant user that made the request." }, "searchType": { "type": "string", "enum": [ "public", "private" ], "description": "API-key public search or JWT tenant search." }, "query": { "$ref": "#/components/schemas/SearchQuery", "description": "Value of the `query` field." }, "success": { "type": "boolean", "description": "Whether the request completed successfully." }, "httpStatus": { "type": "integer", "description": "Recorded HTTP response status." }, "errorCode": { "type": "string", "nullable": true, "description": "Machine-readable failure code." }, "errorMessage": { "type": "string", "nullable": true, "description": "Safe failure summary." }, "actorType": { "type": "string", "enum": [ "apiKey", "user" ], "description": "API key or user actor type." }, "actorSnapshot": { "type": "object", "nullable": true, "properties": { "apiKeyId": { "type": "string", "description": "API key that made the request or is used as a filter." }, "label": { "type": "string", "nullable": true, "description": "User-provided API key label." }, "last4": { "type": "string", "nullable": true, "description": "Last four characters used to distinguish an API key." }, "userId": { "type": "string", "description": "Tenant user that made the request." }, "email": { "type": "string", "nullable": true, "description": "Tenant user email address." }, "fullName": { "type": "string", "nullable": true, "description": "Tenant user display name." } }, "description": "Limited actor snapshot without secrets." }, "resultSummary": { "type": "object", "properties": { "resultCount": { "type": "integer", "description": "Number of results returned by the search." }, "hasMatch": { "type": "boolean", "description": "Whether the search returned at least one candidate." }, "topScore": { "type": "number", "nullable": true, "description": "Highest result score." }, "topEntityName": { "type": "string", "nullable": true, "description": "Name of the highest-scoring entity." }, "topEntityId": { "type": "string", "nullable": true, "description": "Id of the highest-scoring entity." }, "matchedSources": { "type": "array", "items": { "type": "string" }, "description": "Canonical sources that matched." } }, "description": "Limited audit summary of a search result." }, "resultCount": { "type": "integer", "description": "Number of results returned by the search." }, "hasMatch": { "type": "boolean", "description": "Whether the search returned at least one candidate." }, "responseSnapshot": { "type": "object", "nullable": true, "description": "Search response snapshot returned only by the detail endpoint." }, "userAgent": { "type": "string", "nullable": true, "description": "Safely stored request user-agent." }, "ip": { "type": "string", "nullable": true, "description": "Request IP shown in the tenant report." }, "responseTime": { "type": "number", "description": "Request duration in milliseconds." }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Time when the audit record expires." }, "createdAt": { "type": "string", "format": "date-time", "description": "Record creation time." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Record update time." } } } ], "description": "One tenant-scoped search audit record." }, "Pagination": { "type": "object", "properties": { "page": { "type": "integer", "description": "One-based page number." }, "pageSize": { "type": "integer", "description": "Requested or returned records per page." }, "total": { "type": "integer", "description": "Total records matching the filters." }, "totalPages": { "type": "integer", "description": "Total number of pages." } }, "description": "Pagination metadata returned by list endpoints." }, "PaginatedApiKeyLogs": { "allOf": [ { "$ref": "#/components/schemas/Status" }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyLogResponse" }, "description": "Records in this page." }, "pagination": { "$ref": "#/components/schemas/Pagination", "description": "Pagination metadata." } } } ], "description": "Paginated API key access audit records." }, "ApiKeyLogResponse": { "allOf": [ { "$ref": "#/components/schemas/Status" }, { "type": "object", "properties": { "_id": { "type": "string", "description": "Audit record id." }, "institutionId": { "type": "string", "description": "Authenticated tenant institution id." }, "apiKeyId": { "type": "string", "nullable": true, "description": "API key that made the request or is used as a filter." }, "apiKeySnapshot": { "type": "object", "nullable": true, "properties": { "apiKeyId": { "type": "string", "description": "API key that made the request or is used as a filter." }, "label": { "type": "string", "nullable": true, "description": "User-provided API key label." }, "last4": { "type": "string", "nullable": true, "description": "Last four characters used to distinguish an API key." } }, "description": "Limited API key snapshot without secrets or hashes." }, "success": { "type": "boolean", "description": "Whether the request completed successfully." }, "errorType": { "type": "string", "enum": [ "missing_key", "invalid_key", "inactive_key", "inactive_institution", "unapproved_institution", "domain_restriction", "ip_restriction", "service_unavailable" ], "nullable": true, "description": "API key authentication or access error type." }, "errorMessage": { "type": "string", "nullable": true, "description": "Safe failure summary." }, "requestPath": { "type": "string", "description": "Requested API path." }, "requestUrl": { "type": "string", "nullable": true, "description": "Safe request URL summary returned only by the detail endpoint." }, "requestMethod": { "type": "string", "description": "HTTP method." }, "requestHeaders": { "type": "object", "description": "Redacted header summary returned only by the detail endpoint." }, "requestQuery": { "type": "object", "description": "Redacted query summary returned only by the detail endpoint." }, "requestBody": { "type": "object", "description": "Redacted body summary returned only by the detail endpoint." }, "host": { "type": "string", "nullable": true, "description": "Request host returned only by the detail endpoint." }, "origin": { "type": "string", "nullable": true, "description": "Origin header reported by the request." }, "referer": { "type": "string", "nullable": true, "description": "Referer header reported by the request." }, "userAgent": { "type": "string", "nullable": true, "description": "Safely stored request user-agent." }, "ip": { "type": "string", "nullable": true, "description": "Request IP shown in the tenant report." }, "responseTime": { "type": "number", "description": "Request duration in milliseconds." }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Time when the audit record expires." }, "createdAt": { "type": "string", "format": "date-time", "description": "Record creation time." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Record update time." } } } ], "description": "API key access audit record without secrets or key hashes." } } }, "paths": { "/public/search": { "get": { "operationId": "searchSanctionsGet", "tags": [ "Search" ], "summary": "Search sanctions with an API key", "description": "Search the normalized sanctions dataset with an API key. Domain and IP restrictions, source scope, page size and usage limits are enforced by policy. Explainability fields show why each candidate matched.", "security": [ { "apiKeyAuth": [] }, { "apiKeyAuthorization": [] } ], "parameters": [ { "name": "name", "in": "query", "required": true, "description": "Required legal name, display name or known alias to search.", "schema": { "type": "string", "minLength": 2, "maxLength": 160 }, "example": "AEROCARIBBEAN AIRLINES" }, { "name": "type", "in": "query", "description": "Optional entity type filter.", "schema": { "$ref": "#/components/schemas/EntityType" }, "example": "company" }, { "name": "gender", "in": "query", "description": "Optional gender filter for person records.", "schema": { "type": "string" } }, { "name": "birthDate", "in": "query", "description": "Optional birth date filter in YYYY, YYYY-MM or YYYY-MM-DD format.", "schema": { "type": "string", "pattern": "^\\d{4}(-\\d{2}(-\\d{2})?)?$" }, "example": "1980-05-12" }, { "name": "nationality", "in": "query", "description": "Optional nationality filter for person records.", "schema": { "type": "string" }, "example": "TR" }, { "name": "country", "in": "query", "description": "Optional entity or address country filter.", "schema": { "type": "string" }, "example": "TR" }, { "name": "source", "in": "query", "description": "Filter by requested or matched canonical source.", "schema": { "type": "string", "enum": [ "OFAC", "MASAK", "EU_RESTRICTED", "UK_HMT", "UN_CONSOLIDATED", "OFAC_SDN", "OFAC_ALT", "EU", "UK", "UN" ] }, "example": "OFAC" }, { "name": "sources", "in": "query", "description": "Optional multiple source filter.", "schema": { "type": "string" } }, { "name": "identifier", "in": "query", "description": "Optional single identifier value for GET requests.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "One-based page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "pageSize", "in": "query", "description": "Results per page, capped by the API key policy.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" }, "example": { "status": true, "total": 1, "page": 1, "pageSize": 10, "results": [ { "entity": { "entityId": "OFAC-12345", "type": "company", "primaryName": "AEROCARIBBEAN AIRLINES", "names": [ "AEROCARIBBEAN AIRLINES" ], "countries": [ "CU" ], "pep": false }, "sanctions": [ { "entityId": "OFAC-12345", "source": "OFAC", "program": "CUBA", "regime": null, "measures": [ "asset_freeze" ], "listedAt": null, "modifiedAt": null, "referenceId": "12345" } ], "aliases": [], "addresses": [], "identifiers": [], "score": 70, "rawScore": 70, "matchQuality": "strong", "scoreDetails": [ { "field": "primaryName", "score": 70, "reason": "exact_primary_name" } ], "matchedFields": [ "primaryName" ] } ], "meta": { "institutionId": "665f00000000000000000001", "apiKeyId": "665f00000000000000000002" } } } } }, "400": { "description": "Invalid or missing request data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": false, "code": "validation_error", "message": "Geçersiz arama sorgusu", "details": [ { "field": "sources", "message": "Desteklenmeyen kaynak: UNKNOWN", "allowed": [ "OFAC", "MASAK", "EU_RESTRICTED", "UK_HMT", "UN_CONSOLIDATED" ] } ] } } } }, "401": { "description": "Authentication is missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": false, "code": "missing_api_key", "message": "API anahtarı gerekli" } } } }, "403": { "description": "Account, permission, source scope, domain or IP restriction failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": false, "code": "access_restricted", "message": "Bu domain veya IP adresinden erişim izni yok" } } } }, "429": { "description": "Usage, rate or page size limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": false, "code": "daily_limit", "message": "Günlük API sorgu limiti aşıldı" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": false, "code": "internal_error", "message": "Arama yapılamadı" } } } }, "503": { "description": "Temporary service dependency failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": false, "code": "service_unavailable", "message": "API servisi geçici olarak hazır değil" } } } } } }, "post": { "operationId": "searchSanctions", "tags": [ "Search" ], "summary": "Search sanctions with a JSON body", "description": "Recommended for multiple identifiers, multiple source filters or a structured JSON request.", "security": [ { "apiKeyAuth": [] }, { "apiKeyAuthorization": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchQuery" }, "example": { "name": "Example Person", "type": "person", "birthDate": "1980-05-12", "country": "TR", "identifiers": [ { "type": "passport", "value": "AA123456" } ], "pageSize": 10 } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" }, "example": { "status": true, "total": 1, "page": 1, "pageSize": 10, "results": [ { "entity": { "entityId": "OFAC-12345", "type": "company", "primaryName": "AEROCARIBBEAN AIRLINES", "names": [ "AEROCARIBBEAN AIRLINES" ], "countries": [ "CU" ], "pep": false }, "sanctions": [ { "entityId": "OFAC-12345", "source": "OFAC", "program": "CUBA", "regime": null, "measures": [ "asset_freeze" ], "listedAt": null, "modifiedAt": null, "referenceId": "12345" } ], "aliases": [], "addresses": [], "identifiers": [], "score": 70, "rawScore": 70, "matchQuality": "strong", "scoreDetails": [ { "field": "primaryName", "score": 70, "reason": "exact_primary_name" } ], "matchedFields": [ "primaryName" ] } ], "meta": { "institutionId": "665f00000000000000000001", "apiKeyId": "665f00000000000000000002" } } } } }, "400": { "description": "Invalid or missing request data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": false, "code": "validation_error", "message": "Geçersiz arama sorgusu", "details": [ { "field": "sources", "message": "Desteklenmeyen kaynak: UNKNOWN", "allowed": [ "OFAC", "MASAK", "EU_RESTRICTED", "UK_HMT", "UN_CONSOLIDATED" ] } ] } } } }, "401": { "description": "Authentication is missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": false, "code": "missing_api_key", "message": "API anahtarı gerekli" } } } }, "403": { "description": "Account, permission, source scope, domain or IP restriction failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": false, "code": "access_restricted", "message": "Bu domain veya IP adresinden erişim izni yok" } } } }, "429": { "description": "Usage, rate or page size limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": false, "code": "daily_limit", "message": "Günlük API sorgu limiti aşıldı" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": false, "code": "internal_error", "message": "Arama yapılamadı" } } } }, "503": { "description": "Temporary service dependency failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": false, "code": "service_unavailable", "message": "API servisi geçici olarak hazır değil" } } } } } } }, "/api/search-logs": { "get": { "operationId": "listSearchLogs", "tags": [ "Search Logs" ], "summary": "List tenant search logs", "description": "Tenant admins can list search audit records from their own institution. Response snapshots are excluded from list rows.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "description": "One-based page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "pageSize", "in": "query", "description": "Results per page, capped by the API key policy.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "dateFrom", "in": "query", "description": "Start date filter in ISO date format.", "schema": { "type": "string", "format": "date" } }, { "name": "dateTo", "in": "query", "description": "End date filter in ISO date format.", "schema": { "type": "string", "format": "date" } }, { "name": "searchType", "in": "query", "schema": { "type": "string", "enum": [ "public", "private" ] }, "description": "Filter API key searches or tenant JWT searches." }, { "name": "success", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "Filter successful or failed records." }, { "name": "hasMatch", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "Filter records by whether the search returned a match." }, { "name": "apiKeyId", "in": "query", "schema": { "type": "string" }, "description": "Filter by API key id." }, { "name": "userId", "in": "query", "schema": { "type": "string" }, "description": "Filter by user id." }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Free-text search across query, actor and top matched entity fields." }, { "name": "source", "in": "query", "schema": { "type": "string", "enum": [ "OFAC", "MASAK", "EU_RESTRICTED", "UK_HMT", "UN_CONSOLIDATED" ] }, "description": "Filter by requested or matched canonical source." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedSearchLogs" } } } }, "400": { "description": "Invalid or missing request data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Account, permission, source scope, domain or IP restriction failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Record not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/search-logs/{logId}": { "get": { "operationId": "getSearchLog", "tags": [ "Search Logs" ], "summary": "Get a search log detail", "description": "Tenant admins can inspect one search audit record from their own institution, including its response snapshot.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "logId", "in": "path", "required": true, "description": "Audit log id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchLogResponse" } } } }, "400": { "description": "Invalid or missing request data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Account, permission, source scope, domain or IP restriction failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Record not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/api-key-logs": { "get": { "operationId": "listApiKeyLogs", "tags": [ "API Key Logs" ], "summary": "List tenant API key request logs", "description": "Tenant admins can list API key authentication and access records from their own institution.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "description": "One-based page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "pageSize", "in": "query", "description": "Results per page, capped by the API key policy.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "dateFrom", "in": "query", "description": "Start date filter in ISO date format.", "schema": { "type": "string", "format": "date" } }, { "name": "dateTo", "in": "query", "description": "End date filter in ISO date format.", "schema": { "type": "string", "format": "date" } }, { "name": "success", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "Filter successful or failed records." }, { "name": "errorType", "in": "query", "schema": { "type": "string", "enum": [ "missing_key", "invalid_key", "inactive_key", "inactive_institution", "unapproved_institution", "domain_restriction", "ip_restriction", "service_unavailable" ] }, "description": "Filter by API key access error type." }, { "name": "apiKeyId", "in": "query", "schema": { "type": "string" }, "description": "Filter by API key id." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedApiKeyLogs" } } } }, "400": { "description": "Invalid or missing request data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Account, permission, source scope, domain or IP restriction failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Record not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/api-key-logs/{logId}": { "get": { "operationId": "getApiKeyLog", "tags": [ "API Key Logs" ], "summary": "Get an API key log detail", "description": "Tenant admins can inspect one API key access record from their own institution.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "logId", "in": "path", "required": true, "description": "Audit log id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyLogResponse" } } } }, "400": { "description": "Invalid or missing request data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication is missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Account, permission, source scope, domain or IP restriction failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Record not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } } }