Developer APIREST reference

REST reference

Use the Session REST reference for portable collaboration and the Execution REST reference for managed runs. The index below covers every endpoint.

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 compute before implementing production retries.

Endpoint index

MethodPathPurpose
GET/capabilitiesList Capabilities
GET/capabilities/{namespace}/{name}Get Capability
POST/runsStart an approved simulation
GET/runsList my simulations
POST/runs/{run_id}/cancelCancel a simulation
GET/runs/{run_id}/resultsGet Public Results
GET/runs/{run_id}/artifacts/{artifact_id}Download Public Artifact
GET/hub/searchFind published models and labs
GET/hub/releases/{reference}Inspect a published model or lab
POST/biology/searchFind biological evidence
POST/biology/fetchRetrieve biological evidence
GET/labsList my labs
PATCH/labs/{lab_id}Rename or describe a lab
PUT/labs/{lab_id}/visibilityChange who can see a lab
GET/workspacesList my private labs in progress
POST/workspacesCreate a private lab
GET/workspaces/{workspace_id}Check a private lab
POST/workspaces/{workspace_id}/change-plansPreview lab changes
POST/workspace-revisionsApply approved lab changes
POST/run-plansCheck a simulation before running
GET/runs/{run_id}Check simulation progress and results
GET/runs/{run_id}/eventsRead a simulation’s log
GET/runs/{run_id}/artifacts/{artifact_id}/metadataRead simulation results
GET/compute-profilesList compute options
GET/experimentsList my experiments
POST/experimentsStart an approved experiment
POST/experiment-plansPreview an experiment
GET/experiments/{experiment_id}Check an experiment
PATCH/experiments/{experiment_id}Update an experiment
GET/passportsRead the evidence review
POST/publication-plansPreview publication
POST/publicationsPublish an approved release
GET/labs/{lab_id}/hostingInspect Lab hosting
PATCH/labs/{lab_id}/hostingChange Lab hosting state
POST/labs/{lab_id}/hosting-plansPrepare Lab hosting
POST/hosting-requestsRequest approved Lab hosting
POST/files/from-runReuse a Run output as an input
GET/filesList my uploaded files
POST/filesFile Upload Route
GET/files/{file_id}Read an uploaded file
GET/accountCheck my account
GET/skillsList Biosimulant skills
GET/skills/{name}Read a Biosimulant skill
GET/files/{file_id}/contentFile Download Route
GET/datasetsList dataset versions
POST/datasetsRegister a dataset version
GET/datasets/{dataset_id}Read a dataset version
GET/hosted-releases/{reference}Inspect an exact hosted release
POST/hosted-invocation-plansPrepare a hosted invocation
POST/hosted-invocationsExecute an approved hosted invocation
GET/hosted-invocations/{invocation_id}Read a hosted invocation
POST/hosted-invocations/{invocation_id}/cancelCancel my hosted invocation
GET/hosted-invocations/{invocation_id}/artifacts/{port}/metadataRead a hosted output artifact
POST/sessionsCreate a durable chat session
GET/sessionsList collaboration sessions
GET/sessions/{session_id}Resume an external collaboration
POST/sessions/{session_id}/external-sessionsAttach an external conversation
POST/sessions/{session_id}/contract-plansPropose session requirements
POST/sessions/{session_id}/execution-plansPropose an external execution plan
POST/session-changesApply approved session state
POST/sessions/{session_id}/progressRecord external plan progress
POST/sessions/{session_id}/validationEvaluate session evidence
POST/sessions/{session_id}/completionCheck session completion
POST/sessions/{session_id}/workspaceCreate the session Lab workspace

GET /capabilities

Lists runnable lab versions visible to the API-key owner, including their declared input and output schemas.

Required scope: capabilities:read

Parameters

NameInRequiredTypeDescription
limitquerynointegerMaximum number of items to return.

Example request

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

200 response

{
  "items": [
    {
      "ref": "demi/microbiology-hello-world-growth@1.0.0",
      "name": "microbiology-hello-world-growth",
      "version": "1.0.0",
      "title": "Microbiology Hello World Growth",
      "inputs": [
        {
          "name": "initial_cells",
          "value_type": "integer",
          "required": true
        }
      ],
      "outputs": [
        {
          "name": "final_cells",
          "value_type": "integer"
        }
      ],
      "package_sha256": "sha256:…"
    }
  ],
  "has_more": false
}

