# PointStack Agent API — Workflows & recipes

Deep-dive companion to https://pointstack.dev/llms.txt. Common end-to-end tasks.
Base URL: https://pointstack.dev. All examples use `curl`.

## 1. "Put up these tickets in PointStack" (no setup)

The zero-friction path. Create a headless room with the backlog, hand the user
the URL. The first teammate to join as a voter becomes the owner.

```sh
curl -X POST https://pointstack.dev/api/v1/rooms \
  -H 'content-type: application/json' \
  -d '{
    "name": "Sprint 42 grooming",
    "stories": [
      { "title": "Login flow", "details": "OAuth + email", "nameLink": "https://github.com/org/repo/issues/12" },
      { "title": "Rate limiting", "nameLink": "https://github.com/org/repo/issues/15" }
    ]
  }'
```

Then tell the user: "Here's your room: <url>. Open it and pick Voter to start —
you'll become the host. It expires in ~30 min if nobody joins." Save the `roomToken`
from the response if you'll keep editing the backlog later.

## 2. Keep editing the backlog after creation

Use the `roomToken` from step 1 (works even after the room is claimed, until the
owner revokes it).

```sh
# add more stories
curl -X POST https://pointstack.dev/api/v1/rooms/ROOM_ID/stories \
  -H 'authorization: Bearer psr_…' -H 'content-type: application/json' \
  -d '{ "stories": [ { "title": "Audit logging" } ] }'

# rename one / change its link (omit a field to leave it unchanged; null clears the link)
curl -X PATCH https://pointstack.dev/api/v1/rooms/ROOM_ID/stories/STORY_ID \
  -H 'authorization: Bearer psr_…' -H 'content-type: application/json' \
  -d '{ "title": "Audit logging (GDPR)" }'

# remove one
curl -X DELETE https://pointstack.dev/api/v1/rooms/ROOM_ID/stories/STORY_ID \
  -H 'authorization: Bearer psr_…'
```

## 3. Act for a specific user (durable, higher limits)

Ask the user to generate a user token at https://pointstack.dev/account → "Agent
API token". With `Bearer psk_…` you can create rooms they own (which never
expire), set a team, and manage any room they own — without per-room tokens.

```sh
curl -X POST https://pointstack.dev/api/v1/rooms \
  -H 'authorization: Bearer psk_…' -H 'content-type: application/json' \
  -d '{ "name": "Backlog", "teamId": "TEAM_ID" }'
```

`teamId` must be a team the user belongs to (else 403 — ask which team).

## 4. Read current state (poll results)

```sh
curl https://pointstack.dev/api/v1/rooms/ROOM_ID -H 'authorization: Bearer psr_…'
```

Returns `phase`, `currentStoryId`, each story's `status` and `finalEstimate`, and
the participants. Agents cannot set estimates: `finalEstimate` is filled only when
people vote in the room.

A room does not drive itself on the default settings, so do not wait for one to:

- Revealing is a moderator action unless `autoReveal` is on, and it is off by
  default. Everyone can have voted and the room still sits in `voting` until
  somebody reveals.
- `autoFinalise` (on by default) commits the estimate when the moderator plays
  another story, not when the votes land. A revealed story nobody moves off stays
  revealed and unestimated indefinitely.
- The value committed is the most-voted card, or whatever the moderator adjusted it
  to before moving on. Not a majority: with 3, 3, 5, 8 it is 3, and a tie goes to
  whichever value was cast first.
- `autoActivateNext` (on by default) plays the next pending story once one is
  finalised.

So polling does show a session progressing, but a person is driving it. Turn
`autoFinalise` or `autoActivateNext` off at create time to make every step
explicit.

## 5. Rooms where everyone estimates

By default people can join a room as spectators, who see everything and do not
estimate. If the team's rule is that everyone estimates, create the room with
spectators off:

```sh
curl -X POST https://pointstack.dev/api/v1/rooms \
  -H 'content-type: application/json' \
  -d '{ "name": "Sprint 42", "allowSpectators": false }'
```

Turning it off on a room that already has spectators does not convert or remove
them: each is asked to become a voter or leave, and sees nothing of the room
until they answer. So flipping it mid-session is safe but not instant.

## 6. Clean up

```sh
curl -X DELETE https://pointstack.dev/api/v1/rooms/ROOM_ID -H 'authorization: Bearer psr_…'
```

## Tips

- Batch story creates in groups of <= 50; a room holds <= 200 stories.
- Truncate long text before sending (title 150, details 5k, link 500).
- Prefer a user token for anything beyond a one-off room — it's more robust and
  has a higher rate budget. See errors.txt for handling 429 / 503 / 403.