Start building
SandBase

Appearance

Platform API Reference ​

Use the Platform API to define reusable Agents, run them in Sessions, deploy them as Services or Schedules, and connect them to Skills and MCP tools.

Looking for model inference?

Chat, image, video, audio, and model-specific request schemas live in the Model API Reference. The Platform API covers managed Agent resources and operations.

Choose a starting point ​

GoalStart withWhat happens next
Define reusable behaviorAgentsCreate and version an Agent configuration
Run an Agent directlySessionsSend input, stream events, and read history
Invoke an Agent from an applicationServicesEach invocation returns a Run that creates a Session
Run work on a scheduleSchedulesEach firing or manual trigger creates a Run and a Session
Reuse instruction bundlesSkillsUpload versioned ZIP bundles and attach them to Agents
Call external toolsMCP ConnectionsRegister remote HTTPS MCP servers for Agents
Authenticate external toolsSecretsStore write-only Bearer tokens for MCP connections

Resource lifecycle ​

text
Agent + version ─┬─ direct ──────────────────────────────→ Session ─→ events, items, turns
                 ├─ Service ── invoke ──→ Run ────────────→ Session
                 └─ Schedule ─ cron or manual trigger → Run → Session
Agent ─ skills[] → Skill version      Agent ─ mcp_connections[] → MCP connection ─ secret_id → Secret
  • An Agent (agt_) is a saved, versioned configuration; creating one does not execute it.
  • A Session (ses_) runs one Agent version and freezes its Skills and MCP connections. Session paths live under /v1/agents/sessions.
  • A Service (svc_) pins an Agent version for on-demand calls. Each invocation returns a Run (run_) that creates its own Session.
  • A Schedule (sch_) pins an Agent version and input and fires on a cron expression. Each firing or manual trigger creates a Run and a Session.
  • A Skill (skl_) is a versioned instruction bundle. An MCP connection (mcp_) registers a remote tool server, and a Secret (sec_) stores its Bearer token.

Conventions for Agents platform resources ​

Agents, Sessions, Services, Schedules, Skills, MCP connections, and Secrets are served under https://api.sandbase.ai/v1 and share these rules:

  • Authenticate with Authorization: Bearer or X-API-Key. See Authentication.
  • Request bodies are strict JSON up to 1 MiB; unknown fields return 400.
  • Writes that create Runs, Services, Schedules, MCP connections, or Secrets require an Idempotency-Key. Other writes accept one.
  • Optimistic concurrency uses row_version: send the value you last read, and handle 409 by reading again.
  • Agents, Sessions, items, turns, and Skills use cursor pagination (limit, after, order; responses have has_more and last_id). Agent versions, Services, Schedules, Runs, attachments, MCP connections, and Secrets use offset pagination (limit, offset; responses have total).
  • Errors use {"error": {"type", "code", "param", "message"}}. See Agents platform errors.

Authentication ​

Send a SandBase API key as a Bearer token:

http
Authorization: Bearer sk-YOUR_KEY

Treat the key as an opaque secret, keep it on the server, and never include it in browser code or logs. See Authentication for compatibility details and Errors for public error envelopes.

Organization and usage ​

Platform resources belong to the organization associated with the API key. Use the Account API to inspect the supported balance and recent execution-history views. Organization administration and billing management remain Console workflows unless a public endpoint is documented here.

Reference formats ​

  • Browse operations from the sidebar for examples and response details.
  • Download the machine-readable OpenAPI specification.
  • Use the Model API Reference for inference endpoints and model-specific schemas.

Next steps ​