{
  "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"
                  }
                },
                "conversational_agent_with_file": {
                  "summary": "Conversational agent with file",
                  "description": "Send `message` as a string and attach files via the top-level `files` array (`source.bytes` is base64). Limits: 5 files, 2MB each, 10MB total. Formats: pdf, csv, txt, docx, xlsx, png, jpg, jpeg.",
                  "value": {
                    "deployment_id": "6b392a3c-9c6e-4f09-8b55-177d7667d7ec",
                    "message": "Summarize the attached report.",
                    "files": [
                      {
                        "document": {
                          "name": "report.pdf",
                          "format": "pdf",
                          "source": {
                            "bytes": "JVBERi0xLjQKJ... (base64-encoded file content)"
                          }
                        }
                      }
                    ]
                  }
                },
                "structured_agent_with_file": {
                  "summary": "Structured agent with file",
                  "description": "`message` is a JSON object matching the agent's input schema; attach files via the top-level `files` array. Limits: 5 files, 2MB each, 10MB total. Bytes are scanned and converted server-side, never sent to the model as text.",
                  "value": {
                    "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                    "message": {
                      "query": "Extract the line items from this invoice."
                    },
                    "files": [
                      {
                        "image": {
                          "name": "invoice.png",
                          "format": "png",
                          "source": {
                            "bytes": "iVBORw0KGgoAAAANSU... (base64-encoded file content)"
                          }
                        }
                      }
                    ]
                  }
                },
                "structured_agent_file_in_message": {
                  "summary": "File inside structured agent message",
                  "description": "If the agent's input schema declares a `files` field, embed the `files` array inside `message` (same entry shape). The server scans the bytes, then clears `source.bytes` before the model sees the message so the blob never consumes tokens.",
                  "value": {
                    "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                    "message": {
                      "query": "Compare these two documents and list the differences.",
                      "files": [
                        {
                          "document": {
                            "name": "contract_v1.docx",
                            "format": "docx",
                            "source": {
                              "bytes": "UEsDBBQABgAIAAAAIQ... (base64-encoded file content)"
                            }
                          }
                        },
                        {
                          "document": {
                            "name": "contract_v2.docx",
                            "format": "docx",
                            "source": {
                              "bytes": "UEsDBBQABgAIAAAAIQ... (base64-encoded file content)"
                            }
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "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"
          },
          "files": {
            "anyOf": [
              {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/FileUpload"
                }
              },
              {
                "type": "null"
              }
            ],
            "title": "Files",
            "description": "Optional file uploads (5 files, 2MB each, 10MB total). Attach at the top level, or embed inside `message` for structured agents whose input schema declares a `files` field."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "message"
        ],
        "title": "ExternalSessionInvokeRequest",
        "description": "Request body for POST /api/v1/agent-garden-runtime/execute/session (external API)."
      },
      "FileSource": {
        "properties": {
          "bytes": {
            "type": "string",
            "title": "Bytes",
            "description": "Base64-encoded file content. Decoded size must be non-empty and at most 2MB."
          }
        },
        "type": "object",
        "required": [
          "bytes"
        ],
        "title": "FileSource",
        "description": "File source containing the base64-encoded file data."
      },
      "DocumentUpload": {
        "properties": {
          "name": {
            "type": "string",
            "title": "Name",
            "description": "Document filename"
          },
          "format": {
            "type": "string",
            "enum": [
              "pdf",
              "csv",
              "txt",
              "docx",
              "xlsx"
            ],
            "title": "Format",
            "description": "Document format. The MIME (Multipurpose Internet Mail Extensions) type is derived server-side and validated against the actual file content."
          },
          "source": {
            "$ref": "#/components/schemas/FileSource",
            "description": "Document source containing the base64-encoded file content"
          }
        },
        "type": "object",
        "required": [
          "name",
          "format",
          "source"
        ],
        "title": "DocumentUpload",
        "description": "Document upload."
      },
      "ImageUpload": {
        "properties": {
          "name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Name",
            "description": "Image filename"
          },
          "format": {
            "type": "string",
            "enum": [
              "png",
              "jpg",
              "jpeg"
            ],
            "title": "Format",
            "description": "Image format. The MIME type is derived server-side and validated against the actual file content."
          },
          "source": {
            "$ref": "#/components/schemas/FileSource",
            "description": "Image source containing the base64-encoded file content"
          }
        },
        "type": "object",
        "required": [
          "format",
          "source"
        ],
        "title": "ImageUpload",
        "description": "Image upload."
      },
      "FileUpload": {
        "properties": {
          "document": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/DocumentUpload"
              },
              {
                "type": "null"
              }
            ],
            "description": "Document upload data. Provide exactly one of `document` or `image`."
          },
          "image": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ImageUpload"
              },
              {
                "type": "null"
              }
            ],
            "description": "Image upload data. Provide exactly one of `document` or `image`."
          }
        },
        "type": "object",
        "title": "FileUpload",
        "description": "File upload. Must contain exactly one of `document` or `image`."
      },
      "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 REGION)",
      "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 REGION)",
      "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 REGION)",
      "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 REGION)",
      "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 (UK Platform)",
      "variables": {
        "accountId": {
          "default": "your-account-id",
          "description": "Your Boomi account ID."
        }
      }
    }
  ]
}