APIChat API v1

Costruisci conversazioni che possano farlo continuare a lavorare.

Trasmetti in streaming l'agente AI, il flusso di lavoro e le esecuzioni RAG nella tua applicazione con un'interfaccia autenticata, checkpoint ripristinabili ed eventi di avanzamento strutturati.

Protocollo di comunicazione

Server-Sent Events

Flusso di eventi UTF-8 su HTTPS. Ogni frame contiene un payload JSON al suo interno data: campo.

Avvio rapido

Una richiesta, un live streaming

Invia un messaggio a un agente, flusso di lavoro o destinazione RAG. La connessione rimane aperta mentre l'esecuzione emette eventi del ciclo di vita, passaggi di esecuzione e una risposta Markdown finale.

1. Autenticarsi

Invia la tua chiave API con ogni richiesta.

2. Inizia una corsa

Scegli un target e fornisci contenuti.

3. Leggi gli eventi

Analizza ogni frame di dati SSE come JSON.

curl --no-buffer --request POST \
  "https://entry.nymrio.com/api/chat" \
  --header "x-api-key: $CHATBOT_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "agent_id": "7496579023959494656",
    "query": "Summarize our support policy."
  }'

Autenticazione

API key

Every endpoint on this page requires an active API key. Use either header below. When both are present, x-api-key takes precedence.

x-api-keyConsigliata

x-api-key: sk_live_0b••••••••••••••••b0da

Status	Meaning	Response
401	Key is missing, invalid, or revoked.	{ "detail": "..." }
403	The account AI credit quota is exhausted.	{ "detail": "..." }

Richiedi modello

ChatRequest

All fields are JSON. Requiredness is conditional: a new run needs at least one target and either a non-empty query or one attachment.

Property	Type	Required	Description
query	string	Conditional	User prompt. Required when files is empty on a new run. Defaults to an empty string.
agent_id	integer \| string	Conditional	Agent target. At least one target identifier is required for a new run.
workflow_id	integer \| string	Conditional	Workflow target. At least one target identifier is required for a new run.
rag_id	integer \| string	Conditional	RAG target. Execution priority is RAG, then workflow, then agent when several targets are sent.
conversation_id	string	On resume	Existing conversation ID for resume. Generated as a UUID when omitted on a new run.
history	HistoryMessage[]	No	Stateless prior messages supplied by the client. Defaults to an empty array.
files	FileAttachment[]	Conditional	Remote Blob URLs. At least one file is required when query is empty.
is_resume	boolean	No	Resume an interrupted checkpoint. Defaults to false and requires conversation_id when true.

History message

Each item in history contains:

sender *: Required. human or ai
message *: Required text content

File attachment

Each item in files contains:

url *: Required direct or Blob URL
name: Optional file name with extension
mime_type: Optional MIME content type hint

POST/api/chatSSE

Start or resume a chat

Starts a background execution and opens its event stream. Omit conversation_id for a new UUID, or send conversation_id with is_resume set to true to continue from a failed checkpoint.

Content-Typeapplication/json request; text/event-stream response

BodyChatRequest

New runOne target plus a query or at least one file is required.

Resumeconversation_id and is_resume: true are required; stored target and query can be restored.

Request body

{
    "agent_id": "7496579023959494656",
    "query": "Compare the refund options.",
    "history": [
        {
            "sender": "user",
            "message": "I am reviewing the annual plan."
        }
    ],
    "files": []
}

Risposte

200SSE stream opened.

400Invalid target or resume state.

401API key failure.

403Quota exhausted.

422Invalid request body.

GET/api/chat/resume/{conversation_id}SSE

Resume from checkpoint

Restarts an interrupted execution from its persistent SQLite checkpoint. The target and query are restored from stored conversation metadata.

Path parameterconversation_id — required string identifier.

BodyNone.

Use whenExecution failed or was interrupted and a persistent checkpoint exists.

Resume request

curl --no-buffer \
  "https://entry.nymrio.com/api/chat/resume/4e982ba9-3a98-45de-9c17-796b77d76b39" \
  --header "x-api-key: $CHATBOT_API_KEY"

Risposte

200Resumed SSE stream.

400Completed run or no checkpoint.

401API key failure.

403Quota exhausted.

