Add or update documents
POST /api/collections/{name}/docs with up to 10,000 documents. Sending an id that's already there replaces that document: searches see only the newest version.
curl -X POST https://stackgrep.com/api/collections/contracts/docs \
-H "Authorization: Bearer $STACKGREP_KEY" \
-d '{"docs": [
{"id": "acme/msa-2024.txt", "text": "MASTER SERVICES AGREEMENT ...",
"meta": {"customer": "acme", "year": 2024, "signed": true}},
{"id": "globex/nda.txt", "text": "MUTUAL NON-DISCLOSURE AGREEMENT ..."}
]}'
# {"written": 2, "searchable": false}| Name | Type | What it does |
|---|---|---|
docs[].id | string | Your id for the document: up to 512 bytes, on one line. Slashes are fine (a file path makes a good id). |
docs[].text | string | The text to search, up to 2,000,000 bytes. |
docs[].meta | object | Optional. Values to filter on, like customer or type. Strings are kept as they are; numbers and booleans as JSON writes them (2024 becomes "2024"); nulls are dropped. |
wait | boolean | Optional. true: searchable before we answer. Otherwise searchable within a few seconds. |
Either way, the answer comes only once the documents are durably stored: if you get 200, they're kept. Writes that arrive within 50 ms of each other are stored together, so many small writes in parallel are cheap and fast. If storing fails you get 503 and nothing was written; send the same request again.
Read a document
GET /api/collections/{name}/docs/{id} returns the newest version of a document whole, with its metadata. Search results give you the ids.
curl https://stackgrep.com/api/collections/contracts/docs/acme/msa-2024.txt \
-H "Authorization: Bearer $STACKGREP_KEY"{"id": "acme/msa-2024.txt", "text": "MASTER SERVICES AGREEMENT ...",
"meta": {"customer": "acme", "year": "2024", "signed": "true"}}Delete documents
POST /api/collections/{name}/delete with up to 10,000 ids. Deleted documents stop showing up in searches right away.
curl -X POST https://stackgrep.com/api/collections/contracts/delete \
-H "Authorization: Bearer $STACKGREP_KEY" -d '{"ids": ["globex/nda.txt"]}'
# {"written": 1, "searchable": true}Writes cost 1 credit for each 1,000 documents or 10 MB of text in a request, whichever is more. Reading a document costs 1. See pricing.