POST /api/v1/projects/{id}/workspaces/{workspace_id}/invoke
Bearer auth

Invokes a workspace agent and returns its response. 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.

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

  • X-Agent-Engine-Invoke-Timeout-Seconds integer

    Per-request wait budget in seconds for this blocking invoke (1-120). Defaults to the deployment's INVOKE_WORKSPACE_TIMEOUT_SECONDS when omitted

    Minimum value is 1, maximum value is 120.

Path parameters

  • id string Required

    Project ID

  • workspace_id string Required

    Workspace ID

application/json

Body Required

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.

    Additional properties are allowed.

  • 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.

    Hide response attributes Show response attributes object
    • badRequestDetail object

      Optional validation details defined by the standard error schema; API negotiation errors do not emit this field.

      Hide badRequestDetail attribute Show badRequestDetail attribute object
      • fields array[object]

        Fields with validation failures.

        Hide fields attributes Show fields attributes object

        A field and its validation failure.

        • description string Required

          Human-readable validation failure.

        • field string Required

          Name or path of the invalid request field.

    • detail string Required

      Human-readable error details.

    • error integer Required

      HTTP status code.

    • errorCode string Required

      Machine-readable error code.

    • parameters array[string]

      Request parameter names associated with the error; omitted when none apply.

    • reason string Required

      HTTP status reason phrase.

    Hide response attributes Show response attributes object
    • badRequestDetail object

      Optional validation details defined by the standard error schema; API negotiation errors do not emit this field.

      Hide badRequestDetail attribute Show badRequestDetail attribute object
      • fields array[object]

        Fields with validation failures.

        Hide fields attributes Show fields attributes object

        A field and its validation failure.

        • description string Required

          Human-readable validation failure.

        • field string Required

          Name or path of the invalid request field.

    • detail string Required

      Human-readable error details.

    • error integer Required

      HTTP status code.

    • errorCode string Required

      Machine-readable error code.

    • parameters array[string]

      Request parameter names associated with the error; omitted when none apply.

    • reason string Required

      HTTP status reason phrase.
  • 200

    OK

    Hide headers attribute Show headers attribute
    • X-Session-ID string

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

    Hide response attributes Show response attributes object
    • error string
    • error_code string
    • execution_id string
    • response string
    • status string
    • success boolean
    • suspend_context object

      Additional properties are allowed.

    • suspend_reason string
    Hide response attributes Show response attributes object
    • error string
    • error_code string
    • execution_id string
    • response string
    • status string
    • success boolean
    • suspend_context object

      Additional properties are allowed.

    • suspend_reason string
  • 400

    Bad Request

    Hide response attributes Show response attributes object
    • code string
    • error string
    • success boolean
    Hide response attributes Show response attributes object
    • code string
    • error string
    • success boolean
  • 401

    Unauthorized

    Hide response attributes Show response attributes object
    • code string
    • error string
    • success boolean
    Hide response attributes Show response attributes object
    • code string
    • error string
    • success boolean
  • 409

    Conflict

    Hide response attributes Show response attributes object
    • blocking_execution_id string
    • blocking_status string
    • code string
    • error string
    • last_activity_at string
    Hide response attributes Show response attributes 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)

    Hide response attributes Show response attributes object
    • code string
    • error string
    • success boolean
    Hide response attributes Show response attributes object
    • code string
    • error string
    • success boolean
  • 429

    Too Many Requests

    Hide headers attribute Show headers attribute
    • Retry-After string

      Seconds to wait before retrying

    Hide response attributes Show response attributes object
    • code string
    • error string
    • success boolean
    Hide response attributes Show response attributes object
    • code string
    • error string
    • success boolean
  • 500

    InvokeWorkspaceResponse when the agent's own execution settled with an error (Success:false with an execution_id/status); StartupFailureResponse for an AGENT_STARTUP_FAILED/STARTUP_FAILED startup failure; ErrorResponse otherwise

    Any of:
    InvokeWorkspaceResponse object StartupFailureResponse object ErrorResponse object
    Any of:
    InvokeWorkspaceResponse object StartupFailureResponse object ErrorResponse object
  • 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

    Hide headers attribute Show headers attribute
    • Retry-After string

      Seconds to wait before retrying (POOL_EXHAUSTED only)

    Any of:
    StartupFailureResponse object ErrorResponse object
    Any of:
    StartupFailureResponse object ErrorResponse object
  • 504

    Gateway Timeout

    Hide response attributes Show response attributes object
    • code string
    • error string
    • success boolean
    Hide response attributes Show response attributes object
    • code string
    • error string
    • success boolean
