Create an instance

Create a Conversation instance

curl --request POST \
  --url https://api.usenexio.com/api/v1/conversation-instances \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "slug": "<string>",
  "label": "<string>",
  "description": "<string>",
  "config": {
    "model_policy": {
      "max_tokens": 4096
    },
    "system_prompt": "<string>",
    "engines": "*",
    "tools": {
      "platform_packs": [],
      "client_tools": [
        {
          "name": "<string>",
          "description": "<string>",
          "input_schema": {},
          "requires_confirmation": true
        }
      ]
    },
    "components": [
      {
        "component": "<string>",
        "version": 2,
        "props_schema": {}
      }
    ],
    "data_sources": [
      {
        "ref": "<string>",
        "sources": [
          "<string>"
        ],
        "notes": "<string>"
      }
    ],
    "access": {
      "personas": [
        "<string>"
      ]
    },
    "limits": {
      "max_tool_rounds": 25,
      "max_turn_output_tokens": 64000,
      "max_history_messages": 50
    },
    "guardrails": {
      "refusal_domains": [
        {
          "id": "<string>",
          "scenarios": [
            "<string>"
          ],
          "description": "<string>",
          "condition": "<string>",
          "check": "<string>",
          "route": "<string>"
        }
      ],
      "escalation_rules": [
        {
          "id": "<string>",
          "scenarios": [
            "<string>"
          ],
          "description": "<string>",
          "condition": "<string>",
          "check": "<string>",
          "route": "<string>"
        }
      ],
      "output_checks": [
        {
          "id": "<string>",
          "scenarios": [
            "<string>"
          ],
          "description": "<string>",
          "condition": "<string>",
          "check": "<string>",
          "route": "<string>"
        }
      ]
    },
    "evals": {},
    "retention": {
      "conversation_days": 2,
      "thread_days": 2
    },
    "annotations": {
      "enabled": true
    },
    "data_scope": {},
    "attachments": {
      "enabled": true,
      "max_files_per_message": 5,
      "max_bytes_per_file": 19660800,
      "accepted_media_types": [
        "<string>"
      ],
      "unwrap_archives": true,
      "retention_days": 2
    }
  }
}
'

import requests

url = "https://api.usenexio.com/api/v1/conversation-instances"

payload = {
    "slug": "<string>",
    "label": "<string>",
    "description": "<string>",
    "config": {
        "model_policy": { "max_tokens": 4096 },
        "system_prompt": "<string>",
        "engines": "*",
        "tools": {
            "platform_packs": [],
            "client_tools": [
                {
                    "name": "<string>",
                    "description": "<string>",
                    "input_schema": {},
                    "requires_confirmation": True
                }
            ]
        },
        "components": [
            {
                "component": "<string>",
                "version": 2,
                "props_schema": {}
            }
        ],
        "data_sources": [
            {
                "ref": "<string>",
                "sources": ["<string>"],
                "notes": "<string>"
            }
        ],
        "access": { "personas": ["<string>"] },
        "limits": {
            "max_tool_rounds": 25,
            "max_turn_output_tokens": 64000,
            "max_history_messages": 50
        },
        "guardrails": {
            "refusal_domains": [
                {
                    "id": "<string>",
                    "scenarios": ["<string>"],
                    "description": "<string>",
                    "condition": "<string>",
                    "check": "<string>",
                    "route": "<string>"
                }
            ],
            "escalation_rules": [
                {
                    "id": "<string>",
                    "scenarios": ["<string>"],
                    "description": "<string>",
                    "condition": "<string>",
                    "check": "<string>",
                    "route": "<string>"
                }
            ],
            "output_checks": [
                {
                    "id": "<string>",
                    "scenarios": ["<string>"],
                    "description": "<string>",
                    "condition": "<string>",
                    "check": "<string>",
                    "route": "<string>"
                }
            ]
        },
        "evals": {},
        "retention": {
            "conversation_days": 2,
            "thread_days": 2
        },
        "annotations": { "enabled": True },
        "data_scope": {},
        "attachments": {
            "enabled": True,
            "max_files_per_message": 5,
            "max_bytes_per_file": 19660800,
            "accepted_media_types": ["<string>"],
            "unwrap_archives": True,
            "retention_days": 2
        }
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    slug: '<string>',
    label: '<string>',
    description: '<string>',
    config: {
      model_policy: {max_tokens: 4096},
      system_prompt: '<string>',
      engines: '*',
      tools: {
        platform_packs: [],
        client_tools: [
          {
            name: '<string>',
            description: '<string>',
            input_schema: {},
            requires_confirmation: true
          }
        ]
      },
      components: [{component: '<string>', version: 2, props_schema: {}}],
      data_sources: [{ref: '<string>', sources: ['<string>'], notes: '<string>'}],
      access: {personas: ['<string>']},
      limits: {max_tool_rounds: 25, max_turn_output_tokens: 64000, max_history_messages: 50},
      guardrails: {
        refusal_domains: [
          {
            id: '<string>',
            scenarios: ['<string>'],
            description: '<string>',
            condition: '<string>',
            check: '<string>',
            route: '<string>'
          }
        ],
        escalation_rules: [
          {
            id: '<string>',
            scenarios: ['<string>'],
            description: '<string>',
            condition: '<string>',
            check: '<string>',
            route: '<string>'
          }
        ],
        output_checks: [
          {
            id: '<string>',
            scenarios: ['<string>'],
            description: '<string>',
            condition: '<string>',
            check: '<string>',
            route: '<string>'
          }
        ]
      },
      evals: {},
      retention: {conversation_days: 2, thread_days: 2},
      annotations: {enabled: true},
      data_scope: {},
      attachments: {
        enabled: true,
        max_files_per_message: 5,
        max_bytes_per_file: 19660800,
        accepted_media_types: ['<string>'],
        unwrap_archives: true,
        retention_days: 2
      }
    }
  })
};

