kawaa-com Health API

openapi: 3.2.0
info:
  title: Kawaa Health API
  version: 1.0.0
  summary: Email verification, list hygiene and deliverability, over HTTP.
  description: 'The core Kawaa REST API: verify an address or a list, follow the job, read the results, and check how a domain is set up to send mail. This document describes the endpoints a customer integration uses. It is not the whole surface: profile and security settings (password, two-factor, sessions), billing and subscription changes and team management are reachable but not modelled here, because a specification is only worth having if every line of it is kept true, and they have no page at https://kawaa.com/docs/ yet either. Some operations that do have a page there are not modelled here either, and that page is their only reference: the white-label API (`POST /v1/white-label/sub-accounts`, `GET /v1/white-label/sub-accounts`, `GET /v1/white-label/sub-accounts/{subAccountId}`, `PUT /v1/white-label/sub-accounts/{subAccountId}`, `DELETE /v1/white-label/sub-accounts/{subAccountId}`, `POST /v1/white-label/sub-accounts/{subAccountId}/allocate`, `POST /v1/white-label/sub-accounts/{subAccountId}/reset-key`, `GET /v1/white-label/usage`, `GET /v1/white-label/usage/{subAccountId}`, `GET /v1/white-label/custom-domain`, `POST /v1/white-label/custom-domain`, `POST /v1/white-label/custom-domain/verify` and `DELETE /v1/white-label/custom-domain`) at https://kawaa.com/docs/api/white-label/, the domain activity lookup (`GET /v1/activity/domain/{domain}`) at https://kawaa.com/docs/api/activity/#domain-activity, and the tracking links (`POST /v1/tracking/links` and `PUT /v1/tracking/links/{id}`), whose limits are at https://kawaa.com/docs/api/activity/#tracking-link-limits. The HubSpot, Salesforce and Mailchimp integrations are not available yet: their authorize routes answer 503 `INTEGRATION_NOT_CONFIGURED`, so no account can connect one. The guides at https://kawaa.com/docs/ cover verification, batch jobs, account and API keys, webhooks, activity, deliverability and the white-label API; the email finder (`POST /v1/find`, `POST /v1/find/bulk`), the domain lookup (`GET /v1/domain/{domain}`) and the billing catalogue (`GET /v1/billing/plans`, `GET /v1/billing/credit-packages`) are described only in this document. **API key scopes.** A key can be limited to a list of scopes. Each operation below carries `x-kawaa-scopes` naming every scope it requires (more than one where a route genuinely touches two areas). `x-kawaa-unscoped-only: true` marks an operation a scoped key may not use at all, whatever it holds: it mints a credential, or it acts across every tenant. An operation with neither extension needs no credential. An unrestricted key (which is what every key is unless it was created with scopes) reaches everything. An OAuth access token is always scoped: an operation it can call lists the `OAuth2` scheme in its `security`, with the scopes it requires, and an authenticated operation that does not list it refuses one whatever scopes it holds. **Rate-limit headers.** Once a request''s credential is accepted and its rate limit measured, every response to it, success or error, carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `X-RateLimit-Window` and `X-RateLimit-Policy` (described under `components/headers`). They are declared on the success and `429` responses below rather than repeated on every status. **Answers that do not come from Kawaa.** A few failures are answered by the gateway in front of the API rather than by Kawaa, and carry no error envelope, so there is no `error.code` to branch on: read the status. A request still running when its route''s time limit at the gateway runs out (about 29 to 30 seconds on most routes, every route that charges credits included; 15 seconds on `GET /v1/account`, the `/v1/api-keys` routes, `GET /v1/jobs`, `GET /v1/jobs/{id}` and `POST /v1/jobs/{id}/cancel`; 5 seconds on `GET /health`), or one the gateway could not hand over, is a `503` whose whole body is `{"message":"Service Unavailable"}`; the request may still have run, so repeat a charging call only with the same `Idempotency-Key`.'
  termsOfService: https://kawaa.com/terms/
  contact:
    name: Kawaa support
    url: https://kawaa.com/support/
    email: support@kawaa.com
  license:
    name: Proprietary
    identifier: LicenseRef-Kawaa-Terms
