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

# Collecting a signed artifact

`GET /api/v1/artifacts` lists what has been signed for your organisation, and
`GET /api/v1/artifacts/{id}` hands over the bytes, exactly as they were signed.

```
GET /api/v1/artifacts
GET /api/v1/artifacts/{id}
```

```
Authorization: Bearer vitna_push_...
```

```bash
curl -H "authorization: Bearer vitna_push_..." https://vitna.ai/api/v1/artifacts
curl -H "authorization: Bearer vitna_push_..." https://vitna.ai/api/v1/artifacts/12 -o policy.json
```

This is how a signed policy reaches the machine that runs it without anybody at
Vitna running a command. Before it existed, `aperture:sign` wrote the bytes to a
row and only an operator could read them out, which is a different operator
doing the same manual step.

## Two acts, two credentials, and neither can do the other

Asking for an artifact is a write and it does not happen here. An owner of the
organisation asks at `/console/deployment`, signed in, through a role that may
write on their say-so. The signer answers on its own timer, rebuilding the
document from the record rather than signing anything it was handed.

Collecting is a read, and it happens here, with the organisation's own key.

A person signed in to the organisation, owner or member, collects the same bytes
from `/console/deployment` instead, which also prints the key that signed each
file. This route is for a machine with no session: a CI job, or a deploy script.

The route checks the key through the one database role that checks org keys,
and reads the artifacts through a role that is read-only at the role level and
cannot see a key at all. Neither can ask for an artifact, settle a request or
write one. A leaked org key can take away what was already signed. It cannot
make Vitna sign anything.

## The key

An org key with the `push` scope, minted once by an operator:

```bash
npm run org:key:create -- --org convexity --label "CI, collecting policies"
```

A router key is refused here and says so. The two are separate capabilities on
purpose: a router key spends money at a provider, and reading what your register
decided is not that. A push key presented to the router is refused the same way.

A request with no key, or with a key the record does not hold or has revoked,
answers `401` with `"code": "unauthorized"` beside the `refusals`, the same code
the rest of v1 uses for the same refusal.

A revoked key is told the date it was revoked and not the reason. The likeliest
bearer of a revoked key is whoever found it, and a member of the organisation
reads the reason beside the key at `/console/settings`.

## What a listing answers

```json
{
  "org": "convexity",
  "artifacts": [
    {
      "id": 12,
      "kind": "policy",
      "outcome": "signed",
      "at": "2026-08-31T12:04:11.000Z",
      "digest": "9f2c...",
      "decisions": [41],
      "publicKey": "MCowBQYDK2Vw...",
      "refusedBecause": null,
      "body": "/api/v1/artifacts/12"
    }
  ],
  "note": "every signed row is bytes you can take away, and every refused row is a question that was asked and declined."
}
```

**Refused rows are in the listing.** An organisation that asked for an artifact
and did not get one is owed the reason, and a listing showing only successes
would answer "what have we signed" rather than "what did we ask for". A refused
row carries `refusedBecause` and no digest, and collecting it answers `409` with
the reason rather than handing over a file that is not one.

`publicKey` is which key signed. It is the public half, the record publishes it
at `/witness`, and you need it to know which of the keys the record acknowledges
to check this against.

The newest fifty are listed, newest first.

## What a collection answers

The bytes, with `content-type: application/json`, a filename in
`content-disposition`, and the digest in `x-vitna-digest` so a caller can check
the transfer without parsing the document first.

**Byte for byte.** Not re-serialised, not pretty-printed, not wrapped in an
envelope. The signature covers these exact bytes, so anything that touched them
on the way out would break the one check you are meant to run:

```bash
npm run aperture:policy -- --verify policy.json
```

An id belonging to another organisation answers `404`, not `403`. A `403` would
confirm the id exists, which turns a list of guesses into a census of who has
signed what.

## What "short-lived" means here, precisely

`RUNTIME.md` open decision 9 calls this an authenticated short-lived download,
and it is worth saying what that turned out to be rather than implying a
mechanism that is not here.

There is no signed URL and no download token. Every request carries the
organisation's key and is authorised on the spot, so **there is no artifact URL
that works without the credential**, and therefore nothing to expire. That is a
different property from a short expiry on a link anybody holding it can use, and
a stronger one, so it is described rather than borrowed.

## What this does not do

**It does not fetch a policy for a running runtime.** Nothing here is in a
request path and no runtime calls it while serving. A runtime loads its policy
from local disk at boot; putting the file there between deploys is a
management-plane act, and a runtime that fetched its policy per request would
put Vitna's availability inside its own, which is the dependency the whole
architecture refuses.

**It does not sign.** The key is not in this process, and
`tests/environment-boundary.test.mjs` fails if anything a page can import so much
as names it.
Human Machine Shift+M