# StackGrep

> A search and indexing API for AI agents: index your documents (push JSON, or sync an S3 prefix) and find things by exact text or regex in milliseconds, over REST or MCP. Metadata filters, exact counts, no embeddings. Also: search the HTML source of public websites, and fetch any page as Markdown.

Base URL https://stackgrep.com/api. Auth: header "Authorization: Bearer gw_..." (or "X-API-Key: gw_..."). JSON in and out; errors are {"error": "message"}. MCP server: https://stackgrep.com/mcp (Streamable HTTP; API key header or OAuth).

## Your documents (collections)

- POST /api/collections {"name": "invoices"} -> 201 {"id": N}. Names: 1-64 of a-z 0-9 - _. 409 if taken.
- GET /api/collections -> [{"name", "docs_written", "bytes_written", "stored_bytes", "created_at"}]
- DELETE /api/collections/{name} -> 204
- POST /api/collections/{name}/docs {"docs": [{"id": "inv-1", "text": "...", "meta": {"customer": "globex"}}], "wait": false} -> {"written": n, "searchable": bool}. Up to 10,000 docs a request, 2,000,000 bytes of text a doc, ids up to 512 bytes on one line. Same id = new version. Durable before the answer; searchable within seconds (wait=true: before the answer).
- POST /api/collections/{name}/delete {"ids": ["inv-1"]} -> {"written": n, "searchable": true}
- GET /api/collections/{name}/search?q=&regex=1&filter=customer:globex&limit=20 -> {"collection", "took_ms", "docs", "hits": [{"id", "match", "line", "meta"}]}. One hit per document.
- GET /api/collections/{name}/count?q=&regex=1&filter= -> {"collection", "took_ms", "docs", "sample": [ids, up to 20]}. Exact.
- GET /api/collections/{name}/docs/{id} -> {"id", "text", "meta"}

Query: plain q is literal and case-insensitive. regex=1: RE2 syntax, case-sensitive unless (?i). filter: space-separated key:value terms, all must match, compared as text (numbers/booleans as JSON writes them).

## Sync an S3 bucket into a collection

- PUT /api/collections/{name}/source {"bucket", "prefix", "region"} -> {"status", "objects", "last_sync", "last_error", "verify_key", "verify_token", "role", "policy"}
- Add "policy" to the bucket policy (read-only list/get on the prefix), write verify_token into the object verify_key.
- POST /api/collections/{name}/source/sync -> 202 (also runs every few minutes). GET .../source for status. DELETE .../source stops syncing.
- Each object = a document (id = key under the prefix; meta key/etag/size). .gz unzipped; binary and >4 MB skipped; deleted objects are removed.

## The web index

- GET /api/search?q=&regex=1&limit=&cursor=&order=newest -> {"pattern", "took_ms", "pages", "candidates", "hits": [{"url", "site", "match", "line", "seen_at"}], "next", "cached"}. One hit per site; pass next as cursor for more.
- GET /api/count?q=&regex=1 -> {"pattern", "took_ms", "pages", "sites", "sample", "checked"}
- GET /api/facets?filter=shopify AND klaviyo AND NOT attentive AND tld:de&limit= -> {"sites", "breakdown": [{"name", "sites"}], "sample"}
- GET /api/fetch?url=&all=1&max_age=3600&max_chars=100000 -> {"url", "final_url", "status", "title", "description", "markdown", "truncated", "total_chars", "rendered", "blocked", "cached", "age_s", "ms"}

## MCP tools

list_collections (0 credits), search_collection {collection, query, regex, filter, limit} (1), count_collection {collection, query, regex, filter} (5), get_document {collection, id} (1), search_source {query, regex, limit, cursor, order} (1), count_sites {query, regex} (5), filter_sites {filter, limit} (5), fetch_page {url, all, max_age, max_chars} (1).

## Credits and errors

Search, document read, fetch: 1 credit. Count, facets: 5. Writes: 1 per 1,000 docs or 10 MB a request. Statuses: 400 bad body, 401 no/invalid key, 402 out of credits or key cap, 404 not found, 409 name taken, 422 bad query/request, 429 too many requests at once for the plan, 503 busy or write not stored (retry).

## Docs

- [StackGrep API docs](https://stackgrep.com/docs): Index your documents and search them by exact text or regex from code or any AI agent. REST and MCP, metadata filters, exact counts, no embeddings.
- [Quickstart: search your documents in three calls](https://stackgrep.com/docs/quickstart): Create a collection, send documents and search them by exact text or regex: curl, Python and TypeScript examples you can paste.
- [API keys and authentication](https://stackgrep.com/docs/authentication): Authenticate StackGrep API calls with an API key in the Authorization or X-API-Key header. Per-key monthly caps, revoking keys, OAuth for MCP clients.
- [Collections API](https://stackgrep.com/docs/collections): A collection is a named set of your documents that agents can search. Create, list and delete collections, and see what each one stores.
- [Add, update and delete documents](https://stackgrep.com/docs/documents): Send documents to a search index over a JSON API: up to 10,000 a request, durable before we answer, searchable within seconds. Update by id, delete by id.
- [Search: exact text and regex search API](https://stackgrep.com/docs/search): Search your own documents by exact text or regular expression over a REST API, with metadata filters. Results quote the match and the line around it.
- [Count every matching document, exactly](https://stackgrep.com/docs/count): Count every document that contains some text or matches a regex, with metadata filters. An exact number, not an estimate from the top results.
- [Query syntax: exact text, regex and metadata filters](https://stackgrep.com/docs/query-syntax): How StackGrep reads a query: plain text matched literally and ignoring case, RE2 regular expressions, and key:value metadata filters.
- [Search an S3 bucket from your agent](https://stackgrep.com/docs/bucket-sync): Point StackGrep at an S3 prefix you own: new, changed and deleted files are kept in sync every few minutes and searchable by exact text or regex.
- [MCP server for exact and regex search](https://stackgrep.com/docs/mcp): Connect Claude, Claude Code, Cursor, Codex or any MCP client to StackGrep: tools to search, count and read your documents, and to search and fetch the web.
- [Search website source code by API](https://stackgrep.com/docs/web-search): Search the HTML source of public websites by text or regex, count the sites that match, and filter sites by the technologies they use.
- [Fetch API: any web page as Markdown](https://stackgrep.com/docs/fetch): Read a live web page as clean Markdown for an LLM: title, headings, links and tables, scripts and styling dropped, with a browser only when a page needs one.
- [Errors and limits](https://stackgrep.com/docs/errors-and-limits): StackGrep API errors (400, 401, 402, 404, 409, 422, 429, 503) and their meaning, plus size limits for documents, requests and results.
- [API pricing: credits per call](https://stackgrep.com/docs/pricing-and-credits): What each StackGrep API call costs in credits, and what each plan includes: credits a month, results per search, requests at once.