service-api (REST control plane)

service-api is Nairon’s control plane, hosted at https://service.v2.nairon.xyz. Where platform-api is the OpenAI-shaped data plane, service-api is a plain REST API for managing the resources you’d otherwise click through on app./platform..

Authenticate with a secret API key (nrn_sk_...), as Authorization: Bearer nrn_sk_... or x-api-key. Only secret keys are accepted — publishable keys (used for browser-facing surfaces like the web widget) are rejected everywhere on service-api.

Flows & versions

# List flows in a project
curl https://service.v2.nairon.xyz/v1/projects/PROJECT_ID/flows \
  -H "Authorization: Bearer NAIRON_API_KEY"

# Create a flow version
curl -X POST https://service.v2.nairon.xyz/v1/flows/FLOW_ID/versions \
  -H "Authorization: Bearer NAIRON_API_KEY" -H "Content-Type: application/json" \
  -d '{"flowSchema": { /* ... */ }}'

# Activate a version — this is what runtime picks up on the next call
curl -X POST https://service.v2.nairon.xyz/v1/flow-versions/VERSION_ID/activate \
  -H "Authorization: Bearer NAIRON_API_KEY"

Creating/saving a flow version through service-api reimplements the exact same save/publish transaction the dashboard editor uses, so an activated version is picked up by the runtime layer the same way regardless of which path created it.

Phone numbers & agent profiles

GET/POST /v1/projects/{projectId}/phone-numbers, PATCH /v1/phone-numbers/{id}/flow (reassign a number to a different flow), GET /v1/projects/{projectId}/agent-profiles, GET/PUT /v1/agent-profiles/{id}.

Usage

GET /v1/projects/{projectId}/usage and GET /v1/orgs/{orgId}/usage return usage timeseries for API-product consumption — see Usage & billing.

Partner endpoints

POST /v1/partner/customers (create a managed customer organization) and GET /v1/partner (profile, referral code, commission summary) — the API equivalent of the partner portal.

Headless endpoints

/v1/templates, /v1/templates/{id}/versions, /v1/template-versions/{id}/publish, /v1/templates/{id}/instances, /v1/instances/{id}, /v1/instances/{id}/upgrade — the API equivalent of the headless portal for creating templates and provisioning tenant instances programmatically.

Internal endpoints

/internal/* routes (API-key management, usage reads) are used by management-ui itself to power the platform. console and are authenticated with a separate internal service token — they are not part of the public developer surface.

See the full service-api reference for every endpoint, or connect via MCP instead of raw REST.