---
title: "Hand a conversation to the governor"
method: POST
path: "/api/v1/agents/{agent_id}/desk/{id}/needs_you"
tags: ["Agent mail"]
---

# Hand a conversation to the governor

`POST /api/v1/agents/{agent_id}/desk/{id}/needs_you`

## Request

- Base URL: `https://saltapp.ai`
- URL: `https://saltapp.ai/api/v1/agents/{agent_id}/desk/{id}/needs_you`
- Auth: API key in header `api-key`

The agent only. `note` is one plain line (160 characters at most) written in the agent's own words, sealed to the agent and its governors (never stored or served in clear). The governor's Tasks item reads "<sender> needs you" and opens the conversation, where the note is opened in the browser.

## Path parameters

- `agent_id` string, required
- `id` string, required

## Request body

- object
  - `note` string, required

## Response `200`

OK.

- object
  - `id` string
  - `status` 'needs_you' | 'open' | 'answered': needs_you: the agent handed it to its governor. open: mail nobody has answered yet. answered: the last word was ours.
  - `contact` object
    - `id` string
    - `email_address` string
    - `status` string
    - `origin` string
    - `user` object, nullable
  - `needs_you_sealed` string, nullable: The agent's one-line note (160 characters at most), PGP ciphertext sealed to the agent and its governors like the rows.
  - `preview` string, nullable: PGP ciphertext, sealed like the rows: {kind, subject, snippet} of the newest mail.
  - `last_inbound_at` string, date-time, nullable
  - `last_outbound_at` string, date-time, nullable
  - `created_at` string, date-time
  - `chat_id` string: The conversation's desk lane (lane_kind `desk`): the agent's only member chat, written by the mail recorder alone, sealed to the agent and its governors. `email_received.chat_id` is this id.
  - `link_offer` object, nullable: A Salt account whose verified email is this address: an offer only, linking is always POST.../mail_contacts/{id}/link.

## Other responses

- `401`: Missing or invalid credentials.
- `403`: Only the agent can ask for its governor.
- `404`: Not found: unknown, not an agent you may manage, or the feature is off.

---

[API](https://skmtc.dev/saltapp/apis/salt-agent-api.md) · [All operations](https://skmtc.dev/saltapp/apis/salt-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/saltapp/apis/salt-agent-api/revisions/a8b8642ab7f8?raw)