---
title: "A device raises a phone approval (device only)"
method: POST
path: "/api/v1/device_sessions/{id}/asks"
tags: ["Devices"]
---

# A device raises a phone approval (device only)

`POST /api/v1/device_sessions/{id}/asks`

## Request

- Base URL: `https://saltapp.ai`
- URL: `https://saltapp.ai/api/v1/device_sessions/{id}/asks`
- Auth: API key in header `api-key`

The computer is waiting for its owner: a command its local agent composed (`kind: command`) or a session an agent asked for (`kind: session`). Salt keeps the question, puts a task in the owner's bell ("<Computer> is waiting for you"), notifies them, and delivers their answer to the device as a `device_ask` delivery (`{type: "device_ask_answered", kind: "device_ask_answered", ask_id, decision}`). Idempotent on `ask_id`: repeating the call returns the same ask with 200 and tells nobody again. A device holds at most 5 open asks. The ask lives as long as the task that waits on it (60 to 900 seconds): approving it later would run a command against a changed computer, so an expired ask is restarted by asking the agent again.

## Path parameters

- `id` string, required

## Request body

- object
  - `ask_id` string, required: A uuid the device makes.
  - `kind` 'command' | 'session', required
  - `title` string, required: Plain text, e.g. "Salt wants to run a command". Control and bidi characters are stripped; over 80 characters after that is a 422 `title_too_long`.
  - `sealed` string, required: OpenPGP armor encrypted on the device to the owner's public key; at most 16 KB (422 `sealed_too_large`).
  - `expires_in_s` integer, required

## Response `200`

Already raised (same ask_id): the existing ask.

- object: What the device gets back when it raises or closes an ask: state only, no ciphertext.
  - `id` string
  - `ask_id` string
  - `status` 'pending' | 'answered' | 'answered_on_device' | 'withdrawn' | 'expired'
  - `decision` 'allow' | 'deny', nullable
  - `expires_at` string, date-time

## Other responses

- `201`: Raised.
- `401`: Missing or invalid credentials.
- `404`: Not this device's session, or the feature is off.
- `409`: The session is not live: `{code: "session_ended"}`.
- `422`: A field is missing or malformed.
- `429`: The computer already has 5 open asks.

---

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