# Wabee Agent Core API


    Wabee Agent Core API enables developers to interact with an AI agent in a custom, secure and flexible manner through REST API calls.

    One can build applications to interact with the agent API to complete a task using any of the `Agents` endpoints which allow for both text streaming and direct JSON response.
    The `Memory` endpoints are useful for managing the agent memory programatically.
    Moreover, the `Metrics` endpoints provide an interface for monitoring the underlying Agent in terms of latency, health, token consumption and much more.
    

Wabee Agent Core API

Version: v1
License: Proprietary License

## Servers

Production server
```
https://<your_agent_uri>.wabee.ai
```

## Security

### APIKeyHeader

Your API key here

Type: apiKey
In: header
Name: x-wabee-access

## Download OpenAPI description

[Wabee Agent Core API](https://api.docs.wabee.ai/_bundle/openapi.yaml)

## Agent

Endpoints for interacting with the AI agent

### Demand from the agent and get a full response when it finishes

 - [POST /core/v1/chain](https://api.docs.wabee.ai/openapi/agent/chain_core_v1_chain_post.md): Executes a chain of AI-powered reasoning and actions to respond to a given query or task.
    
    The agent leverages its configured tools and knowledge to:
    - Analyze the input query
    - Plan necessary steps
    - Execute relevant tools
    - Synthesize a comprehensive response
    
    ## Image Support
    Include images in your request using the images field:
    - Base64 Format: Set type="base64" with base64-encoded image data
    - File Path: Set type="file_path" with path to existing image
    
    Maximum 5 images per request. Invalid images will trigger a 400 response.
    
    ## Authentication
    Requires API key via x-wabee-access header.
    
    ## Session Management
    Use session-id header to maintain conversation context across requests.

### Demand from the agent and get a streamed response until it finishes

 - [POST /core/v1/chain_streaming](https://api.docs.wabee.ai/openapi/agent/chain_core_v1_chain_streaming_post.md): Requests Wabee AI Agent to answer a question regarding the mission that the agent was given to upon creation.
    
    The agent can make use of any of the available tools along with its own reasoning to complete the given task, depending on its complexity, the response might take some time to be returned to the user.
    
    Note: session_id field on request body is kept for compatibility purposes, it will be overwritten with the header value during request processing
    Note: stream filed on request body is kept for compatibility purposes, it will be ignored during request processing
    Note: this is pretty much the same as in /chain, the only difference is that this endpoint returns a streaming response instead of a JSON object
    Note: the id on the streamming response refers to the current request
    Note: the streamming response ends when finish_reason is different than null
    Note: All headers starting with stix will be sent as context for tools.

### Demand from the agent and get a fast ack response, use callback to receive the completion response

 - [POST /core/v1/chain_async](https://api.docs.wabee.ai/openapi/agent/async_chain_core_v1_chain_async_post.md): Requests Wabee AI Agent to answer a question asynchronously.
    If a callback_url is provided, the agent will send the response to the given URL.
    
    The agent can make use of any of the available tools along with its own reasoning to complete the given task, depending on its complexity, the response might take some time to be returned to the user.
    
    Note: session_id field on request body is kept for compatibility purposes, it will be overwritten with the header value during request processing
    Note: stream filed on request body is kept for compatibility purposes, it will be ignored during request processing

### Get agent configuration

 - [GET /core/v1/agent/config](https://api.docs.wabee.ai/openapi/agent/get_agent_config_core_v1_agent_config_get.md): Returns the current agent configuration.
    
    This endpoint allows you to retrieve the complete agent configuration 
    that is currently loaded in memory. This includes all settings such as:
    - Agent description and metadata
    - LLM configurations
    - Tool definitions
    - Memory settings
    - Other agent-specific parameters
    
    The configuration returned is the actual configuration being used by the agent,
    including any updates that have been applied via the PUT /agent/config endpoint.

### Update agent configuration

 - [PUT /core/v1/agent/config](https://api.docs.wabee.ai/openapi/agent/update_agent_config_core_v1_agent_config_put.md): Updates the agent configuration dynamically without restarting the service.
    
    This endpoint allows you to:
    - Partially update the agent configuration (merges with existing config)
    - Update complete configuration sections or individual fields
    - Validate configuration before applying (using validate_only=true)
    - Automatically trigger agent re-initialization with new config
    
    The provided configuration is merged with the existing configuration, so you only 
    need to specify the fields you want to change. The configuration is written to the 
    mounted volume and the agent is re-initialized.
    
    ## Important Notes:
    - Only specify the fields you want to update - they will be merged with existing config
    - Nested objects are deep-merged (e.g., updating llms.primary.model preserves other llm settings)
    - The JSON file on the mounted volume will be updated with the merged configuration
    - The agent will be re-initialized, which may take a few seconds
    - In-flight requests will complete with the old configuration
    - New requests will use the updated configuration
    - A backup of the previous configuration is automatically created
    
    ## Example Partial Updates:
    
    Update just the agent description:
    json
    {
        "configuration": {
            "description": "Updated agent description"
        },
        "validate_only": false
    }
    
    
    Update a specific LLM model:
    json
    {
        "configuration": {
            "llms": {
                "primary": {
                    "model": "gpt-4-turbo"
                }
            }
        },
        "validate_only": false
    }
    
    
    Add a new tool to the existing tools list:
    json
    {
        "configuration": {
            "tools": [
                {
                    "name": "new_tool",
                    "config": {...}
                }
            ]
        },
        "validate_only": false
    }
    
    
    In-memory only update (for read-only config files):
    json
    {
        "configuration": {
            "max_execution_time": 2000
        },
        "validate_only": false,
        "in_memory_only": true
    }

### Get wabee AI agent metadata

 - [GET /core/v1/metadata](https://api.docs.wabee.ai/openapi/agent/get_metadata_core_v1_metadata_get.md): Returns metadata information about the agent configuration, including its description,
    capabilities and conversation starters.

### Share an artifact generated by the agent

 - [POST /core/v1/share_agent_artifact](https://api.docs.wabee.ai/openapi/agent/share_agent_artifact_core_v1_share_agent_artifact_post.md): Copies a file artifact generated by the agent to a shared location.
    
    This endpoint:
    1. Retrieves the session state using the provided session ID
    2. Gets the specified message by its index in the messages array
    3. Retrieves the generated_artifacts field from the message response_metadata
    4. Copies the file at the specified artifact index to /tmp/share
    
    Returns the path to the copied file or an error if the file cannot be found/copied.

### Generate a downloadable link for an artifact

 - [GET /core/v1/download_artifact/{message_index}/{artifact_index}](https://api.docs.wabee.ai/openapi/agent/download_artifact_core_v1_download_artifact__message_index___artifact_index__get.md): Generates a downloadable link for a file artifact created by the agent.
    
    This endpoint:
    1. Retrieves the session state using the provided session ID (from the 'session-id' header)
    2. Gets the specified message by its index in the messages array
    3. Retrieves the generated_artifacts field from the message response_metadata
    4. Generates a presigned URL for the file at the specified artifact index
    
    Returns the presigned URL that can be used to download the file directly.

## Observability

Endpoints for monitoring agent performance and logs

### Get agent metrics

 - [GET /core/v1/metrics](https://api.docs.wabee.ai/openapi/observability/get_metrics_core_v1_metrics_get.md): Returns quantitative information about agent runs for monitoring. The following metrics are provided:
    
    - status_value_counts (histogram)
    - total_requests
    - total_errors
    - total_tokens
    - mean_tokens
    - mean_latency
    - max_latency
    - min_latency
    - total_prompt_tokens
    - mean_prompt_tokens
    - total_completion_tokens
    - mean_completion_tokens

### Get agent logs

 - [GET /core/v1/logs](https://api.docs.wabee.ai/openapi/observability/get_logs_core_v1_logs_get.md): Returns run execution logs in stringify format. The logs contain the following fields:
    
    - name: run name
    - id: run unique identifier
    - model: model name
    - error: run error if exists, else null
    - status: run status
    - latency: run latency
    - end_time: terminated run timestamp
    - completion_tokens: number of tokens returned by the model when the run is finished
    - total_tokens: total number of tokens associated with the run
    
    The results are paginated. Use offset and limit parameters to navigate through pages.

### Health check endpoint

 - [GET /health](https://api.docs.wabee.ai/openapi/observability/health_health_get.md): Returns the health status of the API

## Sessions

Endpoints for managing agent sessions

### Get the session data

 - [GET /core/v1/sessions/{session_id}](https://api.docs.wabee.ai/openapi/sessions/get_session_core_v1_sessions__session_id__get.md): Retrieves the complete conversation history and metadata for a specific session.
    
    The session data includes:
    - All messages exchanged between user and AI
    - Timestamps for each message
    - Additional context like reasoning steps for AI responses
    - Session metadata
    
    Each message contains:
    - role: Either 'human' or 'ai'
    - content: The actual message text
    - timestamp: When the message was sent
    - additional_context: Extra information like reasoning steps (for AI messages)

### List the sessions

 - [GET /core/v1/sessions](https://api.docs.wabee.ai/openapi/sessions/list_sessions_core_v1_sessions_get.md): Returns a paginated list of all available chat sessions.
    
    The response includes:
    - List of session summaries
    - Pagination information
    - Total count of returned sessions
    
    Each session summary contains:
    - session_id: Unique identifier for the session
    - checkpoint_id: Internal reference ID
    - short_name: Brief description based on first message
    
    Use the query parameters to navigate through pages:
    - before: Get sessions before this session ID
    - limit: Number of sessions per page (1-50)
    
    Sessions are ordered by most recent first.
    Empty sessions (no messages) are automatically filtered out.

## Sub-Agents

Endpoints for managing sub-agents

### List all sub-agents

 - [GET /core/v1/chain/sub_agents](https://api.docs.wabee.ai/openapi/sub-agents/list_sub_agents_core_v1_chain_sub_agents_get.md): Lists all sub-agents that have been created by the parent agent.

### Create a new sub-agent

 - [POST /core/v1/chain/sub_agents](https://api.docs.wabee.ai/openapi/sub-agents/create_sub_agent_core_v1_chain_sub_agents_post.md): Creates a new specialized sub-agent that can handle specific tasks.
    The sub-agent will have access to the specified tools and can be assigned tasks.

### Get a sub-agent's status

 - [GET /core/v1/chain/sub_agents/{sub_agent_id}](https://api.docs.wabee.ai/openapi/sub-agents/get_sub_agent_core_v1_chain_sub_agents__sub_agent_id__get.md): Retrieves information about a specific sub-agent, including its status and basic information.

### Terminate a sub-agent

 - [DELETE /core/v1/chain/sub_agents/{sub_agent_id}](https://api.docs.wabee.ai/openapi/sub-agents/terminate_sub_agent_core_v1_chain_sub_agents__sub_agent_id__delete.md): Terminates a specific sub-agent and cleans up its resources.

## Tool

Endpoints for managing tools

### List all available tools

 - [GET /core/v1/tools](https://api.docs.wabee.ai/openapi/tool/list_tools_core_v1_tools_get.md): Returns a list of all available tools that the agent has access to.

    Each tool entry includes:
    - Name: Unique identifier for the tool
    - Description: What the tool does and how it can be used
    - Status: Current initialization status (ready, initializing, error)
    - Schema: JSON schema defining the input parameters for the tool

    Use this endpoint to discover available tools and their required parameters
    before using the /tool/execute endpoint.

    ## Authentication
    Requires API key via x-wabee-access header.

### Execute a specific tool directly

 - [POST /core/v1/tool/execute](https://api.docs.wabee.ai/openapi/tool/execute_tool_core_v1_tool_execute_post.md): This endpoint allows direct execution of a specific tool with given parameters.

    The tool is executed outside the normal agent conversation flow, allowing users to:
    - Invoke tools programmatically
    - Test tool functionality independently
    - Access tool capabilities without engaging the full agent

    Each tool has different input parameters. Refer to tool documentation for specific input schemas.

    ## Authentication
    Requires API key via x-wabee-access header.

    ## Example Tool Inputs

    Web Search:
    json
    {
        "tool_name": "web_search",
        "tool_input": {
            "query": "Latest market trends in AI"
        }
    }
    

    CSV Search:
    json
    {
        "tool_name": "csv_search",
        "tool_input": {
            "file_path": "data/sales.csv",
            "query": "Find total sales in Q1"
        }
    }