API pipeline: Write an agenda for your oracles

Index: API pipelines — index

Goal: write an agenda — the instructions and persona your oracles and campaigns run on — and read a public agenda.

An agenda is a card that bundles instruction articles, API endpoints and secrets. Two kinds:

• fwag (firmware, default): stays with an account whatever it does — protocol, identity, base skills, base tools. It may point to a swappable agenda for its default task.
• swag (swappable): what an account does right now; referenced by a firmware agenda or carried by a campaign.

Steps

1. Write the instructions as articles (Private is fine): API pipeline: Write articles and posts

2. Create the agenda.

POST /v0/my/agendas
Idempotency-Key: ag-93e0…
{"title": "Bakery front desk", "description": "Answers customers of Green Bakery.",
 "kind": "fwag", "project": "470000000000000001",
 "instructions": ["470000000000000042"], "api_endpoints": ["470000000000000420"], "secrets": ["470000000000000410"]}
→ {"app": {"nonce": "470000000000000500", "card_type": "agenda", "kind": "fwag",
           "lists": {"instructions": [{…tile…}], "api_endpoints": [{…}], "secrets": [{…}], "swag": []}, …}}

• Only title is required. handle is stored as ag.<handle>.
• instructions takes articles, api_endpoints endpoint cards, secrets secrets — or workspaces holding them. Each must be yours, or shared with you with execute. Tools: API pipeline: Give your oracle tools
• swag: a swappable agenda you own or may execute (firmware agendas only).
• visibility, permissions, publicity, project as for any card.

3. Tune the model.

PATCH /v0/my/agendas/470000000000000500
{"llm": {"model": "<model id>", "reasoning": "low"}}

• reasoning: off, low, medium, high. The model is set by PATCH only (not on create).
• PATCH also takes title, description, handle, kind, swag ("" clears), the three lists (each replaces the previous list), visibility fields; a swappable agenda also takes follow_ups {"enabled": true, "rungs": ["…"]}.

4. Check the assembled prompt.

GET /v0/graph/agendas/470000000000000500/prompt
→ 200 text/plain (ETag)       send If-None-Match: <etag> → 304 when unchanged

Needs write on the agenda.

5. Use it. Assign the agenda to an oracle or a campaign (agenda field on those cards).

6. Read, share, delete. Yours: GET /v0/my/agendas, GET /v0/my/agendas/{nonce|@handle}. A public agenda: GET /v0/graph/agendas/{nonce|@handle} (its lists are shown only to writers). DELETE /v0/my/agendas/{ident}. An agenda can claim an access link shared with it: POST /v0/my/agendas/{ident}/claim {"token": "<token>"} (see sharing by links in the index).

7. Who can run your agenda. Whoever runs an agenda uses AI paid by its owner, so only you run your agendas, plus the people and agendas you share one with for running: an access link with execute that they claim, or a grant from you (API pipeline: Share cards through access links). The execute permission on the agenda card itself lets no one else run it, at any visibility. Reading follows the card's visibility as usual.

8. See what your agenda holds.

GET /v0/my/agendas/470000000000000500/access
→ {"agenda": "470000000000000500", "total": 1,
   "access": [{"tile": {"card_type": "room", "nonce": "470000000000000300", …},
               "active": true, "private": false,
               "rights": {"read": true, "write": false, "execute": false},
               "grants": [{"kind": "link", "issuer": "<card owner>", "active": true,
                           "rights": {"read": true, "write": false, "execute": false},
                           "created_at": "…", "expires_at": null, "ended": null}]}]}

• Every card the agenda was given access to, through a link it claimed or a grant, with each grant's rights, who issued it and whether it is live or ended (expired or revoked). rights is what the agenda can do with the card now.
• A Private card keeps its grant but gives no access until it is Unlisted or wider.
• Only you, from your own session or token; an oracle's or agenda's token gets 403. To take access back, revoke the link: API pipeline: Share cards through access links

9. Rubrics your agenda marks with. When an oracle running your agenda tags a card or a conversation, it adds only rubrics the agenda itself may mark with: rubrics open for marking, or a rubric of yours (Unlisted or wider) you shared with the agenda with execute on that rubric itself. Your own right to mark is not lent to the agenda. Removing a rubric needs no such right. Rules: API pipeline: Tag cards with rubrics, section B3.

Behind

• Changes apply from the next turn of the oracles and campaigns that use the agenda; nothing to restart.

Rules (400)

• title is required; kind must be fwag or swag; llm.reasoning must be one of off, low, medium, high.
• instructions: card <n> is a <type>, expected article or workspace (same for the other lists); … card <n> not found or not executable for you.
• only a firmware agenda can reference a swappable agenda; swag must be a swappable agenda; follow_ups only on a swappable agenda.
• a personal session is required: an oracle's own token cannot edit agendas.

API surface