All documentation

API Overview

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

Download Markdown
GuidesAPI ReferenceCode ExamplesBest Practices

API Overview

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

Base URLs

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

Versioning

All external APIs are versioned under:

/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 APIs

Available only to tenants with the AML Screening product enabled.

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

Authentication Model

  • Most endpoints require x-api-key
  • POST /api/v1/websdk/signals requires Authorization: Bearer <short-lived-sdk-token>
  • See for key lifecycle and secure usage

Request Conventions

Content Type

Use JSON for requests and responses:

Content-Type: application/json

Pagination

List endpoints use page and limit:

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

Typical response shape:

{
  "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:

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

Idempotency

Feedback endpoints support idempotency through Idempotency-Key:

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:

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

Next References