---
title: "Create a new agent session"
method: POST
path: "/agent/sessions"
tags: ["Sessions"]
---

# Create a new agent session

`POST /agent/sessions`

## Request body

- CreateAgentSessionDto
  - `workspaceElementType` 'customer' | 'app' | 'connector' | 'integration' | 'flow' | 'flow-instance' | 'flow-run' | 'action' | 'package' | 'action-instance' | 'connection' | 'field-mapping' | 'field-mapping-instance' | 'data-source' | 'data-source-instance' | 'data-link-table' | 'data-link-table-instance' | 'app-event-type' | 'app-event-subscription' | 'app-event-log-record' | 'app-data-schema' | 'app-data-schema-instance' | 'external-event-subscription' | 'external-event-log-record' | 'external-event-pull' | 'external-event-type' | 'screen' | 'action-run-log-record' | 'external-api-log-record' | 'incoming-webhook-log-record' | 'connected-product'
  - `workspaceElementId` string
  - `prompt` string, required
  - `testCustomerId` string
  - `isExternal` boolean
  - `modelId` 'anthropic/claude-sonnet-4.6' | 'anthropic/claude-opus-4.6' | 'anthropic/claude-sonnet-4.5' | 'anthropic/claude-opus-4.5' | 'anthropic/claude-haiku-4.5' | 'openai/gpt-5.2' | 'openai/gpt-5-nano' | 'google/gemini-3-pro-preview' | 'moonshotai/kimi-k2.5'
  - `agentName` 'membrane' | 'membrane-core' | 'self-integrating' | 'connection-building' | 'action-building' | 'universe'
  - `agentHarnessId` string
  - `promptAttachments` object[]
    - `title` string, required
    - `data` object, required

## Response `200`

- AgentSessionDto
  - `userId` string
  - `tenantId` string
  - `id` string, required
  - `workspaceId` string, required
  - `orgWorkspaceId` string
  - `workspaceElementType` 'customer' | 'app' | 'connector' | 'integration' | 'flow' | 'flow-instance' | 'flow-run' | 'action' | 'package' | 'action-instance' | 'connection' | 'field-mapping' | 'field-mapping-instance' | 'data-source' | 'data-source-instance' | 'data-link-table' | 'data-link-table-instance' | 'app-event-type' | 'app-event-subscription' | 'app-event-log-record' | 'app-data-schema' | 'app-data-schema-instance' | 'external-event-subscription' | 'external-event-log-record' | 'external-event-pull' | 'external-event-type' | 'screen' | 'action-run-log-record' | 'external-api-log-record' | 'incoming-webhook-log-record' | 'connected-product'
  - `workspaceElementId` string
  - `type` string, required
  - `status` 'queued' | 'starting' | 'running' | 'completed' | 'failed' | 'cancelled', required
  - `prompt` string, required
  - `error` AgentSessionDtoSchema0
    - `type` 'bad_request' | 'connection' | 'configuration' | 'dependency_error' | 'flow_run' | 'flow_instance_setup' | 'concurrency' | 'internal' | 'action_run' | 'action_instance_setup' | 'unit_run' | 'custom_code' | 'insufficient_credit' | 'openrouter_not_configured'
    - `key` string
    - `message` string, required
    - `data` object
    - `stack` object
    - `causedByError` AgentSessionDtoSchema0 — recursive
    - `logs` object[]
  - `lastActivityAt` string, date-time, required — Last meaningful session progress timestamp used for inactivity timeout checks.
  - `title` string
  - `summary` string
  - `cost` number
  - `state` 'busy' | 'idle'
  - `hasWorker` boolean, required
  - `isExternal` boolean
  - `agentName` 'membrane' | 'membrane-core' | 'self-integrating' | 'connection-building' | 'action-building' | 'universe'
  - `agentHarnessId` string
  - `agentHarnessSnapshotId` string
  - `output` object
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, required

---

[API](https://skmtc.net/getmembrane/apis/membrane-api.md) · [All operations](https://skmtc.net/getmembrane/apis/membrane-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/getmembrane/membrane-api/versions/f8591a09da92/schema)