curl --request POST \
--url https://api.reflecto.dev/v1/interactions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"question": "Deploy to production?"
}
'{
"id": "int_3f6e2a7c9b1d4f8e8a5b6c1d2e3f4a5b",
"expires_at": 1754800000
}Ask a question on your paired phone and wait for an answer
Sends a question — with 2–4 answer choices (default ["Approve","Deny"]) — to the phone paired with the user behind the bearer token. The phone shows it as a high-priority notification; the first tap wins.
Idempotent duplicates. Re-sending the same idempotency_key (or, when it’s omitted, the same question + choices from the same token) while a matching interaction is within its idempotency window (until its expires_at) returns the existing interaction with 200 instead of creating a new one — no second prompt reaches the phone. This holds even after the phone has already answered: the idempotency key outlives the answer, so a duplicate create after an answer still returns the same (now-answered) interaction’s id, not a fresh one. A genuinely new request returns 201.
Poll the result with GET /v1/interactions/{id}. Each owner may have at most 10 pending interactions at once (429 too_many_pending); the owning account must have a paired phone device (409 no_phone_device).
Phone-capability gate. If the paired phone’s reported app build is too old to show the prompt, the request is refused outright (426 phone_app_outdated) rather than accepted and silently dropped on arrival. A phone that has never reported its version is allowed through anyway (unknown builds fail open), but this is not yet surfaced back to the caller for this endpoint.
curl --request POST \
--url https://api.reflecto.dev/v1/interactions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"question": "Deploy to production?"
}
'{
"id": "int_3f6e2a7c9b1d4f8e8a5b6c1d2e3f4a5b",
"expires_at": 1754800000
}Authorizations
Opaque bearer token created on your paired Android phone. The format is rfk_live_ followed by 32 URL-safe alphanumeric characters (≥160 bits of entropy). Test tokens use the rfk_test_ prefix.
Body
The question shown on the phone. 1–1000 characters.
"Deploy to production?"
Answer labels rendered as buttons. 2–4 entries. Default ["Approve","Deny"].
2 - 4 elements["Approve", "Deny"]
Seconds until the ask expires. 60–86400, default 600.
60 <= x <= 86400600
Client-supplied dedup key; server derives one from content hashes when absent.
1 - 128Response
Idempotent duplicate — an existing interaction with the same idempotency key, still within its idempotency window (until its expires_at), was returned instead of creating a new one. No new prompt was sent to the phone. Can surface an already-answered interaction's id if the duplicate arrives after the phone answered but before expiry.