---
title: "Hand Off Goal"
method: POST
path: "/goals/{goal_id}/handoff"
tags: ["goals"]
---

# Hand Off Goal

`POST /goals/{goal_id}/handoff`

## Request

- Base URL: `https://api.imperfect.co` (the document declares no server; this is the origin it was published from)
- URL: `https://api.imperfect.co/goals/{goal_id}/handoff`
- Auth: none declared

Hand back the link that carries this browser's goal into the app (#2566).

Guarded exactly like publishing — cookie, CSRF and ``Origin`` — because it
mints a credential, and refused on an unsettled goal for the same reason
publishing is: there is no promise yet to take anywhere.

The link is one static short link with the token in its query, not a link
minted per goal. That shape is already proven in production by the channel
invite (#858), it survives a deferred install (the store round trip returns
the clicked URL with its query intact), and minting per goal would put a
vendor API key on this service for nothing.

Idempotent: asking again answers with the same link, so reloading the page
never invalidates one the athlete already sent to their phone.

## Path parameters

- `goal_id` string, required

## Response `200`

Successful Response

- GoalHandoffResponse: The link that carries this goal into the app (#2566). One field, and the token is inside it rather than beside it: the page's only job is to open the link or draw it as a QR, and a token served on its own would be a credential a client could store, log, or paste somewhere the URL never goes. Stable: asking again returns the same link, because the mint is a ``COALESCE`` — the athlete may reload their laptop after mailing the link to themselves.
  - `deep_link` string, required

## Other responses

- `422`: Validation Error

## Changes

- **2026-09-15** `28fcc77f6301`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/imperfect/apis/imperfect-api/changes/goals/:goal_id/handoff/post.md)

---

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