> ## Documentation Index > Fetch the complete documentation index at: https://docs.neoagent.io/llms.txt > Use this file to discover all available pages before exploring further. # Create a chat session > Create a session against a CONVERSATIONAL agent. Returns the session resource; messages are appended via `POST /chat/sessions//messages`. Select the agent with **exactly one** of `agent_id` (numeric) or `managed_agent_key` (a stable key for a Neo-managed agent, e.g. `NEO_SUPPORT`); the latter lets a caller target the agent without knowing its per-tenant id. A **platform** service account may pass `client_id` to create the session for another tenant — used by the converged Neo Support relay to run each MSP technician's turn as their own tenant. For a platform caller the agent is resolved from `bot_id` (the inbound Teams bot app id) + `inbound_tenant_id` (the message's M365 tenant): a white-label bot with a channel installed for that tenant routes to the channel's agent acting as the owning MSP (the acting tenant is then resolved server-side, overriding `client_id`, and returned on the resource); else the ACTIVE channel registered for that bot; else that tenant's Neo Support agent. The caller is confined to those outcomes (never an arbitrary agent). Any non-platform caller passing `client_id` is rejected with 403. A white-label session is always scoped to one end-company, resolved server-side from `inbound_tenant_id`. If that tenant isn't linked to exactly one company in the owning MSP's dashboard, the create is refused with 409 `end_company_not_mapped`; the error message is end-user-relayable and tells the MSP admin what to link. ## OpenAPI ````yaml https://api.neoagent.io/public-api/openapi.json post /public-api/chat/sessions openapi: 3.1.0 info: description: >- Neo's public contract for the dashboard ChatAgent, partner integrations, and MSP automation. Every response is wrapped in a `{data, meta}` envelope; errors use `{error: {code, message, details?}, meta: {request_id}}`. Authenticate with a `Bearer neo_sk__` API key (service account) or a Microsoft Entra ID JWT (dashboard user). Signed-URL endpoints (end-user feedback links) take a `signature` query parameter instead. title: Neo Public API version: 1.0.0 servers: - url: https://api.neoagent.io security: [] tags: - description: Service metadata — health, OpenAPI. name: Meta - description: Agents and workflows — read, version history, delete, stats. name: Agents - description: Agent/workflow execution history, sub-resources, retry/cancel. name: Executions - description: PSA webhook events and their workflow-match results. name: Callbacks - description: Technician-in-the-loop approval requests. name: TIL requests - description: RMM script executions triggered by agents. name: RMM scripts - description: Dispatch-agent field-update decisions. name: Dispatch - description: The authenticated tenant. name: Tenant - description: Agent-builder schema catalogs (raw JSON payloads). name: Schemas - description: Escalate to the Neo team (HubSpot ticket). name: Escalation - description: Tenant settings. name: Settings - description: Tenant API-key management (dashboard JWT only). name: API keys - description: End-user feedback links (signed-URL auth). name: Feedback - description: End-client companies (CRUD + bulk-update). name: End companies - description: Channels — bind a CONVERSATIONAL agent to a transport (Teams). name: Channels - description: PSA/RMM/M365 integration status and connection management. name: Integrations - description: Technician roster (controls TIL routing and paging). name: Technicians - description: Future runs queued for TRIGGERED agents. name: Scheduled work - description: Subscription state and customer-facing credit usage (no provider $). name: Billing - description: Inbox messages and announcements. name: Inbox & Comms - description: Tenant-authored agent skills (CRUD) and the built-in skill catalog. name: Skills paths: /public-api/chat/sessions: post: tags: - Chat summary: Create a chat session description: >- Create a session against a CONVERSATIONAL agent. Returns the session resource; messages are appended via `POST /chat/sessions//messages`. Select the agent with **exactly one** of `agent_id` (numeric) or `managed_agent_key` (a stable key for a Neo-managed agent, e.g. `NEO_SUPPORT`); the latter lets a caller target the agent without knowing its per-tenant id. A **platform** service account may pass `client_id` to create the session for another tenant — used by the converged Neo Support relay to run each MSP technician's turn as their own tenant. For a platform caller the agent is resolved from `bot_id` (the inbound Teams bot app id) + `inbound_tenant_id` (the message's M365 tenant): a white-label bot with a channel installed for that tenant routes to the channel's agent acting as the owning MSP (the acting tenant is then resolved server-side, overriding `client_id`, and returned on the resource); else the ACTIVE channel registered for that bot; else that tenant's Neo Support agent. The caller is confined to those outcomes (never an arbitrary agent). Any non-platform caller passing `client_id` is rejected with 403. A white-label session is always scoped to one end-company, resolved server-side from `inbound_tenant_id`. If that tenant isn't linked to exactly one company in the owning MSP's dashboard, the create is refused with 409 `end_company_not_mapped`; the error message is end-user-relayable and tells the MSP admin what to link. operationId: public_api.chat_session_create_post parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateChatSessionRequest' required: true responses: '200': content: application/json: schema: properties: data: $ref: '#/components/schemas/ChatSessionResource' meta: $ref: '#/components/schemas/SuccessMeta' required: - data - meta type: object description: Success. '400': content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: Bad request — malformed input. '401': content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: Unauthenticated — missing or invalid credentials. '403': content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: Forbidden — authenticated but not allowed. '404': content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: Not found. '409': content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: Conflict — the resource is in a state that blocks this operation. '422': content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: Request validation failed. '429': content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: Rate limited — see Retry-After. '500': content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: Internal server error. security: - bearerAuth: [] components: schemas: CreateChatSessionRequest: properties: agent_id: anyOf: - type: integer - type: 'null' default: null description: >- Numeric id of the CONVERSATIONAL agent to run the session against. Provide exactly one of `agent_id` or `managed_agent_key`. title: Agent Id bot_id: anyOf: - type: string - type: 'null' default: null description: >- Inbound Teams bot app id, forwarded by the platform relay so the backend routes the session to the ACTIVE channel registered for that bot — else the tenant's Neo Support agent. Honored only for a platform service account; ignored for other callers. title: Bot Id client_id: anyOf: - type: string - type: 'null' default: null description: >- Target tenant to create the session for. Honored only for a platform service account; the agent is resolved from `bot_id` (a matching channel, else that tenant's Neo Support agent). Any other caller passing it gets 403. Omit to use the caller's own tenant. title: Client Id inbound_tenant_id: anyOf: - type: string - type: 'null' default: null description: >- The inbound message's M365 tenant id, forwarded by the platform relay. With `bot_id`, lets the backend route a white-label turn via the channel installed for that tenant — the acting tenant is then resolved server-side from the channel's owning MSP, overriding `client_id`. Honored only for a platform service account. title: Inbound Tenant Id managed_agent_key: anyOf: - $ref: '#/components/schemas/ManagedAgentKey' - type: 'null' default: null description: >- Target a Neo-managed agent by its stable key instead of a numeric id — the backend resolves the target tenant's row. Lets the converged Neo Support relay stay agent-id-agnostic across tenants. Provide exactly one of `agent_id` or `managed_agent_key`. title: anyOf: - type: string - type: 'null' default: null title: Title title: CreateChatSessionRequest type: object ChatSessionResource: description: >- Public surface of a chat session row. Renamed `agent_id` for partner clarity. properties: agent_id: title: Agent Id type: integer archived_at: anyOf: - format: date-time type: string - type: 'null' title: Archived At channel: title: Channel type: string client_id: title: Client Id type: string created_at: format: date-time title: Created At type: string id: title: Id type: string show_agent_progress_steps: anyOf: - type: boolean - type: 'null' default: null title: Show Agent Progress Steps title: anyOf: - type: string - type: 'null' title: Title updated_at: format: date-time title: Updated At type: string required: - id - agent_id - client_id - title - channel - created_at - updated_at - archived_at title: ChatSessionResource type: object SuccessMeta: properties: pagination: $ref: '#/components/schemas/Pagination' request_id: format: uuid type: string timings_ms: additionalProperties: type: number type: object warnings: description: >- Non-fatal warnings about the created/updated resource (e.g. an unhealthy PSA callback). items: type: string type: array required: - request_id - timings_ms type: object ErrorEnvelope: properties: error: properties: code: description: Stable machine-readable error code. type: string details: additionalProperties: true type: object message: type: string required: - code - message type: object meta: properties: request_id: format: uuid type: - string - 'null' type: object required: - error - meta type: object ManagedAgentKey: description: >- Stable key identifying a Neo-managed agent. `NEO_SUPPORT` is the per-tenant Neo Support agent. enum: - NEO_SUPPORT title: ManagedAgentKey type: string Pagination: properties: has_more: type: boolean next_cursor: type: - string - 'null' required: - next_cursor - has_more type: object securitySchemes: bearerAuth: description: >- `Authorization: Bearer ` where `` is either a `neo_sk__` API key (service account) or a Microsoft Entra ID access token (dashboard user). scheme: bearer type: http ````