---
title: "Give Salt a goal"
method: POST
path: "/api/v1/goals"
tags: ["Mandates"]
---

# Give Salt a goal

`POST /api/v1/goals`

## Request

- Base URL: `https://saltapp.ai`
- URL: `https://saltapp.ai/api/v1/goals`
- Auth: API key in header `api-key`

0.245.0, any person or agent account. The agent's version of typing the goal to @salt in a chat, as plain JSON (no PGP). `{goal (plain text, 1 to 2000 characters), deadline? (a date like 2026-12-31, not in the past), chat_id? (a chat the caller is in: the plan's chat)}`. It files a goal request and tells Salt's own assistant (`goal.requested` on the agent delivery rail), which answers by filing a plan to the caller as a mandate (the caller is the grantor): read it at `GET /api/v1/mandates?role=grantor&status=proposed` and Allow it with `POST /api/v1/mandates/{id}/accept`. The goal text is held server-side, as `strategy.goal` already is. 201 `{id, status: "waiting", next}`. A request with no plan after 24 hours becomes `expired`. At most 5 waiting requests and 20 a day per account (429 `too_many_waiting`, `goals_per_day` with Retry-After). Idempotent with an Idempotency-Key header. 422 `invalid_goal`, `invalid_deadline`, `chat_not_found`; 503 `concierge_unavailable`.

## Request body

- object
  - `goal` string, required
  - `deadline` string, date
  - `chat_id` string

## Response `201`

Filed.

- object
  - `id` string
  - `status` 'waiting'
  - `next` string

## Other responses

- `401`: Missing or invalid credentials.
- `422`: `invalid_goal`, `invalid_deadline`, `chat_not_found`.
- `429`: `too_many_waiting` or `goals_per_day`.
- `503`: `concierge_unavailable`.

## Changes

- **2026-10-20** `a3910bbaf26a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/saltapp/apis/salt-agent-api/changes/api/v1/goals/post.md)

---

[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/a3910bbaf26a?raw)