{
  "openapi": "3.1.0",
  "info": {
    "title": "Etlworks AI Agent API",
    "version": "9.9.9",
    "description": "The API for Simba, the Etlworks AI agent: call its tools directly, chat with it, or keep a\nmulti-turn session.\n\n**Base URL.** `https://app.etlworks.com/rest/v1/ai-agent/api`, or your own host on-premise.\n\n**Authentication.** The same bearer token as the platform API: an API key or a JWT. The agent acts\nwith the caller's permissions.\n\n**Errors.** Some failures return 200 with `{\"success\": false, \"error\": \"...\"}`, for example when an AI\nusage cap is exceeded. 403 means AI features are disabled for the tenant or user.\n\n**Streaming.** The `/stream` endpoints return Server-Sent Events. Each event is a JSON object with a\n`type`: `session`, `phase`, `tool_start`, `tool_end`, `token` and `usage`, then a final\n`end`, or `error` with a `code` and a `retryable` flag.\n\n**MCP.** The same tools are exposed over the Model Context Protocol at `POST /rest/v1/ai-agent/mcp`\n(JSON-RPC 2.0). See https://etlworks.com/dev/ai/mcp.html.\n\nChecked against the source of release 9.9.9.\n",
    "contact": {
      "name": "Etlworks support",
      "email": "support@etlworks.com",
      "url": "https://etlworks.com/dev/ai/"
    }
  },
  "externalDocs": {
    "description": "AI Agent API guide",
    "url": "https://etlworks.com/dev/ai/api-reference.html"
  },
  "servers": [
    {
      "url": "https://app.etlworks.com/rest/v1/ai-agent/api",
      "description": "Etlworks Cloud"
    },
    {
      "url": "https://{host}/rest/v1/ai-agent/api",
      "description": "On-premise",
      "variables": {
        "host": {
          "default": "etlworks.example.com"
        }
      }
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Tools",
      "description": "Call the agent's tools directly."
    },
    {
      "name": "Chat",
      "description": "Single-turn questions."
    },
    {
      "name": "Sessions",
      "description": "Multi-turn conversations."
    }
  ],
  "paths": {
    "/tools": {
      "get": {
        "operationId": "listTools",
        "summary": "List the agent's tools",
        "tags": [
          "Tools"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tools": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string"
                          },
                          "parameters": {
                            "type": "object",
                            "description": "JSON Schema for the tool's arguments.",
                            "additionalProperties": true
                          },
                          "agentic": {
                            "type": "boolean",
                            "description": "True for tools that run a multi-step agent loop."
                          }
                        }
                      }
                    },
                    "count": {
                      "type": "integer",
                      "format": "int32"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token."
          },
          "403": {
            "description": "AI features are disabled for this tenant or user."
          },
          "500": {
            "description": "Server error."
          }
        }
      }
    },
    "/tools/{toolName}/execute": {
      "post": {
        "operationId": "executeTool",
        "summary": "Call one tool directly",
        "tags": [
          "Tools"
        ],
        "description": "Runs a single tool with the given arguments, without the model in the loop.",
        "parameters": [
          {
            "name": "toolName",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "Arguments matching the tool's `parameters` schema.",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tool": {
                      "type": "string"
                    },
                    "result": {
                      "type": "string"
                    },
                    "success": {
                      "type": "boolean"
                    },
                    "error": {
                      "type": "string"
                    },
                    "available_tools": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Returned when the tool name is unknown."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token."
          },
          "403": {
            "description": "AI features are disabled for this tenant or user."
          },
          "500": {
            "description": "Server error."
          }
        }
      }
    },
    "/chat": {
      "post": {
        "operationId": "chat",
        "summary": "Ask the agent a question",
        "tags": [
          "Chat"
        ],
        "description": "Single turn. Returns a `session_id` you can continue with the sessions endpoints.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "message"
                ],
                "properties": {
                  "message": {
                    "type": "string",
                    "description": "What to ask."
                  },
                  "include_tools": {
                    "type": "boolean",
                    "description": "Let the agent call tools. Defaults to true."
                  },
                  "system_prompt": {
                    "type": "string",
                    "description": "Optional extra instructions."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "response": {
                      "type": "string",
                      "description": "The agent's answer, in Markdown."
                    },
                    "session_id": {
                      "type": "string"
                    },
                    "tools_used": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "usage": {
                      "type": "object",
                      "properties": {
                        "prompt_tokens": {
                          "type": "integer",
                          "format": "int32"
                        },
                        "completion_tokens": {
                          "type": "integer",
                          "format": "int32"
                        },
                        "model": {
                          "type": "string"
                        }
                      }
                    },
                    "success": {
                      "type": "boolean"
                    },
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token."
          },
          "403": {
            "description": "AI features are disabled for this tenant or user."
          },
          "500": {
            "description": "Server error."
          }
        }
      }
    },
    "/chat/stream": {
      "post": {
        "operationId": "chatStream",
        "summary": "Ask the agent a question, streamed",
        "tags": [
          "Chat"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "message"
                ],
                "properties": {
                  "message": {
                    "type": "string",
                    "description": "What to ask."
                  },
                  "include_tools": {
                    "type": "boolean",
                    "description": "Let the agent call tools. Defaults to true."
                  },
                  "system_prompt": {
                    "type": "string",
                    "description": "Optional extra instructions."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Server-Sent Events stream.",
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "`data: {json}` lines."
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token."
          },
          "403": {
            "description": "AI features are disabled for this tenant or user."
          },
          "500": {
            "description": "Server error."
          }
        }
      }
    },
    "/sessions": {
      "post": {
        "operationId": "createSession",
        "summary": "Start a session",
        "tags": [
          "Sessions"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "session_id": {
                      "type": "string"
                    },
                    "created": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token."
          },
          "403": {
            "description": "AI features are disabled for this tenant or user."
          },
          "500": {
            "description": "Server error."
          }
        }
      }
    },
    "/sessions/{sessionId}/chat": {
      "post": {
        "operationId": "sessionChat",
        "summary": "Send a message in a session",
        "tags": [
          "Sessions"
        ],
        "parameters": [
          {
            "name": "sessionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "message"
                ],
                "properties": {
                  "message": {
                    "type": "string",
                    "description": "What to ask."
                  },
                  "include_tools": {
                    "type": "boolean",
                    "description": "Let the agent call tools. Defaults to true."
                  },
                  "system_prompt": {
                    "type": "string",
                    "description": "Optional extra instructions."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "response": {
                      "type": "string",
                      "description": "The agent's answer, in Markdown."
                    },
                    "session_id": {
                      "type": "string"
                    },
                    "tools_used": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "usage": {
                      "type": "object",
                      "properties": {
                        "prompt_tokens": {
                          "type": "integer",
                          "format": "int32"
                        },
                        "completion_tokens": {
                          "type": "integer",
                          "format": "int32"
                        },
                        "model": {
                          "type": "string"
                        }
                      }
                    },
                    "success": {
                      "type": "boolean"
                    },
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token."
          },
          "403": {
            "description": "AI features are disabled for this tenant or user."
          },
          "404": {
            "description": "Session not found."
          },
          "500": {
            "description": "Server error."
          }
        }
      }
    },
    "/sessions/{sessionId}/chat/stream": {
      "post": {
        "operationId": "sessionChatStream",
        "summary": "Send a message in a session, streamed",
        "tags": [
          "Sessions"
        ],
        "parameters": [
          {
            "name": "sessionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "message"
                ],
                "properties": {
                  "message": {
                    "type": "string",
                    "description": "What to ask."
                  },
                  "include_tools": {
                    "type": "boolean",
                    "description": "Let the agent call tools. Defaults to true."
                  },
                  "system_prompt": {
                    "type": "string",
                    "description": "Optional extra instructions."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Server-Sent Events stream.",
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "`data: {json}` lines."
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token."
          },
          "403": {
            "description": "AI features are disabled for this tenant or user."
          },
          "404": {
            "description": "Session not found."
          },
          "500": {
            "description": "Server error."
          }
        }
      }
    },
    "/sessions/{sessionId}/messages": {
      "get": {
        "operationId": "listSessionMessages",
        "summary": "Messages in a session",
        "tags": [
          "Sessions"
        ],
        "description": "System and tool messages are left out.",
        "parameters": [
          {
            "name": "sessionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "role": {
                        "type": "string",
                        "enum": [
                          "user",
                          "assistant"
                        ]
                      },
                      "text": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token."
          },
          "403": {
            "description": "AI features are disabled for this tenant or user."
          },
          "404": {
            "description": "Session not found."
          },
          "500": {
            "description": "Server error."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "An Etlworks API key or JWT, sent as `Authorization: Bearer <token>`."
      }
    }
  }
}