Use the session API - Ygaraty User Guide

Use an existing, ready inference session from your own application. API access uses the Session ID; you do not need a separate API key or bearer token. Anyone who has that ID can use the session, so share it only with intended users.

Copy the connection details¶

Open your session page and find API access:

Select Copy ID to copy the Session ID.
Expand API usage and copy the endpoint and model ID shown there.
Check the Reply cap for the maximum output tokens per reply.

Use the endpoint shown on that page, which may have a different address from the panel. The endpoint ends in /v1/chat/completions. Wait until the session is serving before sending a request.

Send your first request¶

Save this as request.json. Replace the example UUID with your Session ID and YOUR_MODEL_ID with the model ID from API usage:

{
  "session_id": "00000000-0000-0000-0000-000000000000",
  "model": "YOUR_MODEL_ID",
  "messages": [
    {"role": "user", "content": "Explain how a rainbow forms in two sentences."}
  ]
}

Then send it with curl, replacing the example endpoint with yours:

curl --fail-with-body 'https://YOUR_COORDINATOR/v1/chat/completions' \
  -H 'Content-Type: application/json' \
  --data-binary @request.json

The reply text is in choices[0].message.content. The response also includes usage.prompt_tokens, usage.completion_tokens and usage.total_tokens. A finish_reason of stop means normal completion; length means the reply reached its output cap.

Continue a conversation¶

Send the full message history with every API request, including prior assistant replies. The final message must have role user:

{
  "session_id": "00000000-0000-0000-0000-000000000000",
  "model": "YOUR_MODEL_ID",
  "conversation_id": "rainbow-chat",
  "messages": [
    {"role": "user", "content": "What makes a rainbow?"},
    {"role": "assistant", "content": "Sunlight is refracted and reflected in water droplets, separating its colours."},
    {"role": "user", "content": "Why does it look curved?"}
  ]
}

The assistant text above is illustrative; use the actual reply in your application. conversation_id defaults to api. If supplied, it must be 1–64 characters using letters, digits, underscores or hyphens. Give separate conversations distinct IDs, but still send their full histories. It does not retrieve chat-page history or replace the messages field. Start a new conversation with a new ID and a fresh message list.

Send API requests one at a time per session. Different conversation IDs do not allow concurrent API requests on the same session.

Stream a reply¶

Add "stream": true to the JSON request, then use curl’s unbuffered output:

curl --no-buffer --fail-with-body 'https://YOUR_COORDINATOR/v1/chat/completions' \
  -H 'Content-Type: application/json' \
  --data-binary @request.json

The response uses server-sent events. Text arrives in choices[0].delta.content; the stream ends with data: [DONE]. A stream can also contain an error object, so [DONE] alone does not establish success. Check errors and the final finish_reason in your client.

Supported request fields¶

Field	Accepted value
`session_id`	Required session UUID copied from the panel
`model`	Required model ID; must match that session
`messages`	Required list of 1–128 text messages with `system`, `user` or `assistant` roles; the last must be `user`
`conversation_id`	Optional conversation name; defaults to `api`
`stream`	`false` by default; `true` for server-sent events
`max_tokens` or `max_completion_tokens`	Optional positive output cap, no higher than the session’s Reply cap. Use one field, not both. Omit to use the session default.
`temperature`	Only `0`, which is also the default
`n`	Only `1`, which is also the default

This is a text-only Chat Completions interface. Images, attachments, tool calls and other request fields are not supported. Requests are limited to 1 MiB; each message must contain 1–100,000 characters. The input tokens plus requested output budget must fit the model’s context capacity.

For response errors and unavailable sessions, see Help.