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

# AgentQL API

Jentic publishes the only available OpenAPI specification for AgentQL API, keeping it validated and agent-ready. AgentQL extracts structured data from web pages and documents using AgentQL query syntax or natural language prompts. The 0.1.0 spec exposes both versioned (/v1) and unversioned routes for the query-data endpoint plus the Tetra remote Chrome browser session API. Each call returns parsed fields keyed by the names declared in the query, removing brittle CSS or XPath selectors from agent code.

## For AI agents

Extract structured fields from any web page using natural language or AgentQL queries. Run inside Tetra remote browser sessions when sites require interaction or login.

## Scope

Does not handle proxy rotation, CAPTCHA solving, dataset storage, or large-scale crawl scheduling - use for structured extraction from individual URLs only.

## Capabilities

- Query structured fields from public web pages without writing CSS or XPath selectors
- Run AgentQL queries inside a Tetra remote browser session for sites that require login or JavaScript interaction
- Use natural language prompts as an alternative to AgentQL syntax for ad-hoc extraction tasks
- Track API key usage and remaining quota with the /v1/usage endpoint
- Capture per-session Tetra usage to reconcile browser-time costs with /v1/tetra/usage

## Use cases

### Web Data Extraction Without Selectors

Replace brittle CSS-selector scrapers with semantic AgentQL queries that survive site redesigns. The agent posts a query to /v1/query-data with the target URL, and AgentQL returns named fields matching the query shape. Suited to monitoring product catalogs, news feeds, or directory pages where layout changes frequently.

Example prompt: Call POST /v1/query-data with url='https://news.ycombinator.com' and query='{ stories[] { title link } }' and return the parsed stories array

### Authenticated Page Scraping via Tetra

Use a Tetra remote browser session to log into a SaaS dashboard, navigate to a report page, and run an AgentQL query to extract the table. The agent calls POST /v1/tetra/sessions to provision the session, drives the browser, and then issues query-data calls scoped to the session. Useful for pulling reports from internal tools that have no public API.

Example prompt: Create a Tetra session, sign in to a vendor dashboard with stored credentials, then run a query-data extraction against the analytics page

### Document Field Extraction

Pass PDF or image URLs to AgentQL with a natural-language prompt to pull invoice numbers, totals, or contract terms into a structured object. The agent does not need to run OCR or build per-template parsers - AgentQL returns the named fields directly. Suited for processing supplier invoices or scanned forms at moderate volume.

Example prompt: Submit a PDF invoice URL with the prompt 'extract invoice_number, total_amount, due_date' and store the parsed fields in the accounting system

### Agent-Driven Research Workflows

Let a Jentic-connected agent decide on the fly which URLs to query and what fields to extract during a research task. The agent searches Jentic for the AgentQL query operation, loads the input schema, and issues queries iteratively as it explores links. This replaces hand-coded scraping pipelines for one-off research jobs.

Example prompt: Given a competitor's homepage URL, recursively query for product pages and extract pricing into a comparison table

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /v1/query-data | Run an AgentQL query against a URL |
| POST | /v1/tetra/sessions | Create a remote browser session |
| GET | /v1/usage | Get account API usage |
| GET | /v1/tetra/usage | Get Tetra session usage |

## Key resources

- **Query** — Submit AgentQL or natural-language queries against URLs to retrieve structured data
- **Tetra Sessions** — Remote Chrome browser sessions for authenticated or interactive scraping
- **Usage** — Track API call quota and Tetra session minutes consumed

## Why Jentic

- **Setup:** Wiring the AgentQL API by hand means managing its X-API-Key header and coding calls that carry the target and query in the body while tracking usage separately. 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 and query in the request body for extraction, and usage reads take no resource id, so limit the agent to the operations it needs, such as extracting data from a page. 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 and accepted query syntax so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Browserless** — Headless Chrome as a service for full-page scraping with selector-driven extraction
- **Apify API** — Pre-built scrapers (Actors) for common sites with persistent dataset storage
- **ZenRows** — Proxy rotation and anti-bot bypass for hard-to-scrape sites

## 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 key never enters the agent's context window.

### Can I scrape sites that require a login with the AgentQL API?

Yes, via the Tetra remote browser. POST /v1/tetra/sessions to provision a Chrome session, drive it to the login flow, then issue /v1/query-data calls scoped to that session id. Static-page queries against /v1/query-data alone do not handle authentication.

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

AgentQL enforces per-plan request and Tetra-minute quotas. Call GET /v1/usage to read the current period's consumption. The API does not document a fixed requests-per-second limit; build retry-with-backoff for any 429 response.

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

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

### Does AgentQL support natural-language extraction without writing AgentQL syntax?

Yes. The /v1/query-data endpoint accepts a prompt parameter as an alternative to a structured query. The result is still returned as JSON, but the field shape is inferred from the prompt rather than declared explicitly.

### 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 page extraction through POST /v1/query-data and usage reads through GET /v1/usage while leaving everything else out. AgentQL passes the target URL and query in the request body and usage reads take no resource id, so scoping happens at the operation level rather than per record. Creating a Tetra remote browser session with POST /v1/tetra/sessions stays outside the allowed set unless you explicitly add it, which keeps authenticated scraping off unless you have approved it.