fetch('https://api.usenexio.com/api/v1/conversation-instances', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "slug": "<string>",
  "label": "<string>",
  "description": "<string>",
  "status": "active",
  "group_key": "<string>",
  "managed_by": "org",
  "follows_canonical": true,
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "config": {
    "model_policy": {
      "max_tokens": 4096
    }
  },
  "config_hash": "<string>"
}

{
  "code": "<string>",
  "message": "<string>",
  "details": "<unknown>"
}

{
  "code": "unauthorized",
  "message": "Missing or invalid API key"
}

{
  "code": "insufficient_capability",
  "message": "API key does not have permission for this action"
}

{
  "code": "<string>",
  "message": "<string>",
  "details": "<unknown>"
}

{
  "code": "rate_limited",
  "message": "Rate limit exceeded"
}

{
  "code": "internal_error",
  "message": "Internal server error"
}

{
  "code": "auth_unavailable",
  "message": "API key authentication is temporarily unavailable"
}

{
  "code": "request_timeout",
  "message": "Request timed out"
}

POST

api

conversation-instances

Create a Conversation instance

curl --request POST \
  --url https://api.usenexio.com/api/v1/conversation-instances \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "slug": "<string>",
  "label": "<string>",
  "description": "<string>",
  "config": {
    "model_policy": {
      "max_tokens": 4096
    },
    "system_prompt": "<string>",
    "engines": "*",
    "tools": {
      "platform_packs": [],
      "client_tools": [
        {
          "name": "<string>",
          "description": "<string>",
          "input_schema": {},
          "requires_confirmation": true
        }
      ]
    },
    "components": [
      {
        "component": "<string>",
        "version": 2,
        "props_schema": {}
      }
    ],
    "data_sources": [
      {
        "ref": "<string>",
        "sources": [
          "<string>"
        ],
        "notes": "<string>"
      }
    ],
    "access": {
      "personas": [
        "<string>"
      ]
    },
    "limits": {
      "max_tool_rounds": 25,
      "max_turn_output_tokens": 64000,
      "max_history_messages": 50
    },
    "guardrails": {
      "refusal_domains": [
        {
          "id": "<string>",
          "scenarios": [
            "<string>"
          ],
          "description": "<string>",
          "condition": "<string>",
          "check": "<string>",
          "route": "<string>"
        }
      ],
      "escalation_rules": [
        {
          "id": "<string>",
          "scenarios": [
            "<string>"
          ],
          "description": "<string>",
          "condition": "<string>",
          "check": "<string>",
          "route": "<string>"
        }
      ],
      "output_checks": [
        {
          "id": "<string>",
          "scenarios": [
            "<string>"
          ],
          "description": "<string>",
          "condition": "<string>",
          "check": "<string>",
          "route": "<string>"
        }
      ]
    },
    "evals": {},
    "retention": {
      "conversation_days": 2,
      "thread_days": 2
    },
    "annotations": {
      "enabled": true
    },
    "data_scope": {},
    "attachments": {
      "enabled": true,
      "max_files_per_message": 5,
      "max_bytes_per_file": 19660800,
      "accepted_media_types": [
        "<string>"
      ],
      "unwrap_archives": true,
      "retention_days": 2
    }
  }
}
'

import requests

url = "https://api.usenexio.com/api/v1/conversation-instances"