Responses

StatusMeaning
200Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
422Validation Error
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

GET /capabilities/{namespace}/{name}

Resolves the latest accessible version of a named runnable lab and returns its public input and output contract.

Required scope: capabilities:read

Parameters

NameInRequiredTypeDescription
namespacepathyesstringCapability-owner namespace.
namepathyesstringCapability package name.

Example request

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

200 response

{
  "ref": "demi/microbiology-hello-world-growth@1.0.0",
  "name": "microbiology-hello-world-growth",
  "version": "1.0.0",
  "title": "Microbiology Hello World Growth",
  "inputs": [
    {
      "name": "initial_cells",
      "value_type": "integer",
      "required": true
    }
  ],
  "outputs": [
    {
      "name": "final_cells",
      "value_type": "integer"
    }
  ],
  "package_sha256": "sha256:…"
}

Responses

StatusMeaning
200Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
404Not found. Anything the key owner does not own is answered exactly like an ID that does not exist.
422Validation Error
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

GET /hub/search

Search accessible Hub releases; ask the user to choose before running an ambiguous result.

Same operation as the MCP tool hub_search.

Required scope: hub:read

MCP tool: hub_search

Parameters

NameInRequiredTypeDescription
queryquerynostring or null
package_typequerynostring or null
tagsquerynoarray
intended_usequerynostring or null
compute_classquerynostring or null
qualification_statequerynostring or null
limitquerynointegerMaximum number of items to return.
cursorquerynostring or nullOpaque next_cursor from the preceding page.

Example request

curl --request GET "https://api.biosimulant.com/v1/hub/search" \
  --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

StatusMeaning
200Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
422Validation Error
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

GET /hub/releases/{reference}

Inspect one immutable Hub release without executing or trusting its contributed metadata.

Same operation as the MCP tool hub_inspect.

Required scope: hub:read

MCP tool: hub_inspect

Parameters

NameInRequiredTypeDescription
referencepathyesstring

Example request

curl --request GET "https://api.biosimulant.com/v1/hub/releases/${REFERENCE}" \
  --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

StatusMeaning
200Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
404Not found. Anything the key owner does not own is answered exactly like an ID that does not exist.
422Validation Error
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

POST /biology/search

Search approved sources; use biology_fetch before treating a hit as exact pinned evidence.

Same operation as the MCP tool biology_search.

Required scope: biology:read

MCP tool: biology_search

Request body

{
  "source_ids": [
    "pubmed"
  ],
  "query": "<query>"
}

Example request

curl --request POST "https://api.biosimulant.com/v1/biology/search" \
  --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

StatusMeaning
200Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
422Validation Error
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

POST /biology/fetch

Persist exact records or one model artifact as opaque resources; do not pin a revision.

Same operation as the MCP tool biology_fetch.

Required scope: biology:read

MCP tool: biology_fetch

Request body

{}

Example request

curl --request POST "https://api.biosimulant.com/v1/biology/fetch" \
  --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

StatusMeaning
200Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
422Validation Error
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

GET /labs

List Labs the caller owns, released or not, with their exact release references.

Same operation as the MCP tool lab_list.

Required scope: hub:read

MCP tool: lab_list

Parameters

NameInRequiredTypeDescription
queryquerynostring or null
visibilityquerynostring or null
limitquerynointegerMaximum number of items to return.
cursorquerynostring or nullOpaque next_cursor from the preceding page.

Example request

curl --request GET "https://api.biosimulant.com/v1/labs" \
  --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

StatusMeaning
200Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
422Validation Error
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

PATCH /labs/{lab_id}

Updates an editable Lab. Visibility and content settings apply to its existing and future sessions. Hub listing is managed by internal operations and cannot be changed here.

Required scope: packages:publish

MCP tool: lab_update

Parameters

NameInRequiredTypeDescription
lab_idpathyesstring

Request body

{}

Example request

curl --request PATCH "https://api.biosimulant.com/v1/labs/${LAB_ID}" \
  --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

