PATCH /api/v1/projects/{id}/workspaces/{workspace_id}
Bearer auth

Partially updates a workspace. The project scope is carried by the route id path parameter. Field-only patches return 204; a status-only patch (pause/resume) is mutually exclusive with other fields and returns 200 with ECP's app body (including any warnings).

Path parameters

  • id string Required

    Project ID

  • workspace_id string Required

    Workspace ID

application/json

Body Required

Fields to update

  • agent_card object
    Hide agent_card attributes Show agent_card attributes object
    • a2a_allowed_callers array[string]

      A2AAllowedCallers restricts which workspace IDs may invoke this agent via A2A. An empty list means any caller is permitted.

    • a2a_enabled boolean

      A2AEnabled controls whether this agent is discoverable for A2A calls.

    • capabilities array[string]
    • input_modes array[string]

      InputModes lists MIME types the agent accepts (e.g. "text/plain", "application/json").

    • output_modes array[string]

      OutputModes lists MIME types the agent can produce.

    • skills array[object]

      Skills advertises discrete tasks the agent can perform.

      Hide skills attributes Show skills attributes object
      • description string
      • example_input string
      • example_output string
      • name string
    • summary string
  • auto_deploy boolean

    AutoDeploy is an app-level ECP field (not persisted in the gateway DB); forwarded verbatim to ECP's app PATCH.

  • description string
  • features object
    Hide features attributes Show features attributes object
    • guardrails boolean
    • memory boolean
    • playground boolean

      Playground reports whether playground UI is provisioned for the workspace (nil/true = provisioned, today's behavior). When false, callers use the invoke API directly.

    • use_custom_parser boolean

      UseCustomParser, when true, makes the Gateway emit only the agent's output-parser custom events on the invoke stream (dropping platform frames). Persisted from agent.yaml features at agentengine init.

  • framework string
  • gitops object
    Hide gitops attributes Show gitops attributes object
    • branch string
    • connection_ref string
    • manifest_path string
    • provider string
    • repo_url string
  • name string
  • release_mode string

    ReleaseMode is an app-level ECP field (not persisted in the gateway DB); forwarded verbatim to ECP's app PATCH. Controls webhook-triggered builds only — API-triggered releases are available in every mode.

  • status string

    Status is a pause/resume signal ("active" | "paused"). The gateway does not persist it locally; the handler forwards a status-only patch straight to ECP, which runs pause-teardown / resume-redeploy.

  • subdirectory string
  • workspace_name string

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

    Returned for status-only patches; proxied from ECP.

    Hide response attributes Show response attributes object
    • app_id string
    • org_id string
    • project_id string
    • status string
    • warnings array[string]
    Hide response attributes Show response attributes object
    • app_id string
    • org_id string
    • project_id string
    • status string
    • warnings array[string]
  • 204

    Returned for field-update patches.

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

    Not Found

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

    Request Entity Too Large

    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

    Internal Server Error

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

    ECP transport or pause-teardown failure.

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

    Service Unavailable

    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
PATCH /api/v1/projects/{id}/workspaces/{workspace_id} 
curl \
 --request PATCH 'https://agentengine.mongodb.com/api/v1/projects/{id}/workspaces/{workspace_id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{
  "agent_card": {
    "a2a_allowed_callers": [
      "string"
    ],
    "a2a_enabled": true,
    "capabilities": [
      "string"
    ],
    "input_modes": [
      "string"
    ],
    "output_modes": [
      "string"
    ],
    "skills": [
      {
        "description": "string",
        "example_input": "string",
        "example_output": "string",
        "name": "string"
      }
    ],
    "summary": "string"
  },
  "auto_deploy": true,
  "description": "string",
  "features": {
    "guardrails": true,
    "memory": true,
    "playground": true,
    "use_custom_parser": true
  },
  "framework": "string",
  "gitops": {
    "branch": "string",
    "connection_ref": "string",
    "manifest_path": "string",
    "provider": "string",
    "repo_url": "string"
  },
  "name": "string",
  "release_mode": "string",
  "status": "string",
  "subdirectory": "string",
  "workspace_name": "string"
}'
Request examples 
{
  "agent_card": {
    "a2a_allowed_callers": [
      "string"
    ],
    "a2a_enabled": true,
    "capabilities": [
      "string"
    ],
    "input_modes": [
      "string"
    ],
    "output_modes": [
      "string"
    ],
    "skills": [
      {
        "description": "string",
        "example_input": "string",
        "example_output": "string",
        "name": "string"
      }
    ],
    "summary": "string"
  },
  "auto_deploy": true,
  "description": "string",
  "features": {
    "guardrails": true,
    "memory": true,
    "playground": true,
    "use_custom_parser": true
  },
  "framework": "string",
  "gitops": {
    "branch": "string",
    "connection_ref": "string",
    "manifest_path": "string",
    "provider": "string",
    "repo_url": "string"
  },
  "name": "string",
  "release_mode": "string",
  "status": "string",
  "subdirectory": "string",
  "workspace_name": "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) 
{
  "app_id": "string",
  "org_id": "string",
  "project_id": "string",
  "status": "active",
  "warnings": [
    "string"
  ]
}
Response examples (200) 
{
  "app_id": "string",
  "org_id": "string",
  "project_id": "string",
  "status": "active",
  "warnings": [
    "string"
  ]
}
Response examples (400) 
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (400) 
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (404) 
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (404) 
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (413) 
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (413) 
{
  "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) 
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (500) 
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (502) 
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (502) 
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (503) 
# Headers
Retry-After: string

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

# Payload
{
  "code": "string",
  "error": "string",
  "success": true
}