Resources

Diese Seite ist noch nicht auf Deutsch verfügbar. Sie sehen die englische Fassung.

All requests use a secret API key: Authorization: Bearer nrn_sk_... or x-api-key: nrn_sk_.... A key can only read or write resources that belong to its own project or organization — anything else is 404 not_found, exactly as if it didn’t exist, whether the mismatch is in the URL or in a body field that names another project’s resource. A publishable key, or a key whose scope can’t call an endpoint, is 403 forbidden. See Errors.

Reference

Operation	What it does
`GET /v1/organization`	The calling key’s own organization.
`GET /v1/me`	The calling key’s organization id, project id, scope, and name. Available with the next service release.
`GET /v1/organization/usage`	Usage rollups for the calling key’s own organization. Not available yet — returns `501 usage_unavailable`.
`GET /v1/projects/{projectId}`	One project.
`GET /v1/projects/{projectId}/agent`	A project’s agent configuration.
`PATCH /v1/projects/{projectId}/agent`	Update a project’s agent configuration.
`GET /v1/projects/{projectId}/agent/simple`	A Simple project’s composed agent configuration.
`PUT /v1/projects/{projectId}/agent/simple`	Update a Simple project’s greeting, facts, or skills.
`GET /v1/catalogue/skills`	The published skill catalogue (for building a Simple-project request).
`GET /v1/catalogue/templates`	The published template catalogue.
`GET /v1/projects/{projectId}/conversations`	List conversations in a project.
`POST /v1/projects/{projectId}/conversations`	Create a conversation.
`GET /v1/conversations/{id}`	One conversation (summary).
`PATCH /v1/conversations/{id}`	Update a conversation’s name, description, or agent.
`DELETE /v1/conversations/{id}`	Delete a conversation.
`GET /v1/conversations/{id}/design`	The active version’s design (Conversation Design).
`PUT /v1/conversations/{id}/design`	Save a new design as the active version.
`GET /v1/conversations/{id}/versions`	List a conversation’s versions (without design bodies).
`GET /v1/conversations/{id}/versions/{n}/design`	One past version’s design.
`POST /v1/conversations/{id}/versions/{n}/activate`	Make an existing version active.
`GET /v1/projects/{projectId}/knowledge`	List knowledge bases in a project.
`POST /v1/projects/{projectId}/knowledge`	Create a knowledge base.
`GET /v1/knowledge/{kbId}`	One knowledge base, with its sources.
`DELETE /v1/knowledge/{kbId}`	Delete a knowledge base.
`POST /v1/knowledge/{kbId}/sources`	Add a source to a knowledge base.
`DELETE /v1/knowledge/{kbId}/sources/{id}`	Delete a source.
`GET /v1/projects/{projectId}/integrations`	List a project’s integrations.
`GET /v1/projects/{projectId}/numbers`	List a project’s phone numbers.
`PATCH /v1/numbers/{id}`	Assign or unassign the conversation a number routes to.
`GET /v1/projects/{projectId}/web-sessions/agents`	List a project’s web session agents.
`POST /v1/projects/{projectId}/web-sessions/agents`	Create a web session agent.
`PATCH /v1/projects/{projectId}/web-sessions/agents/{id}`	Update a web session agent.
`DELETE /v1/projects/{projectId}/web-sessions/agents/{id}`	Delete a web session agent.
`POST /v1/web-sessions`	Dispatch a new web session for a web session agent.
`GET /v1/projects/{projectId}/keys`	List a project’s API keys (never the key value).
`POST /v1/projects/{projectId}/keys`	Mint a new publishable key.
`POST /v1/keys/{id}/revoke`	Revoke an API key.

Organization

curl https://service.testing.nairon.cloud/v1/organization \
  -H "Authorization: Bearer NAIRON_API_KEY"

{ "id": "org_...", "name": "Acme Support", "type": "standard" }

There’s no organization id in the path — a key’s own organization is always what GET /v1/organization and GET /v1/organization/usage mean.

Me

GET /v1/me returns the calling key’s own context: which organization and project it belongs to, its scope, and its id and name. It never returns the key itself. keyName is omitted when the key has no name. Use it to find the projectId the REST paths below need.

curl https://service.testing.nairon.cloud/v1/me \
  -H "Authorization: Bearer NAIRON_API_KEY"