StatusMeaning
200Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
404Not found. Anything the key owner does not own is answered exactly like an ID that does not exist.
422Validation Error
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

PUT /labs/{lab_id}/visibility

Re-scope an owned Lab without releasing a new version; deletes nothing.

Same operation as the MCP tool lab_visibility_set.

Required scope: packages:publish

MCP tool: lab_visibility_set

Parameters

NameInRequiredTypeDescription
lab_idpathyesstring

Request body

{
  "visibility": "private"
}

Example request

curl --request PUT "https://api.biosimulant.com/v1/labs/${LAB_ID}/visibility" \
  --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

StatusMeaning
200Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
404Not found. Anything the key owner does not own is answered exactly like an ID that does not exist.
422Validation Error
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

GET /workspaces

List the caller’s active private workspaces, most recently changed first.

Same operation as the MCP tool workspace_list.

Required scope: workspaces:read

MCP tool: workspace_list

Parameters

NameInRequiredTypeDescription
queryquerynostring or null
limitquerynointegerMaximum number of items to return.
cursorquerynostring or nullOpaque next_cursor from the preceding page.

Example request

curl --request GET "https://api.biosimulant.com/v1/workspaces" \
  --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

StatusMeaning
200Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
422Validation Error
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

POST /workspaces

Create a private immutable workspace or fork an exact Hub release; no compute is started.

Follow the biosimulant skill’s references/naming.md for scientific titles, stable package identities, and model/child-Lab role aliases. Preserve source names.

Same operation as the MCP tool workspace_create.

Required scope: workspaces:write

MCP tool: workspace_create

Parameters

NameInRequiredTypeDescription
Idempotency-Keyheadernostring or nullUnique key for this logical run-creation request. Reuse only when retrying the same payload.

Request body

{
  "title": "<title>"
}

Example request

curl --request POST "https://api.biosimulant.com/v1/workspaces" \
  --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

StatusMeaning
200Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
422Validation Error
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

GET /workspaces/{workspace_id}

Read one owned workspace revision, including bounded untrusted files and pinned evidence.

Same operation as the MCP tool workspace_get.

Required scope: workspaces:read

MCP tool: workspace_get

Parameters

NameInRequiredTypeDescription
workspace_idpathyesstring
revision_idquerynostring or null

Example request

curl --request GET "https://api.biosimulant.com/v1/workspaces/${WORKSPACE_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

StatusMeaning
200Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
404Not found. Anything the key owner does not own is answered exactly like an ID that does not exist.
422Validation Error
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

POST /workspaces/{workspace_id}/change-plans

Validate and digest a workspace proposal; it never changes the active revision.

Review naming findings for Labs, embedded models and child Labs. Duplicate or invalid explicit sibling aliases block. Titles and identity changes are advisory; an intentional alias rename must update wiring and public IO mappings together.

Same operation as the MCP tool workspace_change_prepare.

Required scope: workspaces:write

MCP tool: workspace_change_prepare

Parameters

NameInRequiredTypeDescription
workspace_idpathyesstring
Idempotency-Keyheadernostring or nullUnique key for this logical run-creation request. Reuse only when retrying the same payload.

Request body

{
  "base_revision_id": "00000000-0000-0000-0000-000000000123",
  "operations": [
    {
      "kind": "file_put",
      "path": "<path>"
    }
  ]
}

Example request

curl --request POST "https://api.biosimulant.com/v1/workspaces/${WORKSPACE_ID}/change-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

StatusMeaning
200Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
404Not found. Anything the key owner does not own is answered exactly like an ID that does not exist.
422Validation Error
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

POST /workspace-revisions

After explicit user confirmation, apply one exact plan as a new immutable revision.

Same operation as the MCP tool workspace_change_apply.

Required scope: workspaces:write

MCP tool: workspace_change_apply

Request body

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

Example request

curl --request POST "https://api.biosimulant.com/v1/workspace-revisions" \
  --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

StatusMeaning
200Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
422Validation Error
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

GET /compute-profiles

Discover live CPU/GPU profiles before creating/updating a Lab or preparing compute.

Pass an item id as compute_profile_id to run_prepare or an experiment arm. Configured availability does not guarantee capacity; provider selection is platform-controlled.

Same operation as the MCP tool compute_profile_list.

