> 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.