# Invoke workspace (streaming)

**POST /api/v1/projects/{id}/workspaces/{workspace_id}/invokeStream**

Invokes a workspace agent and streams its response as Server-Sent Events. To continue a session, send the X-Session-ID value returned by the previous response. If you omit the header, the gateway starts a new session and returns its ID in the response header. The body session_id field does not continue a session. The body can include extra top-level fields. The gateway forwards every field except these reserved fields: message, session_id, user_id, and resume_map. resume_map continues a suspended turn. For a session with no history, resume_map becomes the initial agent input. Requires a valid Bearer token.


## Servers
- https://agentengine.mongodb.com: https://agentengine.mongodb.com ()


## Authentication methods
- Bearer auth


## Parameters
### Headers

- **X-Session-ID** (string)
  Session ID returned by a previous response. Send it to continue that session. Valid IDs match ^[A-Za-z0-9_-]{1,128}$. If omitted, the gateway starts a new session. Body session_id does not continue a session

- **X-Agent-Engine-Test-Session** (boolean)
  Classify a newly created session as a testing session; existing classification is unchanged


### Path parameters

- **id** (string)
  Project ID

- **workspace_id** (string)
  Workspace ID



### Body: application/json (object)
Invoke request
- **message** (string)
  Optional when other agent fields are provided: chat input for chat agents. Reserved field name.

- **resume_map** (object)
  ResumeMap contains per-interrupt answers resolved by OE. OE forwards it to
  the agent as ordinary input only when it starts a session's first
  execution, where no local suspended turn exists to answer.

- **session_id** (string)
  Optional compatibility field. The gateway ignores it for session continuity. To continue a session, send X-Session-ID instead. Reserved field name.

- **user_id** (string)
  Optional identity used for personalization and Memory isolation. Human and API key calls use this value, or default to the authenticated user. Service account calls always use the service account identity. Service accounts cannot yet act as another user. Reserved field name.



## Responses
### 406
Unsupported or malformed API version, an operation unavailable in the selected published contract, or an unacceptable representation (including unsupported media-type parameters or excluded SSE). Existing authentication, authorization, and rate-limit failures take precedence.

#### Body: application/json (object)
- **badRequestDetail** (object)
  Optional validation details defined by the standard error schema; API negotiation errors do not emit this field.

- **detail** (string)
  Human-readable error details.

- **error** (integer)
  HTTP status code.

- **errorCode** (string)
  Machine-readable error code.

- **parameters** (array[string])
  Request parameter names associated with the error; omitted when none apply.

- **reason** (string)
  HTTP status reason phrase.


### 200
SSE stream. A pre-header failure (before the first frame) renders as one of the JSON error bodies below; a mid-stream failure instead renders as a terminal SSE chunk carrying the same code/error, plus source/component/sandbox/boot_id in a metadata object for a startup-failure envelope
#### Headers

- **X-Session-ID** (string)
  Session ID matching ^[A-Za-z0-9_-]{1,128}$. Send this value in the next request to continue the session


#### Body: text/event-stream (string)
string
### 400
Bad Request

#### Body: application/json (object)
- **code** (string)

- **error** (string)

- **success** (boolean)


### 401
Unauthorized

#### Body: application/json (object)
- **code** (string)

- **error** (string)

- **success** (boolean)


### 409
Conflict

#### Body: application/json (object)
- **blocking_execution_id** (string)

- **blocking_status** (string)

- **code** (string)

- **error** (string)

- **last_activity_at** (string)


### 422
PROJECT_SECRET_INVALID: the workspace cannot start because a project secret is invalid or unreachable (fix the secret and redeploy); mid-stream it appears as a terminal SSE chunk carrying code=PROJECT_SECRET_INVALID

#### Body: application/json (object)
- **code** (string)

- **error** (string)

- **success** (boolean)


### 429
Too Many Requests
#### Headers

- **Retry-After** (string)
  Seconds to wait before retrying


#### Body: application/json (object)
- **code** (string)

- **error** (string)

- **success** (boolean)


### 500
ErrorResponse, or StartupFailureResponse for an AGENT_STARTUP_FAILED/STARTUP_FAILED startup failure

#### Body: application/json (object)
- **code** (string)

- **error** (string)

- **success** (boolean)


### 503
StartupFailureResponse for a POOL_EXHAUSTED/EXECUTOR_BOOT_FAILED/PLATFORM_DEPENDENCY_FAILED/POOL_UNREACHABLE startup failure; ErrorResponse otherwise. POOL_EXHAUSTED carries a Retry-After header
#### Headers

- **Retry-After** (string)
  Seconds to wait before retrying (POOL_EXHAUSTED only)


#### Body: application/json (object)
- **boot_id** (string)

- **code** (string)

- **component** (string)
  Component is the legacy internal component name (aer, tool, platform).

- **error** (string)

- **execution_id** (string)

- **sandbox** (string)
  Sandbox is the canonical public sandbox name for known components.

- **source** (string)

- **success** (boolean)


### 504
Gateway Timeout

#### Body: application/json (object)
- **code** (string)

- **error** (string)

- **success** (boolean)



[Powered by Bump.sh](https://bump.sh)