{ "organizationId": "org_...", "projectId": "proj_...", "scope": "service_app",
  "keyId": "key_...", "keyName": "CI key" }

Project

{
  "id": "proj_...", "organizationId": "org_...", "name": "Acme Hotline",
  "description": "Main inbound line", "status": "active", "plan": "growth",
  "type": "hotline", "mode": "advanced", "channels": ["phone", "website"],
  "industry": "Healthcare", "createdAt": "...", "updatedAt": "..."
}

mode is advanced (managed through Conversations, below) or simple.

Agent

A project’s agent is its default assistant configuration:

{
  "id": "agent_...", "projectId": "proj_...", "name": "Default agent",
  "languages": ["de", "en"], "profile": "standard",
  "voice": { "id": "voice_...", "name": "Aria" },
  "transcriptionDictionary": ["Nairon", "Kapsule"]
}

profile is one of fast, standard, smart (write) or additionally a preview realtime tier value (read-only). PATCH /v1/projects/{projectId}/agent accepts {name?, languages?, profile?, voiceId?, transcriptionDictionary?} — voiceId must be a global voice or a custom voice belonging to the same project.

Conversations

A Conversation is what a caller or chat visitor actually talks to — one project can have several. design.kind is graph (has a full Conversation Design, managed through this API) or simple (managed through the separate Simple-project agent resource below — reading or writing its design through the Conversation Design endpoints returns 501 not_yet_supported).

curl https://service.testing.nairon.cloud/v1/projects/PROJECT_ID/conversations \
  -H "Authorization: Bearer NAIRON_API_KEY"

{
  "id": "conv_...", "projectId": "proj_...", "name": "Support conversation",
  "description": "Main IVR tree", "design": { "kind": "graph" },
  "activeVersion": { "n": 3, "tag": "v3", "createdAt": "..." }
}

POST /v1/projects/{projectId}/conversations takes {name, description?, design?}; an omitted design creates a minimal greeting-then-end conversation. PATCH /v1/conversations/{id} takes {name?, description?, agentId?} (agentId reassigns which agent the conversation uses at runtime). DELETE /v1/conversations/{id} removes it.

Design

GET /v1/conversations/{id}/design returns the active version’s design, and PUT /v1/conversations/{id}/design saves a new design as the new active version — see Conversation Design for the document format and the save pipeline (structural validation, then an AI-disclosure check on any text you changed). Every successful save both creates the new version and activates it — there is no separate “save” step before “publish”.

GET /v1/conversations/{id}/versions lists every version ({n, tag, isActive, createdAt}, no design body); GET /v1/conversations/{id}/versions/{n}/design reads one specific past version’s design; POST /v1/conversations/{id}/versions/{n}/activate makes an existing version active again without creating a new one.

Simple-project agent

A Simple project’s agent is a template plus a set of enabled skills, not a graph — it has its own resource, separate from Conversations above.

curl https://service.testing.nairon.cloud/v1/projects/PROJECT_ID/agent/simple \
  -H "Authorization: Bearer NAIRON_API_KEY"

{
  "projectId": "proj_...", "agentId": "conv_...", "kind": "simple",
  "template": { "key": "answer-box", "name": "Answer box + callback", "version": 2 },
  "greeting": "Thanks for calling Acme Support, how can I help?",
  "facts": { "business_hours": { "kind": "text", "label": "Business hours", "value": "Mon-Fri 9-5" } },
  "skills": [
    { "key": "business_info", "name": "Business info", "enabled": true, "locked": false, "config": {} },
    { "key": "callback", "name": "Callback", "enabled": true, "locked": false, "config": {} }
  ],
  "afterCall": [],
  "status": { "runtimeReady": true, "skipped": [] }
}

PUT /v1/projects/{projectId}/agent/simple takes a partial {greeting?, facts?, skills?} and returns the same shape updated. hangupAfterSeconds is still accepted for compatibility but ignored: silence on every call is handled by a fixed inactivity rule (a spoken warning after 120 seconds, then the call ends). A skill’s config holds its own structured fields; needs (on a read) names an unmet prerequisite (integration:calendar, integration:crm, or knowledge_base) blocking that skill from actually running. status.skipped lists skills the agent currently skips and why. Enabling a locked skill, or a skill whose template doesn’t offer it, is rejected.

