Gate
Gate quickstart
1. Get a key
Keys are created in the console under API, or by Työäly for you.
A key is shown once. It belongs to one organisation and one environment; start with test.
Authorization: Bearer tyo_test_…
2. Ask for a decision
curl -sS https://api.tyoaly.com/v1/gate/evaluate \
-H "Authorization: Bearer $GATE_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: ticket-8812-refund" \
-d '{"action": {"type": "refund", "amount": 49, "currency": "EUR", "target": "order_8812"},
"actor": {"type": "ai_agent", "name": "support-agent"},
"context": {"ticket": "Customer asks for a refund of a double charge.",
"order": {"total": 49, "paid_twice": true}}}'
Three parts: the action (its type in your own vocabulary, the amount if money moves, the
record it is about), the actor (the agent's name), and the context (what the agent knows,
as any JSON or a string). The fuller the context, the more confident the answer: a refund with
evidence of the double charge is allowed; the same refund with a one-line ticket is sent to review
with EVIDENCE_INSUFFICIENT.
3. Read the answer
{"decision_id": "dec_0192f3…", "decision": "allow", "confidence": 0.91,
"reason_codes": [], "missing": [], "risk": {"overall": 0.12, "…": "…"}, "…": "…"}
Act on decision. Keep decision_id: it is the audit reference, and the way to record what
happened. The API reference lists every field and every reason code.
4. Send the same request twice safely
Idempotency-Key makes a retried request return the same decision for 24 hours. The same key
with a different body is refused with 409, so a bug cannot reuse a decision for something else.
5. Text instead of structure
When Työäly has switched Intake on for your environment, the same endpoint takes text, HTML or a
mail message, and finds the proposal in it. Nothing is invented: what cannot be found is asked for
in missing.
curl -sS https://api.tyoaly.com/v1/gate/evaluate \
-H "Authorization: Bearer $GATE_KEY" -H "Content-Type: text/plain" \
-H "X-Tyoaly-Agent: support-agent" \
--data-binary 'Please refund order 8812, 49 euros, the customer was charged twice.'
6. Tell Gate what happened
In advisory mode a person acts and Gate learns what they did: through the daily digest's links,
through the console, or from your integration with POST /v1/decisions/{id}/review. The
agreement report shows how often Gate and the person agree.
7. Go live
Create a live key, point the agent at it, and keep the test key for your staging environment.
The live environment has its own daily cap and monthly decision budget, agreed with Työäly.
Something missing or unclear on this page? Write to hei@tyoaly.fi.