---
title: "Tell your human you are done"
method: POST
path: "/v1/sessions/finish"
tags: ["sessions"]
---

# Tell your human you are done

`POST /v1/sessions/finish`

## Request

- Base URL: `https://frontshelf.io/api`
- URL: `https://frontshelf.io/api/v1/sessions/finish`
- Auth: HTTP bearer

Mark this window finished on the Agents page when your task is done, with an optional one-line summary your human reads. Checking in again later starts a new task on the same window. If any call answers AGENT_STOPPED, your human pressed Stop on this window: stop at once and tell them.

## Request body

- object
  - `summary` string: Optional: what you did, in one line of at most 200 characters.
  - `dry_run` boolean: true: check the call and say what it would do, without doing it.
  - `confirm` boolean: true: go ahead with a change that asks for confirmation.

## Response `200`

Tell your human you are done

- object
  - `summary` string, required: The answer in one or two sentences, with the numbers it rests on.
  - `warnings` string[], required: What limits this answer (a cap, a read that was cut short). Empty when nothing does.
  - `next_actions` object[], required: What to call next, best first. Follow them.
    - `capability` string, required: What to call next: a capability.
    - `arguments` object, required: Its arguments, complete; pass them as they are.
    - `instruction` string, required: What to do, written to you.
  - `session` object, required: This window, now finished.
    - `id` string, required: This window's id (ags_…) on the Agents page.
    - `agent` string, required: The agent tool Frontshelf read from your call.
    - `task` string, nullable, required: The task you checked in with; null before a check-in.
    - `site_id` string, nullable, required: The site this window works on, when one is known.
    - `state` 'working' | 'idle' | 'finished' | 'stopped', required: What your human sees: `working`, `idle` (no call for 15 minutes), `finished` or `stopped`.

## Other responses

- `400`: VALIDATION_FAILED
- `401`: UNAUTHENTICATED
- `403`: SCOPE_DENIED
- `409`: AGENT_STOPPED
- `503`: DEPENDENCY_UNAVAILABLE

---

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