servers:
- url: https://api.kawaa.com
  description: Production
security:
- ApiKeyHeader: []
- BearerToken: []
tags:
- name: Health
  description: Is the API up.
paths:
  /health:
    get:
      tags:
      - Health
      operationId: getHealth
      summary: Liveness probe
      description: 'Answers without authentication. Not a status page: https://status.kawaa.com reports component health.'
      security: []
      responses:
        default:
          $ref: '#/components/responses/Default'
        '200':
          description: 'The API is serving, but **read `status` in the body before concluding it is healthy**. A degraded dependency does not always change the status code: a worker dead-letter-queue probe that fails or reads above its threshold sets `status: "degraded"` and the response is still 200. A monitor that watches only the status code misses worker degradation entirely.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    examples:
                    - healthy
                  timestamp:
                    type: string
                    format: date-time
                  service:
                    type: string
                  version:
                    type: string
                required:
                - status
                - timestamp
                - service
                - version
        '503':
          description: 'A dependency probe failed: the SAME JSON shape as 200, with `status: "degraded"`. A monitor that treats only 200 as a valid response stops reading precisely when the endpoint has something to say. A 503 whose whole body is `{"message":"Service Unavailable"}` is not this report: the gateway in front of the API answered it (`GatewayError`), and it has no `status` field.'
          content:
            application/json:
              schema:
                oneOf:
                - type: object
                  properties:
                    status:
                      type: string
                      const: degraded
                      description: Always `degraded` on a 503; this response exists to report one.
                      examples:
                      - degraded
                    timestamp:
                      type: string
                      format: date-time
                    service:
                      type: string
                    version:
                      type: string
                  required:
                  - status
                  - timestamp
                  - service
                  - version
                - $ref: '#/components/schemas/GatewayError'
