Session REST reference

Use existing Studio sessions as durable collaboration records. Start with the session workflow; other endpoints are in the 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.

Base URL and authentication

https://api.biosimulant.com/v1

Send a scoped API key on every request:

Authorization: Bearer bsk_live_...

Every response includes a request ID. Run-creation requests also require Idempotency-Key. See Errors, limits and credits before implementing production retries.

Endpoint index

Method	Path	Purpose
`POST`	`/sessions`	Create a durable chat session
`GET`	`/sessions`	List collaboration sessions
`GET`	`/sessions/{session_id}`	Resume an external collaboration
`POST`	`/sessions/{session_id}/external-sessions`	Attach an external conversation
`POST`	`/sessions/{session_id}/contract-plans`	Propose session requirements
`POST`	`/sessions/{session_id}/execution-plans`	Propose an external execution plan
`POST`	`/session-changes`	Apply approved session state
`POST`	`/sessions/{session_id}/progress`	Record external plan progress
`POST`	`/sessions/{session_id}/validation`	Evaluate session evidence
`POST`	`/sessions/{session_id}/completion`	Check session completion
`POST`	`/sessions/{session_id}/workspace`	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

Request body

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

Example request

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

{
  "…": "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

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

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

200 response

{
  "…": "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

Parameters

Name	In	Required	Type	Description
`session_id`	path	yes	string

Example request

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

200 response

{
  "…": "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

Parameters

Name	In	Required	Type	Description
`session_id`	path	yes	string

Request body

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

Example request

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

{
  "…": "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

Parameters

Name	In	Required	Type	Description
`session_id`	path	yes	string

Request body

{
  "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

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

{
  "…": "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

Parameters

Name	In	Required	Type	Description
`session_id`	path	yes	string

Request body

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

Example request

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

{
  "…": "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

Request body

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

Example request

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

{
  "…": "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

Parameters

Name	In	Required	Type	Description
`session_id`	path	yes	string

Request body

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

Example request

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

{
  "…": "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

Parameters

Name	In	Required	Type	Description
`session_id`	path	yes	string

Request body

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

Example request

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

{
  "…": "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

Parameters

Name	In	Required	Type	Description
`session_id`	path	yes	string

Request body

{
  "expected_sequence": 0
}

Example request

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

{
  "…": "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

Parameters

Name	In	Required	Type	Description
`session_id`	path	yes	string

Example request

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

200 response

{
  "…": "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 is generated from the backend routes, enriched with production examples and error responses, and verified with this site.

REST reference Execution REST reference

Session REST reference

Base URL and authentication

Endpoint index

POST /sessions

Request body

Example request

200 response

Responses

GET /sessions

Parameters

Example request

200 response

Responses

GET /sessions/{session_id}

Parameters

Example request

200 response

Responses

POST /sessions/{session_id}/external-sessions

Parameters

Request body

Example request

200 response

Responses

POST /sessions/{session_id}/contract-plans

Parameters

Request body

Example request

200 response

Responses

POST /sessions/{session_id}/execution-plans

Parameters

Request body

Example request

200 response

Responses

POST /session-changes

Request body

Example request

200 response

Responses

POST /sessions/{session_id}/progress

Parameters

Request body

Example request

200 response

Responses

POST /sessions/{session_id}/validation

Parameters

Request body

Example request

200 response

Responses

POST /sessions/{session_id}/completion

Parameters

Request body

Example request

200 response

Responses

POST /sessions/{session_id}/workspace

Parameters

Example request

200 response

Responses

Machine-readable specification

POST `/sessions`

GET `/sessions`

GET `/sessions/{session_id}`

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

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

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

POST `/session-changes`

POST `/sessions/{session_id}/progress`

POST `/sessions/{session_id}/validation`

POST `/sessions/{session_id}/completion`

POST `/sessions/{session_id}/workspace`