Get started

Proposals

Source

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

text
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

ParameterValues
workloadA workload id
statusproposed, 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 for the two grants column by column.

Errors

StatusCodeCause
400bad_statusNot proposed, accepted or superseded
503record_unavailableDecisions 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.