components:
  schemas:
    GatewayError:
      type: object
      description: 'An answer from the gateway in front of the API, with no error envelope and so no code to branch on: read the status. `{"message":"Request Entity Too Large"}` (413, a body over about 6 MB) and `{"message":"Bad Request"}` (400, a path with malformed percent-encoding) never reached Kawaa: nothing was run or charged. `{"message":"Service Unavailable"}` (503) is different: it is also what a request still running when its route''s time limit at the gateway runs out gets (about 29 to 30 seconds on every route that charges credits, 15 on `GET /v1/account`, the `/v1/api-keys` routes, `GET /v1/jobs`, `GET /v1/jobs/{id}` and `POST /v1/jobs/{id}/cancel`, 5 on `/health`), and that request may have finished, and been charged, after the gateway gave up on it. Repeat a charging call after this 503 only with the same `Idempotency-Key`; without one, a repeat can be charged again.'
      required:
      - message
      properties:
        message:
          type: string
          examples:
          - Service Unavailable
          - Request Entity Too Large
          - Bad Request
    ErrorCode:
      type: string
      description: 'The machine-readable reason. NOT a closed set: handlers add codes, and a client that refuses an unfamiliar one rejects ordinary API errors instead of handling them. Branch on the codes you know and fall back to the HTTP status. `examples` lists every code this build''s handlers can return in an error envelope, whether passed to `error(...)` or written into a response body as `{code, message}`, including some from routes this document does not describe, because a client can still meet them. `TEAM_DELETION_IN_PROGRESS` is the odd one: it arrives with `202`, on a deletion that is proceeding rather than failing.'
      examples:
      - ANALYTICS_COVERAGE_UNAVAILABLE
      - API_KEY_REVOKED
      - API_KEY_SUSPENDED
      - AUTOCLEAN_RULES_NOT_APPLIED
      - AUTOCLEAN_SOURCE_INCOMPLETE
      - AUTOCLEAN_UNAVAILABLE
      - BAD_REQUEST
      - BATCH_SIZE_EXCEEDED
      - CHANNEL_NOT_CONFIGURED
      - CONFLICT
      - CRM_CONNECTION_CHANGED
      - CRM_RECOVERY_PENDING
      - CRM_STATE_UNAVAILABLE
      - CRM_UPDATE_UNCERTAIN
      - CROSS_SITE_SESSION_REFUSED
      - EMAIL_VERIFICATION_REQUIRED
      - EXPORT_EXPIRED
      - FORBIDDEN
      - GATEWAY_TIMEOUT
      - HUBSPOT_API_ERROR
      - HUBSPOT_AUTH_FAILED
      - HUBSPOT_CONNECTION_CHANGED
      - HUBSPOT_FORBIDDEN
      - HUBSPOT_INACTIVE
      - HUBSPOT_NOT_CONNECTED
      - HUBSPOT_NOT_INITIALIZED
      - HUBSPOT_NO_TOKEN
      - HUBSPOT_RATE_LIMIT_EXCEEDED
      - HUBSPOT_REAUTH_REQUIRED
      - HUBSPOT_STATE_UNAVAILABLE
      - HUBSPOT_TOKEN_REFRESH_FAILED
      - IDEMPOTENCY_KEY_CONFLICT
      - IDEMPOTENT_JOB_EXPIRED
      - INSUFFICIENT_CREDITS
      - INSUFFICIENT_SCOPE
      - INTEGRATION_NOT_CONFIGURED
      - INTEGRATION_NOT_ENABLED
      - INTERNAL_ERROR
      - INVALID_CURSOR
      - INVALID_IDEMPOTENCY_KEY
      - INVALID_OFFSET
      - INVALID_OPTION
      - INVALID_WEBHOOK_SECRET
      - MAILCHIMP_API_ERROR
      - MAILCHIMP_CONNECTION_CHANGED
      - MAILCHIMP_FORBIDDEN
      - MAILCHIMP_INACTIVE
      - MAILCHIMP_NOT_CONNECTED
      - MAILCHIMP_NOT_INITIALIZED
      - MAILCHIMP_RATE_LIMIT_EXCEEDED
      - MAILCHIMP_REAUTH_REQUIRED
      - MAILCHIMP_STATE_UNAVAILABLE
      - MAILCHIMP_TOKEN_INVALID
      - METHOD_NOT_ALLOWED
      - NOT_FOUND
      - NOT_IMPLEMENTED
      - NO_VALID_FIELDS
      - OAUTH_TOKEN_EXPIRED
      - PASSWORD_SETUP_REQUIRED
      - PAYLOAD_TOO_LARGE
      - PAYMENT_REQUIRED
      - PLAN_LIMIT_EXCEEDED
      - PLAN_UPGRADE_REQUIRED
      - QUOTA_ALERTS_NOT_CONFIGURABLE
      - RATE_LIMITED
      - REAUTHENTICATION_REQUIRED
      - REGISTRATION_PASSWORD_MISMATCH
      - RESET_TOKEN_INVALID
      - RESULT_SUPERSEDED
      - SALESFORCE_API_ERROR
      - SALESFORCE_AUTH_FAILED
      - SALESFORCE_CONNECTION_CHANGED
      - SALESFORCE_FORBIDDEN
      - SALESFORCE_INACTIVE
      - SALESFORCE_INVALID_CAMPAIGN_ID
      - SALESFORCE_NOT_CONNECTED
      - SALESFORCE_NOT_INITIALIZED
      - SALESFORCE_NO_REFRESH_TOKEN
      - SALESFORCE_REAUTH_REQUIRED
      - SALESFORCE_STATE_UNAVAILABLE
      - SALESFORCE_TOKEN_REFRESH_FAILED
      - SALESFORCE_UNAVAILABLE
      - SECURITY_SETTINGS_NOT_CONFIGURABLE
      - SERVICE_UNAVAILABLE
      - SESSION_EXPIRED
      - SESSION_NOT_EXCHANGEABLE
      - SUBSCRIPTION_ACTIVE
      - SUBSCRIPTION_CANCELLING
      - SUBSCRIPTION_EXISTS
      - SUB_ACCOUNT_MANAGED
      - SUPPORT_CHAT_DECLINED
      - TEAM_DELETION_IN_PROGRESS
      - TWO_FACTOR_ACCOUNT_LOCKED
      - TWO_FACTOR_CONTINUATION_EXPIRED
      - TWO_FACTOR_CONTINUATION_UNAVAILABLE
      - UNAUTHORIZED
      - VERIFICATION_TOKEN_EXPIRED
      - VERIFICATION_TOKEN_INVALID
      - VERIFICATION_TOKEN_MALFORMED
      - WEBHOOK_DNS_TEMPORARY_FAILURE
      - WEBHOOK_URL_INVALID
      - WHITE_LABEL_CUSTOM_DOMAIN_UNAVAILABLE
      - IDEMPOTENT_EXPORT_EXPIRED
      - PROFILE_EXPORT_UNAVAILABLE
      - PROFILE_EXPORT_DOWNLOAD_UNAVAILABLE
    ErrorEnvelope:
      type: object
      description: 'Every failure Kawaa answers is `{ "success": false, "error": { … } }`; the few the gateway in front of the API answers itself are not (see the description at the top of this document). Branch on `error.code`, not on the message. The retry fields are optional and are left out, never guessed, when the server does not know: `retryable` says whether repeating the identical request can succeed, `retry_after_seconds` how long to wait, and on a 5xx (or a refusal decided after the charge) from a route that charges credits one of `retry_requires_same_idempotency_key` or `retry_may_charge_again` says how to repeat it without paying twice.'
      properties:
        success:
          const: false
        error:
          type: object
          properties:
            code:
              $ref: '#/components/schemas/ErrorCode'
            message:
              type: string
            request_id:
              type: string
            retryable:
              type: boolean
              description: Whether the identical request, sent again after a wait with nothing else changed, can succeed. `true` for rate limiting and transient failures; `false` when the request, the credential, the plan, the balance or the resource has to change first. Absent when the answer depends on the case, notably `INTERNAL_ERROR` (an unexpected failure, transient or not) and `CONFLICT`. Decided per code; a few responses override their code, such as a `503` for a feature that is switched off (`false`) or a `400` for a download whose job is still running (`true`).
            retry_after_seconds:
              type: integer
              minimum: 1
              description: Seconds to wait before retrying, when the server knows. The same number as the `Retry-After` header, which is sent with it.
            retry_requires_same_idempotency_key:
              const: true
              description: 'Present on a 5xx from a route that charges credits and honours `Idempotency-Key`, for a request that sent one. Repeat it only with the same `Idempotency-Key`: an attempt under the key that was charged is replayed rather than bought again, for as long as the key''s receipt lasts, and one that was not is simply run. An instruction, not a claim that this attempt was charged.'
            nothing_charged:
              const: true
              description: 'Present only when the server can confirm that this attempt left no charge standing: it failed before the debit, the debit did not commit, or the charge was refunded. It does not describe earlier attempts under the same request key. Continue to reuse the same Idempotency-Key when instructed. Absence does not establish whether a charge occurred.'
            retry_may_charge_again:
              const: true
              description: Present on a 5xx (or a refusal decided after the charge, such as an AI-provider 429 once a composition was paid for) from a route that charges credits, for a request with no `Idempotency-Key` to reuse (the route takes none, or the caller sent none), when the server cannot rule out that this attempt was charged. No key marks a repeat as the same request (some routes forgive an identical repeat for a short window, none promises to), so a retry may be charged a second time. Check `GET /v1/usage/credits/transactions`, which lists each debit with its timestamp and description, to see whether this attempt was charged; `GET /v1/usage` gives the balance but not the per-debit detail that answers the question.
            granted_scopes:
              type: array
              items:
                type: string
              description: 'Present on an `INSUFFICIENT_SCOPE` sent to an app connected over OAuth: the scopes its access token holds. To ask for the missing scope it signs in again requesting these together with the scopes the message names; some clients (Codex CLI''s `--scopes`) replace their whole request with the list they are given.'
            confirmation_url:
              type: string
              format: uri
              description: 'Present on a `402` `PAYMENT_REQUIRED` from `POST /v1/billing/subscription/change` when the upgrade is held until its payment is made on the payment provider''s hosted https page. That happens when the customer''s bank asked for the payment to be confirmed (3D Secure): on the page the customer confirms it, or, when the held attempt was declined, pays it with another card. The `message` says which. Nothing is charged and the plan does not change until the payment goes through there; the webhook then applies the plan and grants its credits. Absent when the card was declined without a confirmation request, and when no page could be offered; the `message` then says that nothing was charged.'
            confirmation_expires_at:
              type: string
              format: date-time
              description: 'Present only with `confirmation_url`, when the provider gave an expiry: when that page stops working (ISO 8601, UTC), at most 23 hours after the request and earlier when the billing period ends sooner. The provider then drops the upgrade and voids its invoice. The `message` names the same time in words. A client that receives `confirmation_url` without it should treat the page as expiring within 23 hours.'
          required:
          - code
          - message
      required:
      - success
      - error
  responses:
    Default:
      description: 'Any status this operation does not list. Kawaa''s own errors carry the error envelope. The gateway in front of the API can answer any operation with its own bare body (`GatewayError`): a `503` when the route''s time limit at the gateway runs out (about 29 to 30 seconds on every route that charges credits, 15 on `GET /v1/account`, the `/v1/api-keys` routes, `GET /v1/jobs`, `GET /v1/jobs/{id}` and `POST /v1/jobs/{id}/cancel`, 5 on `/health`), when the request may still have run and been charged, a `413` for a body over about 6 MB, or a `400` for a path with malformed percent-encoding.'
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/ErrorEnvelope'
            - $ref: '#/components/schemas/GatewayError'
        text/html:
          schema:
            type: string
            description: An error page from infrastructure in front of the API. Handle it by its status.
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-Api-Key
      description: 'A Kawaa API key, created in Settings → API keys. Format: `ev_` followed by 32 alphanumeric characters.'
    BearerToken:
      type: http
      scheme: bearer
      description: 'The same API key, sent as `Authorization: Bearer <key>`. Accepted everywhere `X-Api-Key` is. This scheme is the `ev_` API key only. An OAuth access token (`evo_` followed by 40 alphanumeric characters) travels in the same header, but it is the `OAuth2` scheme: it is always scoped, and it is accepted only by the operations that list `OAuth2`, with the scopes they name. An operation that lists `BearerToken` without `OAuth2` refuses it.'
    OAuth2:
      type: oauth2
      description: 'OAuth 2.1 sign-in, for an app or agent that acts for a person who approves it on a Kawaa consent screen, instead of being handed an API key. The access token is sent as `Authorization: Bearer <token>`, the same header as `BearerToken`, and is checked exactly like a scoped API key: scopes, rate limits and credits apply unchanged.


        - **Discovery.** Authorization server metadata (RFC 8414): `https://api.kawaa.com/.well-known/oauth-authorization-server`. Protected resource metadata (RFC 9728): `https://api.kawaa.com/.well-known/oauth-protected-resource` for this API and `https://api.kawaa.com/.well-known/oauth-protected-resource/mcp` for the MCP server.

        - **Client.** Use the https URL of a Client ID Metadata Document, on the default port, as `client_id` (public clients only), or register at `https://api.kawaa.com/oauth/register` (RFC 7591; no credential needed). Registration follows the RFC defaults when a field is omitted: `token_endpoint_auth_method` `client_secret_basic` (a secret is issued) and `grant_types` `authorization_code` alone. Send `none` for a public client, and include `refresh_token` in `grant_types` to be issued refresh tokens. A redirect URI is https, loopback http (any port), or an app''s own scheme: a reversed domain name (RFC 8252 §7.1, `com.example.app:/callback`) or one of `cursor`, `vscode`, `vscode-insiders`, `claude` and `windsurf`. Browser and operating-system handler schemes are refused (`invalid_redirect_uri`).

        - **PKCE.** Required on every authorization request, with `code_challenge_method=S256`; no other method is accepted. The only grants are `authorization_code` and `refresh_token`.

        - **Resource.** Send `resource=https://api.kawaa.com` for this API (RFC 8707). Without it the token is issued for the MCP server, `https://api.kawaa.com/mcp`; any other value is refused with `invalid_target`.

        - **Scopes.** With no `scope` parameter the request is for `verification:write verification:read account:read analytics:read`. Scopes Kawaa does not define, and scopes a connected app can never hold, are dropped rather than refused; if none remain the request is refused with `invalid_scope`. An authorization request refused before the person answers it (`invalid_request`, `unsupported_response_type`, `invalid_target`, `invalid_scope`) is shown to them on a Kawaa error page carrying that code, and is not sent to the redirect URI (RFC 9700 §4.11.2); only their answer is, the code or `access_denied`, with `state` and `iss`. The person approving can untick any scope, and the token response''s `scope` states what was granted. `account:write`, `account:delete`, `billing:write`, `team:write`, `security:write` and `white_label:write` are never granted, so the operations that need them do not list this scheme, and neither do those marked `x-kawaa-unscoped-only`. As for API keys, `<area>:write` also satisfies `<area>:read`.

        - **Tokens.** An access token is `evo_` followed by 40 alphanumeric characters and lasts one hour (`expires_in: 3600`); after that the API answers 401 `OAUTH_TOKEN_EXPIRED`. A refresh token is `evr_` followed by 48 alphanumeric characters and is never accepted as a bearer credential. Every refresh returns a new refresh token and retires the one presented. The one just used may be presented up to 5 more times within 60 seconds of its use (a lost response, or several refreshes sent at once) and gets a new one of its own each time; the first of those to be used retires the rest. Presenting it again after that, or presenting any older refresh token, is treated as theft and ends the connection: its refresh tokens and every live access token stop working. A refresh may ask for fewer scopes than the connection holds, never more. A connection that is not refreshed for 30 days ends. Revoke at `https://api.kawaa.com/oauth/revoke` (RFC 7009).'
      flows:
        authorizationCode:
          authorizationUrl: https://api.kawaa.com/oauth/authorize
          tokenUrl: https://api.kawaa.com/oauth/token
          refreshUrl: https://api.kawaa.com/oauth/token
          scopes:
            verification:read: Read verification results and jobs this account has already paid for. Spends nothing.
            verification:write: 'Anything that spends verification credits: verifying an address, a batch or a file, finding a business email, and the domain and address-history lookups, which are charged too.'
            lists:read: Read auto-clean lists and their run history.
            lists:write: Create, change, pause and delete auto-clean lists, and start rechecks. Each rechecked address spends one credit. Creating, reactivating and starting rechecks require Professional or above and account execution availability.
            deliverability:read: Read deliverability checks, blacklist and DMARC monitors, and inbox-placement and warmup state. Email warmup and inbox placement tests are not available yet.
            deliverability:write: Run deliverability checks and manage blacklist and DMARC monitors. Email warmup and inbox placement tests are not available yet; warmup campaigns and SMTP credentials already set up can still be removed.
            compose:read: Read AI composition history.
            compose:write: Generate and improve email copy with AI. Spends credits.
            exports:read: Read exports, export schedules and data-sharing settings. Downloading an export also needs the scope that reads the data in it. Data sharing is not available yet.
            exports:write: 'Create and delete exports, manage export schedules and delivery destinations, and change export settings. Exported files contain customer addresses, so each kind of data also needs the scope that reads it: verification:read, account:read or security:read. Scheduled exports deliver by email, webhook or Amazon S3; Google Cloud Storage and Azure Blob Storage delivery is not available yet.'
            webhooks:read: Read webhook endpoints and their delivery logs.
            webhooks:write: Create, change and delete webhook endpoints, and rotate their signing secrets.
            integrations:read: Read connected integrations and their status.
            integrations:write: Connect and disconnect integrations, and push verification into them. The HubSpot, Salesforce and Mailchimp connections are not available yet.
            analytics:read: Read usage, analytics and tracking figures.
            analytics:write: Create, change and permanently delete tracking pixels and links, and record usage-analytics events for this account. Deleting a pixel or link breaks the tracking already embedded in sent mail. Credit alert thresholds are fixed, so no scope changes them.
            account:read: Read the account profile, credit balance and notifications.
            billing:read: Read the subscription, invoices, payment methods and billing address.
            team:read: Read the team, its members and its invitations.
            security:read: Read security settings, sessions, login history and the audit log.
            white_label:read: Read white-label configuration, sub-accounts and the custom API domain.
externalDocs:
  description: Guides and reference
  url: https://kawaa.com/docs/