Query Agent

POST /api/v1/agent/query

The Query endpoint is the primary interface for interacting with Statement's AI agent. It allows you to submit natural language questions, business queries, and analytical requests against the data sources connected to your project.

The endpoint accepts a conversation history in chat format, routes the latest user message through the Statement agent router, and returns one or more generated responses.

The response format intentionally follows the OpenAI Chat Completions structure to simplify integration with existing AI clients and SDKs.

How It Works

1. Your application sends a list of conversation messages.
2. The final message in the conversation must be a user message.
3. Statement analyzes the request and determines which connected services, data sources, and agents are relevant.
4. The selected agents retrieve and process the required information.
5. A generated response is returned along with token usage statistics and optional structured output.

Request Body

Parameters

Messages Format

The messages array represents the conversation context provided to the agent.

Each message contains:

The final message in the array must always be from the user, as this message is treated as the query to process.

Example

{
  "messages": [
    {
      "role": "user",
      "content": "What is my MRR?"
    }
  ]
}

Basic Query

Use a simple request when asking a standalone question.

{
  "messages": [
    {
      "role": "user",
      "content": "What is my MRR?"
    }
  ]
}

Scoped Query

You can limit agent routing to specific connected services using agent_scope.

This is useful when multiple integrations contain similar information and you want to control which data sources are used.

{
  "model": "statement",
  "agent_scope": ["stripe", "xero"],
  "messages": [
    {
      "role": "user",
      "content": "What is my MRR?"
    }
  ]
}

In this example, the agent will only consider data from the Stripe and Xero integrations.

Query With Conversation History

Previous conversation messages can be included to provide context.

{
  "messages": [
    {
      "role": "user",
      "content": "hello"
    },
    {
      "role": "assistant",
      "content": "Hi, how can I help?"
    },
    {
      "role": "user",
      "content": "Compare this month's revenue with last month."
    }
  ]
}

Including conversation history enables more natural follow-up questions and contextual responses.

Structured Output

For applications that require machine-readable responses, provide a response_schema.

When the generated output matches the schema, Statement returns both:

• A serialized JSON string inside choices[].message.content
• A parsed object inside choices[].structured

Example Request

{
  "messages": [
    {
      "role": "user",
      "content": "Analyze this: Revenue increased by 20%, expenses by 10%."
    }
  ],
  "response_schema": {
    "type": "object",
    "properties": {
      "summary": {
        "type": "string"
      },
      "financial_metrics": {
        "type": "object",
        "properties": {
          "revenue_growth": {
            "type": "number"
          },
          "expense_growth": {
            "type": "number"
          }
        },
        "required": [
          "revenue_growth",
          "expense_growth"
        ]
      },
      "risk_level": {
        "type": "string",
        "enum": ["low", "medium", "high"]
      }
    },
    "required": [
      "summary",
      "financial_metrics",
      "risk_level"
    ]
  }
}

Example Response

{
  "id": "5cccf684-6547-4e1c-8d32-daf4fcbf8c24",
  "object": "chat.completion",
  "model": "statement",
  "created": 1712345678,
  "usage": {
    "prompt_tokens": 48,
    "completion_tokens": 85,
    "total_tokens": 133,
    "input_tokens": 48,
    "output_tokens": 85
  },
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "{\"summary\":\"Healthy growth\",\"financial_metrics\":{\"revenue_growth\":20,\"expense_growth\":10},\"risk_level\":\"low\"}"
      },
      "structured": {
        "summary": "Healthy growth",
        "financial_metrics": {
          "revenue_growth": 20,
          "expense_growth": 10
        },
        "risk_level": "low"
      },
      "finish_reason": "stop"
    }
  ]
}

Response Fields

Top-Level Fields

Usage Object

Choice Object

Each entry in the choices array contains:

Notes

• The response format is intentionally compatible with OpenAI-style chat completion APIs.
• choices[].structured is only returned when the generated output successfully matches the requested schema.
• Token usage aliases (prompt_tokens / input_tokens and completion_tokens / output_tokens) are provided for compatibility across different client implementations.
• In rare cases, choices may be empty if no usable response can be generated from the upstream agents.
• Agent routing and service selection occur automatically unless restricted through agent_scope.