openapi: 3.1.0
info:
  title: ThreatPrevent API
  version: 1.0.0
  description: >
    Real-time Cyber Trust Intelligence for payment, supply-chain and
    infrastructure decision workflows.
servers:
  - url: https://api.threatprevent.io
security:
  - ApiKeyAuth: []
  - OAuth2: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
    OAuth2:
      type: oauth2
      description: >
        Use Client Credentials for server-to-server access or Authorization Code
        with PKCE for user-authorised applications. Device Flow is documented at
        /developers/oauth/device-flow.
      flows:
        clientCredentials:
          tokenUrl: https://api.threatprevent.io/oauth/token
          scopes:
            risk:payment: Call payment-risk endpoints
            risk:supply-chain: Call supply-chain-risk endpoints
            risk:infrastructure: Call infrastructure-risk endpoints
            risk:bulk: Call bulk risk endpoints
            billing:read: Read billing resources
            billing:write: Change billing resources
            organisation:read: Read organisation resources
            organisation:write: Change organisation resources
        authorizationCode:
          authorizationUrl: https://api.threatprevent.io/oauth/authorize
          tokenUrl: https://api.threatprevent.io/oauth/token
          scopes:
            openid: Request an OpenID Connect ID token
            profile: Request profile claims
            email: Request email claims
            offline_access: Request refresh-token access
            risk:payment: Call payment-risk endpoints
            risk:supply-chain: Call supply-chain-risk endpoints
            risk:infrastructure: Call infrastructure-risk endpoints
            risk:bulk: Call bulk risk endpoints
  schemas:
    BillingMetadata:
      type: object
      properties:
        charged:
          type: boolean
        is_free:
          type: boolean
        unit_price_pence:
          type: integer
        billable_units:
          type: integer
        total_price_pence:
          type: integer
        charged_from_credit_pence:
          type: integer
        overage_pence:
          type: integer
        remaining_credit_pence:
          type: integer
paths:
  /v1/payment-risk:
    post:
      summary: Evaluate one email address for payment risk
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email]
              properties:
                email:
                  type: string
                  format: email
      responses:
        "200":
          description: Risk result
        "401":
          description: Invalid or missing API key
        "403":
          description: Disabled or inactive account
        "502":
          description: Risk service unavailable
  /v1/payment-risk/bulk:
    post:
      summary: Evaluate multiple email addresses for payment risk
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [emails]
              properties:
                emails:
                  type: array
                  minItems: 1
                  maxItems: 10000
                  items:
                    type: string
                    format: email
      responses:
        "200":
          description: Bulk risk results
  /v1/supply-chain-risk:
    post:
      summary: Evaluate one domain for supply-chain risk
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [domain]
              properties:
                domain:
                  type: string
      responses:
        "200":
          description: Risk result
  /v1/supply-chain-risk/bulk:
    post:
      summary: Evaluate multiple domains for supply-chain risk
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [domains]
              properties:
                domains:
                  type: array
                  minItems: 1
                  maxItems: 10000
                  items:
                    type: string
      responses:
        "200":
          description: Bulk risk results
  /v1/infrastructure-risk:
    post:
      summary: Evaluate one IP address for infrastructure risk
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [ip]
              properties:
                ip:
                  type: string
      responses:
        "200":
          description: Risk result
  /v1/infrastructure-risk/bulk:
    post:
      summary: Evaluate multiple IP addresses for infrastructure risk
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [ips]
              properties:
                ips:
                  type: array
                  minItems: 1
                  maxItems: 10000
                  items:
                    type: string
      responses:
        "200":
          description: Bulk risk results