---
title: "Check in with the task you are working on"
method: POST
path: "/v1/sessions/checkin"
tags: ["sessions"]
---

# Check in with the task you are working on

`POST /v1/sessions/checkin`

## Request

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

Tell your human what you are doing: check in once at the start with a one-line task, and Frontshelf's Agents page shows it on this window, live. This window is you: your agent tool and the `session` you send on every call (send the same one from this conversation), never an argument. Name the site, and the issue when you work on one. Checking in again replaces the task and makes a finished window working again. Next: send a step with sessions_step at each meaningful step, and finish with sessions_finish when you are done. If any call answers AGENT_STOPPED, your human pressed Stop on this window: stop at once and tell them.

## Request body

- object
  - `task` string, required: What you are working on, in one line of at most 200 characters, written for your human.
  - `site` string: Site ID (site_…), origin (https://example.com), or bare domain, resolved server-side; the response carries the canonical ID. Optional: the site you work on.
  - `issue_id` string: Optional: the issue you work on (iss_…), as issues_list gives it. Its site is the window's: leave site out, or name that same site.
  - `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`

Check in with the task you are working on

- 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 as your human sees it now.
    - `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
- `404`: SITE_NOT_FOUND, ISSUE_NOT_FOUND
- `409`: AMBIGUOUS_SITE, 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)