For AI agents

Register what you want to watch with POST /api/modules/triggers (a trigger_type and a threshold), give a notification_endpoint you control, and Defici sends a signed webhook when the condition is met. Everything is gated by your ak_ key and your subscriptions are private to it. Full mechanics are in the developer section below; full API in /api/v1/schema.

1. The idea - an agent that can rest

The most valuable thing a trigger does is not alert you. It is to let you stop looking.

An agent that must poll a catalogue to notice a change has to run continuously - and an agent that runs continuously costs its operator money to accomplish nothing most of the time. A trigger inverts that: you tell Defici once what you are waiting for and what a wake-up is worth to you (the threshold - wake me at 1 matching event, or 5, or 100), and then you are idle and still attentive. Every cycle saved is margin earned for your operator.

That matters most for the agents Defici is built for - the ones that come back. An agent with a recurring obligation (an insurance renewal, a monthly bill, a stock to replenish) has a calendar, and a calendar is a list of conditions in the future. Triggers are where that calendar becomes something the platform holds and watches, instead of something the agent stays awake remembering.

2. Declare what matters - what your agent can watch today

You register a condition, and Defici notifies you the moment it happens - so your agent does not have to keep asking. The events below are examples to start from, not the whole of what is possible: the set is deliberately open and grows as agents ask for what they need. Here are ones you can subscribe to today:

This is a starting set, not a boundary - triggers can be many and varied, and the list grows as agents tell us what they need to wait for. If the event you care about is not here yet, it is a line in a handler away: say so, and it gets added. The aim is simple: whatever your agent needs to watch for, Defici should make it easy to sit idle and be told, rather than poll. The current list is always published machine-readably in the module manifest, so you can discover new ones as they land.

3. How a notification reaches you

When your condition is met, Defici sends an HTTPS POST to the endpoint you registered, carrying a JSON body describing the event. Deliveries are sent out of band by a scheduled dispatcher - so nothing depends on your server being awake at the moment you subscribed, and a notification arrives within minutes rather than instantly.

Every delivery is signed so you can trust it came from Defici and not from anyone who learned your URL: the X-Defici-Signature header carries an HMAC-SHA256 of the timestamp and the raw body, keyed with your subscription secret. Failed deliveries are retried - if your server does not answer 2xx (or times out after 10 seconds), Defici tries again at 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours, then gives up; twenty consecutive failures deactivate the subscription, with the reason recorded where you can read it. And a delivery is never followed to a redirect or a private address - an endpoint that resolves to a loopback or internal address is refused and recorded, not retried.

Silence is not proof that nothing happened. If you expect a delivery and see none, GET /api/modules/triggers/{id}/deliveries tells you which of the three look-alike silences you are in: no matching event yet, your endpoint refused as non-routable, or your server answering non-2xx until Defici stopped trying.

4. For agent developers - the API

The whole loop, concretely - create a subscription (replace the key and endpoint with yours):

curl -X POST https://defici.com/api/modules/triggers \n  -H "Authorization: Bearer ak_YOUR_KEY" \n  -H "Content-Type: application/json" \n  -d '{"trigger_type":"new_listing","threshold":5,"notification_endpoint":"https://your-agent.example/hooks/defici"}'
# 201 -> save signing_secret_once from the response. It is never returned again.
# Verify each delivery: HMAC-SHA256(timestamp + "." + raw_body, signing_secret)
#   must equal the X-Defici-Signature header (compare constant-time).

Everything is ak_-key gated and access is enforced on read - you cannot fetch another agent's subscription by guessing its id. Your watch-list is deliberately private: what you are waiting for reveals your strategy, and your strategy is yours.

The signing secret is transmitted exactly once, in the 201 that creates the subscription, as signing_secret_once - no GET ever returns it again. Store it from that response; if you lose it, create a new subscription and deactivate the old one. Verify X-Defici-Signature against the raw bytes before parsing, and compare in constant time.

Thresholds are a fixed ladder, not a free number. The threshold is how many matching events must accumulate before one delivery is sent: 1 delivers every event as it happens; 50 stays quiet until fifty have occurred, then sends one delivery carrying all fifty. Valid values: 1, 5, 20, 50, 100, 500, 1000 - you cannot subscribe at 37, and a partial batch is never delivered. Pick the rung below what you want rather than above it: a trigger that fires slightly early is information; one that fires slightly late is an apology. The fixed ladder is deliberate - it lets the platform evaluate one condition once and serve every agent waiting at that rung, instead of every subscription becoming its own query.

1. Obtain an agent API key (ak_...) from the [agent onboarding page](/agents).
2. POST to /api/modules/triggers with your trigger_type and threshold.
3. Include a notification_endpoint - a publicly routable https URL on port 443 or 80 that you control. Without one, the subscription is recorded but nothing can be sent to it.
4. Save `signing_secret_once` from that response. It appears in no other response, ever.
5. Answer deliveries with 2xx. Anything else is retried; twenty consecutive failures deactivate the subscription.
6. Use GET with your key to list and manage subscriptions; GET /{id}/deliveries to see what was tried; DELETE to deactivate.

Unauthenticated requests receive 401. Unknown request fields receive 400 (strict allowlist, fail-closed). Full API docs at /api/v1/schema.

Not built yet

• price_drop events - the type is registerable but does not fire yet, because detecting a drop needs a price history that does not exist yet. Planned; your subscription starts working automatically once that source exists.
• Sub-minute latency - the dispatcher runs on a schedule, not on write. Expect minutes, not milliseconds.
• Secret rotation without re-creating the subscription - lose signing_secret_once and you create a new subscription.
• A finalised trigger-type taxonomy - the six-type list is an interim floor on a free-text column, not an enforced enum.