Search the docs
Find a page, a section, or an endpoint.
Threads and hand-off
Status, ownership, and giving a conversation back to a person.
A thread is a row, not a grouping key. Messages are threaded when they arrive,
by Message-ID, In-Reply-To and References, and the thread carries the
two things software needs to coordinate with a person: a status and an
owner.
Status
| Status | Means |
| -------------- | ---------------------------- |
| open | Nobody has finished with it. |
| waiting | Waiting on somebody outside. |
| resolved | Done. |
| human_review | A person needs to look. |
Owner
| Owner | Means |
| ------------ | --------------------------- |
| human | A person is reading it. |
| automation | Deterministic code owns it. |
| agent | A model owns it. |
The pair is the coordination primitive. agent + open is software working
on something; human + human_review is the same conversation, in somebody's
inbox, waiting for them.
Hand a conversation to a person
When your software is out of its depth, give the conversation back. It appears
in the inbox, and thread.handed_off tells whatever was driving that it no
longer is.
curl https://pidgeon.ai/api/v1/threads/thr_31ba9 -X PATCH -H "Authorization: Bearer $PIDGEON_API_KEY" -H "Content-Type: application/json" -d '{ "owner_type": "human", "status": "human_review" }'The SDK's handOff is the same two fields, named. It is one call because it
is one intention, and splitting it into two PATCHes is how a conversation
ends up owned by a person but not marked for review.
Taking it back
There is no automatic hand-back. A person who has been given a conversation keeps it until somebody sets the owner again, which is deliberate: software deciding on its own that a human is finished is the failure mode this exists to prevent.
Pidgeon ships no agent runtime
The API and the webhooks are the substrate you build one on. There is no prompt, no model and no loop here, and saying otherwise would be the wrong kind of promise.