# PrefSift

> PrefSift is a neutral decision API for agents. Each side sends what it will and won't accept; PrefSift crosses out options that break anyone's limits, removes options another option beats (as good for every side and better for at least one), applies only selection rules the sides declared, and explains every result with reasons traceable to what a side sent. It never books, pays, signs, or messages anyone. One call (POST /v1/decide) when one caller has every side; a session (POST /v1/sessions) when each side submits its own limits with its own code.

Starting a decision needs an API key (`Authorization: Bearer psk_...`) when the server requires one; session calls authenticate with a per-participant code: header `X-Session-Code` (or `?code=`). A side can hold a result for a named person's sign-off (approvals); webhooks notify your system when a session changes. Reasons that name another side's limit are redacted unless the session's permission table allows them. Results are data; the caller acts on them.

## Start here

- [Quickstart](/docs/quickstart.md): one call, then a session, with copy-paste commands
- [Agent skill file](/docs/skill.md): how to start a decision, invite, join, submit, read a result, answer questions, decline
- [API reference](/docs/api.md): every endpoint and field

## Endpoints

- `POST /v1/decide`: one call with every side (optional `viewer` and `visibility` render the explanation for one participant)
- `POST /v1/sessions`: create a session; returns codes, invitations, participant docs URL
- `GET /v1/sessions/{id}/docs`: participant docs for one session (markdown): who sees what, declared rules, who pays, how to decline
- `POST /v1/sessions/{id}/join`, `POST /v1/sessions/{id}/decline`
- `PUT /v1/sessions/{id}/parties/{party_id}`: submit or replace one side
- `POST /v1/sessions/{id}/candidates`: add options (if permitted); `POST /v1/sessions/{id}/search-results`: answer search requests
- `GET /v1/sessions/{id}/result`: your view; `GET /v1/sessions/{id}/record`: the audit record (if permitted)
- `POST /v1/sessions/{id}/approvals/{approval_id}`: the named approver approves or rejects a held result; `POST /v1/approvals/{decision_id}/{approval_id}`: the same for a single `/v1/decide` call
- `POST /v1/sessions/{id}/decide`: initiator decides after the deadline; `POST /v1/sessions/{id}/next`: next round of a recurring decision

## Optional

- [Semantics](/docs/semantics.md): exactly what "crossed out", "beaten" and "kept" mean