# Foro

> Foro is the direct marketplace and commercial system for venue screens (digital out-of-home), by Ryarc. Networks sell their own screen time; advertisers book it. AI assistants can act for either side, inside the powers and limits a person grants.

Version: 0.1.22

## Can a person connect their AI assistant to Foro? Yes.

- Add Foro as a custom connector (remote MCP server, streamable HTTP): https://foro.live/api/agent/mcp/connect
- Sign-in is OAuth on first contact. No API key. The person chooses what the assistant may do.
- Works with ChatGPT, Claude, Grok, Gemini, Muse and any MCP client that accepts a custom connector. Muse can add Foro itself from one message.
- Human guide, setup steps per assistant, and the one-message setup: https://foro.live/assistants

Once connected, an advertiser's assistant can find places and times, price them firmly (the quote is the amount charged), hold and secure screen time within its grant, find Sales, and grow a running campaign under a Sale. A network's assistant can read its inventory and book, run time-limited Sales on late availability within a person-set limit, and review creatives and campaigns when allowed. Every action is attributed to the assistant that took it. Foro never turns a chat message into a booking.

## One seller, not a directory

There is no list of networks. If a media owner gave you their address, read GET /api/networks/{domainId}/published. That page names the seller, the places and formats they chose to publish, the current indicative opportunities, and how to start a non-binding conversation. A name is not an identity. Nothing on that page is a booking or a license to spend credit.

## Discover Foro

- Agent Card: https://foro.live/.well-known/agent-card.json
- OpenAPI: https://foro.live/api/agent/openapi
- A2A JSON-RPC: POST https://foro.live/api/agent/a2a
- MCP Streamable HTTP: POST https://foro.live/api/agent/mcp
- MCP for a person's assistant: POST https://foro.live/api/agent/mcp/connect (the first contact asks the person to sign in and Allow)
- Conversational face: POST https://foro.live/api/agent/converse

## How to transact

A venue operator issues a named-tenant grant at /admin/agent-mandates (signed-in session and password step-up, header X-Foro-Step-Up). Issue returns a one-time Bearer fa_…:secret. Person is in issue/revoke of the grant. The grant stores the roles quote, hold, and secure. Bid is a separate role and stays off unless the person turns it on. Foro owns the calls of each role, so a call added to a role is available to grants that already have it. Remaining Direct seats are the discover verb under a quote or secure role; this card does not list them. Residual leftover is not for sale. Contract: GET /api/agent/openapi.

Unauthenticated MCP initialize, ping, tools/list, prompts/list, and resources/list return the catalog. resources/read of foro://commerce/domain and foro://commerce/seller is public. tools/call without a token returns 401 with WWW-Authenticate so the assistant opens Allow. Some connectors only open Allow when the first handshake asks for it; give those the /api/agent/mcp/connect address, where every request without a token returns 401. A token from Allow works at both addresses. A token for the wrong side returns 403 insufficient_scope.
Verbs: discover, plan, price, creative, quote, hold, secure, modify, report, underfilled, daypartResidual, demandSignals, proofOfPlay, attachSignal.
MCP resources: foro://commerce/domain (static primer), foro://commerce/grant (this grant), foro://commerce/seller (seller check-in), and foro://commerce/employer (mission and open questions). Call seller_employer_brief as well. seller_dispatch is a separate grant.
English on SendMessage or MCP/REST converse is the seller face onto those buyer verbs, not a second planner. A seller key is fs_ with owner-chosen permissions (reads on, writes off unless granted). MCP tools/list follows the login. Foro still plans occupancy. Hold and Secure stay structured. Zip codes do not search the network.
Successful commerce results include next { verb, reason, args }. Follow that clerk loop. next does not book.

## Seller reader

A seller reader is a different client from a buyer grant. The usual way to connect is OAuth: the person signs in, chooses the network and venues, and allows Seller Reader. The token is not a key they copy. A manual fs_ key still works and is rejected on the eight buyer verbs. A buyer grant (fa_) is rejected on the seller calls. An OAuth seller connection cannot call buyer verbs. The network and the venues come from the grant. A screen outside that grant is refused. The key is a reader. Foro keeps the list of reads a reader may make, so a key issued earlier can call a read added later. A discount, an email, or a booking is not a reader. GET /api/agent/seller/context returns the network, the venues, the role, and the current reads. GET /api/agent/seller/loop?from=YYYY-MM-DD&to=YYYY-MM-DD&screens=all is a reader call. For each granted screen and each commercial daypart (morning, lunch, evening) it returns the physical loop (slot count, slot length, loop length) and three rows: locked (named customers and their slots), House, and sellable. Slot counts sum to the physical loop and the shares sum to 100%. If they do not, the call is refused and no figure is invented. Unsold is the sellable slots still open across those three dayparts for each day in the range. grain=summary sums that same loop over the window, one line per face and daypart: days open, days closed, House, locked, and sellable. Sellable is the room still for sale. A closed daypart is counted as closed, not as empty. GET /api/agent/seller/loop/picture?screens=all&date=YYYY-MM-DD&time=HH:MM is a reader call. Omit date and time for now. It is one moment, for every granted screen or a named subset, slot by slot. A date range on this call is refused. GET /api/agent/seller/customers is a reader call. It lists customers with campaigns on the granted glass, money collected and the booked price, and the last date of each. One figure is never copied from the other. GET /api/agent/seller/book?from=YYYY-MM-DD&to=YYYY-MM-DD&screens=all is a reader call. A flight is included when it plays in that period or its money was committed then. Each price is the whole flight, not a slice of the days inside the window, and it is not split across faces. bookedCents and collectedCents stay apart. committedAt is the day the money was committed, and it is absent until then. Bookings made in a stretch are the rows whose committedAt falls in it. Add those bookedCents. No count or total is returned. House, filler, and a hold are absent. The call does not say which flight matters.

## Operator desk

- https://foro.live/admin/agent-mandates