> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notte.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Data APIs

> Ready-made REST endpoints that turn a URL, a company, a person or a search into structured data

> [!TIP]
>
> Read [the Notte skill](https://notte.cc/skill.md) 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.

> [card] [Open the Console](https://console.notte.cc/data-apis)
>
> Try every Data API in the playground.

> [card] [Get your API key](https://console.notte.cc/apikeys)
>
> Create a key to call the API.

## Quick start

```bash theme={null}
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](https://docs.notte.cc/data-apis/fetch.md) | `POST /data/web/fetch` | Get a page as HTML, markdown or product data |
| [Styleguide](https://docs.notte.cc/data-apis/styleguide.md) | `GET /data/web/styleguide` | Extract a website's colors, fonts and components |
| [Products](https://docs.notte.cc/data-apis/products.md) | `POST /data/products/extract` | Extract price, variants and images from a product page |
| [Company enrichment](https://docs.notte.cc/data-apis/company-enrichment.md) | `POST /data/brand/retrieve` | Get logos, colors, socials and company details |
| [Merchant resolution](https://docs.notte.cc/data-apis/merchants.md) | `POST /data/brand/retrieve` | Turn a raw card-statement line into a merchant |
| [Maps businesses](https://docs.notte.cc/data-apis/maps.md) | `POST /data/maps/search` | Find local businesses on Google Maps |
| [People enrichment](https://docs.notte.cc/data-apis/people.md) | `POST /data/people/enrich` | Enrich a person from a name, email or social profile |
| [Company news](https://docs.notte.cc/data-apis/news.md) | `POST /data/news/search` | Search news articles about a company |
| [YouTube](https://docs.notte.cc/data-apis/youtube.md) | `POST /data/youtube/extract` | Get a video's metadata and captions, or a channel's videos |
| [Monitors](https://docs.notte.cc/data-apis/monitors.md) | `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:

```bash theme={null}
-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:

**X-Notte-Cache-Mode** `string` (default: default)

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

**X-Notte-Cache-Max-Age-Ms** `integer`

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

**X-Notte-Cache-Ttl-Seconds** `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`:

```json theme={null}
{
  "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](https://console.notte.cc/data-apis/usage).

```bash theme={null}
curl https://api.notte.cc/data/analytics \
  -H "Authorization: Bearer $NOTTE_API_KEY"
```

```json theme={null}
{
  "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}`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.