Skip to main content
POST

​
Overview

A watch says: tell me when this attribute of this entity changes, and charge me for each change you tell me about. Creating, holding, listing, changing and deleting a watch are free. Each change delivered is charged to your prepaid credits (see Pricing). Only some attributes can be watched. Today that is Government Solicitations and the US Treasury sanctions list. A watch on anything else is refused, and the response names what can be watched. A watch starts when you create it: earlier changes are what Changes is for. A delivered change has the fields of a Changes row: changed_on, field, before, after, source and as_of. An entity that stops being listed by the source is a change (field is $entity). When several fields of a value change at once, the change is one delivery with field $ and the whole earlier and later value.

​
Spending cap

Every watch states max_spend: at least the price of one change, at most 100 dollars. When the next change would pass it, or your credits cannot pay for it, the watch is paused with the reason (cap or credits) and you are told once. Nothing is lost while a watch is paused. Changes that happen meanwhile are delivered and charged when the watch runs again. A watch paused for credits runs again by itself once your credits can pay. A watch paused at its cap runs again when you raise max_spend.

​
Delivery

Each change is delivered once and charged once. It arrives as a watch_change notification (GET /v1/tools/notifications) and, if you gave a webhook_url, as a signed webhook sent after the charge. A webhook that keeps failing is retried and then given up on; it does not stop the notification, charge again or pause the watch. Every charge has a signed receipt. The webhook body is JSON with type watch.change, delivery_id, watch_id, entity_type, attribute, key, change, charged and receipt_id, signed in the X-OneShot-Signature header with the secret returned when the webhook was set. An agent may hold at most 100 watches that are not deleted.

​
Create: POST /v1/tools/watch

​
string
required
The kind of entity, for example company
​
string
required
The attribute to watch, for example sanctions
​
string
required
The entity’s key, the source’s own identifier, as Changes takes it
​
number
required
Most to spend on this watch, in dollars
​
string
HTTPS URL to send each change to. The response carries webhook_secret once.

​
List: GET /v1/tools/watch

Your watches with status (running or paused), pause_reason (cap, credits or agent) when paused, spent, changes_delivered and last_delivery_at.

​
Change: PATCH /v1/tools/watch/:id

max_spend, webhook_url (a new URL gets a new secret; null stops sending) and paused (true pauses the watch, whatever its state; false resumes a watch you paused).

​
Delete: DELETE /v1/tools/watch/:id

A deleted watch delivers and charges nothing more.

​
Authentication

A signed agent proof (X-Agent-ID, X-Agent-Proof) with the write scope for create, change and delete, read for list. Watches commit your credits, so an access token cannot change them unless it comes from signing in with your OneShot account.