Get started

Your organisation's feed

Source

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.

text
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, 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.kindOther keys in _vitna
proposaldecisionId, workload, outcome, status, candidate, firedByTriggerId
trigger_firedtriggerId, 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 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:

text
{ "error": { "code": "unknown_feed", "message": "..." }, "meta": { ... } }
Statuserror.codeWhen
404unknown_feedThe address is not a live one
503record_unavailableThis instance cannot read the register
503not_configuredThis 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.