payload = {
    "slug": "<string>",
    "label": "<string>",
    "description": "<string>",
    "config": {
        "model_policy": { "max_tokens": 4096 },
        "system_prompt": "<string>",
        "engines": "*",
        "tools": {
            "platform_packs": [],
            "client_tools": [
                {
                    "name": "<string>",
                    "description": "<string>",
                    "input_schema": {},
                    "requires_confirmation": True
                }
            ]
        },
        "components": [
            {
                "component": "<string>",
                "version": 2,
                "props_schema": {}
            }
        ],
        "data_sources": [
            {
                "ref": "<string>",
                "sources": ["<string>"],
                "notes": "<string>"
            }
        ],
        "access": { "personas": ["<string>"] },
        "limits": {
            "max_tool_rounds": 25,
            "max_turn_output_tokens": 64000,
            "max_history_messages": 50
        },
        "guardrails": {
            "refusal_domains": [
                {
                    "id": "<string>",
                    "scenarios": ["<string>"],
                    "description": "<string>",
                    "condition": "<string>",
                    "check": "<string>",
                    "route": "<string>"
                }
            ],
            "escalation_rules": [
                {
                    "id": "<string>",
                    "scenarios": ["<string>"],
                    "description": "<string>",
                    "condition": "<string>",
                    "check": "<string>",
                    "route": "<string>"
                }
            ],
            "output_checks": [
                {
                    "id": "<string>",
                    "scenarios": ["<string>"],
                    "description": "<string>",
                    "condition": "<string>",
                    "check": "<string>",
                    "route": "<string>"
                }
            ]
        },
        "evals": {},
        "retention": {
            "conversation_days": 2,
            "thread_days": 2
        },
        "annotations": { "enabled": True },
        "data_scope": {},
        "attachments": {
            "enabled": True,
            "max_files_per_message": 5,
            "max_bytes_per_file": 19660800,
            "accepted_media_types": ["<string>"],
            "unwrap_archives": True,
            "retention_days": 2
        }
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    slug: '<string>',
    label: '<string>',
    description: '<string>',
    config: {
      model_policy: {max_tokens: 4096},
      system_prompt: '<string>',
      engines: '*',
      tools: {
        platform_packs: [],
        client_tools: [
          {
            name: '<string>',
            description: '<string>',
            input_schema: {},
            requires_confirmation: true
          }
        ]
      },
      components: [{component: '<string>', version: 2, props_schema: {}}],
      data_sources: [{ref: '<string>', sources: ['<string>'], notes: '<string>'}],
      access: {personas: ['<string>']},
      limits: {max_tool_rounds: 25, max_turn_output_tokens: 64000, max_history_messages: 50},
      guardrails: {
        refusal_domains: [
          {
            id: '<string>',
            scenarios: ['<string>'],
            description: '<string>',
            condition: '<string>',
            check: '<string>',
            route: '<string>'
          }
        ],
        escalation_rules: [
          {
            id: '<string>',
            scenarios: ['<string>'],
            description: '<string>',
            condition: '<string>',
            check: '<string>',
            route: '<string>'
          }
        ],
        output_checks: [
          {
            id: '<string>',
            scenarios: ['<string>'],
            description: '<string>',
            condition: '<string>',
            check: '<string>',
            route: '<string>'
          }
        ]
      },
      evals: {},
      retention: {conversation_days: 2, thread_days: 2},
      annotations: {enabled: true},
      data_scope: {},
      attachments: {
        enabled: true,
        max_files_per_message: 5,
        max_bytes_per_file: 19660800,
        accepted_media_types: ['<string>'],
        unwrap_archives: true,
        retention_days: 2
      }
    }
  })
};

fetch('https://api.usenexio.com/api/v1/conversation-instances', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "slug": "<string>",
  "label": "<string>",
  "description": "<string>",
  "status": "active",
  "group_key": "<string>",
  "managed_by": "org",
  "follows_canonical": true,
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "config": {
    "model_policy": {
      "max_tokens": 4096
    }
  },
  "config_hash": "<string>"
}

{
  "code": "<string>",
  "message": "<string>",
  "details": "<unknown>"
}

{
  "code": "unauthorized",
  "message": "Missing or invalid API key"
}

{
  "code": "insufficient_capability",
  "message": "API key does not have permission for this action"
}

{
  "code": "<string>",
  "message": "<string>",
  "details": "<unknown>"
}

{
  "code": "rate_limited",
  "message": "Rate limit exceeded"
}

{
  "code": "internal_error",
  "message": "Internal server error"
}

{
  "code": "auth_unavailable",
  "message": "API key authentication is temporarily unavailable"
}

