Bahasa IndonesiaReferensi APIIndex

Referensi API Publik

Base URL: https://ai.numintek.com/api

Semua endpoint publik diawali /v1/public/. Endpoint internal (/v1/admin/*, /v1/internal/*) tidak diekspos ke tenant.

Autentikasi

Setiap request wajib pakai API key yang dibuat di Settings → API Keys:

curl https://ai.numintek.com/api/v1/public/conversations \
  -H "Authorization: Bearer dnm_live_XXXXXXXXXXXX"

Format key:

  • dnm_live_... — key production
  • dnm_test_... — key test (tidak ditagih, data terisolasi)

Idempotency

Setiap mutation (POST, PUT, PATCH, DELETE) menerima header Idempotency-Key. Key yang sama dalam 24 jam mengembalikan response cache:

curl -X POST https://ai.numintek.com/api/v1/public/conversations \
  -H "Authorization: Bearer dnm_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"channelId": "...", "message": "..."}'

Pagination

Cursor-based. Response include nextCursor kalau masih ada page:

{
  "data": [...],
  "nextCursor": "cnv_abc123"
}

Kirim balik sebagai ?cursor=cnv_abc123 untuk page berikutnya.

Error

RFC 7807 problem+json:

{
  "type": "https://ai.numintek.com/errors/validation",
  "title": "Validation failed",
  "status": 422,
  "detail": "Field 'channelId' is required",
  "instance": "/v1/public/conversations"
}

Status umum:

  • 401 — API key hilang atau invalid
  • 403 — key ada tapi tidak punya scope yang diperlukan (lihat scopes)
  • 409 — conflict (biasanya resource existing dengan key yang sama)
  • 422 — validasi request body gagal
  • 429 — rate limit (per-key, default 60 rpm; upgrade di Settings)

Scopes

Setiap key punya list scope. Rekomendasi least-privilege:

  • read:conversations — GET /conversations dan /messages
  • write:conversations — POST /conversations dan /messages
  • read:customers — GET /customers
  • write:customers — POST /customers dan PATCH /customers/id
  • read:agents — GET /agents
  • write:agents — POST dan PATCH /agents (draft only)
  • read:knowledge — GET /knowledge-bases
  • write:knowledge — POST /knowledge-bases dan upload dokumen
  • read:webhooks — GET /webhooks
  • write:webhooks — POST, PATCH, DELETE /webhooks
  • read:usage — GET /usage

OpenAPI

Skema Swagger lengkap di ai.numintek.com/api-docs.

SDK

  • Node/TypeScript: @danum-ai/sdk-node
  • Lainnya: segera hadir; API REST + JSON, jadi HTTP client apa saja bisa.
IndexIndex