{"components":{"parameters":{"Id":{"in":"path","name":"id","required":true,"schema":{"type":"integer"}},"Uid":{"in":"path","name":"uid","required":true,"schema":{"format":"uuid","type":"string"}}},"responses":{"BadRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"A filter is malformed; `error` says what to send."},"Error":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"An error"},"Forbidden":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The token lacks the scope; `message` names it."},"NotFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not found"},"RateLimited":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Too many requests. Wait `retry-after` seconds.","headers":{"retry-after":{"schema":{"type":"integer"}},"x-ratelimit-limit":{"schema":{"type":"integer"}},"x-ratelimit-remaining":{"schema":{"type":"integer"}}}},"Unauthorized":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"A missing, unknown or revoked token"},"Unprocessable":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The body can't be used; `error` says why."}},"schemas":{"DisplaySettings":{"additionalProperties":false,"properties":{"alerts_enabled":{"description":"Offline emails","type":"boolean"},"community_feed_enabled":{"type":"boolean"},"exclude_own_category":{"type":"boolean"},"excluded_categories":{"items":{"enum":["cafe","restaurant","bar","retail","salon","auto","health","grocery","services","other"],"type":"string"},"type":"array"},"outside_days":{"description":"1 Monday to 7 Sunday; [] every day","items":{"maximum":7,"minimum":1,"type":"integer"},"type":"array"},"outside_hours":{"description":"[start, end] hours on the location's clock; null for all day","items":{"type":"integer"},"maxItems":2,"minItems":2,"type":["array","null"]},"outside_share":{"description":"Percent of slots for outside posts and ads","maximum":100,"minimum":0,"type":"integer"},"public_on_map":{"description":"The public map may show the place has a screen on now","type":"boolean"},"venue_context":{"description":"How posts look there","enum":["casual","constrained","environmental"],"type":"string"}},"type":"object"},"Error":{"description":"`error` is a message or a code; some answers add `message` or `details`.","properties":{"details":{"type":"object"},"error":{"type":"string"},"message":{"type":"string"},"param":{"description":"The field a 422 is about","type":"string"},"request_id":{"description":"The x-request-id header; quote it when you report a problem.","type":"string"}},"required":["error","request_id"],"type":"object"},"Event":{"description":"schema.org Event names alongside the original snake_case fields. Not a schema.org document: `url` is a relative path; the event page's JSON-LD is the schema.org view.","properties":{"@type":{"const":"Event","type":"string"},"description":{"type":["string","null"]},"endDate":{"type":"string"},"ends_at":{"type":["string","null"]},"eventAttendanceMode":{"type":"string"},"eventStatus":{"type":"string"},"external_location_url":{"type":["string","null"]},"ics_url":{"example":"/events/7/calendar.ics","type":"string"},"id":{"type":"integer"},"identifier":{"example":"urn:uuid:…","type":"string"},"jurisdiction":{"properties":{"county":{"description":"The county it lies in; a county is its own county.","properties":{"geoid":{"example":"06095","type":"string"},"ics_url":{"example":"/counties/06095/events.ics","type":"string"},"name":{"type":["string","null"]}},"type":["object","null"]},"geoid":{"type":"string"},"ics_url":{"type":["string","null"]},"level":{"type":"string"},"name":{"type":["string","null"]},"ocd_id":{"type":["string","null"]},"verified_at":{"type":["string","null"]}},"type":["object","null"]},"location":{"description":"A schema.org Place","type":"object"},"location_lat":{"type":["number","null"]},"location_lng":{"type":["number","null"]},"location_name":{"type":["string","null"]},"name":{"type":"string"},"startDate":{"description":"Local time with offset","type":"string"},"starts_at":{"format":"date-time","type":"string"},"timezone":{"description":"IANA zone","type":["string","null"]},"title":{"type":"string"},"uid":{"description":"The stable public id","format":"uuid","type":"string"},"url":{"example":"/events/7","type":"string"}},"type":"object"},"EventItemList":{"description":"JSON-LD: a schema.org ItemList of schema.org Events.","properties":{"@context":{"const":"https://schema.org","type":"string"},"@type":{"const":"ItemList","type":"string"},"itemListElement":{"items":{"properties":{"@type":{"const":"ListItem","type":"string"},"item":{"properties":{"@type":{"const":"Event","type":"string"},"description":{"type":"string"},"endDate":{"format":"date-time","type":"string"},"eventAttendanceMode":{"type":"string"},"eventStatus":{"type":"string"},"identifier":{"example":"urn:uuid:…","type":"string"},"location":{"description":"A schema.org Place or VirtualLocation","type":"object"},"name":{"type":"string"},"startDate":{"description":"Local time with offset","format":"date-time","type":"string"},"url":{"example":"https://commons.app/events/7","format":"uri","type":"string"}},"required":["@type","name","startDate","url","identifier"],"type":"object"},"position":{"description":"From 1 on each page","type":"integer"}},"required":["@type","position","item"],"type":"object"},"type":"array"},"itemListOrder":{"const":"https://schema.org/ItemListOrderAscending","type":"string"}},"required":["@context","@type","itemListElement"],"type":"object"},"EventPage":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Event"},"type":"array"},"links":{"properties":{"ics":{"description":"The place's or county's calendar feed, when filtered to one","type":["string","null"]},"next":{"description":"The next page's URL","type":["string","null"]}},"type":"object"},"next_cursor":{"description":"null on the last page","type":["string","null"]}},"required":["data","next_cursor","links"],"type":"object"},"Location":{"properties":{"address":{"type":["string","null"]},"city":{"type":["string","null"]},"id":{"type":"integer"},"latitude":{"type":"number"},"live_screen":{"description":"Whether a public screen here is on now. Nothing else about displays.","type":"boolean"},"longitude":{"type":"number"},"name":{"type":"string"},"openingHoursSpecification":{"description":"schema.org OpeningHoursSpecification, one per day, on the place's own clock. Only for places with day-by-day hours. A closed day opens and closes at 00:00; a closing time earlier than the opening time is after midnight.","items":{"properties":{"@type":{"const":"OpeningHoursSpecification","type":"string"},"closes":{"example":"17:30","type":"string"},"dayOfWeek":{"example":"https://schema.org/Monday","type":"string"},"opens":{"example":"09:00","type":"string"}},"type":"object"},"type":"array"},"operating_hours":{"description":"Free text as entered","type":["string","null"]},"organization":{"properties":{"id":{"type":"integer"},"name":{"type":"string"},"url":{"type":"string"}},"type":"object"},"url":{"example":"/locations/2","type":"string"}},"type":"object"},"Me":{"properties":{"device":{"properties":{"client_id":{"type":["string","null"]},"kind":{"type":"string"},"name":{"type":["string","null"]},"scopes":{"items":{"type":"string"},"type":"array"}},"type":"object"},"user":{"properties":{"confirmed":{"type":"boolean"},"email":{"type":"string"},"handle":{"type":["string","null"]}},"type":"object"}},"type":"object"},"MyDisplay":{"properties":{"audit_event_id":{"description":"After a change only","type":"integer"},"health":{"properties":{"last_heartbeat_at":{"type":["string","null"]},"online":{"description":"An online heartbeat in the last 5 minutes","type":"boolean"},"uptime_7d_open_hours":{"description":"The share of the location's open hours it was up, last 7 days, 0 to 1","type":"number"}},"type":"object"},"location":{"properties":{"city":{"type":["string","null"]},"name":{"type":"string"},"organization":{"type":["string","null"]},"url":{"format":"uri","type":"string"}},"type":["object","null"]},"name":{"type":"string"},"now_playing":{"properties":{"community_feed":{"type":"boolean"},"items":{"type":"integer"},"reel":{"description":"The reel assigned to the screen","type":["string","null"]}},"type":"object"},"orientation":{"enum":["horizontal","vertical"],"type":"string"},"settings":{"$ref":"#/components/schemas/DisplaySettings"},"uid":{"format":"uuid","type":"string"}},"type":"object"},"MySlide":{"properties":{"actual_impressions":{"description":"Kept for existing clients; see plays.count","type":["integer","null"]},"content_hash":{"type":["string","null"]},"content_type":{"description":"The post's kind","type":["string","null"]},"fields":{"type":"object"},"inserted_at":{"type":"string"},"name":{"type":"string"},"plays":{"properties":{"count":{"type":"integer"},"places":{"description":"Public places only: listed organizations, screens shown on the map.","items":{"properties":{"name":{"type":"string"},"url":{"format":"uri","type":"string"}},"type":"object"},"type":"array"},"screens":{"type":"integer"}},"type":"object"},"rejection_reason":{"description":"Kept for existing clients; see review.reason","type":["string","null"]},"review":{"properties":{"reason":{"description":"Why it was turned down","type":["string","null"]},"reviewed_at":{"type":["string","null"]},"submitted_at":{"type":["string","null"]}},"type":"object"},"reviewed_at":{"description":"Kept for existing clients; see review","type":["string","null"]},"run":{"properties":{"ends_at":{"type":["string","null"]},"starts_at":{"type":["string","null"]}},"type":"object"},"status":{"description":"draft until posted, then pending_review, approved, live, rejected or expired","type":"string"},"uid":{"format":"uuid","type":"string"},"updated_at":{"type":"string"}},"type":"object"},"OAuthError":{"properties":{"error":{"type":"string"},"error_description":{"type":"string"},"request_id":{"type":"string"}},"required":["error","request_id"],"type":"object"}},"securitySchemes":{"bearer":{"description":"A `com_` token from device sign-in (`/api/auth/device`) or the phone app. Scopes: slides:read, slides:write, shares:write, displays:read, displays:write, admin:read, admin:write.","scheme":"bearer","type":"http"}}},"externalDocs":{"url":"https://commons.app/developers"},"info":{"contact":{"email":"hello@commons.app","name":"Commons"},"description":"Public reads need no token and answer `Access-Control-Allow-Origin: *`. Your own records take a `com_` bearer token from device sign-in. Every error body carries `request_id`, the same id as the `x-request-id` header. A 429 sends `retry-after` and `x-ratelimit-limit`. Agents reach the same data over MCP at `POST /api/mcp/message`.","summary":"Events, places and your own cards on Commons, the community screen network.","title":"Commons API","version":"2026-11-17"},"jsonSchemaDialect":"https://spec.openapis.org/oas/3.1/dialect/base","openapi":"3.1.0","paths":{"/.well-known/oauth-authorization-server":{"get":{"operationId":"getAuthorizationServerMetadata","responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"RFC 8414 metadata"}},"summary":"OAuth 2.0 Authorization Server Metadata (RFC 8414): the device and token endpoints, the device_code grant and the scopes a token can carry.","tags":["sign-in"]}},"/api/auth/device":{"post":{"operationId":"startDeviceSignIn","requestBody":{"content":{"application/json":{"schema":{"properties":{"client_id":{"example":"commons-skill","type":"string"},"device_name":{"maxLength":60,"type":"string"},"scope":{"description":"Space-separated subset of slides:read, slides:write, shares:write, displays:read, displays:write, admin:read, admin:write; default slides:read slides:write shares:write.","type":"string"}},"required":["client_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"device_code":{"type":"string"},"expires_in":{"type":"integer"},"interval":{"type":"integer"},"user_code":{"example":"WDJB-MJHT","type":"string"},"verification_uri":{"format":"uri","type":"string"},"verification_uri_complete":{"format":"uri","type":"string"}},"required":["device_code","user_code","verification_uri","expires_in","interval"],"type":"object"}}},"description":"A pending sign-in"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}},"description":"RFC 6749 error"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Start device sign-in (RFC 8628); the person approves the user_code at /device.","tags":["sign-in"]}},"/api/auth/token":{"post":{"operationId":"pollDeviceToken","requestBody":{"content":{"application/json":{"schema":{"properties":{"client_id":{"type":"string"},"device_code":{"type":"string"},"grant_type":{"const":"urn:ietf:params:oauth:grant-type:device_code","type":"string"}},"required":["grant_type","device_code","client_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"access_token":{"example":"com_...","type":"string"},"scope":{"type":"string"},"token_type":{"const":"Bearer","type":"string"}},"required":["access_token","token_type","scope"],"type":"object"}}},"description":"The token"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}},"description":"authorization_pending, slow_down, access_denied, expired_token, invalid_grant, …"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Poll for the token; answers it once, after the person approves.","tags":["sign-in"]}},"/api/events":{"get":{"description":"A bare array by default. `envelope=1`, or a `cursor`, answers `{data, next_cursor, links}`; pass `next_cursor` back as `cursor` with the same filters for the next page. MCP `list_events` takes the same filters.","operationId":"listEvents","parameters":[{"description":"Census GEOID of the jurisdiction an event was located in.","example":"0681554","in":"query","name":"geoid","schema":{"type":"string"}},{"description":"What kind of jurisdiction `geoid` names.","in":"query","name":"level","schema":{"default":"place","enum":["place","county","state"],"type":"string"}},{"description":"For a county: false leaves out the events in the county's places (cities, towns, CDPs), listing only those outside any place.","in":"query","name":"places","schema":{"default":true,"type":"boolean"}},{"description":"Only events starting on or after this date, in their own time zone.","in":"query","name":"from","schema":{"format":"date","type":"string"}},{"description":"Only events starting on or before this date, in their own time zone.","in":"query","name":"to","schema":{"format":"date","type":"string"}},{"description":"Match the venue name.","in":"query","name":"location_name","schema":{"type":"string"}},{"in":"query","name":"limit","schema":{"default":20,"maximum":100,"minimum":1,"type":"integer"}},{"description":"1 wraps the list in `{data, next_cursor, links}`.","in":"query","name":"envelope","schema":{"enum":["1"],"type":"string"}},{"description":"A `next_cursor` from the page before.","in":"query","name":"cursor","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"oneOf":[{"items":{"$ref":"#/components/schemas/Event"},"type":"array"},{"$ref":"#/components/schemas/EventPage"}]}},"application/ld+json":{"schema":{"$ref":"#/components/schemas/EventItemList"}}},"description":"Events"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"Upcoming published events, soonest first.","tags":["public"]}},"/api/events.jsonld":{"get":{"description":"An `ItemList` of `Event`s with `@context` and absolute `url`s, and none of the snake_case fields. The same as `GET /api/events` with `Accept: application/ld+json`. Takes the same filters; the next page is a `Link: <...>; rel=\"next\"` header.","operationId":"listEventsJsonLd","parameters":[{"description":"Census GEOID of the jurisdiction an event was located in.","example":"0681554","in":"query","name":"geoid","schema":{"type":"string"}},{"description":"What kind of jurisdiction `geoid` names.","in":"query","name":"level","schema":{"default":"place","enum":["place","county","state"],"type":"string"}},{"description":"For a county: false leaves out the events in the county's places (cities, towns, CDPs), listing only those outside any place.","in":"query","name":"places","schema":{"default":true,"type":"boolean"}},{"description":"Only events starting on or after this date, in their own time zone.","in":"query","name":"from","schema":{"format":"date","type":"string"}},{"description":"Only events starting on or before this date, in their own time zone.","in":"query","name":"to","schema":{"format":"date","type":"string"}},{"description":"Match the venue name.","in":"query","name":"location_name","schema":{"type":"string"}},{"in":"query","name":"limit","schema":{"default":20,"maximum":100,"minimum":1,"type":"integer"}},{"description":"A `next_cursor` from the page before.","in":"query","name":"cursor","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/EventItemList"}}},"description":"A schema.org ItemList","headers":{"link":{"description":"`<url>; rel=\"next\"` when there is a next page","schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"Upcoming published events as schema.org JSON-LD, soonest first.","tags":["public"]}},"/api/locations":{"get":{"description":"Send `latitude`, `longitude` and `radius_meters` (the names MCP uses), or the original `lat`, `lng` and `radius_km`; the standard names win when both are sent.","operationId":"listLocations","parameters":[{"description":"Decimal degrees, -90 to 90.","in":"query","name":"latitude","schema":{"type":"number"}},{"description":"Decimal degrees, -180 to 180.","in":"query","name":"longitude","schema":{"type":"number"}},{"description":"At most 100000; default 25000.","in":"query","name":"radius_meters","schema":{"type":"number"}},{"description":"Original name for latitude.","in":"query","name":"lat","schema":{"type":"number"}},{"description":"Original name for longitude.","in":"query","name":"lng","schema":{"type":"number"}},{"description":"Original radius, at most 100; default 25.","in":"query","name":"radius_km","schema":{"type":"number"}}],"responses":{"200":{"content":{"application/json":{"schema":{"items":{"allOf":[{"$ref":"#/components/schemas/Location"},{"properties":{"distance_km":{"type":"number"}},"type":"object"}]},"type":"array"}}},"description":"Places"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"Places on the public map near a point, nearest first (at most 50).","tags":["public"]}},"/api/locations/{id}":{"get":{"operationId":"getLocation","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Location"}}},"description":"The place"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"One place on the public map.","tags":["public"]}},"/api/mcp/message":{"post":{"description":"Anyone gets the public tools; a bearer token adds the person's own, as its scopes allow. A keyed tool without a token is a 401 with `WWW-Authenticate` naming the scope.","operationId":"mcpMessage","requestBody":{"content":{"application/json":{"schema":{"properties":{"id":{"type":["string","integer"]},"jsonrpc":{"const":"2.0","type":"string"},"method":{"example":"tools/call","type":"string"},"params":{"type":"object"}},"required":["jsonrpc","method"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"A JSON-RPC response"},"202":{"description":"A notification, accepted"},"401":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"A keyed tool without a token"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{},{"bearer":[]}],"summary":"MCP over JSON-RPC 2.0: initialize, ping, tools/list, tools/call.","tags":["agents"]}},"/api/me":{"get":{"operationId":"getMe","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}},"description":"The person and device"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"bearer":[]}],"summary":"Who the token belongs to and what it may do. MCP `get_me` answers the same.","tags":["me"]}},"/api/me/displays":{"get":{"description":"Needs `displays:read`. A screen is named by its `uid`, never its serial id or device token. MCP `list_my_displays` answers the same.","operationId":"listMyDisplays","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/MyDisplay"},"type":"array"}},"type":"object"}}},"description":"Your screens"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"bearer":[]}],"summary":"The screens you manage, as on /admin, with health, settings and what plays.","tags":["me"]}},"/api/me/displays/{uid}":{"get":{"description":"Needs `displays:read`. A screen you don't manage is a 404.","operationId":"getMyDisplay","parameters":[{"$ref":"#/components/parameters/Uid"}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"$ref":"#/components/schemas/MyDisplay"}},"type":"object"}}},"description":"The screen"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"bearer":[]}],"summary":"One of your screens. MCP `get_my_display` answers the same.","tags":["me"]},"patch":{"description":"Needs `displays:write`. Send only the settings to change; each change is recorded in the audit log and the answer carries its `audit_event_id`. A bad value is a 422 whose `param` names the field (`settings.venue_context`) and whose `message` says what it takes. MCP `update_my_display` does the same.","operationId":"updateMyDisplay","parameters":[{"$ref":"#/components/parameters/Uid"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"settings":{"additionalProperties":false,"properties":{"alerts_enabled":{"description":"Offline emails","type":"boolean"},"community_feed_enabled":{"type":"boolean"},"exclude_own_category":{"type":"boolean"},"excluded_categories":{"items":{"enum":["cafe","restaurant","bar","retail","salon","auto","health","grocery","services","other"],"type":"string"},"type":"array"},"outside_days":{"description":"1 Monday to 7 Sunday; [] every day","items":{"maximum":7,"minimum":1,"type":"integer"},"type":"array"},"outside_hours":{"description":"[start, end] hours on the location's clock; null for all day","items":{"type":"integer"},"maxItems":2,"minItems":2,"type":["array","null"]},"outside_share":{"description":"Percent of slots for outside posts and ads","maximum":100,"minimum":0,"type":"integer"},"public_on_map":{"description":"The public map may show the place has a screen on now","type":"boolean"},"venue_context":{"description":"How posts look there","enum":["casual","constrained","environmental"],"type":"string"}},"type":"object"}},"required":["settings"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"$ref":"#/components/schemas/MyDisplay"}},"type":"object"}}},"description":"The changed screen"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"}},"security":[{"bearer":[]}],"summary":"Change some of a screen's settings, as its edit page on /admin does.","tags":["me"]}},"/api/me/shares":{"post":{"operationId":"shareMySlide","requestBody":{"content":{"application/json":{"schema":{"properties":{"note":{"maxLength":280,"type":"string"},"recipient_name":{"type":"string"},"slide_uid":{"format":"uuid","type":"string"}},"required":["slide_uid"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"properties":{"token":{"type":"string"},"url":{"format":"uri","type":"string"}},"type":"object"}}},"description":"The link"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"bearer":[]}],"summary":"A share link (/s/<token>) for one of your cards.","tags":["me"]}},"/api/me/slides":{"get":{"description":"MCP `list_my_slides` and `get_my_slide` answer the same review, run and plays.","operationId":"listMySlides","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/MySlide"},"type":"array"}},"type":"object"}}},"description":"Your cards"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"bearer":[]}],"summary":"Your cards, newest first, with where each post stands and where it played.","tags":["me"]},"post":{"description":"201 for a new card, 200 for the one that hash already names. A draft is only a draft: the person checks, pays and submits it on commons.app.","operationId":"saveMySlide","requestBody":{"content":{"application/json":{"schema":{"properties":{"hash":{"description":"sha256 of the post's canonical JSON","pattern":"^[0-9a-f]{64}$","type":"string"},"post":{"description":"A post in the app's shape: a kind and its fields by name.","properties":{"kind":{"enum":["event","announcement","business","lost_found","help_wanted","free"],"type":"string"},"name":{"maxLength":200,"type":"string"}},"required":["kind","name"],"type":"object"}},"required":["hash","post"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"$ref":"#/components/schemas/MySlide"}},"type":"object"}}},"description":"Already saved"},"201":{"content":{"application/json":{"schema":{"properties":{"data":{"$ref":"#/components/schemas/MySlide"}},"type":"object"}}},"description":"Saved"},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/Unprocessable"}},"security":[{"bearer":[]}],"summary":"Save a locked card as a draft, named by its content hash.","tags":["me"]}},"/api/me/token":{"delete":{"operationId":"signOut","responses":{"204":{"description":"Signed out"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"bearer":[]}],"summary":"Revoke this token.","tags":["me"]}},"/api/mobile/sign_in":{"post":{"operationId":"startPhoneSignIn","requestBody":{"content":{"application/json":{"schema":{"properties":{"device_name":{"type":"string"},"email":{"format":"email","type":"string"}},"required":["email"],"type":"object"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"properties":{"status":{"const":"sent","type":"string"}},"type":"object"}}},"description":"Sent, if allowed"},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"Email a sign-in link and code (the phone app). Always 202.","tags":["sign-in"]}},"/api/mobile/sign_in/verify":{"post":{"operationId":"verifyPhoneSignIn","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"properties":{"token":{"type":"string"}},"required":["token"],"type":"object"},{"properties":{"code":{"type":"string"},"email":{"format":"email","type":"string"}},"required":["email","code"],"type":"object"}]}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"api_token":{"example":"com_...","type":"string"},"user":{"properties":{"email":{"type":"string"}},"type":"object"}},"type":"object"}}},"description":"Signed in"},"401":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Trade the emailed link token, or the email and code, for a `com_` token.","tags":["sign-in"]}},"/api/openapi.json":{"get":{"operationId":"getOpenAPI","responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OpenAPI 3.1"}},"summary":"This document.","tags":["public"]}},"/counties/{geoid}/events.ics":{"get":{"operationId":"countyEventsCalendar","parameters":[{"description":"The county's five-digit Census GEOID.","example":"06095","in":"path","name":"geoid","required":true,"schema":{"pattern":"^[0-9]{5}$","type":"string"}},{"description":"For a county: false leaves out the events in the county's places (cities, towns, CDPs), listing only those outside any place.","in":"query","name":"places","schema":{"default":true,"type":"boolean"}}],"responses":{"200":{"content":{"text/calendar":{"schema":{"type":"string"}}},"description":"iCalendar (RFC 5545)"}},"summary":"One county's upcoming events, with the events in its places unless places=false. An iCalendar feed to subscribe to.","tags":["public"]}},"/events.ics":{"get":{"operationId":"allEventsCalendar","parameters":[],"responses":{"200":{"content":{"text/calendar":{"schema":{"type":"string"}}},"description":"iCalendar (RFC 5545)"}},"summary":"Every upcoming event. An iCalendar feed to subscribe to.","tags":["public"]}},"/events/{id}/calendar.ics":{"get":{"operationId":"eventCalendar","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"content":{"text/calendar":{"schema":{"type":"string"}}},"description":"iCalendar (RFC 5545)"}},"summary":"One event. An iCalendar feed to subscribe to.","tags":["public"]}},"/places/{geoid}/events.ics":{"get":{"operationId":"placeEventsCalendar","parameters":[{"example":"0681554","in":"path","name":"geoid","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"text/calendar":{"schema":{"type":"string"}}},"description":"iCalendar (RFC 5545)"}},"summary":"One place's upcoming events. An iCalendar feed to subscribe to.","tags":["public"]}}},"servers":[{"url":"https://commons.app"}],"tags":[{"description":"No token.","name":"public"},{"description":"Getting a `com_` token.","name":"sign-in"},{"description":"The token owner's own records.","name":"me"},{"description":"MCP over JSON-RPC.","name":"agents"}]}