Agent Endpoints

Agent Endpoints turn an agent into a stable REST or MCP service. SandBase owns the Session and Sandbox lifecycle, records every run, and restores state for calls that reuse a thread_id.

You can create an Endpoint in two mutually exclusive ways:

Declarative: provide name and runtime, plus optional Skills and agent settings. SandBase creates the managed Agent and Environment.
Advanced: provide an existing agent_id and environment_id.

The first declarative runtime is hermes on E2B. Hermes provides native Skills, persistent memory, tools, subagent delegation, and outbound MCP integration; see Hermes agent capabilities. Endpoint execution supports E2B environments only in this release. Messaging gateways and Cron are not exposed by Endpoint APIs.

List runtime profiles

GET/v1/endpoint_runtime_profiles

bash

curl https://api.sandbase.ai/v1/endpoint_runtime_profiles \
  -H "Authorization: Bearer sk-sb-YOUR_KEY"

json

{
  "data": [
    {
      "id": "hermes",
      "display_name": "Hermes",
      "enabled": true,
      "supports_skills": true,
      "supports_state": true,
      "protocols": ["rest", "mcp", "acp"]
    }
  ]
}

Only enabled profiles are returned. Internal template IDs, entrypoints, system prompts, directories, and checkpoint configuration are never included.

Create a declarative Endpoint

POST/v1/endpoints

The minimum JSON definition is:

bash

curl -X POST https://api.sandbase.ai/v1/endpoints \
  -H "Authorization: Bearer sk-sb-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"research-assistant","runtime":"hermes"}'

YAML is also accepted with Content-Type: application/yaml or application/x-yaml. Save the following as endpoint.yaml, replacing vendor_slug/plugin_slug with the .name returned by the Skills API:

yaml

name: research-assistant
runtime: hermes
description: Research a topic using selected skills and tools.
model: minimax/minimax-m3
system: You are a careful research assistant.
skills:
  - vendor_slug/plugin_slug
mcp_servers:
  - name: search
    type: url
    url: https://mcp.deepwiki.com/mcp
tools:
  - type: agent_toolset_20260401
protocols:
  - rest
  - mcp

bash

curl -fsS -X POST https://api.sandbase.ai/v1/endpoints \
  -H "Authorization: Bearer $SANDBASE_API_KEY" \
  -H 'Content-Type: application/yaml' \
  --data-binary @endpoint.yaml \
  | jq .

The MCP URL above is a third-party, credential-free demo service and is not covered by the SandBase SLA. Replace it with your own HTTPS Streamable HTTP MCP URL for production use.

Field	Type	Required	Description
`name`	string	✅	Endpoint display name.
`runtime`	string	✅	Enabled runtime profile. This release supports `hermes`.
`description`	string	❌	Managed Agent description.
`model`	string or object	❌	Model override. Uses the runtime default when omitted.
`system`	string	❌	System prompt override.
`skills`	string[] or null	❌	Full `vendor_slug/plugin_slug` references returned by the Skills API. Omitted, null, and `[]` all mean no Skills. Maximum 20.
`mcp_servers`	array or null	❌	Up to 20 unique remote HTTP(S) servers in `{name,type,url}` form. Commands, headers, env, URL userinfo, and extra fields are rejected.
`tools`	array or null	❌	Hermes accepts only `[{"type":"agent_toolset_20260401"}]` in this release.
`protocols`	string[]	❌	`rest`, `mcp`, or experimental `acp`. Defaults to `rest,mcp`.

SandBase strictly validates the entire definition before creating resources. Declared Skills and MCP configuration are materialized before the first message is delivered; a failure never silently starts an agent without them.

Each Skill reference remains vendor_slug/plugin_slug, but Hermes runtime identity comes from the bundle-root SKILL.md frontmatter name. The validated name is used for installation and lookup, so a plugin slug may differ from the name returned by Hermes. Missing, invalid, duplicate, or unreadable runtime names fail materialization before message delivery.

json

{
  "id": "ep_01abc",
  "type": "endpoint",
  "name": "research-assistant",
  "agent_id": "agent_01abc",
  "agent_version": 1,
  "environment_id": "env_01abc",
  "protocols": ["rest", "mcp"],
  "status": "active",
  "creation_mode": "declarative",
  "runtime": "hermes",
  "skills": ["vendor_slug/plugin_slug"],
  "run_url": "https://api.sandbase.ai/v1/endpoints/ep_01abc/run",
  "mcp_url": "https://api.sandbase.ai/v1/endpoints/ep_01abc/mcp"
}

Create from an existing Agent

The advanced request remains available for users that manage Agents and Environments directly. Do not mix these fields with runtime. Endpoint invocation currently requires an E2B Environment; an Endpoint bound to another Sandbox provider is rejected before execution with 422 unsupported_sandbox_provider.

json

{
  "name": "existing-agent-service",
  "agent_id": "agent_01abc",
  "environment_id": "env_01abc",
  "protocols": ["rest", "mcp"]
}

