diff --git a/src/content/reference/_meta.ts b/src/content/reference/_meta.ts index 3441c15..6e4291f 100644 --- a/src/content/reference/_meta.ts +++ b/src/content/reference/_meta.ts @@ -7,6 +7,7 @@ const meta: MetaRecord = { collapsed: true, }, }, + 'http-api': 'HTTP API', 'mcp-tools': 'MCP tools', pandascript: 'PandaScript', } diff --git a/src/content/reference/http-api.mdx b/src/content/reference/http-api.mdx new file mode 100644 index 0000000..919af54 --- /dev/null +++ b/src/content/reference/http-api.mdx @@ -0,0 +1,70 @@ +--- +title: HTTP API +description: Reference of the Lightpanda Cloud HTTP API endpoints. +--- + +# HTTP API + +Fetch a URL and retrieve the rendered page. See [how to use the HTTP API](/usage/api) for practical documentation. + +## Fetch a URL + +The `POST /api/fetch` endpoint returns a JSON message containing the page's content. + +### Request + +The request requires a bearer authorization header with your token and the `Content-Type: application/json` header. + +The endpoint accepts the following parameters: + +| Parameter | Type | Required | Default | Description | +|---|---|---|---|---| +| `url` | string | Yes | — | The URL to fetch. | +| `output_format` | `html` \| `markdown` | No | `html` | — | +| `wait_ms` | uint | No | `5000` | Time to wait before retrieving the page, in milliseconds. `0` also falls back to the default; it doesn't mean "don't wait". | +| `wait_event` | `DOMContentLoaded` \| `load` \| `networkAlmostIdle` \| `networkIdle` | No | `networkIdle` | Event to wait for before retrieving the page. | +| `raw` | bool | No | `false` | If true, the raw HTML or markdown is returned directly, without the JSON wrapper, with `Content-Type: text/html` or `text/plain` respectively. | +| `proxy_name` | string | No | `fast_dc` | — | +| `country` | string | No | — | Two-letter country code, case-insensitive. Only used with the `datacenter` proxy. | + +```sh copy +curl -XPOST \ + -H "Authorization: Bearer YOUR_TOKEN" \ + -H "Content-Type: application/json" \ + https://euwest.cloud.lightpanda.io/api/fetch \ + --data '{ + "url": "https://lightpanda.io", + "output_format": "markdown", + "wait_ms": 50000, + "wait_event": "networkIdle", + "raw": false + }' +``` + +### Response + +If the request sets `raw` to `false`, a JSON response is returned. + +| Field | Type | Description | +|---|---|---| +| `data` | string | The page's content, in the format specified by the `output_format` parameter. | +| `status` | int | The response status code. | +| `headers` | object, optional | The HTTP headers returned by the server. | + +```json copy +{ + "data": "\n# Example Domain\n\nThis domain is for use in documentation examples without needing permission. Avoid use in operations.\n\n[Learn more](https://iana.org/domains/example)\n", + "status": 200, + "headers": { + "age": "10026", + "allow": "GET, HEAD", + "cf-cache-status": "HIT", + "cf-ray": "9f0dd9374a2320ab-IAD", + "content-encoding": "br", + "content-type": "text/html", + "date": "Thu, 23 Apr 2026 15:19:47 GMT", + "last-modified": "Sat, 18 Apr 2026 00:51:00 GMT", + "server": "cloudflare" + } +} +``` diff --git a/src/content/usage/api.mdx b/src/content/usage/api.mdx index f0ca07c..426cd0c 100644 --- a/src/content/usage/api.mdx +++ b/src/content/usage/api.mdx @@ -2,92 +2,20 @@ title: API description: Use HTTP API calls to get Lightpanda's results directly. --- -import { Tabs } from 'nextra/components' # HTTP API ## Connect - - Lightpanda Cloud provides an HTTP API to easily retrieve results from Lightpanda without the burden of writing and running a CDP script. -### Authentication - -Every HTTP API request must include a bearer authorization header with your token. - -``` -Authorization: Bearer YOUR_TOKEN -``` - -Example with curl: -```sh copy -curl -XPOST \ - -H "Authorization: Bearer YOUR_TOKEN" \ - -H "Content-Type: application/json" \ - https://euwest.cloud.lightpanda.io/api/fetch \ - --data '{"url":"https://lightpanda.io"}' -``` - - - +See [Getting started on Lightpanda Cloud](/run-on-lightpanda-cloud/getting-started) to create an account, generate your token, and pick the URL for your region. ## Fetch a URL -The main API lets you fetch a URL and retrieve the rendered page in HTML or markdown format. -The `POST /api/fetch` endpoint returns a JSON message containing the page's content. - -### Request - -The request requires the `Content-Type: application/json` header. - -The endpoint accepts the following parameters: - -* `url`: string, required: the URL to fetch. -* `output_format`: `html` or `markdown`, optional, default `html`. -* `wait_ms`: uint, optional, default `5000`: time to wait before retrieving the page, in milliseconds. -* `wait_event`: `DOMContentLoaded`, `load`, `networkAlmostIdle` or `networkIdle`, optional, default `networkIdle`: event to wait for before retrieving the page. -* `raw`: bool, optional, default `false`: if true, the raw HTML or markdown is returned directly, without the JSON wrapper. -* `proxy_name`: optional, default `fast_dc`. -* `country`: optional: only used with the `datacenter` proxy. - -```json copy -{ - "url": "https://lightpanda.io", - "output_format": "markdown", - "wait_ms": 50000, - "wait_event": "networkIdle", - "raw": false -} -``` - -### Response - -If the request sets `raw` to `false`, a JSON response is returned. - -* `data`: string: the page's content, in the format specified by the `output_format` parameter. -* `status`: uint: the response status code. -* `headers`: array, optional: the HTTP headers returned by the server. - -```json copy -{ - "data": "\n# Example Domain\n\nThis domain is for use in documentation examples without needing permission. Avoid use in operations.\n\n[Learn more](https://iana.org/domains/example)\n", - "status": 200, - "headers": { - "age": "10026", - "allow": "GET, HEAD", - "cf-cache-status": "HIT", - "cf-ray": "9f0dd9374a2320ab-IAD", - "content-encoding": "br", - "content-type": "text/html", - "date": "Thu, 23 Apr 2026 15:19:47 GMT", - "last-modified": "Sat, 18 Apr 2026 00:51:00 GMT", - "server": "cloudflare" - } -} -``` +The API lets you fetch a URL and retrieve the rendered page in HTML or markdown format. Find the full list of parameters and the response format in the [HTTP API reference](/reference/http-api). -### Complete example with curl +For example, to fetch a page as markdown: ```sh copy $ curl -XPOST \