Skip to main content
This guide helps you make your first successful request to the Defendis API and adopt conventions that make your integration reliable in production.

​
Quickstart

1

Verify connectivity

curl -sS "https://api.defendis.ai/health"

#Expected response:
{ 
  "status": "ok"
}
2

Export your API key

export DEFENDIS_API_KEY="YOUR_API_KEY"
3

Call an authenticated endpoint

curl -sS \
  -H "Authorization: Bearer ${DEFENDIS_API_KEY}" \
  "https://api.defendis.ai/api/v1/watchlists"

​
Core concepts

​
Watchlists

Datasets in Defendis are access-controlled by your workspace scope. In practice:
  • You define watchlists that represent what you are authorised to monitor (domains, emails, keywords, BINs, and other assets).
  • Many endpoints validate input against your watchlist scope.
  • Requests outside your approved scope return 403 Forbidden.
  • Watchlist write endpoints may return 409 Conflict when your workspace quota is reached.

​
Contract-first integration

  • The OpenAPI spec is the source of truth for endpoints, parameters, and request/response schemas: ../openapi.yaml.
  • If you generate clients, treat the API as additive: new fields may appear without warning. Your parser should ignore unknown fields.

​
Request conventions

​
Content types

  • Use query parameters for filtering and pagination on endpoints that support them.
  • When an endpoint accepts a request body, send JSON:
Content-Type: application/json
For more information, see Errors and Endpoints.

​
Pagination

Paginated list endpoints return a consistent envelope:
  • data: array of records
  • paging: pagination metadata with:
    • currentPage
    • pageSize
    • totalRecords
    • totalPages
    • hasMore
    • nextPage
Recommended ingestion loop:
  • Start with page=1.
  • Keep fetching until paging.hasMore is false (or paging.nextPage is null).
  • Persist checkpoints (page and filter window) so your ingestion can resume safely after failures.
Example
{
  "data": [],
  "paging": {
    "currentPage": 1,
    "pageSize": 50,
    "totalRecords": 120,
    "totalPages": 3,
    "hasMore": true,
    "nextPage": 2
  }
}

​
Date filters

Some endpoints support date window filtering. When supported, use a closed-open window:
  • fromDate: inclusive lower bound
  • toDate: exclusive upper bound
Date parameters are standardized as fromDate and toDate. Always follow the endpoint’s reference docs / OpenAPI contract for exact support. Client recommendation:
  • Use YYYY-MM-DD for date-only filters.
  • Prefer narrow windows for high-volume pulls and widen gradually.

​
Search & sorting

Search and sorting are endpoint-specific. Common patterns include:
  • search
  • sortBy
  • sortOrder
When omitted, server-side defaults apply. Use the OpenAPI contract and the endpoint reference docs to confirm supported parameters and allowed values.

​
Rate limits & reliability

Defendis enforces rate limiting. When exceeded you will receive 429 Too Many Requests. Client best practices:
  • Use exponential backoff for retries (with jitter).
  • Distribute polling workloads over time.
  • Automatically retry safe requests (GET) on transient failures (429, 5xx, timeouts).
  • Avoid retrying non-idempotent writes unless your application guarantees idempotency.

​
Typical integration patterns

​
Pull model

1

Define scope

Configure watchlists so your integration only pulls data within approved scope.
2

Pull datasets

Ingest Dataleaks, Exposure, and Ransomware datasets on a recurring schedule.
3

Normalize downstream

Map results into your SIEM/SOAR, data lake, or case management schema.

​
Near-real-time workflows

For operational workflows, use frequent polling with small time windows and robust retry/backoff behavior.

​
Data handling & privacy

Some datasets, especially Dataleaks, may contain sensitive information. As an API consumer, you are responsible for ensuring the data is handled appropriately within your environment. Recommended practices:

Minimize retention

Keep only the fields and retention window required for your workflow.

Restrict access

Limit sensitive dataset access to the smallest set of users and services.

Redact logs

Avoid logging full payloads or sensitive fields in application and audit logs.

Enforce compliance

Apply your internal security, legal, and compliance controls to this API data.