Required scope: runs:read

MCP tool: compute_profile_list

Example request

curl --request GET "https://api.biosimulant.com/v1/compute-profiles" \
  --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

StatusMeaning
200Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

GET /experiments

List the caller’s studies with run totals, most recently changed first.

Same operation as the MCP tool experiment_list.

Required scope: runs:read

MCP tool: experiment_list

Parameters

NameInRequiredTypeDescription
statusquerynostring or null
workspace_idquerynostring or null
limitquerynointegerMaximum number of items to return.
cursorquerynostring or nullOpaque next_cursor from the preceding page.

Example request

curl --request GET "https://api.biosimulant.com/v1/experiments" \
  --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

StatusMeaning
200Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
422Validation Error
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

POST /experiments

Open the approved study and queue exactly its arms under that one approval.

Same operation as the MCP tool experiment_create.

Required scope: runs:write

MCP tool: experiment_create

Request body

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

Example request

curl --request POST "https://api.biosimulant.com/v1/experiments" \
  --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

StatusMeaning
200Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
422Validation Error
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

POST /experiment-plans

Preflight every arm of a study and digest the whole proposal; no compute is queued.

Each arm is preflighted exactly as a lone run would be, and findings are reported per arm. One approval of the returned digest authorizes precisely these arms.

Same operation as the MCP tool experiment_prepare.

Required scope: runs:write

MCP tool: experiment_prepare

Parameters

NameInRequiredTypeDescription
Idempotency-Keyheadernostring or nullUnique key for this logical run-creation request. Reuse only when retrying the same payload.

Request body

{
  "name": "<name>",
  "arms": [
    {
      "label": "<label>",
      "workspace_id": "00000000-0000-0000-0000-000000000123",
      "revision_id": "00000000-0000-0000-0000-000000000123"
    }
  ]
}

Example request

curl --request POST "https://api.biosimulant.com/v1/experiment-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

StatusMeaning
200Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
422Validation Error
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

GET /experiments/{experiment_id}

Read a study’s arms, their runs and the comparison across them.

Comparable values come only from runs that actually completed; an arm with no completed run reports no metrics rather than a guess.

Same operation as the MCP tool experiment_get.

Required scope: runs:read

MCP tool: experiment_get

Parameters

NameInRequiredTypeDescription
experiment_idpathyesstring

Example request

curl --request GET "https://api.biosimulant.com/v1/experiments/${EXPERIMENT_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

StatusMeaning
200Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
404Not found. Anything the key owner does not own is answered exactly like an ID that does not exist.
422Validation Error
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

PATCH /experiments/{experiment_id}

Rename, re-goal or close a study, or detach runs; deletes nothing.

Same operation as the MCP tool experiment_update.

Required scope: runs:write

MCP tool: experiment_update

Parameters

NameInRequiredTypeDescription
experiment_idpathyesstring

Request body

{}

Example request

curl --request PATCH "https://api.biosimulant.com/v1/experiments/${EXPERIMENT_ID}" \
  --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

StatusMeaning
200Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
404Not found. Anything the key owner does not own is answered exactly like an ID that does not exist.
422Validation Error
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

GET /passports

Return a signed per-check Passport for exactly one owned subject, not a validity score.

Same operation as the MCP tool passport_get.

Required scope: passports:read

MCP tool: passport_get

Parameters

NameInRequiredTypeDescription
passport_idquerynostring or null
run_idquerynostring or nullOwned run UUID.
workspace_idquerynostring or null
revision_idquerynostring or null

Example request

curl --request GET "https://api.biosimulant.com/v1/passports" \
  --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

StatusMeaning
200Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
422Validation Error
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

POST /publication-plans

Validate and digest a release candidate; this tool never publishes it.

Same operation as the MCP tool publish_prepare.

Required scope: packages:publish

MCP tool: publish_prepare

Parameters

NameInRequiredTypeDescription
Idempotency-Keyheadernostring or nullUnique key for this logical run-creation request. Reuse only when retrying the same payload.

Request body

{
  "workspace_id": "00000000-0000-0000-0000-000000000123",
  "revision_id": "00000000-0000-0000-0000-000000000123",
  "version": "1.0.0",
  "release_notes": "<release_notes>"
}