Invoke over REST

POST/v1/endpoints/{endpoint_id}/run

Use Prefer: wait for a synchronous response:

bash

curl -X POST https://api.sandbase.ai/v1/endpoints/ep_01abc/run \
  -H "Authorization: Bearer sk-sb-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait" \
  -d '{"input":"Remember that my project is Atlas.","thread_id":"customer-123"}'

json

{
  "request_id": "req_01abc",
  "endpoint_id": "ep_01abc",
  "thread_id": "customer-123",
  "status": "completed",
  "output": "I will remember that your project is Atlas.",
  "usage": {"prompt_tokens": 0, "completion_tokens": 0},
  "latency_ms": 1240
}

The default mode is asynchronous. After request and Endpoint/provider validation, it durably creates the run and returns 202 with a running request ID without waiting for Sandbox provisioning, state restore, Skill/MCP materialization, message delivery, or turn completion. Poll the run API for its terminal result. Send Accept: text/event-stream to receive status, delta, tool, done, and error SSE events.

X-Sandbase-Thread-Id takes precedence over the body thread_id. Reuse the same value to preserve a durable conversation. If no thread_id is supplied, the call is single-turn and stateless.

State checkpoints contain only Hermes native memory. Skills, Tools, outbound MCP configuration, general workspace files, and the rest of the CLI home are not checkpointed. Whenever EnsureSandbox replaces the underlying E2B Sandbox, SandBase restores the latest committed memory checkpoint before delivering the next message and rematerializes declared static capabilities from the managed Agent definition. A restore failure never continues with blank memory.

Invoke over MCP

POST/v1/endpoints/{endpoint_id}/mcp

The Endpoint MCP URL is an inbound protocol for clients to call the agent. It is separate from declarative mcp_servers, which configure outbound tools used by Hermes.

Send JSON-RPC initialize, then tools/list and tools/call. Preserve the returned Mcp-Session-Id header on subsequent requests. Release it with DELETE /v1/endpoints/{endpoint_id}/mcp and the same header. Runtime failures use generic JSON-RPC error messages; internal paths, object keys, credentials, and upstream error details are not returned.

Invoke over ACP (experimental)

POST /v1/endpoints/{endpoint_id}/acp exposes the experimental ACP-over-HTTP JSON-RPC transport. It supports initialize, session/new, session/prompt, and session/cancel; prompt streams are newline-delimited JSON. ACP runtime failures use the same redacted public error messages as MCP. The remote transport may change while ACP remains experimental.

Manage Endpoints and runs

Method	Path	Description
`GET`	`/v1/endpoints`	List Endpoints in the current organization.
`GET`	`/v1/endpoints/{id}`	Get one Endpoint and its invocation URLs.
`PATCH`	`/v1/endpoints/{id}`	Update operational fields. A declarative definition is immutable in this release.
`DELETE`	`/v1/endpoints/{id}`	Delete the Endpoint. Declarative managed resources follow their protected lifecycle.
`GET`	`/v1/endpoint_runs?endpoint_id={id}`	List run records.
`GET`	`/v1/endpoint_runs/{request_id}`	Get one run, including cold-start, usage, latency, and terminal error metadata.

Errors

Status	Type	Description
400	`invalid_definition`	Invalid JSON/YAML, field, Skill reference, toolset, or MCP server.
400	`invalid_creation_mode`	Declarative and advanced fields are mixed or incomplete.
404	`skill_not_found`	Skill does not exist, is disabled, or is not visible to the caller.
409	`managed_endpoint_immutable`	A PATCH attempted to replace a declarative definition.
422	`unsupported_runtime`	Runtime is unknown or not enabled.
422	`unsupported_sandbox_provider`	Endpoint execution is bound to a Sandbox provider other than E2B. No turn is delivered.
422	`skill_runtime_incompatible`	Skill cannot run on the selected runtime.
502	`skill_materialization_failed`	Declared Skill could not be installed or resolved by its `SKILL.md` runtime name before delivery.
502	`mcp_materialization_failed`	Hermes MCP configuration could not be materialized before delivery.
503	`state_persistence_unavailable`	A stateful call cannot guarantee checkpoint persistence.
503	`state_recovery_failed`	The latest committed checkpoint could not be restored; the message was not delivered.

REST, MCP, and ACP error responses do not include system prompts, MCP credentials, internal paths, checkpoint object URLs, Skill bundle contents, or raw upstream errors.

Agent Endpoints ​

List runtime profiles ​

Create a declarative Endpoint ​

Create from an existing Agent ​

Invoke over REST ​

Invoke over MCP ​

Invoke over ACP (experimental) ​

Manage Endpoints and runs ​

Errors ​

Agent Endpoints

List runtime profiles

Create a declarative Endpoint

Create from an existing Agent

Invoke over REST

Invoke over MCP

Invoke over ACP (experimental)

Manage Endpoints and runs

Errors