openapi: 3.2.0 info: title: SanctionsKit Usage API version: 1.0.0 description: Explore success and error examples without an account or API key. Recorded examples use isolated synthetic application data; remaining examples are labeled contract fixtures. Potential-match screening is for review. No-match is limited to selected, qualified sources. Sandbox uses synthetic records and is never billed. Each successfully completed subject consumes one allowance unit, including monitoring rescreens. Failed rows and idempotent retries do not consume additional units. servers: - url: /api/v1 description: This site origin; deployment configuration and access rules apply tags: - name: Usage paths: /usage: get: operationId: get__usage summary: Read period allowance, used subjects and pending reservations tags: - Usage description: 'Required API key scope: usage:read.' security: - bearerAuth: [] parameters: [] responses: '200': headers: X-Request-Id: description: Server-generated request correlation identifier. schema: type: string format: uuid description: Successful response. JSON object with the required data key. All properties marked required are present, including keys whose value may be null. Unmarked properties can be omitted; clients should tolerate additional response properties. content: application/json: examples: recorded_inactive_subscription: summary: Storage remains visible after subscription access ends; new production allowance is zero description: Recorded from the real application handler against an isolated synthetic database. IDs, times and nonfunctional temporary secrets are normalized. No customer data or live provider request. value: data: environment: production period: 2026-09 used: 0 reserved: 0 limit: 0 planLimit: 0 spendingCap: 0 effectiveLimit: 0 remaining: 0 plan: inactive events: [] fileStorage: plan: sandbox maxBytes: 104857600 usedBytes: 0 reservedBytes: 0 remainingBytes: 104857600 sandbox: maxBytes: 104857600 usedBytes: 0 reservedBytes: 0 remainingBytes: 104857600 maxBatchUploadBytes: 26214400 maxEvidenceAttachmentBytes: 200000 monitoringForecast: null forecastUnavailable: subscription_required recorded_sandbox: summary: Synthetic sandbox usage is not billed description: Recorded from the real application handler against an isolated synthetic database. IDs, times and nonfunctional temporary secrets are normalized. No customer data or live provider request. value: data: environment: sandbox period: 2026-09 used: 3 reserved: 0 limit: 100 planLimit: 100 spendingCap: 0 effectiveLimit: 100 remaining: 97 plan: sandbox events: - kind: screening subjects: 3 fileStorage: plan: sandbox maxBytes: 104857600 usedBytes: 0 reservedBytes: 0 remainingBytes: 104857600 sandbox: maxBytes: 104857600 usedBytes: 0 reservedBytes: 0 remainingBytes: 104857600 maxBatchUploadBytes: 26214400 maxEvidenceAttachmentBytes: 200000 monitoringForecast: generatedAt: '2026-09-17T12:00:00.000Z' periodEnd: '2026-09-17T12:00:00.000Z' dailyScreenings: 0 projectedRemainingScreenings: 14 effectiveLimit: 100 used: 3 reserved: 0 remaining: 97 projectedExhaustionAt: null forecastUnavailable: null schema: type: object required: - data properties: data: $ref: '#/components/schemas/Usage' '400': headers: X-Request-Id: schema: type: string format: uuid description: Server-generated correlation identifier, also returned in error.requestId. description: '**invalid_request** — Correct the request fields, resource identifiers, JSON body or query parameters before retrying.' content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_request: summary: invalid request description: Synthetic error example. Correct the request fields, resource identifiers, JSON body or query parameters before retrying. value: error: code: invalid_request message: The request is invalid. requestId: 01234567-89ab-4cde-8f01-23456789abcd '401': headers: X-Request-Id: schema: type: string format: uuid description: Server-generated correlation identifier, also returned in error.requestId. WWW-Authenticate: schema: type: string description: Bearer authentication challenge. description: '**authentication_required** — Send Authorization: Bearer with a valid API key. An omitted header can produce authentication_required; invalid supplied credentials produce invalid_api_key. **invalid_api_key** — Use an active key for the intended environment.' content: application/json: schema: $ref: '#/components/schemas/Error' examples: authentication_required: summary: authentication required description: 'Synthetic error example. Send Authorization: Bearer with a valid API key. An omitted header can produce authentication_required; invalid supplied credentials produce invalid_api_key.' value: error: code: authentication_required message: Sign in to continue. requestId: 01234567-89ab-4cde-8f01-23456789abcd invalid_api_key: summary: invalid api key description: Synthetic error example. Use an active key for the intended environment. value: error: code: invalid_api_key message: The API key is invalid, expired, or revoked. requestId: 01234567-89ab-4cde-8f01-23456789abcd '402': headers: X-Request-Id: schema: type: string format: uuid description: Server-generated correlation identifier, also returned in error.requestId. description: '**subscription_required** — Use the synthetic sandbox or arrange an active production subscription before retrying.' content: application/json: schema: $ref: '#/components/schemas/Error' examples: subscription_required: summary: subscription required description: Synthetic error example. Use the synthetic sandbox or arrange an active production subscription before retrying. value: error: code: subscription_required message: An active subscription is required for production screening. requestId: 01234567-89ab-4cde-8f01-23456789abcd '403': headers: X-Request-Id: schema: type: string format: uuid description: Server-generated correlation identifier, also returned in error.requestId. description: '**permission_denied** — Ask an organization owner to grant the required role or API-key scope. **insufficient_scope** — Use a key with the scope stated in this operation.' content: application/json: schema: $ref: '#/components/schemas/Error' examples: permission_denied: summary: permission denied description: Synthetic error example. Ask an organization owner to grant the required role or API-key scope. value: error: code: permission_denied message: Your role does not allow this action. requestId: 01234567-89ab-4cde-8f01-23456789abcd insufficient_scope: summary: insufficient scope description: Synthetic error example. Use a key with the scope stated in this operation. value: error: code: insufficient_scope message: The API key does not grant this action. requestId: 01234567-89ab-4cde-8f01-23456789abcd '405': headers: X-Request-Id: schema: type: string format: uuid description: Server-generated correlation identifier, also returned in error.requestId. Allow: schema: type: string description: Comma-separated supported HTTP methods. description: '**method_not_allowed** — Use a method in the Allow response header. OPTIONS lists supported methods; HEAD follows GET authorization and returns no body.' content: application/json: schema: $ref: '#/components/schemas/Error' examples: method_not_allowed: summary: method not allowed description: Synthetic error example. Use a method in the Allow response header. OPTIONS lists supported methods; HEAD follows GET authorization and returns no body. value: error: code: method_not_allowed message: This method is not supported for this endpoint. requestId: 01234567-89ab-4cde-8f01-23456789abcd '413': headers: X-Request-Id: schema: type: string format: uuid description: Server-generated correlation identifier, also returned in error.requestId. description: '**response_too_large** — Reduce the requested page size or use the documented segmented case archive. No evidence is silently truncated.' content: application/json: schema: $ref: '#/components/schemas/Error' examples: response_too_large: summary: response too large description: Synthetic error example. Reduce the requested page size or use the documented segmented case archive. No evidence is silently truncated. value: error: code: response_too_large message: This response exceeds the size limit. Request a smaller page or a segmented export. requestId: 01234567-89ab-4cde-8f01-23456789abcd '429': headers: X-Request-Id: schema: type: string format: uuid description: Server-generated correlation identifier, also returned in error.requestId. Retry-After: schema: type: string description: When present, a delay in seconds or an HTTP-date before which the client should not retry. Service-unavailable responses default to a one-second delay unless another safe value is supplied. A usage allowance error may require quota recovery instead of retrying. description: '**rate_limited** — Wait for the request window to reset and retry with backoff.' content: application/json: schema: $ref: '#/components/schemas/Error' examples: rate_limited: summary: rate limited description: Synthetic error example. Wait for the request window to reset and retry with backoff. value: error: code: rate_limited message: The per-minute request limit has been reached. requestId: 01234567-89ab-4cde-8f01-23456789abcd '500': headers: X-Request-Id: schema: type: string format: uuid description: Server-generated correlation identifier, also returned in error.requestId. description: '**internal_error** — Retry with backoff. For writes reuse the same idempotency key and identical input; include requestId when contacting support.' content: application/json: schema: $ref: '#/components/schemas/Error' examples: internal_error: summary: internal error description: Synthetic error example. Retry with backoff. For writes reuse the same idempotency key and identical input; include requestId when contacting support. value: error: code: internal_error message: The request could not be completed. requestId: 01234567-89ab-4cde-8f01-23456789abcd '503': headers: X-Request-Id: schema: type: string format: uuid description: Server-generated correlation identifier, also returned in error.requestId. Retry-After: schema: type: string description: When present, a delay in seconds or an HTTP-date before which the client should not retry. Service-unavailable responses default to a one-second delay unless another safe value is supplied. A usage allowance error may require quota recovery instead of retrying. description: '**temporarily_unavailable** — Honor Retry-After when present and retry with bounded backoff. Follow this endpoint’s retry contract; preserve the same key and input for idempotent writes. Contact support with requestId if the failure persists.' content: application/json: schema: $ref: '#/components/schemas/Error' examples: temporarily_unavailable: summary: temporarily unavailable description: Synthetic error example. Honor Retry-After when present and retry with bounded backoff. Follow this endpoint’s retry contract; preserve the same key and input for idempotent writes. Contact support with requestId if the failure persists. value: error: code: temporarily_unavailable message: The service is temporarily unavailable. Retry shortly. requestId: 01234567-89ab-4cde-8f01-23456789abcd components: schemas: Error: type: object required: - error description: Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change. properties: error: type: object required: - code - message - requestId properties: code: type: string description: Machine-readable failure code. See this operation’s status-specific examples for codes and recovery. message: type: string description: Human-readable explanation. Do not parse this text to control application behavior. requestId: type: string format: uuid description: Server correlation ID, also returned in X-Request-Id. Include this ID in support requests. details: description: Optional JSON details for client and validation failures. Validation failures return an array of { path, message } issues; other 4xx codes may return a code-specific object. Server failures omit details. Never assume this key is present. anyOf: - type: array maxItems: 50 items: type: object required: - path - message properties: path: type: string maxLength: 160 description: Dot-separated invalid field path, including array indexes. message: type: string maxLength: 300 description: Validation problem for this field. - type: object additionalProperties: true - type: - string - number - boolean - 'null' detailsTruncated: type: boolean description: True when only the first 50 validation issues are returned. Validation paths and messages are bounded. MonitoringForecast: type: object properties: generatedAt: type: string format: date-time periodEnd: type: string format: date-time dailyScreenings: type: number minimum: 0 projectedRemainingScreenings: type: integer minimum: 0 effectiveLimit: type: integer minimum: 0 used: type: integer minimum: 0 reserved: type: integer minimum: 0 remaining: type: integer minimum: 0 projectedExhaustionAt: anyOf: - type: string format: date-time - type: 'null' required: - generatedAt - periodEnd - dailyScreenings - projectedRemainingScreenings - effectiveLimit - used - reserved - remaining - projectedExhaustionAt Usage: type: object properties: environment: type: string enum: - sandbox - production period: type: string used: type: integer minimum: 0 reserved: type: integer minimum: 0 limit: type: integer minimum: 0 planLimit: type: integer minimum: 0 spendingCap: type: integer minimum: 0 effectiveLimit: type: integer minimum: 0 remaining: type: integer minimum: 0 plan: type: string events: type: array items: type: object properties: kind: type: string subjects: type: integer minimum: 0 required: - kind - subjects fileStorage: $ref: '#/components/schemas/FileStorage' monitoringForecast: anyOf: - $ref: '#/components/schemas/MonitoringForecast' - type: 'null' forecastUnavailable: anyOf: - type: string - type: 'null' required: - environment - period - used - reserved - limit - planLimit - spendingCap - effectiveLimit - remaining - plan - events - fileStorage - monitoringForecast - forecastUnavailable FileStorage: type: object properties: plan: type: string maxBytes: type: integer minimum: 0 usedBytes: type: integer minimum: 0 reservedBytes: type: integer minimum: 0 remainingBytes: type: integer minimum: 0 sandbox: type: object properties: maxBytes: type: integer minimum: 0 usedBytes: type: integer minimum: 0 reservedBytes: type: integer minimum: 0 remainingBytes: type: integer minimum: 0 required: - maxBytes - usedBytes - reservedBytes - remainingBytes maxBatchUploadBytes: type: integer minimum: 0 maxEvidenceAttachmentBytes: type: integer minimum: 0 required: - plan - maxBytes - usedBytes - reservedBytes - remainingBytes - sandbox - maxBatchUploadBytes - maxEvidenceAttachmentBytes securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: sk_test_... or sk_live_... x-docs-revision: 499779e00214c23622695c6d7114fb3656edf29161460d9f9e9d2ab65d0cf087 x-provenance: method: harvested publisher: SanctionsKit source: https://www.sanctionskit.com/openapi.json note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json); stamped by stamp-openapi-provenance.py (roadmap#793)