vitna.ai/docs/api/v1/engine/proposals Machine view
Raw .md llms.txt
> Source: https://vitna.ai/docs/api/v1/engine/proposals
> Raw Markdown: https://vitna.ai/docs/api/v1/engine/proposals.md
> Corpus index: https://vitna.ai/llms.txt

# Proposals

The decision register: what the engine proposed, what a person ruled, and the
exact rows each brief was derived from.

```
GET /api/v1/proposals
```

```bash
curl "https://vitna.ai/api/v1/proposals?status=proposed"
curl "https://vitna.ai/api/v1/proposals?workload=convexity/earnings-lens"
```

## Query parameters

| Parameter | Values |
|---|---|
| `workload` | A workload id |
| `status` | `proposed`, `accepted`, `superseded` |

## Response

```json
{
  "proposals": [
    {
      "id": 7, "workloadId": "...", "title": "...", "reason": "...",
      "outcome": "...", "status": "proposed", "decidedAt": "...", "decidedBy": null,
      "candidateSkuId": "...", "firedByTriggerId": 3,
      "inputs": { "pricePeriodIds": [ ... ], "evidenceIds": [ ... ] }
    }
  ],
  "meta": { "generatedAt": "...", "count": 12, "awaitingReview": 2 }
}
```

`meta.awaitingReview` counts proposals nobody has ruled on, which is the number
in this record that is waiting for a person.

## Human decisions are here too

Not only the engine's. A register showing the machine half would misreport what
a workload is actually doing, because human decisions are what it is doing.

`status` and `decidedBy` separate a proposal nobody has ruled on from the one
that stands.

## `inputs` is published deliberately

It names the exact `witness.price_period` and `aperture.evidence` ids the run
read. Every one of them is append-only, so a brief can be regenerated and
checked at any distance.

Publishing the verdict without them would be publishing an opinion.

## Nothing here writes

Accepting or refusing moves `status`, and that is a person's act: at a prompt as
the owning role, or at `/console` as `vitna_console`.

This is enforced below the application, and the enforcement is about the role
this endpoint runs as rather than about the schema being frozen. Two roles hold
a column-level `UPDATE` in `aperture`: `vitna_collector` marks a trigger fired,
and `vitna_console` records a ruling on a decision. **This API runs as
neither.** It reads through `vitna_site`, which holds `SELECT` and nothing else
anywhere, so no write endpoint could be added here without a migration granting
this role a privilege it has never had.

See [the decision concept](../../../concepts/decision.md) for the two grants
column by column.

## Errors

| Status | Code | Cause |
|---|---|---|
| 400 | `bad_status` | Not `proposed`, `accepted` or `superseded` |
| 503 | `record_unavailable` | Decisions are held in the record |

## Caching

`no-store`. A proposal is accepted by a person, and a stale answer says somebody
has not acted when they have.
Human Machine Shift+M