Loading…
Loading…
Developers · API 1.10.1
Step by step: start an alert, add a channel, rename or pause, read saved settings, and run approved paid previews and checks.
| Action | Who | How |
|---|---|---|
| Create and start an alert | The person, in Poacher | start_ gives them a link |
| Spend from the balance | The agent, after the person agrees to the ceiling | Quote, show the ceiling, then approve |
| Turn on a new channel | The person, who reads the code it received | confirm_channel with their code |
| Text-message consent | The person, after reading the disclosure | sms_consent on add_channel |
| Billing, payment methods, allowance | The person, in Poacher | Not available through the API |
list_sources, or use the search page the person is already looking at.start_ with source_url and a brief in the person’s words.The search travels in the link’s fragment, so nothing is sent to Poacher until the page opens.
Needs channels:manage. A new channel stays off until someone enters the 6-digit code sent to it, so a key can never send results somewhere nobody confirmed.
POST /channels (add_channel) with type (slack, discord, ntfy or sms) and destination. Add alert_id to put it on that alert once confirmed.POST / (confirm_channel) with the code. Five wrong codes need resend_.PUT / (set_). [] keeps results in Poacher only.{"type":"sms","destination":"+15552014477","alert_id":42,"sms_consent":{"accepted":true,"disclosure_version":"sms-consent-2026-11-12"}}Email and browser notifications are set up in the app.
Needs alerts:write. Read the alert first, then send its edit_revision.
curl -X PATCH https://app.poacher.io/api/v1/alerts/42 \
-H "Authorization: Bearer $POACHER_API_KEY" \
-H 'If-Match: "EDIT_REVISION"' \
-H "Idempotency-Key: UNIQUE_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Gatsby first editions","status":"paused"}'The response holds the new edit_revision. Retrying with the same key and body returns the first response without editing twice. Pausing stops future checks; checks already running finish and are charged. Resuming, filters, schedules and recipients stay in the app.
GET / (get_, alerts:read) returns one consistent snapshot: source URLs and form settings, each source’s interval and schedule, exact filters, the matching brief, selected channels and the accepted minimum. Credentials, recipients and internal set-up details are never included.
Keep configuration_ and send it with a replacement quote: if settings changed since, the quote is refused with configuration_.
Needs work:execute and a daily API allowance the person sets in Developer access. The allowance starts at $0 and covers all keys.
POST /previews (quote_preview) with url (or sources: 1–10 URLs, each with its own interval_ and schedule), criteria, maximum_ and an Idempotency-Key. Nothing runs yet.POST / (approve_preview) with the quote’s request_hash, using the same key. Quotes expire after 15 minutes.GET / (get_preview) with backoff for status, sample results and the receipt.POST / with {}. Work already sent finishes and is charged.{"url":"https://www.abebooks.com/servlet/SearchResults?kn=great%20gatsby%20first%20edition","criteria":"First edition, first printing, under $5,000","maximum_charge_micros":1000000}If any source fails, the preview cannot create or replace an alert, and the cost of the work done is still charged. URLs that import different exact price filters need separate previews. A preview never starts ongoing monitoring. Its review_url opens the draft in the app, where the person can start the alert.
Needs work:execute. Checks all of an active alert’s sources once, applies its filters and result review, and sends new matches to its channels.
POST /checks (quote_check) with alert_id, maximum_ and an Idempotency-Key.POST / (approve_check) with the exact request_hash.GET /checks/ID (get_check) for status and the receipt, and list_results for the matches.One check per alert can run at a time. An interrupted or cancelled check is never repeated automatically.
View this page as MarkdownAPI version 1.10.1Changelog