Quickstart

discatch is built so an AI assistant that knows only the domain name can find out what discatch is, decide whether to use it, sign up, and make its first call without a person opening a browser. This page is that path, in order. A person can follow it too.

1. Start with the doctor call

One call explains all the others. It also comes back for any unknown address, so a wrong URL still lands you here.

curl https://api.discatch.com/v1/doctor

The response lists where to start (start_here: OpenAPI, MCP, CLI, llms.txt, playbooks), how to get a key (get_a_key), today’s prices (prices_today), which sources are live (sources_now), two calls to try, and what to do next (next_action).

2. Get a trial key

No email, no credit card. Each network address and device gets a limited number of calls, so nobody can create endless keys. Enough to try discatch on your own brand.

curl -X POST https://api.discatch.com/v1/keys/trial
# → { "key": "dk_live_…", "allowance": { "search": 100, "result": 2500, "alert": 200, … } }

3. Get the price, then search

Every call that costs money accepts dry_run: true and returns only the price. Before anything runs, discatch tells you the most it can cost, and you never pay more than that number.

curl -X POST https://api.discatch.com/v1/search \
  -H "Authorization: Bearer $DISCATCH_KEY" \
  -d '{ "query": "\"your product\"", "sources": ["hackernews", "discourse", "web"], "since": "7d", "dry_run": true }'
# → { "amount_usd_max": 0.0145, "unit_prices": { "search": 0.002, "result": 0.0005 }, "units_max": { "search": 1, "result": 25 }, "valid_for_seconds": 60, "quote_id": "q_…" }

curl -X POST https://api.discatch.com/v1/search \
  -H "Authorization: Bearer $DISCATCH_KEY" \
  -d '{ "query": "\"your product\"", "sources": ["hackernews", "discourse", "web"], "since": "7d", "quote_id": "q_…" }'

Results come back with duplicates removed and ranked. Each one carries a prescore (a rough relevance score from 0 to 1 that comes free with every result), thread counts, and the terms that matched. Deciding what is truly relevant is up to you or your assistant.

4. Set up a catch

A catch is a standing search with a delivery address. It is the same search as above, run on a schedule. When something new matches, discatch calls the address you gave it.

curl https://api.discatch.com/v1/catches \
  -H "Authorization: Bearer $DISCATCH_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "your product",
    "query": "\"your product\" OR \"yourdomain.com\"",
    "sources": ["hackernews", "discourse", "web"],
    "interval": "15m",
    "destination": { "type": "webhook", "url": "https://example.com/hooks/discatch", "secret": "whsec_…" }
  }'

5. Read the event log

Everything a catch finds is added to your account’s event log, a running record of every match. Read it from where you left off, wait on it for new entries, or stream it. Nothing is lost while your assistant is offline.

curl "https://api.discatch.com/v1/events?since=24h&limit=25" -H "Authorization: Bearer $DISCATCH_KEY"

When something goes wrong

• Every error includes a next_action field that says what to do, and it always includes a link to the doctor call.
• A 429 error (too many requests) says when to retry and which limit would lift the block.
• A 402 error (payment needed) says the exact price that was refused and how to add funds.
• An unknown address returns the doctor response, not a 404 error page.