{
  "openapi": "3.1.0",
  "info": {
    "title": "Boomi Agent Garden \u2014 Execute API",
    "description": "The Boomi Agent Garden Execute API runs your deployed AI agents. Send a message to an agent (by deployment or agent id) and receive its reply \u2014 conversational agents stream the response as Server-Sent Events, while structured agents return a single JSON object. Continue a multi-turn conversation by passing the session id returned on the first call.\n\n**Authentication:** every request requires either a Boomi Platform JWT (Bearer token) or a Boomi Platform API Key (HTTP Basic \u2014 username `BOOMI_TOKEN.<email>`, password = token value). See the security schemes below.\n",
    "contact": {
      "name": "Customer Support",
      "url": "https://community.boomi.com/s/support",
      "email": "support@boomi.com"
    },
    "version": "1.0.0"
  },
  "paths": {
    "/session": {
      "post": {
        "tags": [
          "Session"
        ],
        "summary": "Invoke an agent session",
        "description": "Send a message to a deployed agent and receive its reply. Identify the agent by `deployment_id`. Omit `session_id` to start a new conversation, or pass the `session_id` returned on a previous call to continue an existing one.\n\n**Required privileges:** `AGENT_GARDEN_ACCESS`, `AGENT_VIEW`, `AGENT_INTERACT`.",
        "operationId": "invoke_session",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExternalSessionInvokeRequest"
              },
              "examples": {
                "new_conversation": {
                  "summary": "Start a new conversation",
                  "description": "Omit session_id to begin a fresh session, provide deployment_id.",
                  "value": {
                    "deployment_id": "6b392a3c-9c6e-4f09-8b55-177d7667d7ec",
                    "message": "Hello, how can you help me?"
                  }
                },
                "continue_session": {
                  "summary": "Continue an existing session",
                  "description": "Pass the session_id returned from a previous response to continue the conversation.",
                  "value": {
                    "deployment_id": "2c552c50-e26b-47a1-a9a7-1a4a08692ba5",
                    "message": "What did I ask before?",
                    "session_id": "01KSFE6WT8G0SHSTCRWAC28WN8"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The response format depends on the agent type. Conversational agents stream the reply as Server-Sent Events (SSE): the stream opens with a `start` event, may emit `progress_notification` events during processing, delivers the reply in a `message` event, and closes with a `done` event. Structured agents return a single JSON object containing the agent's response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessInvokeResponse"
                },
                "example": {
                  "success": true,
                  "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                  "session_id": "01KSFE6WT8G0SHSTCRWAC28WN8",
                  "data": {
                    "response": "I'm here to help. How can I assist you today?"
                  }
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                },
                "example": "event: start\ndata: {\"session_id\": \"01KSFE6WT8G0SHSTCRWAC28WN8\", \"agent_id\": \"ddccf1ad-c01f-4d13-b8f2-98730cc204a2\", \"user_id\": \"user-LSRW9G\", \"created_at\": \"1779708427.473681\"}\n\nevent: progress_notification\ndata: {\"type\": \"THINKING\", \"content\": \"Thinking\"}\n\nevent: progress_notification\ndata: {\"type\": \"GENERATING_TITLE\", \"content\": \"Customer Greeting\"}\n\nevent: progress_notification\ndata: {\"type\": \"THINKING\", \"content\": \"Responding\"}\n\nevent: message\ndata: {\"id\": \"01KSFE7C6PRSVTSSSZWJVC2RQ1\", \"session_id\": \"01KSFE6WT8G0SHSTCRWAC28WN8\", \"role\": \"agent\", \"content\": \"Hello! I'm your Enterprise O2C Agent, here to help you with your order-to-customer needs.\"}\n\nevent: [DONE]\ndata: null"
              }
            }
          },
          "401": {
            "description": "Authentication failed \u2014 missing or malformed bearer token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": "We were unable to verify your identity. Please ensure you are using a valid authentication token and try again."
                }
              }
            }
          },
          "403": {
            "description": "Missing required privileges, or the agent is not available on this runtime.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": "You do not have permission to perform this action. Please contact your administrator if you believe this is an error."
                }
              }
            }
          },
          "422": {
            "description": "Request validation failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": "We were unable to process your request. Please review the request details and try again."
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ErrorResponse": {
        "properties": {
          "success": {
            "type": "boolean",
            "title": "Success",
            "default": false
          },
          "error": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Error"
          }
        },
        "type": "object",
        "title": "ErrorResponse"
      },
      "ExternalSessionInvokeRequest": {
        "properties": {
          "deployment_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Deployment Id",
            "description": "Deployment identifier"
          },
          "agent_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Agent Id",
            "description": "Agent identifier"
          },
          "message": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "additionalProperties": true,
                "type": "object"
              }
            ],
            "title": "Message",
            "description": "User message"
          },
          "session_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Session Id",
            "description": "Existing session to continue"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "message"
        ],
        "title": "ExternalSessionInvokeRequest",
        "description": "Request body for POST /api/v1/agent-garden-runtime/execute/session (external API)."
      },
      "SuccessInvokeResponse": {
        "properties": {
          "success": {
            "type": "boolean",
            "title": "Success",
            "default": true
          },
          "agent_id": {
            "type": "string",
            "title": "Agent Id"
          },
          "session_id": {
            "type": "string",
            "title": "Session Id"
          },
          "data": {
            "title": "Data"
          }
        },
        "type": "object",
        "required": [
          "agent_id",
          "session_id",
          "data"
        ],
        "title": "SuccessInvokeResponse"
      }
    },
    "securitySchemes": {
      "Boomi-Platform-JWT": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Boomi Platform JWT authentication. Pass a valid JWT token in the Authorization header as: Bearer <token>"
      },
      "Boomi-Platform-API-Key": {
        "type": "http",
        "scheme": "basic",
        "description": "Boomi Platform API Token authentication using HTTP Basic. Username: BOOMI_TOKEN.<your_email> (e.g. BOOMI_TOKEN.user@example.com). Password: your API token value."
      }
    }
  },
  "tags": [
    {
      "name": "Session",
      "description": "Invoke a deployed agent and exchange messages in a session."
    }
  ],
  "security": [
    {
      "Boomi-Platform-JWT": []
    },
    {
      "Boomi-Platform-API-Key": []
    }
  ],
  "servers": [
    {
      "url": "https://c01-usa-east.ai-agent-garden.boomi.com/execute/api/v1/{accountId}",
      "description": "Agent Garden Execute API (US)",
      "variables": {
        "accountId": {
          "default": "your-account-id",
          "description": "Your Boomi account ID."
        }
      }
    },
    {
      "url": "https://c01-aus.ai-agent-garden.boomi.com/execute/api/v1/{accountId}",
      "description": "Agent Garden Execute API (ANZ)",
      "variables": {
        "accountId": {
          "default": "your-account-id",
          "description": "Your Boomi account ID."
        }
      }
    },
    {
      "url": "https://c01-jp.ai-agent-garden.boomi.com/execute/api/v1/{accountId}",
      "description": "Agent Garden Execute API (JP)",
      "variables": {
        "accountId": {
          "default": "your-account-id",
          "description": "Your Boomi account ID."
        }
      }
    },
    {
      "url": "https://c01-gbr.ai-agent-garden.boomi.com/execute/api/v1/{accountId}",
      "description": "Agent Garden Execute API (GBR)",
      "variables": {
        "accountId": {
          "default": "your-account-id",
          "description": "Your Boomi account ID."
        }
      }
    },
    {
      "url": "https://c01-gbr.ai-agent-garden.gb.boomi.com/execute/api/v1/{accountId}",
      "description": "Agent Garden Execute API (GBR)",
      "variables": {
        "accountId": {
          "default": "your-account-id",
          "description": "Your Boomi account ID."
        }
      }
    }
  ]
}