GET/api/chat/stream/{conversation_id}SSE

Reconnect to a run

Reattaches to an existing in-memory run after a network interruption. Buffered steps and a completed response, when available, are replayed before live events continue.

Path parameterconversation_id — required string identifier.

BodyNone.

Use whenThe SSE connection dropped but the background run still exists.

Reconnect request

curl --no-buffer \
  "https://entry.nymrio.com/api/chat/stream/4e982ba9-3a98-45de-9c17-796b77d76b39" \
  --header "x-api-key: $CHATBOT_API_KEY"

Risposte

200Reconnected SSE stream.

401API key failure.

403Quota exhausted.

404No run found in memory.

POST/api/chat/stop/{conversation_id}JSON

Stop an active run

Cancels the background task and closes execution. This endpoint returns regular JSON and reports whether an active run was found to stop.

Path parameterconversation_id — required string identifier.

BodyNone.

ResponseA status, message, and metadata object containing conversation_id.

Request and response

curl --request POST \
  "https://entry.nymrio.com/api/chat/stop/4e982ba9-3a98-45de-9c17-796b77d76b39" \
  --header "x-api-key: $CHATBOT_API_KEY"

{
    "status": 200,
    "message": "Chat run stopped successfully.",
    "metadata": {
        "conversation_id": "4e982ba9-3a98-45de-9c17-796b77d76b39"
    }
}

Risposte

200Stopped, or no active run found.

401API key failure.

Contratto di streaming

SSE event lifecycle

The API does not use the SSE event: field. Inspect the JSON type property inside each data: frame. Native browser EventSource cannot send the required authentication header, so browser clients should consume the stream with Fetch or an SSE library that supports custom headers.

SSE wire format

data: {"type":"session.started","message":"Session started...","metadata":{"conversation_id":"4e9...","is_resume":false}}

data: {"type":"execution.started","message":"Execution started","metadata":{"conversation_id":"4e9..."}}

data: {"type":"step.completed","message":"Agent 'Support' started...","step":{"status":"completed","name":"agent_started"},"metadata":{"conversation_id":"4e9..."}}

data: {"type":"response.completed","message":"Generated response","response":{"status":"completed","answer":{"content":"...","format":"markdown"}},"metadata":{"conversation_id":"4e9..."}}

data: {"type":"execution.completed","message":"Chat processing completed","metadata":{"conversation_id":"4e9..."}}

session.started

Initial handshake for a new or reconnected stream.

message, metadata.conversation_id, metadata.is_resume?

session.resumed

Initial handshake when continuing from a persistent checkpoint.

message, metadata.conversation_id, metadata.is_resume

execution.startedMay emit

Signals background execution. A very fast run can begin before the subscriber attaches.

message, metadata.conversation_id

step.startedMay emit

An execution step is in progress. Reconnected clients can receive replayed steps.

message, step, metadata.conversation_id

step.completedMay emit

An execution step completed. Step details vary by agent, workflow, and RAG implementation.

message, step.id, step.name, step.title, step.status, step.input?, step.output?, metadata

response.started / response.deltaMay emit

Incremental response events supported by compatible execution paths.

message, metadata.conversation_id

response.completed

Contains the final Markdown answer and optional RAG sources.

response.status, response.answer.content, response.answer.format, response.sources?, metadata

step.failedMay emit

Reports an execution error after the SSE connection has started.

message, metadata.conversation_id, metadata.message_id?

execution.completed

Terminal event for success, failure, or a user-requested stop.

message, metadata.conversation_id, metadata.message_id?

Keep reading until execution.completed. The successful answer is in response.answer.content and uses Markdown. RAG responses can also contain response.sources.

Errori

Two error channels

Prima dello streaming

HTTP JSON error

Authentication, quota, validation, missing checkpoint, and unknown run failures use HTTP status codes with a JSON detail field.

Durante lo streaming

SSE failure event

Once HTTP 200 has started, execution failures arrive as step.failed, followed by execution.completed.

Stream failure

data: {"type":"step.failed","message":"An error occurred while processing the chat query: ...","metadata":{"conversation_id":"4e9..."}}

data: {"type":"execution.completed","message":"An error occurred while processing the chat query: ...","metadata":{"conversation_id":"4e9..."}}