Developers

Commons answers JSON over HTTPS at https://commons.app, and agents reach the same data over MCP. Every endpoint on this page exists today. Public reads need no token; your own slides and shares take a com_ token you approve.

Import the whole API into your tools from /api/openapi.json, an OpenAPI 3.1 document checked against the router on every build.

Public reads

No token. Events and places on the public map, as anyone sees them on commons.app. The JSON reads answer Access-Control-Allow-Origin: *, so your own site can show them in a browser.

  • GET /api/events
    Upcoming published events, soonest first. Takes geoid and level (place, county or state), from and to (ISO dates, in each event's own time zone), location_name and limit (1 to 100, default 20). It answers a bare array; add envelope=1 to wrap it in data, next_cursor and links, and pass next_cursor back as cursor for the next page. MCP list_events takes the same filters and pages the same way.
  • GET /api/events.jsonld
    The same events as schema.org JSON-LD: an ItemList of Events with @context and absolute urls. GET /api/events with Accept: application/ld+json answers the same. It takes the same filters and cursor; the next page is in the Link header.
  • GET /api/locations
    Places near a point, nearest first. Takes latitude, longitude and radius_meters (at most 100000, default 25000), the names MCP uses. The original lat, lng and radius_km still work; when both are sent, the standard names win. A place that keeps its hours day by day also answers them as schema.org openingHoursSpecification, one per day on the place's own clock. A closed day opens and closes at 00:00.
  • GET /api/locations/:id
    One place.
  • GET /events.ics, GET /places/:geoid/events.ics, GET /counties/:geoid/events.ics and GET /events/:id/calendar.ics
    Calendar feeds to subscribe to. A county's feed takes in the events in its places; add ?places=false for only those outside any place.

Sign in

A tool with no browser of its own uses device sign-in (RFC 8628). It asks for a code, the person approves it at /device, and the tool polls for its token.

  • POST /api/auth/device
    Takes client_id, device_name and scope; answers a device_code and a user_code.
  • POST /api/auth/token
    Polls with the device_code until the person approves, then answers the token once.
  • POST /api/mobile/sign_in and POST /api/mobile/sign_in/verify
    The phone app's email link and six-digit code.

Scopes say what a token may do: slides:read, slides:write and shares:write by default. If you run screens, ask for displays:read (see your screens) and displays:write (change their settings) too. The admin scopes, admin:read and admin:write, are opt-in, and only a platform admin can approve them. Send the token as Authorization: Bearer com_..., never in a query string.

Clients can discover both endpoints at GET /.well-known/oauth-authorization-server (RFC 8414).

Admin token

A platform admin can get an admin token from Claude Code with the same device sign-in. With the Commons plugin installed, run:

commons-login --admin

It asks for admin:read admin:write only, and saves the token to ~/.commons/admin-token with mode 600. Your posting token in ~/.commons/token stays as it is. Approve the code at /device; the page warns about admin access first.

The plugin's commons-admin helper reads that file and adds the header itself, so the token never shows in the chat or in a command line. The admin calls themselves are for platform admins and are documented with the admin tools, not here.

Only a platform admin can approve an admin request. A token whose owner isn't a platform admin gets 403 on every admin call. Every change is recorded in the audit log. Sign the token out with commons-logout --admin when the work is done.

Your own slides

With your token, each of these works on your own records only.

  • GET /api/me
    Who the token belongs to.
  • GET /api/me/slides
    Your slides, newest first, each with its status. Each carries review (submitted_at, reviewed_at and the reason a post was turned down), run (starts_at, ends_at) and plays (count, screens and the public places it played, each a name and url). The flat rejection_reason, reviewed_at and actual_impressions stay for existing clients.
  • POST /api/me/slides
    Saves a draft, named by its content hash, so a repeat returns the same slide. A draft is only a draft; you check it, pay and submit it on commons.app.
  • POST /api/me/shares
    A share link for one of your slides.
  • DELETE /api/me/token
    Signs this token out.

Your screens

If you run screens, your own tools can check on them and change their settings. You reach the same screens you manage on /admin, named by a uid; the answers never carry a device token.

  • GET /api/me/displays
    Your screens, with health (online, last_heartbeat_at and uptime_7d_open_hours), settings and now_playing. Needs displays:read.
  • GET /api/me/displays/:uid
    One of your screens.
  • PATCH /api/me/displays/:uid
    Changes the settings you send in {"settings": {...}}: venue_context, community_feed_enabled, public_on_map, alerts_enabled, outside_share, outside_hours, outside_days, excluded_categories and exclude_own_category. Needs displays:write. Each change is recorded in the audit log, and a bad value is a 422 whose param names the field.

Show events on your site

Paste these two lines into any page to list the next events in your city, read live from Commons. Each event links to its page and its calendar file. It needs no account and sets no cookie.

<script src="https://commons.app/embed.js" async></script>
<commons-events geoid="0681554" limit="5"></commons-events>

geoid is the Census place GEOID (0681554 is Vacaville). It also takes level, from, to and heading, and limit up to 20. Style it from your page with ::part(frame), ::part(heading) and ::part(list).

Errors and limits

Every error body carries request_id, the same id as the x-request-id header. Over MCP it is in the JSON-RPC error's data. Quote it when you report a problem, and we can find the exact request.

A 429 sends retry-after in seconds and x-ratelimit-limit. Wait that long, then try again.

Agents and MCP

Agents reach Commons over the Model Context Protocol. One endpoint speaks JSON-RPC 2.0:

POST https://commons.app/api/mcp/message
  • Public tools, no token: list_events, find_locations_near_point and list_post_kinds. They answer the same objects as GET /api/events and GET /api/locations.
  • Your own tools, with a com_ token from /device : get_me, list_my_slides, get_my_slide, draft_post, compose_post and share_slide. A draft is only a draft; you check it, pay and submit it on commons.app.
  • Your screens, with displays:read or displays:write: list_my_displays, get_my_display and update_my_display. Ask your agent whether the screen at your shop is on, or to switch it to a calmer look.
  • Claude Code: the Commons skill at github.com/afomi/commons-skill connects this endpoint and signs you in from the terminal.