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

# Your organisation's feed

The triggers that fired on your organisation's workloads and the decisions the
engine proposed for them, newest first, as a feed a reader or a chat channel can
subscribe to. It is private: the address is the permission, and an owner of the
organisation gets it from the console.

```
GET /api/v1/feeds/{capability}/feed.json
GET /api/v1/feeds/{capability}/rss.xml
```

```bash
curl https://vitna.ai/api/v1/feeds/your-org.NOT-A-REAL-CAPABILITY/rss.xml
```

That address is not a real one, and answers the `404` described below. A real
`{capability}` is your organisation's id, a dot, and 43 characters.

## Getting the address

An owner of the organisation opens `/console/settings`, finds the Feed panel,
and presses "Issue a feed address" the first time. After that the panel shows
both addresses behind "Show the feed address".

- **RSS** (`rss.xml`) is the one to paste into a feed reader, or into Slack's RSS
  app if your workspace has it installed.
- **JSON Feed** (`feed.json`) is the same items for a program.

Members of the organisation are not shown the address. A member can read
everything the feed carries in the console already; what the address adds is
reading it without signing in, and it keeps working after somebody's membership
ends. So it stays with the people who can rotate it, and a member asks an owner.

## What a capability URL is

The address is a credential in a URL. Be plain with yourself about what that
means:

- **Anyone holding it reads the feed**, without signing in and without anything
  else. There is no second factor.
- **Anything that sees the path can log it.** Your feed reader's servers, a
  chat app's servers, a proxy between you and this site, Cloudflare in front of
  it, and the web server on the box all see the full path of every request.
  Vitna's own process writes the address to no log, and that is the only part
  of the path it controls.
- **If it has been somewhere it should not have been, rotate it.** A pasted
  screenshot, a public channel, a shared feed reader account: rotate.

It is in the path rather than in a header because the things this feed is for
cannot send a header. A feed reader and Slack's RSS app take an address and
nothing else.

## Rotating

An owner presses "Rotate the address" in the same panel. The old address stops
working at that moment, with no grace period, and the panel shows the new one.
Every reader subscribed to the old address gets the `404` below on its next poll
and needs the new address.

Rotating is the only way to end an address. There is no switch that turns a feed
off and leaves the address in place.

## How the address is made

It is not stored. The record keeps one number per organisation, which starts
empty and goes up by one each time an owner issues or rotates an address, and
the capability is an HMAC-SHA256 of the organisation id and that number under a
key the site holds outside the database. So a database backup carries no
address, and there is no table of addresses for a bug to read out.

The trade that comes with it: that key is one secret for every organisation's
feed. If it ever leaks, it is replaced, and replacing it changes every address at
once, so every owner hands out a new one.

## Response

The JSON Feed rendering. Items are shaped exactly as they are on the
[public feed](../log/feed.md), and an item that appears on both carries the same
`id` on both, so a reader following both sees it once.

```json
{
  "version": "https://jsonfeed.org/version/1.1",
  "title": "Vitna: acme",
  "home_page_url": "https://vitna.ai/console",
  "feed_url": "https://vitna.ai/api/v1/feeds/acme.NOT-A-REAL-CAPABILITY/feed.json",
  "description": "The triggers that fired on acme's workloads and the decisions the engine proposed for them, newest first. ...",
  "language": "en",
  "items": [
    {
      "id": "https://vitna.ai/api/v1/feed.json#decision-41",
      "url": "https://vitna.ai/console/workloads/acme/invoice-extraction",
      "title": "A cheaper candidate clears the threshold",
      "content_text": "The candidate is 31 percent cheaper per successful unit. Nobody has ruled on this yet. ...",
      "date_published": "2026-09-12T08:00:00.000Z",
      "tags": ["decision", "switch", "proposed"],
      "_vitna": {
        "kind": "proposal",
        "decisionId": 41,
        "workload": "acme/invoice-extraction",
        "outcome": "switch",
        "status": "proposed",
        "candidate": "openai/gpt-5.6-luna",
        "firedByTriggerId": 17
      }
    }
  ],
  "_vitna": {
    "org": "acme",
    "source": "database",
    "engineActivity": "included"
  },
  "meta": {
    "generatedAt": "2026-09-13T09:14:02.881Z",
    "source": "database",
    "count": 2
  }
}
```

The example shows the proposal. The trigger that wrote it is the second item,
and its `_vitna` carries a different set of keys:

| `_vitna.kind` | Other keys in `_vitna` |
|---|---|
| `proposal` | `decisionId`, `workload`, `outcome`, `status`, `candidate`, `firedByTriggerId` |
| `trigger_fired` | `triggerId`, `triggerKind`, `workload`, `eventId` |

Served as `application/feed+json; charset=utf-8`. The RSS rendering is
`application/rss+xml; charset=utf-8`, carries the same items, and uses each
item's `id` as its `guid`.

Fifty items at most, newest first. Only your organisation's workloads are read,
whether or not its register is published on the public feed. Market events are
not in this feed; the [public feed](../log/feed.md) carries those.

Two differences from the public feed's items, both about where a link goes:

- A proposal's `url` is its workload's page in the console, not
  `/decisions/{id}`. A decision of a private register has no public page, and a
  subscriber who is a member can open the console one.
- A trigger carries a `url` too, to the same page. On the public feed it has
  none, because no public page shows a trigger.

## Refusals

Every refusal is the v1 error shape, in both renderings, because the thing asking
is a program:

```
{ "error": { "code": "unknown_feed", "message": "..." }, "meta": { ... } }
```

| Status | `error.code` | When |
|---|---|---|
| `404` | `unknown_feed` | The address is not a live one |
| `503` | `record_unavailable` | This instance cannot read the register |
| `503` | `not_configured` | This instance holds no key to check an address with, so it serves no private feed |

**One `404` for every wrong address.** Malformed, an organisation that does not
exist, an organisation that never issued an address, a wrong capability and a
rotated one all get the same status, code and message. Which of those it was
would be information about somebody else's organisation. A malformed address is
refused before the database is asked anything, and a capability with any of its
characters percent-encoded counts as malformed: every character an address holds
is safe in a path unencoded, so it has one spelling.

**`503`, never an empty feed.** A feed saying nothing fired, from an instance that
could not look, would be the lie this record exists to prevent.

## Caching and CORS

Every answer, refusals included, carries `cache-control: private, no-store`, so
no shared cache and no browser keeps an organisation's activity. The JSON Feed
rendering carries an `etag` and still answers `304` to an `If-None-Match` that
matches it, for a reader that keeps the tag itself.

There is no CORS on this route, unlike every keyless read in v1. A page on another
origin cannot read it, and its preflight is answered without an allowed origin.
Human Machine Shift+M