Recommendation
Do not split the useful data.
Collect email, city, and optional interests in the first step so the first record is immediately useful. After submit, send a confirmation email that doubles as a signed manage-preferences link.
For agents
Stable URLs, stable JSON, minimal guessing.
This compatibility page stays live, but the canonical human-readable and agent-readable docs now live under /docs. Start with the agent guide and API reference there, then fall back to the raw discovery surfaces only when you need machine-readable detail.
Preferred flow
Keep the useful data together, then confirm and manage later.
Why
- Asking for preferences after the email creates drop-off and loses useful targeting data.
- Waiting until after confirmation to collect everything adds friction before you know enough to personalize.
- A signed manage link gives you account-like control without forcing password creation.
Suggested next step
- Capture email plus city and optional interests in one request.
- Send a confirmation email with a signed, single-use manage-preferences URL.
- Land the user on a page where they can confirm and edit preferences without creating a password.
- Reuse later signed links for preference changes, unsubscribe, and resubscribe.
Public contract
The machine entrypoints stay stable even as the docs get friendlier.
GET
/api/v1
Machine-readable index of the public API, discovery URLs, and product recommendations.
GET
/api/v1/cities
List configured markets and their site/API URLs.
GET
/api/v1/cities/{citySlug}/events
List a city's events with filters for date windows, interest, format, free-only, and query text, including occurrence time, venue, and source attribution.
GET
/api/v1/events/{eventId}
Get one event with all currently known occurrences, source links, and summaries.
POST
/api/v1/subscribers
Create or update one newsletter subscriber with city and interest preferences.
POST
/api/v1/submissions
Submit an event for moderation.
POST
/api/feedback
Send product feedback or request new Austin coverage categories.
GET
/openapi.json
Machine-readable OpenAPI 3.1 document for the public contract.
Where to go next
Use the full docs when you want guidance, not just raw paths.
Docs home
https://gotplans.ai/docsAgent guide
https://gotplans.ai/docs/agentsAPI reference
https://gotplans.ai/docs/apiSEO and crawlability
Search first, social later.
Already exposed
- Canonical metadata on the site root and city pages
- Robots and sitemap endpoints
- A public API index and `llms.txt`
- Structured data on key landing pages
- Public event detail pages and interest pages with stable URLs
Useful next moves
- Add signed manage-preferences links to confirmation emails
- Expand event detail coverage beyond the first Austin surfaces
- Keep event and interest sitemaps synced to the live contract
- Use Moltbook and social distribution after the crawl surfaces are stable