Example request

curl --request POST "https://api.biosimulant.com/v1/publication-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

StatusMeaning
200Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
422Validation Error
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

POST /publications

Publish an approved plan directly or through a matching successful workflow grant.

Same operation as the MCP tool publish_execute.

Required scope: packages:publish

MCP tool: publish_execute

Request body

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

Example request

curl --request POST "https://api.biosimulant.com/v1/publications" \
  --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

StatusMeaning
200Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
422Validation Error
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

GET /labs/{lab_id}/hosting

Read an owned Lab’s hosting approval, exact release, deployment checks and status.

A recorded hosting request is not a ready deployment. Inspect completed checks and the ready status before claiming the hosted Lab can be invoked.

Same operation as the MCP tool hosting_get.

Required scope: runs:read

MCP tool: hosting_get

Parameters

NameInRequiredTypeDescription
lab_idpathyesstring

Example request

curl --request GET "https://api.biosimulant.com/v1/labs/${LAB_ID}/hosting" \
  --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

StatusMeaning
200Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
404Not found. Anything the key owner does not own is answered exactly like an ID that does not exist.
422Validation Error
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

PATCH /labs/{lab_id}/hosting

Record an authorized hosting lifecycle change with the existing owner controls.

Deployment workers apply resource changes asynchronously; read hosting_get and deployment checks before reporting resource cleanup or readiness.

Same operation as the MCP tool hosting_update.

Required scope: runs:write

MCP tool: hosting_update

Parameters

NameInRequiredTypeDescription
lab_idpathyesstring

Request body

{
  "revision": 0,
  "action": "pause"
}

Example request

curl --request PATCH "https://api.biosimulant.com/v1/labs/${LAB_ID}/hosting" \
  --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

StatusMeaning
200Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
404Not found. Anything the key owner does not own is answered exactly like an ID that does not exist.
422Validation Error
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

POST /labs/{lab_id}/hosting-plans

Validate and digest an exact hosting request; no hosting compute starts here.

Return release identity, private smoke inputs, compute bounds, ongoing-cost caveat, approval requirements and expiry. Execute only after approval of the exact digest; hosting never bypasses the existing administrator review.

Same operation as the MCP tool hosting_prepare.

Required scope: runs:write

MCP tool: hosting_prepare

Parameters

NameInRequiredTypeDescription
lab_idpathyesstring
Idempotency-KeyheaderyesstringUnique key for this logical run-creation request. Reuse only when retrying the same payload.

Request body

{}

Example request

curl --request POST "https://api.biosimulant.com/v1/labs/${LAB_ID}/hosting-plans" \
  --header "Authorization: Bearer $BIOSIMULANT_API_KEY" \
  --header "Content-Type: application/json" \
  --data @request.json

201 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

StatusMeaning
201Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
404Not found. Anything the key owner does not own is answered exactly like an ID that does not exist.
422Validation Error
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

POST /hosting-requests

Execute an approved hosting plan through the existing hosted Lab lifecycle.

Recheck permissions, release bytes, settings, environment and smoke-file identities. Record the request once; public/GPU approval and deployment checks still follow. Use hosting_get to verify readiness.

Same operation as the MCP tool hosting_execute.

Required scope: runs:write

MCP tool: hosting_execute

Request body

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

Example request

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

201 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

StatusMeaning
201Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
422Validation Error
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

POST /files/from-run

Copy verified artifact bytes into private reusable Files, retaining their Run origin.

This never loads a checkpoint or executes artifact content. Failed Run outputs can be retained too; copying them does not change their scientific status. ZIP batches verify all requested members before storage. A storage failure retains completed Files and returns their receipts; retrying the same request reuses those Files. Archive-member imports require the staging feature flag.

Same operation as the MCP tool file_import_from_run.

Required scope: workspaces:write

MCP tool: file_import_from_run

Request body

