canonical: https://jentic.com/apis/agentql.com/agentql-api

# AgentQL REST API

Jentic publishes the only available OpenAPI specification for AgentQL REST API, keeping it validated and agent-ready. The 1.0.0 surface is the slimmest production cut of AgentQL: three endpoints that cover web-page queries, document queries, and Tetra remote browser session creation. Each request takes a target (URL or document) plus an AgentQL query or natural-language prompt and returns parsed fields keyed by the query shape. Everything else - pagination, scheduling, dataset storage - is intentionally out of scope.

## For AI agents

Run a single AgentQL query against a web page or document and get structured fields back, or create a remote Chrome session for authenticated scraping.

## Scope

Does not handle proxy rotation, CAPTCHA solving, scheduled crawls, or dataset storage - use for one-off structured extraction from URLs and documents only.

## Capabilities

- Extract named fields from a public web page using AgentQL query syntax via POST /query-data
- Pull invoice numbers, totals, or contract terms from PDFs and images via POST /query-document
- Provision a Tetra remote Chrome session for sites that require login or interaction via POST /tetra/sessions
- Use natural-language prompts as an alternative to AgentQL syntax on either query endpoint

## Use cases

### One-Shot Web Page Query

Send a target URL and an AgentQL query to /query-data and receive a parsed JSON object matching the query's named fields. The agent skips HTML parsing, selector maintenance, and DOM traversal entirely. Best for occasional or low-volume extraction where a single request resolves the task.

Example prompt: POST /query-data with url='https://example.com/products' and query='{ products[] { name price sku } }' and write the result to a CSV

### Document Field Extraction

Pass a PDF or image URL with a prompt or AgentQL query to /query-document to extract invoice fields, contract clauses, or form values. The endpoint handles OCR and layout-agnostic field naming. Suitable for accounts-payable workflows or contract intake without per-template parsers.

Example prompt: POST /query-document with a PDF URL and the prompt 'extract supplier_name, invoice_number, total_amount, currency'

### Authenticated Scraping Setup

Create a Tetra browser session, drive it through a login flow with the returned session controls, then issue /query-data calls scoped to the session. Useful for SaaS dashboards or member-only content where direct GET requests fail.

Example prompt: POST /tetra/sessions, complete the login flow, then run a query-data call against the post-login analytics page

### Agent-Driven Field Discovery

Let a Jentic-connected agent iterate on AgentQL query shapes until the target page yields the fields it needs. The agent loads the /query-data schema once and adjusts the query string in subsequent calls without redeploying. This makes the v1 surface a clean default tool for ad-hoc scraping inside a multi-step plan.

Example prompt: Try three progressively more specific AgentQL queries against the same URL and pick the one that returns the most non-null fields

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /query-data | Query data from a web page |
| POST | /query-document | Query data from a PDF or image |
| POST | /tetra/sessions | Create a remote browser session |

## Key resources

- **Query** — Run AgentQL queries or natural-language prompts against URLs and documents
- **Browser Sessions** — Provision Tetra remote Chrome sessions for authenticated or interactive scraping

## Why Jentic

- **Setup:** Wiring the AgentQL REST API by hand means managing its X-API-Key header and coding calls that carry the target URL and AgentQL query in the body. Through Jentic you install once, import the AgentQL REST API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** AgentQL takes the target URL or document and query in the request body, so limit the agent to the operations it needs, such as extracting structured data from a page or document. You choose which operations are in the allowed set, so session creation is not included unless you add it.
- **Credential handling:** Your AgentQL API key is stored once, encrypted, by your own Jentic One instance and injected as the X-API-Key header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'extract a PDF invoice', and Jentic returns the matching query-data or query-document operation with its input schema, including the AgentQL query format, so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Browserless** — Raw headless Chrome as a service without an extraction query layer
- **Apify API** — Site-specific pre-built scrapers (Actors) with dataset storage
- **ZenRows** — Proxy rotation and anti-bot bypass to reach blocked targets

## FAQ

### Why is there no official OpenAPI spec for AgentQL REST API?

AgentQL does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call AgentQL REST API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the AgentQL REST API use?

AgentQL uses an API key in the X-API-Key header. Through Jentic the key lives in the credential vault and is injected at execution; the raw value never reaches the agent.

### Can I extract fields from a PDF invoice with the AgentQL REST API?

Yes. POST /query-document with a PDF URL and either an AgentQL query or a natural-language prompt naming the fields you need. The response is a JSON object keyed by those field names.

### What are the rate limits for the AgentQL REST API?

Rate limits are tied to your plan's monthly query and Tetra-minute quotas rather than a fixed requests-per-second cap. AgentQL throttles abusive bursts at the network layer; build retry-with-backoff for 429 responses.

### How do I extract data from a single web page through Jentic?

Use the Jentic search 'extract data from a web page'. Jentic returns POST /query-data; load its schema, supply the url and your AgentQL query (or prompt), and execute. The parsed object is returned in the response body.

### Do I need a Tetra session to scrape every page?

No. Public pages are handled by /query-data and /query-document directly. Use POST /tetra/sessions only when the target site needs login, JavaScript interaction, or cookie-based gating that the static endpoints cannot reach.

### Can I limit what my agent is allowed to do with the AgentQL REST API?

Yes. Because you run Jentic One yourself, your own rules decide which AgentQL operations and credentials the agent may use. You can allow only the extraction calls it needs, such as POST /query-data for web pages and POST /query-document for PDFs and images, while leaving POST /tetra/sessions out of the allowed set so the agent cannot create authenticated browser sessions unless you add it. Your API key is injected at execution and never enters the agent's prompt or context.