{"slug": "making-a-local-events-api-discoverable-to-developers-and-ai-assistants", "title": "Making a Local Events API Discoverable to Developers and AI Assistants", "summary": "The DondeGo API, a local discovery platform for Barcelona and Madrid, has launched a public discovery layer to make its cultural data more accessible beyond standard web pages. This package includes OpenAPI, llms.txt, an API Catalog linkset, Postman documentation, and an Agent Skills index, designed to help developers, API clients, and AI assistants easily discover, understand, and use the API. The project emphasizes accurate documentation and a \"detail-first attribution rule,\" requiring any public display of event data to include a direct link to the canonical DondeGo event page.", "body_md": "Local cultural data should not only live as web pages.\n\nThat is the idea behind the public discovery layer we just shipped for the DondeGo API.\n\nDondeGo is a local discovery platform for Barcelona and Madrid, focused on events, places, cultural life, and local news. We are building it as a media and discovery product, but we also want the data surface to be understandable by developers, API clients, documentation tools, and AI assistants.\n\nSo instead of only publishing a human-readable API page, we built a small discovery package around the API.\n\nIt includes OpenAPI, llms.txt, an API Catalog linkset, Postman documentation, examples, and a documentation-only Agent Skills index.\n\nThe goal is simple:\n\nmake the API easier to discover, understand, cite, and use without pretending to support capabilities that do not exist yet.\n\n## What is live\n\nHere are the main public entry points.\n\nOpenAPI 3.1:\n\n[https://dondego.es/openapi.json](https://dondego.es/openapi.json)\n\nllms.txt:\n\n[https://dondego.es/llms.txt](https://dondego.es/llms.txt)\n\nAPI Catalog linkset:\n\n[https://dondego.es/.well-known/api-catalog](https://dondego.es/.well-known/api-catalog)\n\nRich DondeGo discovery JSON:\n\n[https://dondego.es/api-catalog.json](https://dondego.es/api-catalog.json)\n\nDocumentation-only Agent Skills index:\n\n[https://dondego.es/.well-known/agent-skills/index.json](https://dondego.es/.well-known/agent-skills/index.json)\n\nPostman documentation:\n\n[https://documenter.getpostman.com/view/55094507/2sBXwjvZRZ](https://documenter.getpostman.com/view/55094507/2sBXwjvZRZ)\n\nGitHub repository:\n\n[https://github.com/revanbcn/DondeGo-API](https://github.com/revanbcn/DondeGo-API)\n\nThe repository also includes server-side examples for curl, Python, and Node:\n\n[https://github.com/revanbcn/DondeGo-API/tree/main/examples](https://github.com/revanbcn/DondeGo-API/tree/main/examples)\n\nAnd a ready-to-import Postman Collection:\n\n[https://github.com/revanbcn/DondeGo-API/tree/main/postman](https://github.com/revanbcn/DondeGo-API/tree/main/postman)\n\n## Why not just publish OpenAPI?\n\nOpenAPI is the most important artifact, but it is not the whole discovery story.\n\nDifferent tools look for different signals:\n\n- developers want examples and a clear README\n- API clients want OpenAPI\n- Postman users want a collection\n- LLM-oriented tools can benefit from llms.txt\n- API discovery systems can use a linkset\n- agents need short, explicit usage guidance\n- partners need attribution and usage rules\nSo the discovery layer is intentionally made of several small, stable surfaces instead of one giant documentation page.\n## Verified endpoint families\nThe current OpenAPI v0.1 spec is intentionally conservative.\nIt documents only endpoint families we have verified and are ready to describe clearly:\n`GET /locations/ GET /events/ GET /events/{id}/ GET /places/ GET /places/{id}/ GET /news/ GET /news/{id}/ GET /events-of-the-day/ GET /search/?q=...`\n\nWe did not add endpoints just because they might exist somewhere.\n\nWe did not document parameters that still need verification.\n\nWe did not generate a huge speculative spec.\n\nThe goal of v0.1 is to describe what can be described accurately.\n\nQuick example\n\nThe public API base is:\n\n[https://dondego.es/public-api/v1.4](https://dondego.es/public-api/v1.4)\n\nList supported locations:\n\n`curl -s https://dondego.es/public-api/v1.4/locations/ | jq`\n\nList a few Barcelona event summaries:\n\n`curl -s \"https://dondego.es/public-api/v1.4/events/?location=barcelona&page_size=3\" | jq`\n\nFetch event details:\n\n```\ncurl -s \"https://dondego.es/public-api/v1.4/events/{id}/?expand=place,images,dates,categories,tags,participants\" | jq\n```\n\nMore complete examples are available here:\n\n[https://github.com/revanbcn/DondeGo-API/tree/main/examples](https://github.com/revanbcn/DondeGo-API/tree/main/examples)\n\nThe detail-first attribution rule\n\nOne important rule in the current API is event attribution.\n\nEvent list rows are useful for discovery, but they do not expose everything needed for safe public rendering. In particular, list rows do not expose the canonical DondeGo event page URL.\n\nFor public event rendering, the rule is:\n\nevent list -> fetch event detail -> use EventDetail.site_url as the visible DondeGo source link\n\nThis matters because any public website, app, newsletter, bot, AI assistant, or partner integration that displays DondeGo event descriptions or substantial DondeGo event data must include a visible direct link to the canonical DondeGo.es event page as the source.\n\nThat rule is repeated across the docs, examples, Postman collection, llms.txt, and API catalog.\n\nIt is not just a legal or SEO detail. It is part of making local data trustworthy.\n\nIf a user sees an event recommendation in an app or assistant, they should be able to click through to the original canonical page.\n\nllms.txt\n\nWe publish:\n\nThis file is a short LLM-oriented index.\n\nIt points to the most important resources:\n\n- what DondeGo is\n- what the public API covers\n- where the OpenAPI spec lives\n- where the API Catalog lives\n- where examples live\n- what attribution rule must be followed\n- what is not supported yet\n\nIt does not magically make every model use the API.\n\nBut it gives AI systems and developer tools a clear, stable, crawlable reference.\n\nAPI Catalog linkset\n\nWe also publish:\n\n[https://dondego.es/.well-known/api-catalog](https://dondego.es/.well-known/api-catalog)\n\nThis is served as:\n\napplication/linkset+json\n\nIt links to the core discovery resources:\n\n- OpenAPI\n- documentation\n- llms.txt\n- attribution policy\n- examples\n- version history\n- richer DondeGo discovery JSON\n\nThe richer DondeGo-specific JSON is available separately:\n\n[https://dondego.es/api-catalog.json](https://dondego.es/api-catalog.json)\n\nThis split is intentional.\n\nThe .well-known/api-catalog route is a compact machine-readable linkset. The /api-catalog.json route carries richer DondeGo-specific context.\n\nDocumentation-only Agent Skills\n\nWe also publish a documentation-only Agent Skills index:\n\n[https://dondego.es/.well-known/agent-skills/index.json](https://dondego.es/.well-known/agent-skills/index.json)\n\nThe important part is “documentation-only”.\n\nThere are no scripts. No executable code. No hidden tool access. No permission escalation. No OAuth. No MCP transport.\n\nThe skill exists to teach an AI agent how to discover and correctly use the DondeGo public API documentation.\n\nIt explains the stable discovery URLs, verified endpoint families, attribution requirement, and detail-first event rendering rule.\n\nWhat we intentionally do not advertise\n\nThis is probably the most important architectural decision in the whole package.\n\nWe do not advertise OAuth or OIDC support, because DondeGo does not currently run an OAuth issuer.\n\nWe do not publish OAuth Protected Resource Metadata, because the current public discovery package does not expose OAuth-protected scopes.\n\nWe do not claim to have an MCP server.\n\nWe do not claim to have WebMCP tools.\n\nWe do not document date filters or the limit parameter in OpenAPI v0.1, because those still need separate verification.\n\nWe do not publish browser-only examples yet, because CORS behavior should be handled deliberately, not assumed.\n\nAccurate discovery metadata is more useful than fake “agent-ready” metadata.\n\nIf a site publishes machine-readable discovery files, those files should describe real capabilities.\n\nPostman documentation\n\nFor developers who prefer Postman, we published public documentation:\n\n[https://documenter.getpostman.com/view/55094507/2sBXwjvZRZ](https://documenter.getpostman.com/view/55094507/2sBXwjvZRZ)\n\nThe repository also includes a ready-to-import Postman Collection v2.1:\n\n[https://github.com/revanbcn/DondeGo-API/tree/main/postman](https://github.com/revanbcn/DondeGo-API/tree/main/postman)\n\nThe collection uses only public GET requests. It does not include environments, secrets, API keys, cookies, bearer tokens, or OAuth settings.\n\nWhat this enables\n\nThis discovery layer is useful for several types of builders:\n\n- local newsletters that want to enrich issues with cultural events\n- city guides that need venues and event details\n- travel or lifestyle apps building a Barcelona or Madrid experience layer\n- AI assistants that need structured local data instead of guessing\n- developers who want to explore the API through OpenAPI or Postman\n- partners who need clear attribution rules before building on the data\n\nThe package is not a huge platform launch.\n\nIt is a foundation.\n\nBut I think this foundation matters.\n\nLocal media and cultural platforms should be easier to integrate with. They should publish machine-readable contracts. They should be understandable by AI-assisted tools. And they should be clear about attribution.\n\nThat is the direction we are taking with DondeGo.\n\nStart here\n\nGitHub repository:\n\n[https://github.com/revanbcn/DondeGo-API](https://github.com/revanbcn/DondeGo-API)\n\nLive OpenAPI:\n\n[https://dondego.es/openapi.json](https://dondego.es/openapi.json)\n\nPostman documentation:\n\n[https://documenter.getpostman.com/view/55094507/2sBXwjvZRZ](https://documenter.getpostman.com/view/55094507/2sBXwjvZRZ)\n\nllms.txt:\n\n[https://dondego.es/llms.txt](https://dondego.es/llms.txt)\n\nAPI Catalog:\n\n[https://dondego.es/.well-known/api-catalog](https://dondego.es/.well-known/api-catalog)\n\nIf you are building a local guide, AI assistant, cultural newsletter, events app, map product, or city discovery experience for Barcelona or Madrid, I would be happy to talk.\n\nPartner access and integration discussions:\n\n[bcn@dondego.es](mailto:bcn@dondego.es)", "url": "https://wpnews.pro/news/making-a-local-events-api-discoverable-to-developers-and-ai-assistants", "canonical_source": "https://dev.to/revan_dondego/making-a-local-events-api-discoverable-to-developers-and-ai-assistants-4i07", "published_at": "2026-05-21 23:14:32+00:00", "updated_at": "2026-05-22 00:04:57.234668+00:00", "lang": "en", "topics": ["developer-tools", "data", "artificial-intelligence", "open-source", "products"], "entities": ["DondeGo", "Barcelona", "Madrid", "OpenAPI", "Postman", "GitHub", "llms.txt", "API Catalog"], "alternates": {"html": "https://wpnews.pro/news/making-a-local-events-api-discoverable-to-developers-and-ai-assistants", "markdown": "https://wpnews.pro/news/making-a-local-events-api-discoverable-to-developers-and-ai-assistants.md", "text": "https://wpnews.pro/news/making-a-local-events-api-discoverable-to-developers-and-ai-assistants.txt", "jsonld": "https://wpnews.pro/news/making-a-local-events-api-discoverable-to-developers-and-ai-assistants.jsonld"}}