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.