> ## Documentation Index
> Fetch the complete documentation index at: https://docs.profy.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Sessions

> /v1/sessions — create long-lived sessions, append events, replay history, interrupt runs

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.

<Note>
  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.
</Note>

## Create a session

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

<ParamField body="agent" type="string" required>
  Agent (Expert) identifier.
</ParamField>

<ParamField body="title" type="string">
  Session title. Defaults to "New Chat".
</ParamField>

<ParamField body="environment_id" type="string">
  [Environment](/en/developers/api/environments) id. Resolved at every run, so editing the environment takes effect on the next event.
</ParamField>

```bash curl theme={null}
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"}'
```

```json theme={null}
{
  "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
```

<ParamField body="type" type="string" default="user.message">
  Only `user.message` is supported today; anything else returns 400.
</ParamField>

<ParamField body="content" type="string" required>
  Message content.
</ParamField>

<ParamField body="model" type="string">
  Model override. Defaults to the platform model.
</ParamField>

<ParamField body="attachment_file_ids" type="string[]">
  Up to 20 file ids returned by [Files](/en/developers/api/files).
</ParamField>

The response is an SSE stream with exactly the same event vocabulary as [Invoke an Expert](/en/developers/api/agents-run) — both endpoints run through one shared execution path.

```bash curl theme={null}
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:

```json theme={null}
{
  "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` |

## Next steps

<CardGroup cols={2}>
  <Card title="Environments" icon="box" href="/en/developers/api/environments">
    Define sandbox runtime and dependencies
  </Card>

  <Card title="Manage Agents" icon="robot" href="/en/developers/api/agents">
    Create and publish Experts via API
  </Card>
</CardGroup>