{
  "code": "request_timeout",
  "message": "Request timed out"
}

Authorizations

Authorization

string

header

required

Send the key as Authorization: Bearer <key>. Two kinds of key exist.

Organization keys are issued in the portal (Settings, then API keys), each bound to one environment, shaped nx_<environment slug>_<64 hex>. They carry no capabilities and pass every capability check, with one exception: routes under /api/v1/records, /api/v1/engines/{id}/opportunities, /api/v1/graph and /api/v1/catalog/documents accept an organization key only when its environment is live, and refuse any other with 403 scoped_key_required. Revocation takes effect within 60 seconds.

Scoped keys are issued by Nexio on request, shaped nxsk_v1_<24 hex key id>_<43 character secret>. Each is bound to one org, one environment, a set of engines and a set of capabilities. A malformed, unknown or revoked nxsk_ key fails with 401 and is never retried as an organization key. Revocation takes effect on the next request. A scoped key without a route's capability gets 403 insufficient_capability; a scoped key not bound to the engine gets 403 engine_binding_forbidden.

Key-grantable capabilities: engines:read, runs:write, runs:read, runs:defensibility:read, runs:test, catalog:read, catalog:documents:read, webhooks:manage, conversations:use, conversations:export, records:read, records:opportunities:run, actions:write, actions:read, graph:read, records:analyze.

Routes that accept organization keys only (every scoped key gets 403 insufficient_capability): environment management, engine create, update, configuration and publish, and conversation instance authoring. Each operation description names the capability a scoped key needs.

Body

application/json

slug

string

required

Required string length: 3 - 50

Pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$

label

string

required

1 to 100 UTF-8 bytes.

Minimum string length: 1

description

string

At most 500 UTF-8 bytes.

config

object

Full instance config; defaults applied when omitted.

Option 1
Option 2

Hide child attributes

config.model_policy

object

required

Hide child attributes

config.model_policy.max_tokens

integer

required

Maximum output tokens for each model call in a turn (a turn with tool rounds makes several calls; limits.max_turn_output_tokens bounds the whole turn). 0 selects the platform default of 1024.

Required range: 0 <= x <= 8192

config.system_prompt

string

required

The instance's instructions.

config.engines

required

The engine allowlist. The string * allows every engine the calling principal may see; an array lists engine slugs or IDs. An empty array allows none. Array entries must be non-blank and unique.

Available options:

*

config.tools

object

required

Hide child attributes

config.tools.platform_packs

enum<string>[]

required

Declaring platform.write also requires platform.read.

Available options:

platform.read,

platform.write

config.tools.client_tools

object[]

required

Hide child attributes

config.tools.client_tools.name

string

required

At most 64 characters, unique within the instance, and must not contain __.

Maximum string length: 64

Pattern: ^[a-zA-Z0-9_-]+$

config.tools.client_tools.effect

enum<string>

required

Available options:

read,

write,

outbound,

destructive

config.tools.client_tools.description

string

config.tools.client_tools.input_schema

object | null

JSON Schema for the tool's input. It must be an object that compiles as a JSON Schema. Absent or null means no input schema.

config.tools.client_tools.requires_confirmation

boolean

Always true in effect for write, outbound and destructive tools; sending false for one of them is rejected.

config.components

object[]

required

No two entries may share the same component and version.

Hide child attributes

config.components.component

string

required

Must not be blank.

Pattern: \S

config.components.version

integer

required

Required range: x >= 1

config.components.props_schema

object | null

JSON Schema for the component's props. Absent or null means no props schema.

config.data_sources

object[]

required

At least one grounding surface. Each entry declares exactly one form: an inline sources list (at least one key, with optional notes), or a ref to a stored data scope with no sources and no notes (blank notes is accepted).

Minimum array length: 1

Option 1
Option 2

Hide child attributes

config.data_sources.ref

string

required

Pattern: \S

config.data_sources.sources

string[]

Data-access keys, compared after trimming. Each must be one of engines, runs, run_payloads, metrics, catalog, connections, webhooks, feedback, team.

Pattern: \S

config.data_sources.notes

string

Absent or blank. A reference entry with notes answers 400.

Pattern: ^\s*$

config.access

object

required

Hide child attributes

config.access.personas

string[]

required

At least one persona. "*" allows any persona.

Minimum array length: 1

Pattern: \S

config.limits

object

required

Hide child attributes

config.limits.max_tool_rounds

integer

required

Required range: 1 <= x <= 50

config.limits.max_turn_output_tokens

integer

required

Required range: 1 <= x <= 128000

config.limits.max_history_messages

integer

required

Required range: 1 <= x <= 100

