---
title: "Create a phone pairing link"
method: POST
path: "/api/task-creations/{id}/phone-links"
---

# Create a phone pairing link

`POST /api/task-creations/{id}/phone-links`

## Request

- Base URL: `https://www.toma.com`
- URL: `https://www.toma.com/api/task-creations/{id}/phone-links`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `better-auth.session_token`
  - API key in header `x-task-creation-token`

Creates a short-lived pairing URL suitable for a QR code. The secret stays in the URL fragment. A paired phone may contribute camera or audio without logging in, but cannot read other evidence, submit the agent handoff, or publish. Reopening an active link resumes the same scoped capture session.

## Path parameters

- `id` string, required

## Request body

- object
  - `requestId` string

## Response `200`

An expiring phone pairing URL. Its fragment contains a private secret; do not log or publish it.

- TaskCreationPhoneLink
  - `id` string, required
  - `url` string
  - `expiresAt` string, required
  - `status` 'waiting' | 'connected' | 'received' | 'expired' | 'revoked', required

## Other responses

- `400`: Invalid input.
- `401`: Sign in or use a valid recording capability.
- `404`: Not found, expired, revoked, or owned by another member.
- `409`: The revision, take, upload sequence, or processing state changed. Fetch the current session.
- `503`: Processing or storage is unavailable. No publication was made.

---

[API](https://skmtc.dev/toma/apis/toma-api.md) - [All operations](https://skmtc.dev/toma/apis/toma-api/llms.txt) - [OpenAPI document](https://skmtc.dev/toma/apis/toma-api/revisions/b4e56e1db5a2?raw)