---
title: "Query document(s) with an AI agent (synchronous)"
method: POST
path: "/document/agent"
tags: ["Usage"]
---

# Query document(s) with an AI agent (synchronous)

`POST /document/agent`

Run the full document agent against one or more indexed PDFs or documents. The agent uses tools (search, read sections, read pages) to research the document(s) and produce a comprehensive answer with citations. Supports optional structured output via json_schema.

**This endpoint is synchronous and holds the HTTP connection for the entire agent run (typically 1-10 minutes).** For production workloads or anything that may run longer, use POST /document/agent/jobs instead — it returns a job_id immediately and lets you poll or stream results without an HTTP connection limit.

## Request body

- DocumentQueryRequest — Request for the v2 document/agent endpoint.
  - `source_id` string, nullable — Data source ID of a single indexed document
  - `source_ids` string[], nullable — List of data source IDs for multi-document queries (max 50)
  - `query` string, required — Question to ask about the document(s)
  - `json_schema` object, nullable — JSON Schema for structured output
  - `model` string — Model to use (claude-opus-4-7, claude-sonnet-4-5-20250929, etc.)
  - `thinking_enabled` boolean — Enable extended thinking
  - `thinking_budget` integer — Token budget for thinking (ignored for adaptive models like Opus 4.7)
  - `stream` boolean — Stream response as SSE events

## Response `200`

Successful Response

- DocumentQueryResponse — Response from the v2 document/agent endpoint.
  - `answer` string, required
  - `citations` DocumentCitation[]
    - `content` string, required
    - `page_number` integer, nullable
    - `section_id` string, nullable
    - `section_title` string, nullable
    - `section_path` string[], nullable
    - `tool_source` string, required
    - `source_id` string, nullable
    - `source_name` string, nullable
  - `structured_output` unknown
  - `model` string, required
  - `usage` object, nullable

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/trynia/apis/nia-ai-api.md) · [All operations](https://skmtc.net/trynia/apis/nia-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/trynia/nia-ai-api/versions/d216ffc3efb6/schema)