# Call the REST API from a script

Every tool is also an HTTP endpoint: `POST /api/agent/tools/<action>` with a JSON body. Use this for scripts, cron jobs and integrations that are not MCP clients.

The examples read the host and token from the environment:

```bash
export PICKPOST_URL=https://your-pickpost-host
export PICKPOST_TOKEN=pp_…
```

## List the actions

```bash
curl -s -H "Authorization: Bearer $PICKPOST_TOKEN" "$PICKPOST_URL/api/agent/tools"
```

The answer is a JSON array with each action's `name`, `description`, `policy` and `inputSchema`. The [tool reference](/reference/tools/) is generated from the same catalog.

## Create a draft

```bash
curl -s -X POST "$PICKPOST_URL/api/agent/tools/posts.create" \
  -H "Authorization: Bearer $PICKPOST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"body":"Hello from the Pickpost API"}'
```

```json
{"id":"5dabd24187e84ff5","status":"Draft","accountIds":[],"versions":[{"content":[{"body":"Hello from the Pickpost API","media":[]}]}],"results":[],"updatedAt":"2026-09-25T01:34:14.107650Z"}
```

Pass `accountIds` (from `accounts.list`) to choose where it will go. Without them the draft has no accounts yet, and you can pick them in the app.

## Schedule, publish, delete

These answer `403`:

```bash
curl -s -X POST "$PICKPOST_URL/api/agent/tools/posts.schedule" \
  -H "Authorization: Bearer $PICKPOST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id":"5dabd24187e84ff5","at":"2030-01-01T09:00:00Z"}'
```

```json
{"code":"ApprovalRequired","message":"'posts.schedule' needs a human to confirm it in the app.","issues":[]}
```

A person schedules the draft in the app. Unlike MCP, the REST API does not create an approval card; it only refuses. If you want the card, go through MCP. See [Approvals](/concepts/approvals/).

## Handle errors

Every error has the same shape, `{"code", "message", "issues"}`. Branch on `code`, not on the message:

| HTTP | `code` | What to do |
|---|---|---|
| 400 | `BadInput` | The JSON does not match the input schema. `message` names the field. |
| 400 | `Invalid` | The post breaks a network limit. `issues` lists each problem. |
| 401 | `Unauthorized` | Missing, wrong or revoked token. |
| 403 | `ApprovalRequired` | Needs a human in the app. Do not retry. |
| 404 | `NotFound`, `UnknownAction` | Wrong id, or a typo in the action name. |
| 409 | `Conflict` | The post changed state, for example it is already published. Re-read it. |
| 429 | `TooManyRequests` | Wait and retry. |
| 500 | `Internal` | Our fault. Retry later; the response header `x-request-id` helps us find it. |