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": "auto",
      "provider_profile": "optimize-hosted"
    },
    {
      "id": "open_coder",
      "object": "model",
      "owned_by": "neurico",
      "deployment_mode": "hosted-shared",
      "status": "ACTIVE",
      "routed_model": "deepseek/deepseek-v4-pro",
      "provider_profile": "optimize-hosted"
    }
  ]
}

Notes

• owned_by identifies the Neurico registry owner; provider_profile comes from the endpoint configuration
• routed_model is the exact model slug dispatched for a registry tier. The defaults are open_small → google/gemini-3.5-flash-lite, open_coder_small → minimax/minimax-m3, open_general → z-ai/glm-5.2, open_coder → deepseek/deepseek-v4-pro, open_coder_heavy → moonshotai/kimi-k3, open_reasoner → deepseek/deepseek-v4-pro, quality_reviewer → openai/gpt-5.6-sol, and frontier_model → openai/gpt-5.6-sol
• Fixed reasoning profiles are open_coder=high, open_coder_heavy=max, open_reasoner=max, quality_reviewer=medium, and frontier_model=xhigh (xhigh is the wire value for extra-high). open_coder_small and open_general select within their allowed effort set from the task profile and retry policy; open_small disables reasoning.
• Every default router tier uses OpenRouter. OpenRouter provider fallback remains enabled, so it may select another provider that serves the same exact model. It cannot select another model: Neurico alone walks the model fallback chain, and requests never send OpenRouter models or fallbacks arrays
• quality_reviewer is the hard replacement for the former api_mini alias; old clients must update the alias
• 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 execute the endpoint's configured default model; this transport call does not create a router decision
• Send an enabled registry key such as model: "open_coder" to map directly to that model profile
• Even if you don't send model, the endpoint's active model is used
• If quota is exceeded, 429 is returned
• If 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
• If the server-side OPENROUTER_API_KEY is missing or rejected, the request fails as a provider-configuration error. /v1/responses does not walk a cross-model fallback chain

Router V1 for orchestrated workflows

Agent Orchestrator uses the separate authoritative contract under /v1/router/*: capabilities, models, routes, feedback, completions, estimates, pricing, and revisioned outcomes.

The router contract requires bounded RoutingEvidenceV1, commits one exact primary/fallback chain and generation profile, and returns likely and upper attempt costs for each executable model. Retries and fallbacks reuse the same route. The OpenAI-compatible /v1/responses endpoint is transport-only and does not classify tasks or update routing learning.

See the repository's docs/router-v1.md for the integrity headers, idempotency rules, structured errors, and lifecycle contract.

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
• 429: Endpoint quota exceeded. Example message: Quota exceeded for this endpoint.
• 500: Unexpected server or upstream error

Audit export endpoint

For legal-record 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
• Privacy guide for compliance operations