Sessions

A session is a conversation you can keep appending events to. Compared with passing session_id to POST /v1/agents/run yourself, the sessions API lets you create, inspect, replay, and interrupt it explicitly.

Creating a session provisions no sandbox and costs nothing. The sandbox is provisioned on the first event, and billing follows events — not the existence of a session.

Create a session

POST https://api.profy.cn/v1/sessions

string

required

Agent (Expert) identifier.

string

Session title. Defaults to “New Chat”.

string

Environment id. Resolved at every run, so editing the environment takes effect on the next event.

curl

curl -X POST https://api.profy.cn/v1/sessions \
  -H "Authorization: Bearer sk-pro-your-key" \
  -H "Content-Type: application/json" \
  -d '{"agent": "my-expert", "environment_id": "env_abc"}'

{
  "code": 0,
  "message": "ok",
  "data": { "id": "ses_abc123", "agent": "my-expert", "environment_id": "env_abc", "status": "idle" }
}

Send an event (SSE)

POST https://api.profy.cn/v1/sessions/{session_id}/events

string

default:"user.message"

Only user.message is supported today; anything else returns 400.

string

required

Message content.

string

Model override. Defaults to the platform model.

string[]

Up to 20 file ids returned by Files.

The response is an SSE stream with exactly the same event vocabulary as Invoke an Expert — both endpoints run through one shared execution path.

curl

curl -N -X POST https://api.profy.cn/v1/sessions/ses_abc123/events \
  -H "Authorization: Bearer sk-pro-your-key" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"content": "Review this customs declaration"}'

Replay history

GET https://api.profy.cn/v1/sessions/{session_id}/events?after={event_id}&limit=100

Returns the persisted user and assistant messages:

{
  "code": 0,
  "data": {
    "events": [
      { "id": "msg_1", "type": "user.message", "role": "user", "content": "Hi", "metadata": {}, "created_at": "..." },
      { "id": "msg_2", "type": "assistant.message", "role": "assistant", "content": "Hello…", "metadata": {}, "created_at": "..." }
    ]
  }
}

An unknown after cursor replays from the beginning rather than returning an empty page — empty would be indistinguishable from “caught up”. limit maxes out at 200.

Interrupt a run

POST https://api.profy.cn/v1/sessions/{session_id}/interrupt

Asks the runtime to stop generating. This is idempotent: interrupting a session with nothing running still succeeds, because the intent (“stop”) is already satisfied.

Other operations

Method	Path	Notes
`GET`	`/v1/sessions?agent=&limit=`	List your sessions, max 100
`GET`	`/v1/sessions/{id}`	Detail, including bound agent and environment
`DELETE`	`/v1/sessions/{id}`	Delete the session and its messages

Errors

Status	Meaning
`400`	Missing `agent` / `content`, or unsupported `type`
`401`	Authentication failed
`404`	Session not found or not yours, or invalid `environment_id`

Get Started

Authentication & Keys

API Guides

SDK

Integrations

Cookbook

Reference

Create a session

Send an event (SSE)

Replay history

Interrupt a run

Other operations

Errors

Next steps

Environments

Manage Agents

​Create a session

​Send an event (SSE)

​Replay history

​Interrupt a run

​Other operations

​Errors

​Next steps

Environments

Manage Agents

Create a session

Send an event (SSE)

Replay history

Interrupt a run

Other operations

Errors

Next steps