The NLWeb API from Agent Ready — 1 operation(s) for nlweb.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/agent-ready-dev-nlweb-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Agent Ready NL Web API
version: 1.0.0
contact:
name: Agent Ready
url: https://agent-ready.dev/about#contact
email: support@agent-ready.dev
description: Programmatic access to agent-ready.dev scans.
x-guidance: 'Scan any public website for AI agent-readability. POST /api/x402/scan with a JSON body {"url":"https://…"} and pay per scan with no account via x402 (X-PAYMENT header) or MPP (Authorization: Payment) — $0.02 for up to 25 pages, $0.25 for up to 250, USDC on Base mainnet. The same scan is available free under quota at POST /api/scan, or with an API key for Pro subscribers. Read-only; only public URLs are scanned.'
servers:
- url: https://agent-ready.dev
security:
- ApiKey: []
tags:
- name: NLWeb
paths:
/api/v1/ask:
get:
operationId: askGet
summary: Ask in natural language (NLWeb)
description: 'NLWeb /ask endpoint, conventional GET form: /ask?query=. Natural-language search over Agent Ready''s own content (methodology, check registry, specs, and the content library — explainers, comparisons, how-to guides, glossary). Public — no API key required. Returns NLWeb result objects with a nested Schema.org `schema_object`. Set stream=true for Server-Sent Events. Also served at the root path /ask.'
tags:
- NLWeb
security: []
parameters:
- schema:
type: string
example: how is the score calculated?
required: true
name: query
in: query
- schema:
type: string
enum:
- list
- summarize
required: false
name: mode
in: query
- schema:
type: string
enum:
- methodology
- checks
- specs
- llms-txt
- check
- page
required: false
name: itemType
in: query
- schema:
type: string
enum:
- 'true'
- 'false'
required: false
name: stream
in: query
responses:
'200':
description: An NLWeb answer.
content:
application/json:
schema:
$ref: '#/components/schemas/AskResponse'
'400':
description: Missing or invalid query.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Rate limit exceeded. Response carries `Retry-After` (seconds) plus `X-RateLimit-Limit` and `X-RateLimit-Remaining`. Back off using exponential delay with jitter — see the Rate limits & retry section in the docs.
headers:
X-RateLimit-Limit:
description: Maximum number of requests permitted in the current window.
schema:
type: integer
example: 10
X-RateLimit-Remaining:
description: Requests remaining in the current window. `0` on a 429 response.
schema:
type: integer
example: 0
Retry-After:
description: Seconds until a slot frees in the sliding window (RFC 7231 §7.1.3). Honour this before retrying.
schema:
type: integer
example: 42
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: Service temporarily unavailable. Retry with backoff.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
post:
operationId: askPost
summary: Ask in natural language (NLWeb), JSON-body form
description: 'NLWeb /ask endpoint, JSON-body form: { query: { q }, prefer: { mode, streaming } }. Same response as the GET form. Public — no API key required.'
tags:
- NLWeb
security: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AskRequest'
responses:
'200':
description: An NLWeb answer.
content:
application/json:
schema:
$ref: '#/components/schemas/AskResponse'
'400':
description: Invalid /ask request body.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: No results (NLWeb failure envelope).
content:
application/json:
schema:
$ref: '#/components/schemas/AskResponse'
'429':
description: Rate limit exceeded. Response carries `Retry-After` (seconds) plus `X-RateLimit-Limit` and `X-RateLimit-Remaining`. Back off using exponential delay with jitter — see the Rate limits & retry section in the docs.
headers:
X-RateLimit-Limit:
description: Maximum number of requests permitted in the current window.
schema:
type: integer
example: 10
X-RateLimit-Remaining:
description: Requests remaining in the current window. `0` on a 429 response.
schema:
type: integer
example: 0
Retry-After:
description: Seconds until a slot frees in the sliding window (RFC 7231 §7.1.3). Honour this before retrying.
schema:
type: integer
example: 42
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: Service temporarily unavailable. Retry with backoff.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
AskRequest:
type: object
properties:
query:
anyOf:
- type: string
minLength: 1
maxLength: 2000
- type: object
properties:
text:
type: string
minLength: 1
maxLength: 2000
q:
type: string
minLength: 1
maxLength: 2000
itemType:
type: string
enum:
- methodology
- checks
- specs
- llms-txt
- check
- page
- any
description: Optional filter mapping to an Agent Ready corpus type. 'any' (default) searches everything.
site:
type: string
required:
- text
- type: object
properties:
q:
type: string
minLength: 1
maxLength: 2000
itemType:
type: string
enum:
- methodology
- checks
- specs
- llms-txt
- check
- page
- any
description: Optional filter mapping to an Agent Ready corpus type. 'any' (default) searches everything.
site:
type: string
required:
- q
example:
text: how is the agent readability score calculated?
mode:
type: string
enum:
- list
- summarize
- generate
streaming:
anyOf:
- type: boolean
- type: string
itemType:
type: string
enum:
- methodology
- checks
- specs
- llms-txt
- check
- page
- any
description: Optional filter mapping to an Agent Ready corpus type. 'any' (default) searches everything.
site:
type: string
query_id:
type: string
prev:
type: string
decontextualized_query:
type: string
prefer:
type: object
properties:
streaming:
type: boolean
format:
type: string
enum:
- json
mode:
type: string
enum:
- list
- summarize
language:
type: string
context:
type: array
items:
type: object
properties:
role:
type: string
enum:
- user
- assistant
content:
type: string
required:
- role
- content
meta:
type: object
properties:
version:
type: string
session:
type: string
user:
type: string
required:
- query
description: 'NLWeb /ask request. The spec shape is `{ query: { text } }`; the legacy string and `{ query: { q } }` forms plus a `prefer` envelope are also accepted.'
AskResponse:
anyOf:
- $ref: '#/components/schemas/AskAnswer'
- $ref: '#/components/schemas/AskFailure'
description: Either an answer or a failure.
Error:
type: object
properties:
error:
type: object
properties:
code:
type: string
example: subscription_required
message:
type: string
required:
- code
- message
required:
- error
description: Structured error envelope.
SchemaObject:
type: object
properties:
'@context':
type: string
enum:
- https://schema.org
'@type':
type: string
enum:
- Article
- TechArticle
- WebPage
name:
type: string
url:
type: string
description:
type: string
required:
- '@context'
- '@type'
- name
- url
description: Schema.org JSON-LD for a result.
AskResult:
type: object
properties:
url:
type: string
name:
type: string
site:
type: string
score:
type: number
description: Relevance score (BM25).
description:
type: string
schema_object:
$ref: '#/components/schemas/SchemaObject'
required:
- url
- name
- site
- score
- description
- schema_object
description: An NLWeb result object.
AskMeta:
type: object
properties:
response_type:
type: string
enum:
- answer
- failure
- elicitation
- promise
version:
type: string
enum:
- '0.55'
mode:
type: string
enum:
- list
- summarize
required:
- response_type
- version
- mode
description: NLWeb response envelope metadata.
AskAnswer:
type: object
properties:
_meta:
$ref: '#/components/schemas/AskMeta'
query_id:
type: string
site:
type: string
mode:
type: string
enum:
- list
- summarize
query:
type: string
results:
type: array
items:
$ref: '#/components/schemas/AskResult'
summary:
type: string
description: Present when mode is 'summarize'.
required:
- _meta
- query_id
- site
- mode
- query
- results
description: Successful NLWeb answer.
AskFailure:
type: object
properties:
_meta:
$ref: '#/components/schemas/AskMeta'
error:
type: object
properties:
code:
type: string
enum:
- NO_RESULTS
- INVALID_QUERY
- RATE_LIMITED
- TIMEOUT
- INTERNAL
message:
type: string
required:
- code
- message
required:
- _meta
- error
description: NLWeb failure envelope.
securitySchemes:
ApiKey:
type: http
scheme: bearer
bearerFormat: ar_live_<prefix>_<secret>
description: API key issued from /dashboard/api-keys. Pro subscription required.