---
title: "The same search with parameters in a JSON body"
method: POST
path: "/v1/search"
tags: ["search"]
---

# The same search with parameters in a JSON body

`POST /v1/search`

## Request

- Base URL: `https://api.publicwww.com`
- URL: `https://api.publicwww.com/v1/search`
- Auth: HTTP bearer

For queries too long or too multi-line for a url. Takes the same parameters as GET; an array in query means all of those phrases.

## Request body

- SearchRequest
  - `query` union, required: The search; an array means all of those phrases.
    - string
    - string[]
  - `page` integer
  - `per_page` integer
  - `snippets` boolean
  - `format` 'json' | 'ndjson' | 'xml' | 'csv' | 'tsv' | 'txt'
  - `columns` string
  - `delimiter` string
  - `header` boolean

## Response `200`

Search results. The body follows format; the totals are also in the headers.

- SearchResponse
  - `query` string, required
  - `page` integer, required
  - `per_page` integer, required
  - `total` integer, required: Websites matching the query in the index.
  - `total_pages` integer, required
  - `returned` integer, required: Rows in this answer.
  - `truncated` boolean, required: true when the plan cut this page short.
  - `index_complete` boolean, required: false when part of the index did not answer in time; the results may be incomplete.
  - `took_ms` integer, required
  - `query_note` string: Present when the query could not be run as written, with the reason.
  - `results` SearchResult[], required
    - `domain` string
    - `url` string: The page the match was found on.
    - `rank` integer, nullable: Popularity rank, 1 is the most popular; null for an unranked website.
    - `ranked` boolean
    - `snippets` Snippet[]: Only with snippets=1. Up to 5 fragments of page source around the match.
      - `text` string, required: The fragment of page source.
      - `match` string, required: The part of text that matched the query.

## Other responses

- `400`: The request cannot be served as asked: missing_query, unknown_format, unknown_column, format_not_available, per_page_too_large, page_too_deep, invalid_json.
- `401`: missing_key - no Authorization: Bearer header; invalid_key - the token does not name an account.
- `403`: plan_required - the account has no paid plan.
- `429`: too_many_requests - more than 10 requests a minute, wait Retry-After seconds; quota_exceeded - the day's searches are used up, searches with snippets included; snippet_quota_exceeded - the day's snippet searches are used up, searching without snippets still works.

---

[API](https://skmtc.dev/publicwww/apis/publicwww-search-api.md) · [All operations](https://skmtc.dev/publicwww/apis/publicwww-search-api/llms.txt) · [OpenAPI document](https://skmtc.dev/publicwww/apis/publicwww-search-api/revisions/79d49d819de3?raw)