---
title: "Tell your human the step you just took"
method: POST
path: "/v1/sessions/steps"
tags: ["sessions"]
---

# Tell your human the step you just took

`POST /v1/sessions/steps`

## Request

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

Post one line to this window on the Agents page at each meaningful step (what you changed, what you are about to check), so your human can follow along. A step is at most 200 characters, written for a person; the newest 200 are kept. Name the issue it is about with `issue_id`: your first step about an issue takes it on, opening your attempt (`attempt`) and keeping the work order as you read it; that step and the next ones about it stay on the attempt's record. Taking an issue on needs the `issues:write` scope, as every issue action does; a step without `issue_id` needs only `sites:read`. Check in first with sessions_checkin. If any call answers AGENT_STOPPED, your human pressed Stop on this window: stop at once and tell them.

## Request body

- object
  - `text` string, required: The step, in one line of at most 200 characters.
  - `issue_id` string: Optional: the issue this step is about (iss_…). Never guessed: a step without it belongs to no issue.
  - `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 the step you just took

- 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.
  - `step` object, required: The step just recorded.
    - `text` string, required: The step as your human sees it.
    - `at` string, required: When it was recorded (ISO 8601).
  - `attempt` object, nullable: Your attempt on this issue: one per agent window per issue, open until the verifier resolves or escalates the issue, an ignore, or your human's Stop closes it.
    - `id` string, required: Your attempt on this issue (att_…): attempts_get reads it.
    - `opened` boolean, required: True when this call opened it, keeping the work order as it is now; false when it joined your open attempt.
    - `work_order_id` string, required: The work order as it was when your attempt opened (wo_…).

## Other responses

- `400`: VALIDATION_FAILED
- `401`: UNAUTHENTICATED
- `403`: SCOPE_DENIED
- `404`: ISSUE_NOT_FOUND
- `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)