POST /api/v1/projects/{id}/workspaces/{workspace_id}/invoke 
curl \
 --request POST 'https://agentengine.mongodb.com/api/v1/projects/{id}/workspaces/{workspace_id}/invoke' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "X-Session-ID: string" \
 --header "X-Agent-Engine-Test-Session: true" \
 --header "X-Agent-Engine-Invoke-Timeout-Seconds: 42" \
 --data '{
  "message": "string",
  "resume_map": {},
  "session_id": "string",
  "user_id": "string"
}'
Request examples 
# Headers
X-Session-ID: string
X-Agent-Engine-Test-Session: true
X-Agent-Engine-Invoke-Timeout-Seconds: 42

# Payload
{
  "message": "string",
  "resume_map": {},
  "session_id": "string",
  "user_id": "string"
}
Response examples (406) 
{
  "detail": "This operation is not available in API version 2026-09-20-preview.",
  "error": 406,
  "errorCode": "OPERATION_NOT_IN_API_VERSION",
  "parameters": [
    "Accept"
  ],
  "reason": "Not Acceptable"
}
{
  "detail": "This operation supports text/event-stream, which the Accept header excludes. Remove unsupported media-type parameters or accept this type with a positive q value.",
  "error": 406,
  "errorCode": "UNACCEPTABLE_MEDIA_TYPE",
  "parameters": [
    "Accept"
  ],
  "reason": "Not Acceptable"
}
{
  "detail": "The requested API version is not supported. Supported versions: 2026-09-20-preview.",
  "error": 406,
  "errorCode": "UNSUPPORTED_API_VERSION",
  "parameters": [
    "Accept"
  ],
  "reason": "Not Acceptable"
}
Response examples (406) 
{
  "detail": "This operation is not available in API version 2026-09-20-preview.",
  "error": 406,
  "errorCode": "OPERATION_NOT_IN_API_VERSION",
  "parameters": [
    "Accept"
  ],
  "reason": "Not Acceptable"
}
Response examples (200) 
# Headers
X-Session-ID: string

# Payload
{
  "error": "string",
  "error_code": "string",
  "execution_id": "string",
  "response": "string",
  "status": "string",
  "success": true,
  "suspend_context": {},
  "suspend_reason": "string"
}
Response examples (200) 
# Headers
X-Session-ID: string

# Payload
{
  "error": "string",
  "error_code": "string",
  "execution_id": "string",
  "response": "string",
  "status": "string",
  "success": true,
  "suspend_context": {},
  "suspend_reason": "string"
}
Response examples (400) 
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (400) 
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (401) 
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (401) 
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (409) 
{
  "blocking_execution_id": "string",
  "blocking_status": "string",
  "code": "string",
  "error": "string",
  "last_activity_at": "string"
}
Response examples (409) 
{
  "blocking_execution_id": "string",
  "blocking_status": "string",
  "code": "string",
  "error": "string",
  "last_activity_at": "string"
}
Response examples (422) 
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (422) 
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (429) 
# Headers
Retry-After: string

# Payload
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (429) 
# Headers
Retry-After: string

# Payload
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (500) 
{
  "error": "string",
  "error_code": "string",
  "execution_id": "string",
  "response": "string",
  "status": "string",
  "success": true,
  "suspend_context": {},
  "suspend_reason": "string"
}
{
  "boot_id": "string",
  "code": "string",
  "component": "string",
  "error": "string",
  "execution_id": "string",
  "sandbox": "string",
  "source": "string",
  "success": true
}
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (500) 
{
  "error": "string",
  "error_code": "string",
  "execution_id": "string",
  "response": "string",
  "status": "string",
  "success": true,
  "suspend_context": {},
  "suspend_reason": "string"
}
{
  "boot_id": "string",
  "code": "string",
  "component": "string",
  "error": "string",
  "execution_id": "string",
  "sandbox": "string",
  "source": "string",
  "success": true
}
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (503) 
# Headers
Retry-After: string

# Payload
{
  "boot_id": "string",
  "code": "string",
  "component": "string",
  "error": "string",
  "execution_id": "string",
  "sandbox": "string",
  "source": "string",
  "success": true
}
# Headers
Retry-After: string

# Payload
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (503) 
# Headers
Retry-After: string

# Payload
{
  "boot_id": "string",
  "code": "string",
  "component": "string",
  "error": "string",
  "execution_id": "string",
  "sandbox": "string",
  "source": "string",
  "success": true
}
# Headers
Retry-After: string

# Payload
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (504) 
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (504) 
{
  "code": "string",
  "error": "string",
  "success": true
}