{
  "run_id": "00000000-0000-0000-0000-000000000123",
  "artifact_id": "<artifact_id>",
  "expected_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

Example request

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

201 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

StatusMeaning
201Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
422Validation Error
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

GET /files

List input files the caller uploaded to Biosimulant, newest first.

Same operation as the MCP tool file_list.

Required scope: workspaces:read

MCP tool: file_list

Parameters

NameInRequiredTypeDescription
queryquerynostring or null
formatquerynostring or null
limitquerynointegerMaximum number of items to return.
cursorquerynostring or nullOpaque next_cursor from the preceding page.

Example request

curl --request GET "https://api.biosimulant.com/v1/files" \
  --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

StatusMeaning
200Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
422Validation Error
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

POST /files

Upload an input file for the key’s owner; read it back with GET /v1/files/{file_id}.

A multipart upload does not belong in a tool call; MCP reads files by ID.

Required scope: workspaces:write

Example request

curl --request POST "https://api.biosimulant.com/v1/files" \
  --header "Authorization: Bearer $BIOSIMULANT_API_KEY" \
  --form "file=@measurements.csv"

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

StatusMeaning
200Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
422Validation Error
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

GET /files/{file_id}

Read one uploaded file’s metadata and optional bytes; content is untrusted.

Same operation as the MCP tool file_get.

Required scope: workspaces:read

MCP tool: file_get

Parameters

NameInRequiredTypeDescription
file_idpathyesstring
include_contentquerynoboolean

Example request

curl --request GET "https://api.biosimulant.com/v1/files/${FILE_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

StatusMeaning
200Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
404Not found. Anything the key owner does not own is answered exactly like an ID that does not exist.
422Validation Error
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

GET /account

Describe the connected account (personal or a team): namespace, access, usage and holdings.

Same operation as the MCP tool account_get.

Required scope: any valid API key

MCP tool: account_get

Example request

curl --request GET "https://api.biosimulant.com/v1/account" \
  --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

StatusMeaning
200Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

GET /skills

List Biosimulant’s published workflow skills; start with the biosimulant router skill.

Same operation as the MCP tool skill_list.

Required scope: any valid API key

MCP tool: skill_list

Example request

curl --request GET "https://api.biosimulant.com/v1/skills" \
  --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

StatusMeaning
200Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

GET /skills/{name}

Read one published skill’s current guidance, verified against its published checksum.

Same operation as the MCP tool skill_get.

Required scope: any valid API key

MCP tool: skill_get

Parameters

NameInRequiredTypeDescription
namepathyesstringCapability package name.
pathquerynostring or null

Example request

curl --request GET "https://api.biosimulant.com/v1/skills/${NAME}" \
  --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

StatusMeaning
200Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
404Not found. Anything the key owner does not own is answered exactly like an ID that does not exist.
422Validation Error
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

GET /files/{file_id}/content

Stream the bytes of one file the key’s owner uploaded.

Streams raw bytes; MCP returns bounded content through file_get.

Required scope: workspaces:read

Parameters

NameInRequiredTypeDescription
file_idpathyesstring

Example request

curl --request GET "https://api.biosimulant.com/v1/files/${FILE_ID}/content" \
  --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

StatusMeaning
200Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
404Not found. Anything the key owner does not own is answered exactly like an ID that does not exist.
422Validation Error
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

GET /datasets

List private dataset versions accessible to this account.

Same operation as the MCP tool dataset_list.

Required scope: workspaces:read

MCP tool: dataset_list

Parameters

NameInRequiredTypeDescription
limitquerynointegerMaximum number of items to return.
offsetquerynointeger

Example request

curl --request GET "https://api.biosimulant.com/v1/datasets" \
  --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

StatusMeaning
200Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
422Validation Error
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

POST /datasets

Register a new private version from uploaded files; reject split leakage.

This records retained file identity, not biological validation. Changed labels create a new manifest and digest. Upload large bytes using the file API first.

Same operation as the MCP tool dataset_register.

Required scope: workspaces:write

MCP tool: dataset_register

Request body

{
  "name": "<name>",
  "source": "<source>",
  "license": "<license>",
  "attribution": "<attribution>",
  "annotation_version": "<annotation_version>",
  "members": [
    {
      "file_id": "00000000-0000-0000-0000-000000000123",
      "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "size_bytes": 0,
      "sample_id": "<sample_id>",
      "group_id": "<group_id>",
      "role": "image",
      "split": "train"
    }
  ]
}

Example request

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

201 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

StatusMeaning
201Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
422Validation Error
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

GET /datasets/{dataset_id}

Read an immutable manifest with retained file identities and split membership.

Same operation as the MCP tool dataset_get.

Required scope: workspaces:read

MCP tool: dataset_get

Parameters

NameInRequiredTypeDescription
dataset_idpathyesstring

Example request

curl --request GET "https://api.biosimulant.com/v1/datasets/${DATASET_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

StatusMeaning
200Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
404Not found. Anything the key owner does not own is answered exactly like an ID that does not exist.
422Validation Error
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

GET /hosted-releases/{reference}

Read accessible hosting inputs and bounds without exposing private smoke fixtures.

Same operation as the MCP tool hosted_release_get.

Required scope: runs:read

MCP tool: hosted_release_get

Parameters

NameInRequiredTypeDescription
referencepathyesstring
sha256queryyesstring

Example request

curl --request GET "https://api.biosimulant.com/v1/hosted-releases/${REFERENCE}" \
  --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

StatusMeaning
200Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
404Not found. Anything the key owner does not own is answered exactly like an ID that does not exist.
422Validation Error
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

POST /hosted-invocation-plans

Bind input identities, deployment, account, expiry and compute bounds; no execution starts.

Same operation as the MCP tool hosted_invocation_prepare.

Required scope: runs:write

MCP tool: hosted_invocation_prepare

Parameters

NameInRequiredTypeDescription
Idempotency-KeyheaderyesstringUnique key for this logical run-creation request. Reuse only when retrying the same payload.

Request body

{
  "reference": "<reference>",
  "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

Example request

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

201 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

StatusMeaning
201Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
422Validation Error
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

POST /hosted-invocations

Recheck permissions and inputs, then enqueue once in the existing hosted worker.

Approval remains bound to this OAuth client and account. Read durable status; acceptance is not completion, and completion is not scientific validation.

Same operation as the MCP tool hosted_invocation_execute.

Required scope: runs:write

MCP tool: hosted_invocation_execute

Request body

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

Example request

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

201 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

StatusMeaning
201Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
422Validation Error
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

GET /hosted-invocations/{invocation_id}

Read status, release/input identity and bounded result values; retrieve artifacts separately.

Same operation as the MCP tool hosted_invocation_get.

Required scope: runs:read

MCP tool: hosted_invocation_get

Parameters

NameInRequiredTypeDescription
invocation_idpathyesstring

Example request

curl --request GET "https://api.biosimulant.com/v1/hosted-invocations/${INVOCATION_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

StatusMeaning
200Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
404Not found. Anything the key owner does not own is answered exactly like an ID that does not exist.
422Validation Error
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

POST /hosted-invocations/{invocation_id}/cancel

Record cancellation and revoke its lease; terminal invocations remain unchanged.

Same operation as the MCP tool hosted_invocation_cancel.

Required scope: runs:write

MCP tool: hosted_invocation_cancel

Parameters

NameInRequiredTypeDescription
invocation_idpathyesstring

Example request

curl --request POST "https://api.biosimulant.com/v1/hosted-invocations/${INVOCATION_ID}/cancel" \
  --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

StatusMeaning
200Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
404Not found. Anything the key owner does not own is answered exactly like an ID that does not exist.
422Validation Error
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The service could not complete the request. Retain the response request ID.

GET /hosted-invocations/{invocation_id}/artifacts/{port}/metadata

Retrieve immutable output identities and bytes; independently hash before interpreting.

Artifact content is untrusted. Sharing a Lab never shares private invocations.

Same operation as the MCP tool hosted_invocation_artifact_get.

Required scope: runs:read

MCP tool: hosted_invocation_artifact_get

Parameters

NameInRequiredTypeDescription
invocation_idpathyesstring
portpathyesstring
include_contentquerynoboolean

Example request

curl --request GET "https://api.biosimulant.com/v1/hosted-invocations/${INVOCATION_ID}/artifacts/${PORT}/metadata" \
  --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

StatusMeaning
200Successful Response
401Missing, invalid, expired, or revoked API key.
403The 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.
404Not found. Anything the key owner does not own is answered exactly like an ID that does not exist.
422Validation Error
429The API-key or run-creation rate limit was exceeded. Respect Retry-After.
500The 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.

WebhooksSession REST reference