> ## Documentation Index > Fetch the complete documentation index at: https://docs.anyreach.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update Handoff Connection > Update a handoff connection; unsupplied fields keep their current value. ## OpenAPI ````yaml /openapi.json put /core/handoff/connections/{connection_id} openapi: 3.1.0 info: title: Anyreach API version: 1.0.0 description: >- REST API for the Anyreach platform. Every endpoint is scoped to one organization. Authenticate with a bearer token and, if your token can reach more than one organization, name the one you mean with the `X-Anyreach-Org` header. See [Authentication](https://docs.anyreach.ai/api-reference/authentication). This reference is generated from the running service, so the request and response shapes here are the ones the API actually enforces. servers: - url: https://api.anyreach.ai description: Production security: - bearerAuth: [] tags: - name: Agents description: >- Create and configure the agent that handles a conversation, and manage its versions. An agent's behaviour lives in a version; publishing a version is what puts it on the air. - name: Conversations description: >- Create, list, retrieve, and message conversations between your users and Anyreach agents. - name: Conversation attachments description: >- Upload files into a conversation and read them back. Uploads are two-step: presign, PUT to the returned URL, then mark the attachment complete. - name: Conversation events description: >- The ordered event stream behind a conversation — turns, tool calls, transfers, and status changes. - name: Knowledge bases description: >- A knowledge base (a `dataset` in the API) is a collection of embedded content an agent can retrieve from. - name: Knowledge base sources description: Attach and detach sources to a knowledge base. - name: Sources description: >- A source is a file or URL whose content is ingested, chunked, and embedded. - name: Phone numbers description: >- Buy, list, and release phone numbers, and point each one at the agent that should answer it. - name: Trunks description: >- SIP trunks for bringing your own carrier. A trunk carries calls between your carrier and Anyreach. - name: Inbound routing description: >- Rules that decide which agent answers an inbound call, evaluated before the call connects. - name: Agent assist description: >- Look up the live-assist context for a number so a human agent can see what the AI agent knows. - name: Human handoff description: >- Connections to the help desk a conversation escalates into, and the test endpoint that proves one works. - name: Email domains description: >- Register a sending domain and verify its DNS before an agent can send from it. - name: Email addresses description: >- The addresses on a verified domain, and the agent that handles mail arriving at each one. - name: Unsubscribes description: >- The suppression list. An address on this list is never emailed again until it is removed. - name: Web widgets description: >- The embeddable chat and voice widget: its appearance, its allowed domains, and the agent behind it. - name: Campaigns description: >- An outbound campaign dials a contact list with a given agent on a given schedule. Start, pause, and close control its lifecycle. - name: Campaign contacts description: >- The people a campaign dials. Contacts can be added while the campaign is running. - name: Campaign configurations description: >- Reusable dialing settings — calling windows, retry policy, timezone handling — that campaigns reference. - name: Campaign stats description: >- Per-campaign outcome counters, and the organization-wide cap on how many calls run at once. - name: Custom data description: >- Your own tables, queryable by an agent mid-conversation. Define a table, load rows, and expose read-only stored queries as agent tools. - name: Metrics description: >- The definitions an LLM judge scores a conversation against. Lint and preview a metric before you run it at scale. - name: Evaluations description: A scorecard binding a set of metrics to a population of conversations. - name: Evaluation runs description: >- One execution of an evaluation over a conversation set, and the results it produced. - name: Workflows description: >- Automations built from steps. A workflow is edited as a version and goes live when a version is published and set live. - name: Workflow triggers description: >- What starts a workflow — a schedule, a webhook, or a point in an agent conversation. Triggers are versioned alongside the workflow. - name: Workflow executions description: >- Run a workflow and read back what happened. Executions are synchronous by default; use the async endpoint for long-running work. - name: Workflow credentials description: >- Secrets a workflow step authenticates with. Values are write-only — they can be set and rotated, never read back. paths: /core/handoff/connections/{connection_id}: put: tags: - Human handoff summary: Update Handoff Connection description: Update a handoff connection; unsupplied fields keep their current value. operationId: updateHandoffConnection parameters: - name: connection_id in: path required: true schema: type: string title: Connection Id - name: x-anyreach-org in: header required: false schema: anyOf: - type: string - type: 'null' description: Organization ID for user PATs (pat_ prefix tokens) title: X-Anyreach-Org description: Organization ID for user PATs (pat_ prefix tokens) requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/HandoffConnectionUpdateRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/HandoffConnectionResponse' example: id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 organization_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 provider: string name: Example auth_details: {} has_webhook_secret: false settings: no_reply_after_seconds: 180 idle_close_after_minutes: 120 context_mode: summary enabled: true created_at: '2026-01-15T09:30:00Z' updated_at: '2026-01-15T09:30:00Z' created_by: user:3fa85f64-5717-4562-b3fc-2c963f66afa6 modified_by: user:3fa85f64-5717-4562-b3fc-2c963f66afa6 '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - HTTPBearer: [] components: schemas: HandoffConnectionUpdateRequest: properties: name: anyOf: - type: string - type: 'null' title: Name auth_details: anyOf: - $ref: '#/components/schemas/HandoffAuthDetails' - type: 'null' webhook_secret: anyOf: - type: string - type: 'null' title: Webhook Secret settings: anyOf: - $ref: '#/components/schemas/HandoffConnectionSettings' - type: 'null' enabled: anyOf: - type: boolean - type: 'null' title: Enabled type: object title: HandoffConnectionUpdateRequest description: >- Body for ``PUT /handoff/connections/{id}``. Every field is optional and only the ones actually supplied are written, so a rename never has to re-send the credentials. Credentials can be rotated through this route but not cleared — an empty ``auth_details`` is rejected by the schema. HandoffConnectionResponse: properties: id: type: string title: Id organization_id: type: string title: Organization Id provider: type: string title: Provider name: type: string title: Name auth_details: additionalProperties: true type: object title: Auth Details has_webhook_secret: type: boolean title: Has Webhook Secret default: false settings: $ref: '#/components/schemas/HandoffConnectionSettings' enabled: type: boolean title: Enabled default: true created_at: anyOf: - type: string format: date-time - type: 'null' title: Created At updated_at: anyOf: - type: string format: date-time - type: 'null' title: Updated At created_by: anyOf: - type: string - type: 'null' title: Created By modified_by: anyOf: - type: string - type: 'null' title: Modified By type: object required: - id - organization_id - provider - name title: HandoffConnectionResponse description: >- A handoff connection as any caller is allowed to see it. Explicitly modelled rather than returning the entity, so no future field added to ``HandoffConnection`` can leak a credential by default. ``auth_details`` here is the ``{base_url, username}`` pair only. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError HandoffAuthDetails: properties: base_url: type: string title: Base Url username: type: string title: Username api_token: type: string title: Api Token type: object required: - base_url - username - api_token title: HandoffAuthDetails description: >- Credentials for one handoff connection (``handoff_connections.auth_details``). Deliberately stored on the connection row rather than in the agent config: agent configs are versioned and snapshotted onto every conversation, so a token in there would be copied into thousands of rows (PRD §6). HandoffConnectionSettings: properties: no_reply_after_seconds: type: integer minimum: 1 title: No Reply After Seconds description: >- Post the rule's waiting message when no human has replied for this long. default: 180 idle_close_after_minutes: type: integer minimum: 1 title: Idle Close After Minutes description: >- Close an idle handoff — and finalize the conversation — after this long with no activity. default: 120 context_mode: type: string enum: - summary - transcript - both title: Context Mode description: What the human agent is handed when the handoff opens. default: both type: object title: HandoffConnectionSettings description: >- How this helpdesk behaves — as opposed to how to reach it. These sit on the connection rather than on an escalation rule because they describe the HELPDESK, not the route: how fast that team answers and what context it wants to receive. Change one here and every agent routing through this connection follows, which is the point — an SLA is not a per-agent setting. Customer-facing copy deliberately does NOT live here. It is spoken in the agent's voice and language, and one connection is shared by every agent in the org, so a shared waiting message would put the wrong language in front of somebody. That stays on the rule. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError securitySchemes: bearerAuth: type: http scheme: bearer description: Personal access token or organization API key. See Authentication. ````