---
title: "API Overview"
description: "Base URL, versioning, and high-level API surface."
collection: "api-reference"
slug: "overview"
url: "https://naiza.ai/docs/api-reference/overview"
markdown: "https://naiza.ai/docs/api-reference/overview.md"
full_docs: "https://naiza.ai/docs.md"
product: "Naiza"
base_url: "https://api.naiza.ai/api/v1"
---

# API Overview

> Base URL, versioning, and high-level API surface.

## Table of contents

- [Base URLs](#base-urls)
- [Versioning](#versioning)
- [Endpoint Map](#endpoint-map)
  - [Core APIs](#core-apis)
  - [Web SDK APIs](#web-sdk-apis)
  - [AML Screening APIs](#aml-screening-apis)
- [Authentication Model](#authentication-model)
- [Request Conventions](#request-conventions)
  - [Content Type](#content-type)
  - [Pagination](#pagination)
  - [Time Filters](#time-filters)
  - [Idempotency](#idempotency)
  - [Correlation IDs](#correlation-ids)
- [Next References](#next-references)
- [Next Guides](#next-guides)

This page covers the shared behavior for Naiza public APIs exposed under `/api/v1`.

## Base URLs

```text
Production:  https://api.naiza.ai
Staging:     https://staging-api.naiza.ai
Development: http://localhost:3000
```

## Versioning

All external APIs are versioned under:

```http
/api/v1/*
```

The version segment defaults to `v1` and is controlled server-side by `EXTERNAL_API_VERSION`.

## Endpoint Map

### Core APIs

- `POST /api/v1/decisions/evaluate`
- `GET /api/v1/decisions`
- `GET /api/v1/decisions/:id`
- `GET /api/v1/decisions/stats`
- `POST /api/v1/events`
- `POST /api/v1/events/async`
- `GET /api/v1/events`
- `GET /api/v1/events/:id`
- `GET /api/v1/events/stats`
- `GET /api/v1/lists`
- `POST /api/v1/lists`
- `DELETE /api/v1/lists/:id`
- `POST /api/v1/feedback/decision/:id`
- `POST /api/v1/feedback/event/:id`
- `POST /api/v1/webhooks/subscriptions`
- `GET /api/v1/webhooks/subscriptions`
- `POST /api/v1/webhooks/subscriptions/:id/test`
- `DELETE /api/v1/webhooks/subscriptions/:id`

### Web SDK APIs

- `POST /api/v1/websdk/tokens`
- `POST /api/v1/websdk/signals`

### AML Screening APIs

- `POST /api/v1/aml/events`
- `GET /api/v1/aml/events/:externalEventId`
- `POST /api/v1/aml/screen`
- `GET /api/v1/aml/screenings/:id`

See [AML Screening API](https://naiza.ai/docs/api-reference/aml.md) for request/response details. Available only
to tenants with the AML Screening product enabled.

## Authentication Model

- Most endpoints require `x-api-key`
- `POST /api/v1/websdk/signals` requires `Authorization: Bearer <short-lived-sdk-token>`
- See [Authentication](https://naiza.ai/docs/api-reference/authentication.md) for key lifecycle and secure usage

## Request Conventions

### Content Type

Use JSON for requests and responses:

```http
Content-Type: application/json
```

### Pagination

List endpoints use `page` and `limit`:

```http
GET /api/v1/decisions?page=1&limit=50
```

Typical response shape:

```json
{
  "data": [],
  "total": 0,
  "page": 1,
  "limit": 50,
  "hasMore": false
}
```

### Time Filters

Many analytics/list endpoints use **Unix timestamp seconds** for `from` and `to` query parameters:

```http
GET /api/v1/decisions?from=1711833600&to=1711920000
```

### Idempotency

Feedback endpoints support idempotency through `Idempotency-Key`:

```http
POST /api/v1/feedback/decision/evt_123
Idempotency-Key: feedback-evt_123-fraud
```

When a key is provided:

- First request is processed normally and the response is stored for replay
- Replays with the same key (same tenant + same endpoint path) return the stored response
- Keys expire after 24 hours

### Correlation IDs

Decision responses include correlation identifiers to connect logs, events, and follow-up calls:

```json
{
  "correlationIds": {
    "requestId": "req_abc123xyz",
    "eventId": "evt_ckm9876543210"
  }
}
```

## Next References

- [Decisions API](https://naiza.ai/docs/api-reference/decisions.md)
- [Events API](https://naiza.ai/docs/api-reference/events.md)
- [AML Screening API](https://naiza.ai/docs/api-reference/aml.md)
- [Web SDK API](https://naiza.ai/docs/api-reference/websdk.md)
- [Rate Limiting](https://naiza.ai/docs/api-reference/rate-limiting.md)
- [Error Handling](https://naiza.ai/docs/api-reference/errors.md)

## Next Guides

- [Event Monitoring Integration](https://naiza.ai/docs/guides/event-monitoring.md)
- [AML Integration Guide](https://naiza.ai/docs/guides/aml-integration.md)

## Related documentation

- [Authentication](https://naiza.ai/docs/api-reference/authentication.md) — API keys, Web SDK tokens, and secure key handling.
- [Web SDK API](https://naiza.ai/docs/api-reference/websdk.md) — Browser SDK endpoints and device signal collection.
- [Events API](https://naiza.ai/docs/api-reference/events.md) — Submit and query product events for risk evaluation.
- [Sessions API](https://naiza.ai/docs/api-reference/sessions.md) — Session grouping and timeline endpoints.
- [Error Handling](https://naiza.ai/docs/api-reference/errors.md) — Error shapes, status codes, and retry guidance.
- [Rate Limiting](https://naiza.ai/docs/api-reference/rate-limiting.md) — Quota headers and rate-limit behavior.
- [Decisions API](https://naiza.ai/docs/api-reference/decisions.md) — approve / deny / review evaluation and decision payloads (Events API uses ALLOW/REVIEW/BLOCK).
- [Lists API](https://naiza.ai/docs/api-reference/lists.md) — Allowlists, blocklists, and list membership management.

---

*Source: [https://naiza.ai/docs/api-reference/overview](https://naiza.ai/docs/api-reference/overview) · Full docs: [https://naiza.ai/docs.md](https://naiza.ai/docs.md)*