<!-- Source: https://docs.biosimulant.com/developer-api/session-reference -->

# Session REST reference

Use existing Studio sessions as durable collaboration records. Start with the [session workflow](/agents/sessions); other endpoints are in the [REST reference](/developer-api/rest-reference).

The Developer API is the same service as the Biosimulant MCP server: each route runs the operation of the MCP tool it names, for the API key owner only, and returns the same envelope. For the guided path, start with the [Developer API quickstart](/developer-api/quickstart).

## Base URL and authentication

```text
https://api.biosimulant.com/v1
```

Send a scoped API key on every request:

```http
Authorization: Bearer bsk_live_...
```

Every response includes a request ID. Run-creation requests also require `Idempotency-Key`. See [Errors, limits and credits](/developer-api/errors) before implementing production retries.

## Endpoint index

| Method | Path | Purpose |
|---|---|---|
| `POST` | [`/sessions`](#post-sessions) | Create a durable chat session |
| `GET` | [`/sessions`](#get-sessions) | List collaboration sessions |
| `GET` | [`/sessions/{session_id}`](#get-sessionssession_id) | Resume an external collaboration |
| `POST` | [`/sessions/{session_id}/external-sessions`](#post-sessionssession_idexternal-sessions) | Attach an external conversation |
| `POST` | [`/sessions/{session_id}/contract-plans`](#post-sessionssession_idcontract-plans) | Propose session requirements |
| `POST` | [`/sessions/{session_id}/execution-plans`](#post-sessionssession_idexecution-plans) | Propose an external execution plan |
| `POST` | [`/session-changes`](#post-session-changes) | Apply approved session state |
| `POST` | [`/sessions/{session_id}/progress`](#post-sessionssession_idprogress) | Record external plan progress |
| `POST` | [`/sessions/{session_id}/validation`](#post-sessionssession_idvalidation) | Evaluate session evidence |
| `POST` | [`/sessions/{session_id}/completion`](#post-sessionssession_idcompletion) | Check session completion |
| `POST` | [`/sessions/{session_id}/workspace`](#post-sessionssession_idworkspace) | Create the session Lab workspace |

## POST `/sessions`

Create a research or execution session without invoking the internal agent or allocating compute.

Same operation as the MCP tool `session_create`.

**Required scope:** `workspaces:write`

**MCP tool:** [`session_create`](/agents/tools)

### Request body

```json
{
  "title": "<title>",
  "idempotency_key": "request-0001"
}
```

### Example request

```bash
curl --request POST "https://api.biosimulant.com/v1/sessions" \
  --header "Authorization: Bearer $BIOSIMULANT_API_KEY" \
  --header "Content-Type: application/json" \
  --data @request.json
```

### 200 response

```json
{
  "…": "the fields of the MCP tool result",
  "schema_version": "2026-09-16",
  "request_id": "00000000-0000-0000-0000-00000000abcd",
  "warnings": [],
  "next_actions": [
    {
      "tool": "run_get",
      "description": "The suggested next step.",
      "arguments": {
        "run_id": "…"
      },
      "http": {
        "method": "GET",
        "path": "/v1/runs/…"
      }
    }
  ],
  "links": {}
}
```

### Responses

| Status | Meaning |
|---:|---|
| `200` | Successful Response |
| `401` | Missing, invalid, expired, or revoked API key. |
| `403` | The API key lacks the required scope, or the operation starts compute, publishes, changes content or calls external sources and the Agent Gateway is not enabled for the account. |
| `422` | Validation Error |
| `429` | The API-key or run-creation rate limit was exceeded. Respect Retry-After. |
| `500` | The service could not complete the request. Retain the response request ID. |

## GET `/sessions`

List accessible existing chat sessions; use the session linked to a workspace rather than creating another task.

Same operation as the MCP tool `session_list`.

**Required scope:** `workspaces:read`

**MCP tool:** [`session_list`](/agents/tools)

### Parameters

| Name | In | Required | Type | Description |
|---|---|---:|---|---|
| `limit` | query | no | integer | Maximum number of items to return. |
| `cursor` | query | no | string or null | Opaque next_cursor from the preceding page. |

### Example request

```bash
curl --request GET "https://api.biosimulant.com/v1/sessions" \
  --header "Authorization: Bearer $BIOSIMULANT_API_KEY"
```

### 200 response

```json
{
  "…": "the fields of the MCP tool result",
  "schema_version": "2026-09-16",
  "request_id": "00000000-0000-0000-0000-00000000abcd",
  "warnings": [],
  "next_actions": [
    {
      "tool": "run_get",
      "description": "The suggested next step.",
      "arguments": {
        "run_id": "…"
      },
      "http": {
        "method": "GET",
        "path": "/v1/runs/…"
      }
    }
  ],
  "links": {}
}
```

### Responses

| Status | Meaning |
|---:|---|
| `200` | Successful Response |
| `401` | Missing, invalid, expired, or revoked API key. |
| `403` | The API key lacks the required scope, or the operation starts compute, publishes, changes content or calls external sources and the Agent Gateway is not enabled for the account. |
| `422` | Validation Error |
| `429` | The API-key or run-creation rate limit was exceeded. Respect Retry-After. |
| `500` | The service could not complete the request. Retain the response request ID. |

## GET `/sessions/{session_id}`

Retrieve the approved goal, criteria, pinned guidance, plan, receipts, approvals, blockers and remaining run budget. Refresh before writes; sequence rejects stale updates.

Same operation as the MCP tool `session_resume`.

**Required scope:** `workspaces:read`

**MCP tool:** [`session_resume`](/agents/tools)

### Parameters

| Name | In | Required | Type | Description |
|---|---|---:|---|---|
| `session_id` | path | yes | string |  |

### Example request

```bash
curl --request GET "https://api.biosimulant.com/v1/sessions/${SESSION_ID}" \
  --header "Authorization: Bearer $BIOSIMULANT_API_KEY"
```

### 200 response

```json
{
  "…": "the fields of the MCP tool result",
  "schema_version": "2026-09-16",
  "request_id": "00000000-0000-0000-0000-00000000abcd",
  "warnings": [],
  "next_actions": [
    {
      "tool": "run_get",
      "description": "The suggested next step.",
      "arguments": {
        "run_id": "…"
      },
      "http": {
        "method": "GET",
        "path": "/v1/runs/…"
      }
    }
  ],
  "links": {}
}
```

### Responses

| Status | Meaning |
|---:|---|
| `200` | Successful Response |
| `401` | Missing, invalid, expired, or revoked API key. |
| `403` | The API key lacks the required scope, or the operation starts compute, publishes, changes content or calls external sources and the Agent Gateway is not enabled for the account. |
| `404` | Not found. Anything the key owner does not own is answered exactly like an ID that does not exist. |
| `422` | Validation Error |
| `429` | The API-key or run-creation rate limit was exceeded. Respect Retry-After. |
| `500` | The service could not complete the request. Retain the response request ID. |

## POST `/sessions/{session_id}/external-sessions`

Associate this client conversation with an accessible Biosimulant chat. Visibility never transfers another client execution grants.

Same operation as the MCP tool `session_attach`.

**Required scope:** `workspaces:write`

**MCP tool:** [`session_attach`](/agents/tools)

### Parameters

| Name | In | Required | Type | Description |
|---|---|---:|---|---|
| `session_id` | path | yes | string |  |

### Request body

```json
{
  "external_session_id": "<external_session_id>",
  "label": "<label>"
}
```

### Example request

```bash
curl --request POST "https://api.biosimulant.com/v1/sessions/${SESSION_ID}/external-sessions" \
  --header "Authorization: Bearer $BIOSIMULANT_API_KEY" \
  --header "Content-Type: application/json" \
  --data @request.json
```

### 200 response

```json
{
  "…": "the fields of the MCP tool result",
  "schema_version": "2026-09-16",
  "request_id": "00000000-0000-0000-0000-00000000abcd",
  "warnings": [],
  "next_actions": [
    {
      "tool": "run_get",
      "description": "The suggested next step.",
      "arguments": {
        "run_id": "…"
      },
      "http": {
        "method": "GET",
        "path": "/v1/runs/…"
      }
    }
  ],
  "links": {}
}
```

### Responses

| Status | Meaning |
|---:|---|
| `200` | Successful Response |
| `401` | Missing, invalid, expired, or revoked API key. |
| `403` | The API key lacks the required scope, or the operation starts compute, publishes, changes content or calls external sources and the Agent Gateway is not enabled for the account. |
| `404` | Not found. Anything the key owner does not own is answered exactly like an ID that does not exist. |
| `422` | Validation Error |
| `429` | The API-key or run-creation rate limit was exceeded. Respect Retry-After. |
| `500` | The service could not complete the request. Retain the response request ID. |

## POST `/sessions/{session_id}/contract-plans`

Prepare measurable requirements separately from the plan. A human approves the exact proposal in Biosimulant; then session_change_apply records an immutable contract. Scientific judgment requires human_review.

Same operation as the MCP tool `session_contract_prepare`.

**Required scope:** `workspaces:write`

**MCP tool:** [`session_contract_prepare`](/agents/tools)

### Parameters

| Name | In | Required | Type | Description |
|---|---|---:|---|---|
| `session_id` | path | yes | string |  |

### Request body

```json
{
  "expected_sequence": 0,
  "contract": {
    "goal": "<goal>",
    "intended_use": "<intended_use>",
    "scope": "<scope>",
    "criteria": [
      {
        "id": "<id>",
        "description": "<description>",
        "validator": "passport_check"
      }
    ]
  },
  "idempotency_key": "request-0001"
}
```

### Example request

```bash
curl --request POST "https://api.biosimulant.com/v1/sessions/${SESSION_ID}/contract-plans" \
  --header "Authorization: Bearer $BIOSIMULANT_API_KEY" \
  --header "Content-Type: application/json" \
  --data @request.json
```

### 200 response

```json
{
  "…": "the fields of the MCP tool result",
  "schema_version": "2026-09-16",
  "request_id": "00000000-0000-0000-0000-00000000abcd",
  "warnings": [],
  "next_actions": [
    {
      "tool": "run_get",
      "description": "The suggested next step.",
      "arguments": {
        "run_id": "…"
      },
      "http": {
        "method": "GET",
        "path": "/v1/runs/…"
      }
    }
  ],
  "links": {}
}
```

### Responses

| Status | Meaning |
|---:|---|
| `200` | Successful Response |
| `401` | Missing, invalid, expired, or revoked API key. |
| `403` | The API key lacks the required scope, or the operation starts compute, publishes, changes content or calls external sources and the Agent Gateway is not enabled for the account. |
| `404` | Not found. Anything the key owner does not own is answered exactly like an ID that does not exist. |
| `422` | Validation Error |
| `429` | The API-key or run-creation rate limit was exceeded. Respect Retry-After. |
| `500` | The service could not complete the request. Retain the response request ID. |

## POST `/sessions/{session_id}/execution-plans`

Prepare ordered steps with dependencies and criterion links for the approved contract. Approval does not grant compute or publication authority.

Same operation as the MCP tool `session_plan_prepare`.

**Required scope:** `workspaces:write`

**MCP tool:** [`session_plan_prepare`](/agents/tools)

### Parameters

| Name | In | Required | Type | Description |
|---|---|---:|---|---|
| `session_id` | path | yes | string |  |

### Request body

```json
{
  "expected_sequence": 0,
  "plan": {
    "title": "<title>",
    "objective": "<objective>",
    "steps": [
      {
        "title": "<title>"
      }
    ]
  },
  "idempotency_key": "request-0001"
}
```

### Example request

```bash
curl --request POST "https://api.biosimulant.com/v1/sessions/${SESSION_ID}/execution-plans" \
  --header "Authorization: Bearer $BIOSIMULANT_API_KEY" \
  --header "Content-Type: application/json" \
  --data @request.json
```

### 200 response

```json
{
  "…": "the fields of the MCP tool result",
  "schema_version": "2026-09-16",
  "request_id": "00000000-0000-0000-0000-00000000abcd",
  "warnings": [],
  "next_actions": [
    {
      "tool": "run_get",
      "description": "The suggested next step.",
      "arguments": {
        "run_id": "…"
      },
      "http": {
        "method": "GET",
        "path": "/v1/runs/…"
      }
    }
  ],
  "links": {}
}
```

### Responses

| Status | Meaning |
|---:|---|
| `200` | Successful Response |
| `401` | Missing, invalid, expired, or revoked API key. |
| `403` | The API key lacks the required scope, or the operation starts compute, publishes, changes content or calls external sources and the Agent Gateway is not enabled for the account. |
| `404` | Not found. Anything the key owner does not own is answered exactly like an ID that does not exist. |
| `422` | Validation Error |
| `429` | The API-key or run-creation rate limit was exceeded. Respect Retry-After. |
| `500` | The service could not complete the request. Retain the response request ID. |

## POST `/session-changes`

Apply a digest-bound, human-approved, unexpired contract or plan proposal prepared by this client. Changes to current requirements, plan progress or workspace invalidate stale proposals.

Same operation as the MCP tool `session_change_apply`.

**Required scope:** `workspaces:write`

**MCP tool:** [`session_change_apply`](/agents/tools)

### Request body

```json
{
  "plan_id": "00000000-0000-0000-0000-000000000123",
  "plan_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
```

### Example request

```bash
curl --request POST "https://api.biosimulant.com/v1/session-changes" \
  --header "Authorization: Bearer $BIOSIMULANT_API_KEY" \
  --header "Content-Type: application/json" \
  --data @request.json
```

### 200 response

```json
{
  "…": "the fields of the MCP tool result",
  "schema_version": "2026-09-16",
  "request_id": "00000000-0000-0000-0000-00000000abcd",
  "warnings": [],
  "next_actions": [
    {
      "tool": "run_get",
      "description": "The suggested next step.",
      "arguments": {
        "run_id": "…"
      },
      "http": {
        "method": "GET",
        "path": "/v1/runs/…"
      }
    }
  ],
  "links": {}
}
```

### Responses

| Status | Meaning |
|---:|---|
| `200` | Successful Response |
| `401` | Missing, invalid, expired, or revoked API key. |
| `403` | The API key lacks the required scope, or the operation starts compute, publishes, changes content or calls external sources and the Agent Gateway is not enabled for the account. |
| `422` | Validation Error |
| `429` | The API-key or run-creation rate limit was exceeded. Respect Retry-After. |
| `500` | The service could not complete the request. Retain the response request ID. |

## POST `/sessions/{session_id}/progress`

Record the owning client progress against the current approved plan. Done is progress only; acceptance requires server validation or an authenticated human review.

Same operation as the MCP tool `session_progress_update`.

**Required scope:** `workspaces:write`

**MCP tool:** [`session_progress_update`](/agents/tools)

### Parameters

| Name | In | Required | Type | Description |
|---|---|---:|---|---|
| `session_id` | path | yes | string |  |

### Request body

```json
{
  "expected_sequence": 0,
  "plan_id": "00000000-0000-0000-0000-000000000123",
  "step_id": "00000000-0000-0000-0000-000000000123",
  "status": "active"
}
```

### Example request

```bash
curl --request POST "https://api.biosimulant.com/v1/sessions/${SESSION_ID}/progress" \
  --header "Authorization: Bearer $BIOSIMULANT_API_KEY" \
  --header "Content-Type: application/json" \
  --data @request.json
```

### 200 response

```json
{
  "…": "the fields of the MCP tool result",
  "schema_version": "2026-09-16",
  "request_id": "00000000-0000-0000-0000-00000000abcd",
  "warnings": [],
  "next_actions": [
    {
      "tool": "run_get",
      "description": "The suggested next step.",
      "arguments": {
        "run_id": "…"
      },
      "http": {
        "method": "GET",
        "path": "/v1/runs/…"
      }
    }
  ],
  "links": {}
}
```

### Responses

| Status | Meaning |
|---:|---|
| `200` | Successful Response |
| `401` | Missing, invalid, expired, or revoked API key. |
| `403` | The API key lacks the required scope, or the operation starts compute, publishes, changes content or calls external sources and the Agent Gateway is not enabled for the account. |
| `404` | Not found. Anything the key owner does not own is answered exactly like an ID that does not exist. |
| `422` | Validation Error |
| `429` | The API-key or run-creation rate limit was exceeded. Respect Retry-After. |
| `500` | The service could not complete the request. Retain the response request ID. |

## POST `/sessions/{session_id}/validation`

Evaluate a criterion using a server-owned Passport for its exact approved revision and validator version. Imported reports await human review and cannot auto-pass.

Same operation as the MCP tool `session_validation_submit`.

**Required scope:** `workspaces:write`

**MCP tool:** [`session_validation_submit`](/agents/tools)

### Parameters

| Name | In | Required | Type | Description |
|---|---|---:|---|---|
| `session_id` | path | yes | string |  |

### Request body

```json
{
  "expected_sequence": 0,
  "criterion_id": "<criterion_id>"
}
```

### Example request

```bash
curl --request POST "https://api.biosimulant.com/v1/sessions/${SESSION_ID}/validation" \
  --header "Authorization: Bearer $BIOSIMULANT_API_KEY" \
  --header "Content-Type: application/json" \
  --data @request.json
```

### 200 response

```json
{
  "…": "the fields of the MCP tool result",
  "schema_version": "2026-09-16",
  "request_id": "00000000-0000-0000-0000-00000000abcd",
  "warnings": [],
  "next_actions": [
    {
      "tool": "run_get",
      "description": "The suggested next step.",
      "arguments": {
        "run_id": "…"
      },
      "http": {
        "method": "GET",
        "path": "/v1/runs/…"
      }
    }
  ],
  "links": {}
}
```

### Responses

| Status | Meaning |
|---:|---|
| `200` | Successful Response |
| `401` | Missing, invalid, expired, or revoked API key. |
| `403` | The API key lacks the required scope, or the operation starts compute, publishes, changes content or calls external sources and the Agent Gateway is not enabled for the account. |
| `404` | Not found. Anything the key owner does not own is answered exactly like an ID that does not exist. |
| `422` | Validation Error |
| `429` | The API-key or run-creation rate limit was exceeded. Respect Retry-After. |
| `500` | The service could not complete the request. Retain the response request ID. |

## POST `/sessions/{session_id}/completion`

Establish completion only when every required criterion passes, every step is done and the approved exact revision remains current. Returns blockers otherwise; starts no compute.

Same operation as the MCP tool `session_completion_check`.

**Required scope:** `workspaces:write`

**MCP tool:** [`session_completion_check`](/agents/tools)

### Parameters

| Name | In | Required | Type | Description |
|---|---|---:|---|---|
| `session_id` | path | yes | string |  |

### Request body

```json
{
  "expected_sequence": 0
}
```

### Example request

```bash
curl --request POST "https://api.biosimulant.com/v1/sessions/${SESSION_ID}/completion" \
  --header "Authorization: Bearer $BIOSIMULANT_API_KEY" \
  --header "Content-Type: application/json" \
  --data @request.json
```

### 200 response

```json
{
  "…": "the fields of the MCP tool result",
  "schema_version": "2026-09-16",
  "request_id": "00000000-0000-0000-0000-00000000abcd",
  "warnings": [],
  "next_actions": [
    {
      "tool": "run_get",
      "description": "The suggested next step.",
      "arguments": {
        "run_id": "…"
      },
      "http": {
        "method": "GET",
        "path": "/v1/runs/…"
      }
    }
  ],
  "links": {}
}
```

### Responses

| Status | Meaning |
|---:|---|
| `200` | Successful Response |
| `401` | Missing, invalid, expired, or revoked API key. |
| `403` | The API key lacks the required scope, or the operation starts compute, publishes, changes content or calls external sources and the Agent Gateway is not enabled for the account. |
| `404` | Not found. Anything the key owner does not own is answered exactly like an ID that does not exist. |
| `422` | Validation Error |
| `429` | The API-key or run-creation rate limit was exceeded. Respect Retry-After. |
| `500` | The service could not complete the request. Retain the response request ID. |

## POST `/sessions/{session_id}/workspace`

Create or reuse the session's one private Lab workspace, with no compute or internal agent. Research-only sessions can defer this until files are needed.

Same operation as the MCP tool `session_workspace_create`.

**Required scope:** `workspaces:write`

**MCP tool:** [`session_workspace_create`](/agents/tools)

### Parameters

| Name | In | Required | Type | Description |
|---|---|---:|---|---|
| `session_id` | path | yes | string |  |

### Example request

```bash
curl --request POST "https://api.biosimulant.com/v1/sessions/${SESSION_ID}/workspace" \
  --header "Authorization: Bearer $BIOSIMULANT_API_KEY"
```

### 200 response

```json
{
  "…": "the fields of the MCP tool result",
  "schema_version": "2026-09-16",
  "request_id": "00000000-0000-0000-0000-00000000abcd",
  "warnings": [],
  "next_actions": [
    {
      "tool": "run_get",
      "description": "The suggested next step.",
      "arguments": {
        "run_id": "…"
      },
      "http": {
        "method": "GET",
        "path": "/v1/runs/…"
      }
    }
  ],
  "links": {}
}
```

### Responses

| Status | Meaning |
|---:|---|
| `200` | Successful Response |
| `401` | Missing, invalid, expired, or revoked API key. |
| `403` | The API key lacks the required scope, or the operation starts compute, publishes, changes content or calls external sources and the Agent Gateway is not enabled for the account. |
| `404` | Not found. Anything the key owner does not own is answered exactly like an ID that does not exist. |
| `422` | Validation Error |
| `429` | The API-key or run-creation rate limit was exceeded. Respect Retry-After. |
| `500` | The service could not complete the request. Retain the response request ID. |

## Machine-readable specification

The [OpenAPI 3.1 document](/openapi/developer-v1.json) is generated from the backend routes, enriched with production examples and error responses, and verified with this site.