Create Deployment

POST /v1/deployments

Creates a Hermes agent in an isolated container for one of your customers. Bring your system prompt, skills, MCP tools, and connector secrets — the deployment ships with session management, observational memory, automations, self-learning, and a persistent filesystem, plus an SSE endpoint to stream agent events. Provisioning usually completes in seconds. Poll Get Deployment until status is ready, then start sending messages.

Request

curl "https://api.prismagents.com/v1/deployments" \
  -X POST \
  -H "Authorization: Bearer $PRISM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_123",
    "name": "Acme Creative Agent",
    "runtime": "hermes",
    "model": "anthropic/claude-sonnet-4.5",
    "system_prompt": "You are Acme'\''s media generation agent. Help the user plan, create, and iterate on high-performing short-form videos.",
    "sandbox": {
      "enabled": true,
      "type": "docker",
      "persistent_filesystem": true
    },
    "mcp_servers": [
      {
        "name": "prism-media",
        "url": "https://api.prismvideos.com/mcp",
        "tools": [
          "search_models",
          "generate_image",
          "generate_video"
        ]
      }
    ],
    "skills": [
      {
        "name": "ugc-video-creation",
        "source": "file",
        "path": ".prism/skills/ugc-video-creation/SKILL.md"
      },
      {
        "name": "storyboarding",
        "source": "inline",
        "content": "---\nname: storyboarding\ndescription: Create shot-by-shot storyboards\n---\n# Storyboarding\n..."
      },
      {
        "name": "social-media-visual-effects",
        "source": "url",
        "url": "https://example.com/skills/social-media-visual-effects/SKILL.md"
      }
    ],
    "secrets": {
      "META_ADS_TOKEN": "sec_meta_ads_token",
      "GOOGLE_DRIVE_TOKEN": "sec_google_drive_token"
    },
    "features": {
      "memory": true,
      "dreaming": true,
      "automations": true,
      "steering": true,
      "filesystem_webhooks": true
    }
  }'

Body parameters

Parameter	Type	Required	Description
`customer_id`	string	Yes	Your identifier for the customer this agent serves. One agent per customer is the recommended model
`name`	string	Yes	Human-readable deployment name
`runtime`	string	No	Agent harness to run. Currently `hermes` (default)
`model`	string	No	Model in `provider/model` form, such as `anthropic/claude-sonnet-4.5`. No provider lock-in
`system_prompt`	string	Yes	The agent’s system prompt
`sandbox`	object	No	Sandbox configuration — see Sandbox
`mcp_servers`	array	No	Your MCP servers exposing first-party tools — see MCP servers
`skills`	array	No	Skill files that teach the agent your domain playbooks — see Skills
`secrets`	object	No	Map of environment variable names to secret references (`sec_...`) for connectors
`features`	object	No	Feature flags — see Features

Sandbox

Field	Type	Default	Description
`enabled`	boolean	`true`	Run the agent in an isolated container
`type`	string	`docker`	Sandbox backend
`persistent_filesystem`	boolean	`true`	Persist the agent’s workspace across sessions

MCP servers

Field	Type	Required	Description
`name`	string	Yes	Unique server name
`url`	string	Yes	URL of your MCP server
`tools`	string[]	No	Allowlist of tool names. Omit to expose all tools

Skills

Each skill is loaded from one of three sources:

`source`	Required fields	Description
`file`	`name`, `path`	A `SKILL.md` file uploaded to the deployment
`inline`	`name`, `content`	Skill markdown provided directly in the request
`url`	`name`, `url`	A `SKILL.md` fetched from a public URL

Features

Field	Type	Default	Description
`memory`	boolean	`true`	Observational memory across sessions
`dreaming`	boolean	`false`	Idle-time self-learning between sessions
`automations`	boolean	`true`	Scheduled and recurring agent runs
`steering`	boolean	`true`	Human-in-the-loop approvals mid-run
`filesystem_webhooks`	boolean	`false`	Webhook notifications on agent filesystem changes

Response

{
  "deployment_id": "dep_7xK9s2",
  "customer_id": "cus_123",
  "runtime": "hermes",
  "status": "ready",
  "model": "anthropic/claude-sonnet-4.5",
  "thread_id": "thr_default_8a1",
  "filesystem": {
    "workspace_path": "/workspace",
    "persistent": true
  },
  "events": {
    "transport": "sse",
    "url": "https://api.prismagents.com/v1/deployments/dep_7xK9s2/events"
  }
}

Response fields

Field	Type	Description
`deployment_id`	string	Deployment ID to pass to other endpoints
`customer_id`	string	The customer identifier you supplied
`runtime`	string	Agent harness running in the deployment
`status`	string	One of `provisioning`, `ready`, `error`
`model`	string	Resolved model identifier
`thread_id`	string	Default thread for Send Message
`filesystem.workspace_path`	string	Path of the agent’s workspace inside the container
`filesystem.persistent`	boolean	Whether the workspace persists across sessions
`events.transport`	string	Always `sse`
`events.url`	string	Stream Events endpoint for this deployment

Errors

Status	Error	When
400	`validation_error`	Invalid JSON request body
401	`unauthorized`	Missing or invalid API key
402	`insufficient_credits`	The account does not have enough credits
403	`forbidden`	API key lacks `deployments:write` scope
422	`invalid_skill`	A skill could not be fetched or parsed
422	`invalid_secret_ref`	A secret reference does not exist

See Errors for the full error reference.

​Request

​Body parameters

​Sandbox

​MCP servers

​Skills

​Features

​Response

​Response fields

​Errors