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

# AgentQL API

Jentic publishes the only available OpenAPI specification for AgentQL API, keeping it validated and agent-ready. The main 1.0.0 surface combines AgentQL's web and document extraction with Tetra remote browser session creation behind a single base URL. Three endpoints handle the full flow: query a web page, query a document, or spin up a browser session for sites that need login. Each query call accepts AgentQL syntax or a natural-language prompt and returns parsed fields directly.

## For AI agents

Query any web page or document with AgentQL syntax or natural language and get structured fields back; spin up a Tetra browser session for authenticated targets.

## Scope

Does not handle proxy rotation, CAPTCHA solving, scheduled crawling, or dataset persistence - use for AgentQL-style structured extraction from URLs and documents only.

## Capabilities

- Run AgentQL queries against URLs to extract named fields without selectors via POST /query-data
- Pull invoice and contract fields out of PDFs and images via POST /query-document
- Provision a Tetra remote Chrome session via POST /tetra/sessions for authenticated scraping
- Substitute natural-language prompts for AgentQL syntax when ad-hoc extraction is faster
- Issue scoped queries inside an existing browser session for multi-step authenticated workflows

## Use cases

### Selectorless Web Extraction

Skip CSS or XPath maintenance by sending AgentQL queries to /query-data alongside the target URL. The API returns parsed fields keyed by the query, surviving most layout changes. Suited to monitoring product, news, and directory pages where DOM churn breaks traditional scrapers.

Example prompt: POST /query-data with url='https://example.com' and query='{ headlines[] { title link } }' and return the parsed list

### Document Intelligence

Parse PDFs and images into structured data without per-template OCR pipelines. POST /query-document with a file URL and either an AgentQL query or a natural-language prompt naming fields like invoice_number, total_amount, and due_date. Best for accounts payable, contract intake, and form processing at moderate volume.

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

### Authenticated Browser Workflows

Use POST /tetra/sessions to provision a Chrome session, drive it through a login, then issue /query-data calls scoped to the session. This unlocks data behind sign-in walls without managing your own headless browser infrastructure.

Example prompt: Create a Tetra session, sign in to a vendor portal, then query for the latest report table on the dashboard

### Agent Tool for Live Web Lookups

Connect a Jentic-managed agent to the AgentQL main surface and let it decide when to query a page during a longer plan. The agent searches Jentic for the AgentQL query operation, loads the input schema, and issues queries on demand. This makes selectorless web extraction a primitive for autonomous research, comparison, and monitoring agents.

Example prompt: Given a startup's homepage, query for product page links, follow each, and extract pricing into a single comparison object

## 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 scraping

## Why Jentic

- **Setup:** Wiring the AgentQL 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 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 data from a web page', and Jentic returns the matching AgentQL operation with its input schema, including the supported query syntax, so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Browserless** — Headless Chrome with raw HTML, screenshots, and PDF output
- **Apify API** — Pre-built site-specific scrapers (Actors) with persistent dataset storage
- **ZenRows** — Proxy and anti-bot bypass for hard-to-fetch targets

## FAQ

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

AgentQL does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call AgentQL 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 API use?

AgentQL uses an API key passed in the X-API-Key request header. Through Jentic the key is held in the credential vault and injected at execution time, so the raw value never reaches the agent's context.

### Can I scrape sites that require login with AgentQL?

Yes, by using Tetra. POST /tetra/sessions to create a session, drive it through the login flow, then run /query-data calls scoped to that session id. Static page queries against /query-data alone do not handle authentication.

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

Limits are enforced as monthly query and Tetra-minute quotas tied to your plan rather than a hard requests-per-second cap. Build retry-with-backoff into the agent for 429 responses.

### How do I extract structured data from a URL through Jentic?

Run the Jentic search 'extract structured data from a web page'. Jentic returns the POST /query-data operation; load its schema, supply the url and an AgentQL query like '{ products[] { name price } }', and execute. The parsed object comes back in the response.

### Does AgentQL accept natural language instead of AgentQL syntax?

Yes. Both /query-data and /query-document accept a prompt parameter. The shape of the returned JSON is inferred from the prompt rather than declared explicitly in a query.

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

Yes. Because you run Jentic One yourself, your own rules decide which AgentQL operations the agent may call, so you can allow only structured extraction from a web page (POST /query-data) or a document (POST /query-document) and keep those in the permitted set. Since browser session creation (POST /tetra/sessions) is not included unless you add it, an agent scoped to extraction alone cannot spin up a Tetra session. Your API key is held by your own instance and injected as the X-API-Key header at execution time, so it never reaches the agent's context.