API reference

Five-minute start

The only call that works today with no key and no setup is the health check. Start with it to confirm your instance is running and the network can reach it.

# replace the domain with your own server
curl https://bot.example.sa/health

# response
{ "ok": true }

Then request a key from the setup team, and store it in an environment variable. Do not put it in front-end code, because the key grants full access to your customers' records.

export NAATEQ_URL=https://bot.example.sa
export NAATEQ_KEY=nq_live_…

curl "$NAATEQ_URL/api/v1/conversations?limit=1" \
  -H "Authorization: Bearer $NAATEQ_KEY"

The base URL is your own domain

Every customer has their own instance of Naateq, so there's no single address for all customers. Your address is the domain your system was installed on:

https://<your-domain>/api/v1

When you run on your own server, your customers' chats stay inside your business, except for reading documents and images, which needs a cloud provider, as explained in security page. The server, the key and the access log are all with you.

On the other hand, keeping the server running is your responsibility. We don't commit to an uptime percentage for a server we don't manage, and what we do commit to is written on the support page.

One key in the header

Every request carries your key in Authorization. The key is shown once at creation and can't be retrieved afterward. If it's lost, create a new one and revoke the old one.

# missing or revoked key
HTTP/1.1 401 Unauthorized

{
  "error": {
    "type": "authentication_error",
    "code": "key_revoked", "message": "The key has been revoked. Request a new key.", "request_id": "req_01J8…" } }

Conversations and messages

Every conversation is isolated by the customer's number. The isolation is built into the system and always on, so no call can reach another customer's record.

POST /api/v1/messages
Authorization: Bearer $NAATEQ_KEY
Idempotency-Key: a3f1c9de-…

{
  "to": "966501234567", "text": "Your quote is ready — shall we send it?" }

Customers

The customer log is the same one the system writes, and the fields below are copied from it as is. So what you read from the API is what the system sees at the moment it replies.

{ "number": "966501234567", "name": "Mohammed Al-Harbi", "stage": "quoted", "project": "12-metre majlis — custom", "quote": { "amount": 4200, "project": "12-metre majlis — custom", "status": "sent", "date": "2026-08-04" }, "contract": null, "milestones": [], "tickets": [], "payment_links": [], "next_payment_due": null, "created_at": "2026-08-0

Documents

Quotes and contracts. The document number is built from your business prefix, a type letter, the date, and a three-digit sequence:

HT-Q-260804-058
│ │ │ └── daily sequence │ │ └────────── YYMMDD │ └─────────────── Q quote · C contract └──────────────────── your business prefix

⚠ The prefix changes when the business package changes, so Do not hard-code it in your integration and match the full pattern.

Payments

The system calculates the payment plan from the total. The last instalment is calculated by subtracting the earlier ones from the total, so the instalments always add up to exactly the total whatever the rounding, and no one-riyal difference shows up at collection:

[ { "id": "moyasar", "label_ar": "<Arabic label>", "configured": true, "mode": "live",
    "min_amount_minor": 100,
    "fields": ["secret_key"] },
  { "id": "paylink", "label_ar": "Paylink",
    "configured": false, "mode": null,
    "min_amount_minor": 500, "fields": ["api_id", "secret_key"] }, { "id": "tap", "label_ar": "<Arabic label>", "configured": false, "mode": null, "min_amount_minor": 100, "fields": ["secret_key"] } ]

{
  "provider": "moyasar",
  "url": "https://…",
  "ref": "inv_01J8…",
  "status": "pending",
  "amount_minor": 210000,
  "currency": "SAR"
}

Webhooks

You register a single URL, and the subscribed events arrive there as JSON with a signature X-Naateq-Signature.

All the events Spec, and none of them are sent yet.

POST /your-endpoint
X-Naateq-Signature: t=1785838800,v1=5f2b…
X-Naateq-Delivery: whd_01J8…

{
  "event": "quote.issued",
  "created_at": "2026-08-04T09:31:02.771Z",
  "data": {
    "doc_number": "NQ-Q-260804-058", "customer": { "number": "966501234567", "name": "Mohammed Al-Harbi" }, "total": 420000, "currency": "SAR", "payment_plan": "50% on signing • 30% on initial delivery • 20% on final delivery" } }

Any system that retries may send an event twice or out of order, so build your handler with that in mind.

Never trust an unsigned request

Compute HMAC-SHA256 over t + "." + the raw body with the webhook secret, and compare it against v1 using a constant-time comparison. And reject any request older than five minutes so an old request cannot be replayed against you.

import crypto from "node:crypto";

export function verify(raw, header, secret) {
  const [t, v1] = header.split(",").map(p => p.split("=")[1]);
  // time window: prevents replaying an old request
  if (Math.abs(Date.now() / 1000 - +t) > 300) return false;

  const expect = crypto
    .createHmac("sha256", secret)
    .update(`${t}.${raw}`)
    .digest("hex");

  // constant-time comparison: == leaks the difference through execution time
  const a = Buffer.from(expect), b = Buffer.from(v1);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

⚠ timingSafeEqual throws if the lengths differ, so we check the length first. This is a common mistake that breaks many integrations in production.

And compute the signature over the raw body before parsing the JSON, because reordering the keys breaks the signature.

Idempotency, so you don't pay twice

Every POST accepts Idempotency-Key. If the connection drops and you don't get the response, resend the same request with the same key, and you'll get the same result with no second payment link or duplicate message.

Cursor-based pagination

We don't use page=2, because a new record arriving between two requests shifts the page numbering, so you miss items or get duplicates. A cursor keeps your place.

{
  "data": [ … ],
  "has_more": true,
  "next_cursor": "cur_01J8…"
}

And for periodic syncing use updated_after with the last updated_at you received, so you only transfer what changed instead of the whole record set.

One shape for every error

Every error carries type for classification,code for programmatic handling,message for display, and request_id for support. Rely on code in your code, not message, because we may improve the message text, while the code stays fixed.

⚠ Gateway credentials never appear in any error message, whether in full or truncated. This is a rule built into the payment layer, because error messages are among the most common places keys leak from.

Limits and data policy

The limits above Spec, and none of them are enforced yet. Since each customer has their own instance, the request limit protects your instance's resources. You can raise it in your instance settings without buying anything from us.

Versioning and scheduled deprecation

The version is in the path: /api/v1/. And within one version we add and never remove.

If we decide to retire an endpoint: we give you notice of 180 days in advance, add a Sunset header to every response from it, and it keeps working for the whole period.

Changelog

We log every change to this reference here with its date, including corrections to anything written wrong.