synthetic-search
Use Synthetic's /v2/search and /v2/quotas endpoints with verified curl patterns, quota checks, and a small wrapper script for readable output.
Verified against the live API on April 9, 2026. The published skills.sh version and an older local wrapper both informed this skill, but the instructions here prioritize observed behavior over inherited claims.
Decision Tree
What do you need to do?
Run a raw API call, pipe results into jq, or inspect the exact request/response shape
Set up SYNTHETIC_API_KEY, confirm prerequisites, or decide whether to use curl, jq, or Node
- Read
references/configuration.md
Use the helper script for readable search output, JSON passthrough, URL-only output, or quota summaries
- Read
references/patterns.md
Debug missing published, blank 500 responses, fixed result counts, or auth/input failures
- Read
references/gotchas.md
Quick Reference
| Task |
Command |
Read |
| Raw search request |
curl -s https://api.synthetic.new/v2/search -H "Authorization: Bearer $SYNTHETIC_API_KEY" -H "Content-Type: application/json" -d '{"query":"rust async await"}' |
references/api.md |
| URLs only |
curl -s ... -d '{"query":"nix flake tutorial"}' | jq -r '.results[].url' |
references/patterns.md |
| Titles with URLs |
curl -s ... -d '{"query":"python requests library documentation"}' | jq -r '.results[] | "\\(.title)\\t\\(.url)"' |
references/patterns.md |
| Human-readable search output |
node scripts/search.js "rust async await" |
references/patterns.md |
| Raw JSON from helper |
node scripts/search.js --json "rust async await" |
references/patterns.md |
| Quota summary |
node scripts/search.js quotas |
references/api.md |
| Structured live probe |
python3 scripts/probe_synthetic_search.py --mode all --query "rust async await" |
references/patterns.md |
Reading Guide
| If the user says... |
Read |
| "Use Synthetic Search on this query" |
references/api.md |
"Give me the best curl or jq one-liner" |
references/patterns.md |
| "Check my Synthetic limits / quota" |
references/api.md |
"Why is published missing?" |
references/gotchas.md |
"How do I set up SYNTHETIC_API_KEY or test it?" |
references/configuration.md |
Verified Behaviors
POST /v2/search currently returns 5 results for a normal query in live testing.- Live search responses exposed
url, title, and text; the docs and older skill versions still show a published field, but it was absent in verified samples.
GET /v2/quotas returned live subscription, hourly search, weekly token, and rolling-five-hour quota metadata.- Bad auth returned
401 with {"error":"Invalid API Key."}.
- Missing
query returned 400 with a helpful JSON error, while {"query":""} returned a blank-body 500.
Gotchas
- Treat
published as optional: Synthetic documents it and older wrappers surfaced it, but live results did not include it in testing. Write fallbacks for null or absent values.
- Display limits are local, not API-side: the API still returned 5 results in testing;
-n or --limit in scripts/search.js only controls what you print.
- Empty queries fail badly: a missing
query key returns a useful 400, but an empty string currently returns 500 with no body.
- Quota numbers are easier to trust than docs prose: the docs mention quota surfaces, but the live
/v2/quotas response is the authoritative source for current numeric limits.
- Use raw API mode when you need precision: the helper script is convenient, but raw
curl plus jq is safer when another tool will consume the JSON directly.
Helper Scripts
scripts/search.js wraps search and quotas with zero npm dependencies.scripts/probe_synthetic_search.py runs repeatable live probes for search, quotas, and failure cases, then prints structured JSON.scripts/validate.py checks structure, frontmatter, and cross-references.scripts/test_skill.py checks eval shape and cross-reference integrity.
1---2name: synthetic-search3description: Use Synthetic Search or the Synthetic API (`api.synthetic.new`, `SYNTHETIC_API_KEY`) for zero-data-retention web search, curl/jq examples, quota checks, and a small Node helper. Do NOT use for browser automation, crawling, or unrelated search providers.4---56# synthetic-search78Use Synthetic's `/v2/search` and `/v2/quotas` endpoints with verified `curl` patterns, quota checks, and a small wrapper script for readable output.910Verified against the live API on April 9, 2026. The published `skills.sh` version and an older local wrapper both informed this skill, but the instructions here prioritize observed behavior over inherited claims.1112## Decision Tree1314What do you need to do?1516- Run a raw API call, pipe results into `jq`, or inspect the exact request/response shape17 - Read `references/api.md`1819- Set up `SYNTHETIC_API_KEY`, confirm prerequisites, or decide whether to use `curl`, `jq`, or Node20 - Read `references/configuration.md`2122- Use the helper script for readable search output, JSON passthrough, URL-only output, or quota summaries23 - Read `references/patterns.md`2425- Debug missing `published`, blank 500 responses, fixed result counts, or auth/input failures26 - Read `references/gotchas.md`2728## Quick Reference2930| Task | Command | Read |31| --- | --- | --- |32| Raw search request | `curl -s https://api.synthetic.new/v2/search -H "Authorization: Bearer $SYNTHETIC_API_KEY" -H "Content-Type: application/json" -d '{"query":"rust async await"}'` | `references/api.md` |33| URLs only | `curl -s ... -d '{"query":"nix flake tutorial"}' \| jq -r '.results[].url'` | `references/patterns.md` |34| Titles with URLs | `curl -s ... -d '{"query":"python requests library documentation"}' \| jq -r '.results[] \| "\\(.title)\\t\\(.url)"'` | `references/patterns.md` |35| Human-readable search output | `node scripts/search.js "rust async await"` | `references/patterns.md` |36| Raw JSON from helper | `node scripts/search.js --json "rust async await"` | `references/patterns.md` |37| Quota summary | `node scripts/search.js quotas` | `references/api.md` |38| Structured live probe | `python3 scripts/probe_synthetic_search.py --mode all --query "rust async await"` | `references/patterns.md` |3940## Reading Guide4142| If the user says... | Read |43| --- | --- |44| "Use Synthetic Search on this query" | `references/api.md` |45| "Give me the best `curl` or `jq` one-liner" | `references/patterns.md` |46| "Check my Synthetic limits / quota" | `references/api.md` |47| "Why is `published` missing?" | `references/gotchas.md` |48| "How do I set up `SYNTHETIC_API_KEY` or test it?" | `references/configuration.md` |4950## Verified Behaviors51521. `POST /v2/search` currently returns 5 results for a normal query in live testing.532. Live search responses exposed `url`, `title`, and `text`; the docs and older skill versions still show a `published` field, but it was absent in verified samples.543. `GET /v2/quotas` returned live subscription, hourly search, weekly token, and rolling-five-hour quota metadata.554. Bad auth returned `401` with `{"error":"Invalid API Key."}`.565. Missing `query` returned `400` with a helpful JSON error, while `{"query":""}` returned a blank-body `500`.5758## Gotchas59601. **Treat `published` as optional**: Synthetic documents it and older wrappers surfaced it, but live results did not include it in testing. Write fallbacks for `null` or absent values.612. **Display limits are local, not API-side**: the API still returned 5 results in testing; `-n` or `--limit` in `scripts/search.js` only controls what you print.623. **Empty queries fail badly**: a missing `query` key returns a useful `400`, but an empty string currently returns `500` with no body.634. **Quota numbers are easier to trust than docs prose**: the docs mention quota surfaces, but the live `/v2/quotas` response is the authoritative source for current numeric limits.645. **Use raw API mode when you need precision**: the helper script is convenient, but raw `curl` plus `jq` is safer when another tool will consume the JSON directly.6566## Helper Scripts6768- `scripts/search.js` wraps `search` and `quotas` with zero npm dependencies.69- `scripts/probe_synthetic_search.py` runs repeatable live probes for search, quotas, and failure cases, then prints structured JSON.70- `scripts/validate.py` checks structure, frontmatter, and cross-references.71- `scripts/test_skill.py` checks eval shape and cross-reference integrity.
jpcaparas