Auth, endpoints and error behavior

Neurico provides an endpoint-based v1 contract. You can keep your existing OpenAI client and proceed by only changing the base URL and the bearer key.

Core rules

• All requests require the Authorization: Bearer <token> header
• The production URL is in the https://{slug}.gateway.neurico.ai/v1 format
• The local and proxy fallback is in the https://neurico.ai/api/gateway/{slug}/v1 format
• Use Content-Type: application/json for JSON requests
• The x-request-id response is returned for tracking on both successful and failed requests

Authentication

Neurico API keys are in the form nrc_<prefix>.<secret>. If the bearer token is missing or invalid, the gateway returns 401.

curl https://team-alpha.gateway.neurico.ai/v1/models \
  -H "Authorization: Bearer nrc_xxxxx.yyyyy"

GET /v1/models

Lists the client-facing Neurico model alias and enabled router model keys for the active endpoint.

Example request

curl https://team-alpha.gateway.neurico.ai/v1/models \
  -H "Authorization: Bearer nrc_xxxxx.yyyyy"

Example response

{
  "object": "list",
  "data": [
    {
      "id": "neurico",
      "object": "model",
      "owned_by": "neurico",
      "deployment_mode": "hosted-shared",
      "status": "ACTIVE",
      "routed_model": "gpt-5.4-mini",
      "provider_profile": "openai"
    },
    {
      "id": "open_coder",
      "object": "model",
      "owned_by": "neurico",
      "deployment_mode": "hosted-shared",
      "status": "ACTIVE",
      "routed_model": "deepseek-v4-pro",
      "provider_profile": "openai"
    }
  ]
}

Notes

• owned_by identifies the Neurico registry owner; provider_profile comes from the endpoint configuration
• routed_model is the concrete model a registry tier dispatches to. The defaults are open-weight-first: open_small → qwen3-8b, open_coder_small → deepseek-v4-flash, open_general → qwen3-32b, open_coder → deepseek-v4-pro, open_coder_heavy → deepseek-v4-pro with thinking enabled, open_reasoner → kimi-k2.6-thinking. Two tiers are proprietary: api_mini → gpt-5.4-mini (cheap fallback) and frontier_model → gpt-5.5 (high-risk + end-of-chain)
• Open-weight ≠ free: the open_small tier is small enough to self-host with no per-token fee, while open_coder_small / open_general / open_coder / open_coder_heavy / open_reasoner default to a cheap paid hosted API. Because their weights are open you can drop the per-token fee by self-hosting (point the tier at your own inference server). api_mini and frontier_model are proprietary (closed weights) — a paid API is the only way to reach them
• deployment_mode can change based on the endpoint plan
• If the endpoint is not active, 403 is returned

POST /v1/responses

Makes an OpenAI-compatible Responses API call. It passes input, instructions, tools, stream and other supported fields through to the upstream.

Example request

curl https://team-alpha.gateway.neurico.ai/v1/responses \
  -H "Authorization: Bearer nrc_xxxxx.yyyyy" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "neurico",
    "instructions": "Answer briefly and clearly.",
    "input": "Explain why audit logs are necessary."
  }'

Example response

{
  "id": "resp_123",
  "object": "response",
  "created_at": 1767206400,
  "status": "completed",
  "model": "gpt-5.4-mini",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Audit logs are necessary to track the chain of access, changes and events."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 37,
    "output_tokens": 18,
    "total_tokens": 55
  }
}

Notes

• Send model: "neurico" to let the gateway select and execute the upstream model
• Send an enabled registry key such as model: "open_coder" to bypass auto-routing and dispatch directly to that model
• Even if you don't send model, the endpoint's active model is used
• If quota is exceeded, 429 is returned
• If compliance consent is missing or the account is in the deletion process, 403 is returned
• If chat log retention is on, the request and response are stored according to the dashboard policy

Error behavior

Gateway error responses are generally in the error.message form.

Gateway endpoints

• 401: Bearer API key missing. Example message: Bearer API key is required.
• 401: API key invalid. Example message: The API key is not valid.
• 403: Endpoint not active. Example message: This endpoint is not active.
• 403: Account deletion pending. The gateway returns a pending-deletion payload
• 403: KVKK consent required. The gateway returns a payload with a link back to the compliance screen
• 429: Endpoint quota exceeded. Example message: Quota exceeded for this endpoint.
• 500: Unexpected server or upstream error

Audit export endpoint

For KVKK and audit operations, the GET /api/audit/export route is used. This route can be called with a session cookie or the same bearer key.

Query parameters

• format: csv or json
• from: YYYY-MM-DD or ISO date
• to: YYYY-MM-DD or ISO date
• event_type: optional filter

Example request

curl "https://neurico.ai/api/audit/export?format=csv&from=2026-05-01&to=2026-05-31&event_type=endpoint.created" \
  -H "Authorization: Bearer nrc_xxxxx.yyyyy"

Audit export error codes

• 400 INVALID_FORMAT: the format field is not csv or json
• 400 INVALID_RANGE: the date range is invalid or longer than 90 days
• 401 UNAUTHORIZED: no session or bearer auth
• 429 RATE_LIMITED: the limit of 5 exports per hour per user is exceeded
• 500 INTERNAL_ERROR: the export stream broke unexpectedly

Choosing the base URL

• For customer traffic, target the subdomain contract first
• In local tests or when DNS isn't ready, proceed with the path fallback
• Teams using the OpenAI SDK should update base_url to end with .../v1

Related pages

• Quickstart for the first setup
• Migration guide for the OpenAI client change
• KVKK guide for compliance operations