config.guardrails

object

required

Hide child attributes

config.guardrails.refusal_domains

object[]

required

Hide child attributes

config.guardrails.refusal_domains.id

string

required

Pattern: \S

config.guardrails.refusal_domains.scenarios

string[]

required

Minimum array length: 1

Pattern: \S

config.guardrails.refusal_domains.description

string

config.guardrails.refusal_domains.condition

string

config.guardrails.refusal_domains.check

string

A regular expression, matched case-insensitively with . matching newlines. It is not compiled when the config is saved; a pattern that does not compile fails every turn with 500 guardrail_config_invalid.

config.guardrails.refusal_domains.route

string

config.guardrails.escalation_rules

object[]

required

Hide child attributes

config.guardrails.escalation_rules.id

string

required

Pattern: \S

config.guardrails.escalation_rules.scenarios

string[]

required

Minimum array length: 1

Pattern: \S

config.guardrails.escalation_rules.description

string

config.guardrails.escalation_rules.condition

string

config.guardrails.escalation_rules.check

string

config.guardrails.escalation_rules.route

string

config.guardrails.output_checks

object[]

required

Hide child attributes

config.guardrails.output_checks.id

string

required

Pattern: \S

config.guardrails.output_checks.scenarios

string[]

required

Minimum array length: 1

Pattern: \S

config.guardrails.output_checks.description

string

config.guardrails.output_checks.condition

string

config.guardrails.output_checks.check

string

config.guardrails.output_checks.route

string

config.evals

object

required

Hide child attributes

config.evals.on_regression

enum<string>

required

Available options:

block,

warn

config.retention

object

required

Needs conversation_days or its legacy spelling thread_days.

Option 1
Option 2

Hide child attributes

config.retention.conversation_days

integer | null

required

A positive number of days. Null selects the platform default.

Required range: x >= 1

config.retention.thread_days

integer | null

deprecated

Legacy spelling of conversation_days, read as it when conversation_days is absent and ignored when it is present.

Required range: x >= 1

config.annotations

object

required

Hide child attributes

config.annotations.enabled

boolean

required

Recorded with the config. The annotation routes do not check it today.

config.data_scope

object

deprecated

Legacy spelling of one data_sources entry. Read as a one-entry data_sources list when data_sources is absent, and ignored when it is present.

config.attachments

object | null

Optional upload policy. Absent or null means the instance takes no attachments.

Hide child attributes

config.attachments.enabled

boolean | null

Null is read as false.

config.attachments.max_files_per_message

integer | null

0 or null selects the default of 5.

Required range: 0 <= x <= 10

config.attachments.max_bytes_per_file

integer<int64> | null

0 or null selects the platform ceiling of 39,321,600 bytes.

Required range: 0 <= x <= 39321600

config.attachments.accepted_media_types

string[] | null

Narrows the platform's accepted types. Empty or null means every type the platform accepts. Entries must be non-empty, unique and on the platform allowlist. A container type (message/rfc822, application/zip) needs unwrap_archives: true.

Minimum string length: 1

config.attachments.unwrap_archives

boolean | null

Null is read as false.

config.attachments.retention_days

integer | null

A positive number of days. Null follows the conversation's own retention.

Required range: x >= 1

Response

The created instance.

A Conversation instance: the configured object of the Conversations family, an orchestrator over engines. Its versioned config declares the engine access allowlist and data sources alongside model policy, tools, guardrails, evals, and retention. managed_by records who governs the instance (org or platform); follows_canonical marks a platform-managed follower whose effective config resolves from the platform-managed instance it follows (followers expose no local config).

string<uuid>

required

slug

string

required

label

string

required

description

string

required

status

enum<string>

required

Available options:

active,

archived

group_key

string

required

Key of the instance's semantic group within the organization, or an empty string when ungrouped. Same semantics as the engine group_key.

managed_by

enum<string>

required

Available options:

org,

platform

follows_canonical

boolean

required

created_at

string<date-time>

required

updated_at

string<date-time>

required

config

object

The live draft config; omitted on listings and for followers.

Hide child attributes

config.model_policy

object

Hide child attributes

config.model_policy.max_tokens

integer

Maximum output tokens for each model call in a turn (a turn with tool rounds makes several calls; limits.max_turn_output_tokens bounds the whole turn). 0 selects the platform default of 1024.

Required range: 0 <= x <= 8192

config_hash

string

Content hash of the live draft config. Omitted on listings and for followers, like config.

Last modified on September 25, 2026

Overview

Engines

Environments

Conversations

Webhooks

Events

Records

Graph

Platform

Create an instance

Authorizations

Body

Response