{"name":"Foro Commerce","description":"Intelligence lives outside Foro. Buyer grant fa_ : discover, plan, price, quote, hold, secure, creative, modify, report, residual reads, proofOfPlay, attachSignal. Seller key fs_ : one key with owner-chosen permissions (reads default on, writes default off). Locked SOV is immutable. Residual leftover is never sellable. Residual cannot go negative. Grant scope is absolute. Optional tasks store structured objects; Foro does not propose terms. Stateless verbs still work. 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. 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.","version":"0.1.22","protocolVersion":"1.0","supportedInterfaces":[{"url":"https://foro.live/api/agent/a2a","protocolBinding":"JSONRPC","protocolVersion":"1.0"},{"url":"https://foro.live/api/agent/mcp","protocolBinding":"MCP","protocolVersion":"2025-03-26"}],"provider":{"organization":"Ryarc","url":"https://foro.live/about"},"documentationUrl":"https://foro.live/api/agent/openapi","iconUrl":"https://foro.live/icon.png","capabilities":{"streaming":false,"pushNotifications":false,"extendedAgentCard":true,"extensions":[{"uri":"https://foro.live/a2a/grant","description":"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.","required":false},{"uri":"https://foro.live/a2a/constraints","description":"Hard constraints Foro never overrides: locked share of voice is immutable, residual leftover is never sellable, residual cannot go negative, grant scope is absolute, quote is the amount charged.","required":true,"params":{"lockedSovImmutable":true,"residualCannotGoNegative":true,"residualLeftoverNeverSellable":true,"grantScopeAbsolute":true,"quoteIsAmountCharged":true,"intelligence":"outside"}},{"uri":"https://foro.live/a2a/doors","description":"Buyer verbs share MCP Streamable HTTP (Bearer fa_). Seller tools need Bearer fs_ and follow permissions. seller_commit needs seller.commit. converse is English on a buyer grant. Optional tasks: OpenTask, UpdateTask, CloseTask, GetTask. Stateless SendMessage still works.","required":false,"params":{"mcp":{"url":"https://foro.live/api/agent/mcp","transport":"streamableHttp","protocolVersion":"2025-03-26","public":["notifications/initialized"],"oauthProtectedResource":"https://foro.live/.well-known/oauth-protected-resource/api/agent/mcp","connectUrl":"https://foro.live/api/agent/mcp/connect","connectOauthProtectedResource":"https://foro.live/.well-known/oauth-protected-resource/api/agent/mcp/connect"},"openapi":"https://foro.live/api/agent/openapi","llmsTxt":"https://foro.live/llms.txt","grantDesk":"https://foro.live/admin/agent-mandates","sellerContext":"https://foro.live/api/agent/seller/context"}}]},"securitySchemes":{"agent":{"httpAuthSecurityScheme":{"scheme":"Bearer","bearerFormat":"clientId:clientSecret","description":"Buyer grant. Authorization: Bearer fa_…:secret. Rejected on the seller reads."}},"seller":{"httpAuthSecurityScheme":{"scheme":"Bearer","bearerFormat":"clientId:clientSecret","description":"Seller key. Authorization: Bearer fs_…:secret. Permissions chosen at issue. A buyer grant is rejected on seller tools."}}},"securityRequirements":[{"schemes":{"agent":{"list":[]}}}],"defaultInputModes":["application/json"],"defaultOutputModes":["application/json"],"skills":[{"id":"discover","name":"Discover","description":"Purpose: remaining Direct seats on grant faces, same occupancy ledger as Secure. Returns: faces with remaining seats by date, window, remainingCeilingCents, next. Side effects: none. Constraints: residual leftover is never returned; grant venues and dates only; a closed daypart is closed, not empty; drafts do not occupy seats.","tags":["foro","fa_","discover"],"examples":["{\"verb\":\"discover\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"plan","name":"Plan","description":"Purpose: occupancy construction under the grant — alternatives Foro can legally book, not a recommendation. Returns: alternatives with occupancy and price facts, or a draft campaignId when materializeKey is set, plus next. Side effects: materializeKey writes a draft. Constraints: drafts do not occupy seats; residual leftover is never offered; grant venues and dates only.","tags":["foro","fa_","plan"],"examples":["{\"verb\":\"plan\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"creative","name":"Creative","description":"Purpose: creative requirements for a campaign, or attach approved tenant library media. Returns: coverage facts and next. Side effects: attaching media updates What only. Constraints: the agent does not approve media; locked share of voice is immutable — creative may change, airtime may not; submitted campaigns stay plan-locked.","tags":["foro","fa_","creative"],"examples":["{\"verb\":\"creative\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"quote","name":"Quote","description":"Purpose: firm Secure quote for a campaign, optionally under a Sale. Returns: totalCents (the amount that will be charged), list vs Secure facts, remainingCeilingCents, next; with saleId also sale (version, normal media, Sale and voucher reductions, fee, expiry) and normalTotalCents. Side effects: none; quoting never uses up a voucher. Constraints: the total is the amount charged at Secure; pass it as expectedPriceCents on secure (with saleId and saleVersion when quoted under a Sale); residual leftover is not quoted.","tags":["foro","fa_","quote"],"examples":["{\"verb\":\"quote\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"hold","name":"Hold","description":"Purpose: short occupancy reservation so two agents do not race. Returns: campaign on hold, next. Side effects: occupies until convert, cancel, or expiry. Constraints: not a human approval step; drafts otherwise do not occupy; grant venues and dates only.","tags":["foro","fa_","hold"],"examples":["{\"verb\":\"hold\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"secure","name":"Secure","description":"Purpose: commit Direct inventory. Returns: campaign, receipt, quoteCents, replay flag, next. Side effects: occupies and charges the quoted Secure total. Constraints: quote is the amount charged; replay the same idempotencyKey must not double-book; expectedPriceCents fails PRICE_CHANGED if the live quote moved; locked share of voice is then immutable; you mint idempotencyKey — next does not book.","tags":["foro","fa_","secure"],"examples":["{\"verb\":\"secure\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"modify","name":"Modify","description":"Purpose: amend a draft within the grant, or cancel. Returns: campaign, next. Side effects: writes the draft or cancels. Constraints: submitted campaigns are plan-locked (Where/When/slots immutable; creatives stay on creative); drafts do not occupy seats; grant venues and dates only.","tags":["foro","fa_","modify"],"examples":["{\"verb\":\"modify\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"report","name":"Report","description":"Purpose: this buyer's campaigns, approved media, credit, and optional spend window. Returns: remainingCeilingCents, credit, campaigns or one campaign, media, spend when from/to are set, next. Side effects: none. Constraints: pending files and realm reserve are omitted; each flight price is the whole flight; credit is this network relationship only.","tags":["foro","fa_","report"],"examples":["{\"verb\":\"report\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"price","name":"Price","description":"Purpose: price a described flight without saving a campaign. Returns: whether the flight is clear, short days, secureTotalCents (the Secure charge), bid floor facts, next. Side effects: none — no draft, no occupy. Constraints: needs startDate and endDate and grant glass (venueIds and/or screenIds); a closed day is closed, not booked out; residual leftover is never priced; quote/secure still use a campaignId after plan materialize.","tags":["foro","fa_","price"],"examples":["{\"verb\":\"price\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"underfilled","name":"Underfilled faces","description":"Purpose: list grant faces that still have remaining Direct seats in the window. Returns: those faces with remaining Direct seat-days, sellable seat-days, remainingByDate, orderOfSale direct_secure, next. Side effects: none. Constraints: residual leftover is never returned as sellable; same occupancy ledger as discover and Secure; grant venues and dates only; facts only — no package or action.","tags":["foro","fa_","underfilled"],"examples":["{\"verb\":\"underfilled\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"daypartResidual","name":"Daypart residual","description":"Purpose: remaining Direct seats by face × date × named daypart (morning, lunch, evening). Returns: cells with remainingSeats, sellableSeats, closed, orderOfSale direct_secure, next. Side effects: none. Constraints: Full Day leftover and last-look residual are not in this catalog; a closed daypart is closed, not empty; grant scope; facts only.","tags":["foro","fa_","daypartResidual"],"examples":["{\"verb\":\"daypartResidual\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"demandSignals","name":"Demand signals","description":"Purpose: observed occupancy rate, day-of-week occupancy, and bid-event counts on grant faces. Returns: occupancyRate (occupied/sellable on open days), weekday rates, bidInterest counts, openBidCampaigns, next. Side effects: none. Constraints: lookback is observed history on grant faces, not a sale of leftover; missing data is zero or null; facts only — no heat label or advice.","tags":["foro","fa_","demandSignals"],"examples":["{\"verb\":\"demandSignals\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"proofOfPlay","name":"Proof of play","description":"Purpose: proof-of-play facts Foro already recorded for a grant campaign. Returns: playCount, lastPlayedAt, plays (creative, face, date, daypart), rollups byCreative/byFace/byDate/byDaypart, static postings, attached external signals. Side effects: none. Constraints: grant campaigns only; this is the delivery ledger, not leftover; Foro does not recommend pause, extend, or reallocate.","tags":["foro","fa_","proofOfPlay"],"examples":["{\"verb\":\"proofOfPlay\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"attachSignal","name":"Attach external signal","description":"Purpose: store an external measurement the caller already has (sales_lift_proxy, footfall, dwell, or other) against a grant campaign. Returns: the stored signal and signalCount. Side effects: appends the number; does not change occupancy, price, or playout. Constraints: grant campaigns only; Foro does not interpret or act on the value; locked SOV is unchanged.","tags":["foro","fa_","attachSignal"],"examples":["{\"verb\":\"attachSignal\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"seller_context","name":"Seller context","description":"Purpose: identify this seller key. Returns: network, venues, permissions, and the calls each permission unlocks. Side effects: none. Constraints: a buyer grant (fa_) is rejected; does not return prices or remaining seats.","tags":["foro","fs_","seller_context"],"examples":["{\"verb\":\"seller_context\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"seller_loop","name":"Seller loop","description":"Purpose: loop composition on authorised glass — locked, House, and sellable rows plus physical slot count. Returns: grain=day is face × date × daypart with those rows; grain=summary sums the window. Sellable is remaining Direct. Side effects: none. Constraints: locked + House + sellable must equal the loop or the read is refused; residual leftover is not sellable; House is not a sale; a closed daypart is closed; witching hours are omitted; grant glass only; facts only.","tags":["foro","fs_","seller_loop"],"examples":["{\"verb\":\"seller_loop\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"seller_loop_picture","name":"Seller loop picture","description":"Purpose: slot-by-slot content on authorised glass at one moment. Returns: each hole's kind and creative facts. Side effects: none. Constraints: omit date and time for now; a from/to range is refused; this is not occupancy remaining and not a count of people; grant glass only.","tags":["foro","fs_","seller_loop_picture"],"examples":["{\"verb\":\"seller_loop_picture\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"seller_customers","name":"Seller customers","description":"Purpose: customers with flights on authorised glass. Returns: name, bookedCents (whole-flight list), collectedCents (committed money, absent until paid), lastBookedOn, lastCollectedOn. Side effects: none. Constraints: House, filler, and holds are not sales; grant venues only; facts only — no yield advice.","tags":["foro","fs_","seller_customers"],"examples":["{\"verb\":\"seller_customers\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"seller_census","name":"Seller census","description":"Purpose: advertisers with a relationship on this network. Returns: accountId, name, status, timestamps, walk-up origin, and relationship credit (limit, used, prepaid, availableCents, waiting line-increase). Side effects: none. Constraints: this is signup census, not spend; no weekly totals; grant network only; facts only.","tags":["foro","fs_","seller_census"],"examples":["{\"verb\":\"seller_census\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"seller_queue","name":"Seller queue","description":"Purpose: work waiting on a person. Returns: holds on granted glass with expiresAt, pending creatives, pending walk-ups, waiting attention (bid outcomes, deal recheck, open invoices). Side effects: none. Constraints: facts only — no approve/decline advice; House and filler are absent.","tags":["foro","fs_","seller_queue"],"examples":["{\"verb\":\"seller_queue\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"seller_book","name":"Seller book","description":"Purpose: paying flights on authorised glass in a window. Returns: each flight's bookedCents and collectedCents as the whole flight, committedAt when paid. Side effects: none. Constraints: do not split money across faces or days; House, filler, and holds are absent; grant glass only; facts only.","tags":["foro","fs_","seller_book"],"examples":["{\"verb\":\"seller_book\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"seller_occupancy","name":"Seller occupancy","description":"Purpose: remaining Direct seats on authorised glass by face × date × named daypart. Returns: cells with remainingDirectSeats, lockedSlots, houseSlots, slotCount, closed, catalog remaining_direct. Side effects: none. Constraints: remaining Direct is the sellable row of the physical loop; residual leftover is not sellable; a closed daypart is closed; grant glass only; this key cannot quote, hold, Secure, or modify; facts only.","tags":["foro","fs_","seller_occupancy"],"examples":["{\"verb\":\"seller_occupancy\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"seller_locked","name":"Seller locked SOV","description":"Purpose: locked Direct share of voice by customer on authorised glass. Returns: cells with lockedSlots and customers[{ name, slots }] per face × date × daypart. Side effects: none. Constraints: locked airtime is immutable; creative may change; grant glass only; this key cannot quote, hold, Secure, or modify; facts only.","tags":["foro","fs_","seller_locked"],"examples":["{\"verb\":\"seller_locked\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"seller_media","name":"Seller media","description":"Purpose: show the operator one creative on this network. Returns: name, customer, status, mime, size, and url of a GUID-named copy a sessionless GET can fetch. Pending items include the rejection-reason catalog. Side effects: writes that GUID copy; does not change review status. Constraints: grant network only; Realm reserve is absent; Foro does not recommend approve or reject. Show the url to the human. Then seller_media_decide records their decision.","tags":["foro","fs_","seller_media"],"examples":["{\"verb\":\"seller_media\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"seller_media_decide","name":"Seller media decide","description":"Purpose: approve, reject, or ask for a person to review a pending creative under this network's principles. Returns: mediaId and the new status. Side effects: pending becomes approved or rejected and the advertiser is notified; review leaves it pending for a person; when the creative touches a principle marked approval needs a person, an approval stays pending with your recommendation. Constraints: read seller_principles first and apply every one, including the approval standard; name the ones you applied in principlesApplied and say why in reasoning; if uncertain, decision review with a short reason rather than reject; to approve, list in touches the marked principles the creative touches (an empty list means none) when any are marked; rejected requires at least one catalog reason id from seller_media; pending only; grant network only.","tags":["foro","fs_","seller_media_decide"],"examples":["{\"verb\":\"seller_media_decide\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"seller_agents","name":"Seller agents","description":"Purpose: agents connected to this network and buyer grants on granted glass. Returns: connections (profile, status, lastUsedAt) and buyer grants with remaining ceiling. Side effects: none. Constraints: this network only; facts only — Foro does not say who to revoke.","tags":["foro","fs_","seller_agents"],"examples":["{\"verb\":\"seller_agents\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"seller_intent","name":"Seller intent","description":"Purpose: drafts, auction events, and Agent Secure on this network. Returns: draft flights on granted glass, recent auctionEvents, recent agent_secure audit. Side effects: none. Constraints: related accounts and grant glass only; facts only.","tags":["foro","fs_","seller_intent"],"examples":["{\"verb\":\"seller_intent\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"seller_capabilities","name":"Seller capabilities","description":"Purpose: playback-time If signals and player presence on granted glass. Returns: signals offered to buyers, Advertise Here on/off, player lastSeenAt, face signals. Side effects: none. Constraints: this is capability, not Pulse market life; grant glass only; facts only.","tags":["foro","fs_","seller_capabilities"],"examples":["{\"verb\":\"seller_capabilities\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"seller_pricing","name":"Seller pricing","description":"Purpose: rack and yield facts this network charges. Returns: dayparts, allowed packages, volume discount knobs, yield killSwitch/floor/channels, venue pricePerScreenPerDay. Side effects: none. Constraints: facts only; this key cannot change a price; yield policy writes stay on the website.","tags":["foro","fs_","seller_pricing"],"examples":["{\"verb\":\"seller_pricing\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"seller_campaigns","name":"Seller campaigns","description":"Purpose: flights on granted glass. Returns: status, kind, customer, dates, totalCents, reviewStatus. Side effects: none. Constraints: related advertisers plus House/filler on this glass; grant glass only; facts only.","tags":["foro","fs_","seller_campaigns"],"examples":["{\"verb\":\"seller_campaigns\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"seller_ledger","name":"Seller ledger","description":"Purpose: money movements for related advertisers on this network. Returns: up to 200 ledger lines (amountCents, signedAmountCents, description). Side effects: none. Constraints: related accounts only; optional from/to YYYY-MM-DD; facts only.","tags":["foro","fs_","seller_ledger"],"examples":["{\"verb\":\"seller_ledger\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"seller_delivery","name":"Seller delivery","description":"Purpose: proof-of-play on granted glass. Returns: last 200 plays (face, campaign, media, date, daypart) plus playCount. Side effects: none. Constraints: grant glass only; optional campaignId; Foro does not pause, extend, or reallocate from these numbers.","tags":["foro","fs_","seller_delivery"],"examples":["{\"verb\":\"seller_delivery\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"seller_blackouts","name":"Seller blackouts","description":"Purpose: active blackouts and open conflicts on granted glass. Returns: blackout windows and open conflicts. Side effects: none. Constraints: grant glass only; facts only.","tags":["foro","fs_","seller_blackouts"],"examples":["{\"verb\":\"seller_blackouts\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"seller_commit","name":"Seller commit","description":"Purpose: Secure a package. Returns: campaignId, chargedCents, defaultSecureCents, mode default or authorized_outside_default, replay. Side effects: occupies remaining Direct seats and charges the customer. Constraints: remaining Direct seats must suffice; locked SOV is untouched; residual cannot go negative; grant glass only; reader keys are refused; a price other than the authoritative quote needs an owner-set floor on this key. The flag authorizedOutsideDefault is not itself authority.","tags":["foro","fs_","seller_commit"],"examples":["{\"verb\":\"seller_commit\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"seller_relationship_decide","name":"Seller relationship decide","description":"Purpose: record approved or declined on a pending walk-up. Returns: accountId and the new status. Side effects: pending becomes active or disabled; a complimentary day may place after approve. Constraints: pending only; this network only; default off; Foro does not recommend the decision.","tags":["foro","fs_","seller_relationship_decide"],"examples":["{\"verb\":\"seller_relationship_decide\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"seller_credit_set","name":"Seller credit set","description":"Purpose: set this network’s credit line for a related advertiser, or accept/refuse a waiting line-increase. Returns: accountId and creditLimitCents. Side effects: writes the line only; prepaid and used are untouched. Constraints: default off; set needs creditLimitCents ≥ 0; accept_request/refuse_request need a waiting request.","tags":["foro","fs_","seller_credit_set"],"examples":["{\"verb\":\"seller_credit_set\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"seller_blackout_declare","name":"Seller blackout declare","description":"Purpose: declare a blackout window on named granted screens. Returns: blackoutsAdded and conflictsOpen. Side effects: replace-window ingest for those screens. Constraints: default off; grant screens only; source is network.","tags":["foro","fs_","seller_blackout_declare"],"examples":["{\"verb\":\"seller_blackout_declare\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"seller_campaign_review","name":"Seller campaign review","description":"Purpose: record approved or rejected on a campaign in review, or cancel House. Returns: campaignId and status. Side effects: approved occupies; rejected is issue; cancel_house cancels House. Constraints: default off; grant glass only; in_review for approved/rejected; cancel_house is House only.","tags":["foro","fs_","seller_campaign_review"],"examples":["{\"verb\":\"seller_campaign_review\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"seller_sales","name":"Seller Sales","description":"Purpose: this network's Sales (time-limited prices on chosen screens and days for a chosen audience) and what was bought under each. Returns: each Sale's current terms and version, results (purchases, media, Sale and voucher reductions), whether launching is open here, and your launch limit. Side effects: none. Constraints: results are attribution, not proof a Sale caused demand.","tags":["foro","fs_","seller_sales"],"examples":["{\"verb\":\"seller_sales\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"seller_sale_save","name":"Save Sale","description":"Purpose: create or change a Sale with the same rules as the Sales Desk. Returns: the saved terms and version, or a code. Side effects: appends a new version; launching makes it visible to its audience from its opening time. Constraints: default off (seller.sale.manage); create with requestKey and terms (state draft); change with saleId, expectedVersion and the full terms; a running Sale can only be paused or ended; launch (state scheduled) only when this network has launching open AND both discount.percentOff and limits.maximumCombinedPercentOff are within the limit a person set on your key; the same requestKey replays.","tags":["foro","fs_","seller_sale_save"],"examples":["{\"verb\":\"seller_sale_save\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"seller_sale_audience_save","name":"Save Sale audience","description":"Purpose: save who may buy a Sale. Returns: the audience with its id and version (pin both in the Sale's terms). Side effects: appends a revision; Sales keep the revision they pinned. Constraints: default off (seller.sale.manage); definition {bookedInWindow: any|required|excluded, includeAccountIds, excludeAccountIds, rule: {kind: everyone} or {kind: accounts, values}}; rules on industry, country or screen-seconds cannot launch.","tags":["foro","fs_","seller_sale_audience_save"],"examples":["{\"verb\":\"seller_sale_audience_save\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"seller_voucher_issue","name":"Seller voucher issue","description":"Purpose: issue one tightly bounded voucher to one related active advertiser. Returns: voucherId, code, kind. Side effects: one redemption, not auto-applied on Secure. Constraints: default off; percent_off 1–25; credit_fixed 100–50000 cents; endsAt within 30 days; one related active account.","tags":["foro","fs_","seller_voucher_issue"],"examples":["{\"verb\":\"seller_voucher_issue\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"seller_publish","name":"Publish indicative opportunity","description":"Purpose: publish an indicative opportunity on this network's own door. Returns: the public card. Side effects: strangers who already know this network's address can read it. Constraints: needs seller.offer; not a booking, hold, or quote; no private floors or customer records; one network, not a directory.","tags":["foro","fs_","seller_publish"],"examples":["{\"verb\":\"seller_publish\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"seller_withdraw","name":"Withdraw publication","description":"Purpose: take a published opportunity off this network's door. Returns: the id. Side effects: the public address no longer shows it. Constraints: needs seller.offer; this key only.","tags":["foro","fs_","seller_withdraw"],"examples":["{\"verb\":\"seller_withdraw\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"seller_propose","name":"Record a proposition","description":"Purpose: record exact commercial terms the seller is willing to discuss. Returns: the proposition version. Side effects: none on inventory or price. Constraints: needs seller.offer; not a hold or a booking; Foro does not choose the terms; grant glass only.","tags":["foro","fs_","seller_propose"],"examples":["{\"verb\":\"seller_propose\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"seller_proposition_decide","name":"Accept or reject a proposition","description":"Purpose: accept or reject the current buyer version. Returns: the version status. Side effects: accept does not book and does not hold. Constraints: needs seller.offer; the author cannot accept their own version; commit is a separate call.","tags":["foro","fs_","seller_proposition_decide"],"examples":["{\"verb\":\"seller_proposition_decide\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"seller_employer_brief","name":"Employer brief","description":"Purpose: read this network's mission, the operator's standing instructions for you, and their open questions. Returns: mission text, brief text, and waiting questions. Side effects: none. Constraints: neither is a permission; follow the brief within your permissions. Read this first. Also available as foro://commerce/employer.","tags":["foro","fs_","seller_employer_brief"],"examples":["{\"verb\":\"seller_employer_brief\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"seller_principles","name":"Network principles","description":"Purpose: read the rules this network sets for every assistant working here. Returns: each principle's name, rule, the power it governs, and whether an approval under it needs a person. Side effects: none. Constraints: apply every principle that governs a power before you use it; they bind you, not the network's people.","tags":["foro","fs_","seller_principles"],"examples":["{\"verb\":\"seller_principles\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"seller_events","name":"Network events","description":"Purpose: what happened since you last checked on this network. Returns: events oldest first (seq, type, at, summary, facts, routine) and a cursor; pass it back as since next time. Without since, the last day. Types: booking.made, hold.expiring, hold.converted, hold.lapsed, creative.waiting, customer.waiting, offer.answered, daypart.behind. Side effects: none. Constraints: facts, not advice; kept 30 days.","tags":["foro","fs_","seller_events"],"examples":["{\"verb\":\"seller_events\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"seller_webhook","name":"Event webhook","description":"Purpose: have Foro send these events to your own https address as they happen. Returns: on set, a signing secret shown once; on status, the address and recent deliveries. Side effects: set replaces this grant\"s webhook and starts from now; remove stops it. Constraints: one per grant; public https only. Each POST carries Foro-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of 't.body' with the secret>. Failed deliveries retry with back-off; events stay readable with the events tool.","tags":["foro","fs_","seller_webhook"],"examples":["{\"verb\":\"seller_webhook\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"seller_dispatch","name":"File a dispatch","description":"Purpose: file a short self-reported commercial note for the operator. Returns: the note id. Side effects: none on inventory, price, or credit. Constraints: needs seller.dispatch, which is not granted by reads. Text is untrusted. Kinds: progress, opportunity, obstacle, decision_request. Link only ids on this network.","tags":["foro","fs_","seller_dispatch"],"examples":["{\"verb\":\"seller_dispatch\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"openTask","name":"Open task","description":"Optional stateful task (negotiation, monitoring, package_assembly). Foro stores objects. It does not propose terms.","tags":["foro","task"],"examples":["{\"kind\":\"negotiation\"}"],"inputModes":["application/json"],"outputModes":["application/json"]},{"id":"seller_context","name":"Seller context","description":"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.","tags":["foro","seller","read"],"examples":["GET /api/agent/seller/context"],"inputModes":["application/json"],"outputModes":["application/json"]}]}