API conventions

This page summarizes the rules common to every endpoint of the External Integrations API. If your integration doesn't follow them, you will get 400 Bad Request, 401 Unauthorized, or structured errors.

Base URLs

Environment	Base URL	When
Production	https://api.neuroon.ai	Real traffic, persistent data, conversions that count
Development	https://dev-api.neuroon.ai	Integration testing, error payloads, edge cases without risk

API keys issued in Development do not work against Production and vice versa. Use separate environment variables:

NEUROON_API_URL=https://api.neuroon.ai
NEUROON_API_KEY=your_api_key_here

See Switching environments for per-stack configuration.

Format

• Request body: JSON with Content-Type: application/json; charset=utf-8. camelCase on every field.
• Response body: JSON camelCase. Keys are always strings; numbers may be int, long, decimal (prices). Dates are ISO 8601 (2026-05-06T10:15:00Z, or without Z if local — the backend returns UTC without offset).
• Charset: UTF-8 mandatory. The backend rejects latin-1 with 400.

Strict JSON

PascalCase, snake_case or keys with whitespace will be ignored or produce 400 Validation failed. Use JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase } in .NET, or the equivalent in your stack.

Mandatory headers

Header	Applies to	Value
Content-Type	requests with body	application/json
Accept	recommended	application/json
Authorization	all endpoints	Bearer <api-key>

Useful optional headers:

• Accept-Language: es-ES, en-US, fr-FR, etc. — the backend uses this value for generated text when it matches one of the supported locales; otherwise it falls back to es.
• User-Agent: YourApp/1.2.3 — for your own log analysis (recommended).

Authentication

All calls to /api/integrations/v1/* require:

Authorization: Bearer <api-key>

The API key is obtained from the Neuroon dashboard (shop settings) and is bound to a specific shop. You don't need to include shopId in the URL — the backend resolves the shop from the API key.

See Authentication · Overview for more details.

Idempotency

• POST /api/integrations/v1/products/sync is idempotent by externalId: sending the same externalId twice updates the product, it does not duplicate. This includes INCREMENTAL mode. FULL mode replaces the entire catalog — use it only for initial migrations.
• POST /api/integrations/v1/conversions accepts a unique orderId per shop; a second POST with the same orderId is silently ignored.
• The remaining endpoints are GET (no side effects), PUT (update), DELETE (deletion) or stateless.

Latency and consistency

• Product indexing: 2-5 seconds after 200 OK on products/sync. The product is not searchable immediately. If your integration test does GET /products/by-external/{id} right after the sync, wait ~5 s or poll with backoff.
• Quotas: totalProducts and searchesLimit in GET /shop are cached ~5 min by some consumers. The backend always returns the up-to-date value.

Error shape

All errors follow a uniform format with error and message. Validation errors include field-level details.

Rate limits

Based on your subscription plan. Response headers: X-RateLimit-Limit, X-RateLimit-Remaining. On 429, also Retry-After (seconds).

Pagination

GET /api/integrations/v1/products accepts:

• page (0-indexed, default 0)
• size (default 20, maximum 100)
• sort (format property,asc|desc, e.g. name,asc)

CORS

• /api/widget/*: CORS open to any origin (it is JS from customer browsers).
• /api/integrations/*: CORS disabled by design — these are server-to-server calls. Calling from a browser will be rejected.

If your server-to-server integration goes through a proxy that automatically adds Origin and breaks validation, configure the proxy not to send the header.

Further reading

• Authentication · Overview — which credential to use.
• Reference · Errors — every code.
• Reference · Data models — real schemas.