> ## Documentation Index
> Fetch the complete documentation index at: https://docs.defendis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

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

## Quickstart

<Steps>
  <Step title="Verify connectivity">
    ```http theme={null}
    curl -sS "https://api.defendis.ai/health"
    ```

    ```http theme={null}
    #Expected response:
    { 
      "status": "ok"
    }
    ```
  </Step>

  <Step title="Export your API key">
    ```bash theme={null}
    export DEFENDIS_API_KEY="YOUR_API_KEY"
    ```
  </Step>

  <Step title="Call an authenticated endpoint">
    ```bash theme={null}
    curl -sS \
      -H "Authorization: Bearer ${DEFENDIS_API_KEY}" \
      "https://api.defendis.ai/api/v1/watchlists"
    ```
  </Step>
</Steps>

## 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 <span style={{ color: "#dc2626", fontWeight: 500 }}>403 Forbidden</span>.
* Watchlist write endpoints may return <span style={{ color: "#dc2626", fontWeight: 500 }}>409 Conflict</span> 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 <span style={{ color: "#16a34a", fontWeight: 500 }}>additive</span>: 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:

```http theme={null}
Content-Type: application/json
```

For more information, see [Errors](/api/errors) and [Endpoints](/api/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.

```json title="Example" theme={null}
{
  "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 <span style={{ color: "#dc2626", fontWeight: 500 }}>429 Too Many Requests</span>.

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

<Steps>
  <Step title="Define scope">
    Configure watchlists so your integration only pulls data within approved scope.
  </Step>

  <Step title="Pull datasets">
    Ingest Dataleaks, Exposure, and Ransomware datasets on a recurring schedule.
  </Step>

  <Step title="Normalize downstream">
    Map results into your SIEM/SOAR, data lake, or case management schema.
  </Step>
</Steps>

### 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:

<Columns cols={1}>
  <Card title="Minimize retention">
    Keep only the fields and retention window required for your workflow.
  </Card>

  <Card title="Restrict access">
    Limit sensitive dataset access to the smallest set of users and services.
  </Card>

  <Card title="Redact logs">
    Avoid logging full payloads or sensitive fields in application and audit logs.
  </Card>

  <Card title="Enforce compliance">
    Apply your internal security, legal, and compliance controls to this API data.
  </Card>
</Columns>