Data APIs

AI agent instructions

Read the Notte skill and follow its setup instructions when setting up Notte or building browser automation. This is the shared source for CLI setup, authentication, and the browser-to-code workflow.

Data APIs are single-call REST endpoints. You send a URL, a domain, a name or a query, and you get structured JSON back. No browser session to manage.

Open the Console

Try every Data API in the playground.

Get your API key

Create a key to call the API.

Quick start

curl -X POST https://api.notte.cc/data/brand/retrieve \
  -H "Authorization: Bearer $NOTTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "by_domain", "domain": "stripe.com"}'

The 10 Data APIs

API	Endpoint	Use it to
Raw fetch	`POST /data/web/fetch`	Get a page as HTML, markdown or product data
Styleguide	`GET /data/web/styleguide`	Extract a website’s colors, fonts and components
Products	`POST /data/products/extract`	Extract price, variants and images from a product page
Company enrichment	`POST /data/brand/retrieve`	Get logos, colors, socials and company details
Merchant resolution	`POST /data/brand/retrieve`	Turn a raw card-statement line into a merchant
Maps businesses	`POST /data/maps/search`	Find local businesses on Google Maps
People enrichment	`POST /data/people/enrich`	Enrich a person from a name, email or social profile
Company news	`POST /data/news/search`	Search news articles about a company
YouTube	`POST /data/youtube/extract`	Get a video’s metadata and captions, or a channel’s videos
Monitors	`POST /data/monitors`	Watch a page on a schedule and get a webhook when it changes

You can list them at any time with GET /data.

Authentication

Every request needs your API key as a bearer token:

-H "Authorization: Bearer $NOTTE_API_KEY"

Caching

Results are cached on the server. Defaults per API:

API	Default cache
Company enrichment	7 days
Styleguide, People, YouTube, Merchants	24 hours
Maps	1 hour
Fetch, Products	15 minutes
News	5 minutes
Monitors	Never cached (always live)

Control it per request with these headers:

string

default:"default"

default uses the cache, refresh re-fetches and updates it, bypass skips it.

integer

Maximum age of a cached result you accept, in milliseconds. 0 forces a fresh result.

integer

Store the result for less time than the default. 0 means don’t store it.

Fetch, Styleguide and Company enrichment (including Merchant resolution) responses include cache_metadata with status (hit or miss) and age_ms. Read your current policy with GET /data/cache. Clear cached results with DELETE /data/cache.

Common parameters

Some APIs accept these optional fields. Check the table before sending them, because unsupported fields are rejected.

Field	What it does	Accepted by
`timeoutOpts`	`milliseconds` (integer) and `behavior`: `fail` returns an error on timeout, `return-partial` returns what was collected so far	Fetch, Styleguide, Company enrichment, Merchant resolution, People
`zdr`	`enabled` turns on zero data retention for the request. `disabled` is the default	Fetch, Styleguide, People
`tags`	Free-form labels attached to the request	Fetch, Styleguide, Company enrichment, Merchant resolution, People, News, Monitors

Products, Maps and YouTube take none of them. For Styleguide, which is a GET, they are query parameters (timeoutOpts[milliseconds], timeoutOpts[behavior], zdr, tags). For the others they go in the JSON body.

Errors

Errors return a JSON body with an error_code, a message and a request_id:

{
  "error_code": "UNAUTHORIZED",
  "message": "Not authenticated",
  "request_id": "6bc00896-30e1-490d-8de8-16756eb7c95f"
}

Status	`error_code`	Meaning
400	`INPUT_VALIDATION_ERROR`	A field is missing or invalid. The `message` names it.
401	`UNAUTHORIZED`	Missing or invalid API key.
408	`TIMEOUT`	The page didn’t finish loading in time.
	`NOT_FOUND`	The API couldn’t resolve what you asked for (for example an unknown merchant).

The OpenAPI spec also lists a 422 response with a detail array for validation errors on some endpoints. Handle both 400 and 422 as invalid input. Include the request_id when you contact support.

Usage

GET /data/analytics returns your request counts, successes, partial results and p50/p95 latency per API. It takes optional since and until (ISO 8601) query parameters and defaults to the last 7 days. You can also see usage in the Console.

curl https://api.notte.cc/data/analytics \
  -H "Authorization: Bearer $NOTTE_API_KEY"

{
  "data": [
    {
      "operation": "products",
      "capability": "products",
      "requests": 37,
      "successes": 25,
      "partial_results": 0,
      "server_errors": 0,
      "p50_ms": 6093.5,
      "p95_ms": 25712.3
    }
  ],
  "since": "2026-11-04T20:10:09Z",
  "until": "2026-11-11T20:10:09Z"
}

To inspect individual requests, use GET /data/analytics/requests and GET /data/analytics/requests/{request_id}.

Getting Started

Sessions

Authentication

Functions

Anything API

Data APIs

Open the Console

Get your API key

Quick start

The 10 Data APIs

Authentication

Caching

Common parameters

Errors

Usage

Open the Console

Get your API key

​Quick start

​The 10 Data APIs

​Authentication

​Caching

​Common parameters

​Errors

​Usage

Quick start

The 10 Data APIs

Authentication

Caching

Common parameters

Errors

Usage