GET /v1/catalogue/skills and GET /v1/catalogue/templates return the published skill and template catalogues — the reference data you need to build a valid PUT body (every skill key Simple projects can enable, each template’s default skill set, and each skill’s config field shapes). Both are global reads, not scoped to a project.

Knowledge

A knowledge base holds one or more sources a Conversation can search.

{
  "id": "kb_...", "name": "Product FAQ", "sources": [
    { "id": "src_...", "name": "faq.html", "type": "website", "indexingStatus": "ready", "progress": 100 }
  ]
}

GET /v1/projects/{projectId}/knowledge lists knowledge bases (summary, no sources); GET /v1/knowledge/{kbId} returns one with its sources. POST /v1/projects/{projectId}/knowledge creates one ({name, description?}); DELETE /v1/knowledge/{kbId} removes it along with its sources.

POST /v1/knowledge/{kbId}/sources adds a source — one of:

{"type": "website", "name": "FAQ", "url": "https://example.com/faq"}
{"type": "file", "name": "Manual", "url": "https://example.com/manual.pdf"}
{"type": "text", "name": "Policy", "text": "Returns are accepted within 30 days..."}

The response includes indexing: "deferred" | "triggered" — indexing may be deferred in some environments; poll GET /v1/knowledge/{kbId} and watch indexingStatus/progress either way. DELETE /v1/knowledge/{kbId}/sources/{id} removes a single source.

Integrations

{ "id": "int_...", "provider": "salesforce", "name": "Sales CRM", "connected": true }

GET /v1/projects/{projectId}/integrations lists a project’s integrations. Credentials and provider-specific configuration are never included in a response — only whether one is connected.

Numbers

{
  "id": "num_...", "projectId": "proj_...", "e164": "+41800000000",
  "type": "local", "status": "active", "conversationId": "conv_..."
}

GET /v1/projects/{projectId}/numbers lists a project’s phone numbers. PATCH /v1/numbers/{id} with {conversationId: "conv_..." | null} assigns or unassigns which Conversation a number routes to — a conversation id from a different project, or one that doesn’t exist at all, is 404.

Web Sessions

A web session agent is a reusable configuration for embedding voice or text sessions in your own site or app (see also Voice Embed).

{
  "id": "wa_...", "name": "Site widget", "channel": "web",
  "scopes": ["voice", "text"], "allowedOrigins": ["https://example.com"],
  "conversationId": "conv_...", "status": "active"
}

GET /v1/projects/{projectId}/web-sessions/agents lists them. POST /v1/projects/{projectId}/web-sessions/agents creates one ({name, conversationId, channel?, scopes, allowedOrigins}); PATCH .../{id} partially updates one; DELETE .../{id} removes one.

POST /v1/web-sessions dispatches an actual session for a web session agent:

curl -X POST https://service.testing.nairon.cloud/v1/web-sessions \
  -H "Authorization: Bearer NAIRON_API_KEY" -H "Content-Type: application/json" \
  -d '{"webAgentId": "wa_...", "mode": "WEB_FULL"}'

{ "roomUrl": "wss://...", "token": "...", "expiresAt": "..." }

mode is WEB_FULL (voice, defaults here) or WEB_TEXT (text-only — see Web widget & text mode); an unrecognized value is rejected rather than silently falling back to a different, possibly-billed mode. This is the server-side way to start a session — with your own secret key, from your own backend — as an alternative to the client-side widget flow that uses a publishable key.

Keys

{
  "id": "key_...", "name": "CI key", "keyType": "publishable",
  "scope": "service_app", "keyPrefix": "nrn_pk_ab12", "last4": "wxyz",
  "status": "active", "lastUsedAt": "..."
}

GET /v1/projects/{projectId}/keys lists a project’s keys — the value is never included; only a prefix and last 4 characters. POST /v1/projects/{projectId}/keys mints a new key ({name, keyType?}); the response includes plaintext, the only time the full key value is ever returned. Only keyType: "publishable" can be minted this way — minting a secret key is 400 secret_keys_not_mintable. POST /v1/keys/{id}/revoke revokes a key; revoking the key you’re currently authenticated with is 409 cannot_revoke_current_key.

Also see

Conversation Design — the design document format.
MCP — every operation above as an MCP tool.
Errors — the full error code reference.
Full endpoint reference — generated request/response schema.