DEV Community

Cover image for Making a Local Events API Discoverable to Developers and AI Assistants
Alexander Prokofiev
Alexander Prokofiev

Posted on

Making a Local Events API Discoverable to Developers and AI Assistants

#openapi #ai #webdev #api

Local cultural data should not only live as web pages.
That is the idea behind the public discovery layer we just shipped for the DondeGo API.
DondeGo 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.
So instead of only publishing a human-readable API page, we built a small discovery package around the API.
It includes OpenAPI, llms.txt, an API Catalog linkset, Postman documentation, examples, and a documentation-only Agent Skills index.
The goal is simple:
make the API easier to discover, understand, cite, and use without pretending to support capabilities that do not exist yet.

What is live

Here are the main public entry points.
OpenAPI 3.1:
https://dondego.es/openapi.json
llms.txt:
https://dondego.es/llms.txt
API Catalog linkset:
https://dondego.es/.well-known/api-catalog
Rich DondeGo discovery JSON:
https://dondego.es/api-catalog.json
Documentation-only Agent Skills index:
https://dondego.es/.well-known/agent-skills/index.json
Postman documentation:
https://documenter.getpostman.com/view/55094507/2sBXwjvZRZ
GitHub repository:
https://github.com/revanbcn/DondeGo-API
The repository also includes server-side examples for curl, Python, and Node:
https://github.com/revanbcn/DondeGo-API/tree/main/examples
And a ready-to-import Postman Collection:
https://github.com/revanbcn/DondeGo-API/tree/main/postman

Why not just publish OpenAPI?

OpenAPI is the most important artifact, but it is not the whole discovery story.
Different tools look for different signals:

  • developers want examples and a clear README
  • API clients want OpenAPI
  • Postman users want a collection
  • LLM-oriented tools can benefit from llms.txt
  • API discovery systems can use a linkset
  • agents need short, explicit usage guidance
  • partners need attribution and usage rules So the discovery layer is intentionally made of several small, stable surfaces instead of one giant documentation page. ## Verified endpoint families The current OpenAPI v0.1 spec is intentionally conservative. It documents only endpoint families we have verified and are ready to describe clearly: 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=...

We did not add endpoints just because they might exist somewhere.

We did not document parameters that still need verification.

We did not generate a huge speculative spec.

The goal of v0.1 is to describe what can be described accurately.

Quick example

The public API base is:

https://dondego.es/public-api/v1.4

List supported locations:

curl -s https://dondego.es/public-api/v1.4/locations/ | jq

List a few Barcelona event summaries:

curl -s "https://dondego.es/public-api/v1.4/events/?location=barcelona&page_size=3" | jq

Fetch event details:

curl -s "https://dondego.es/public-api/v1.4/events/{id}/?expand=place,images,dates,categories,tags,participants" | jq
Enter fullscreen mode Exit fullscreen mode

More complete examples are available here:

https://github.com/revanbcn/DondeGo-API/tree/main/examples

The detail-first attribution rule

One important rule in the current API is event attribution.

Event 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.

For public event rendering, the rule is:

event list -> fetch event detail -> use EventDetail.site_url as the visible DondeGo source link

This 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.

That rule is repeated across the docs, examples, Postman collection, llms.txt, and API catalog.

It is not just a legal or SEO detail. It is part of making local data trustworthy.

If a user sees an event recommendation in an app or assistant, they should be able to click through to the original canonical page.

llms.txt

We publish:

https://dondego.es/llms.txt

This file is a short LLM-oriented index.

It points to the most important resources:

  • what DondeGo is
  • what the public API covers
  • where the OpenAPI spec lives
  • where the API Catalog lives
  • where examples live
  • what attribution rule must be followed
  • what is not supported yet

It does not magically make every model use the API.

But it gives AI systems and developer tools a clear, stable, crawlable reference.

API Catalog linkset

We also publish:

https://dondego.es/.well-known/api-catalog

This is served as:

application/linkset+json

It links to the core discovery resources:

  • OpenAPI
  • documentation
  • llms.txt
  • attribution policy
  • examples
  • version history
  • richer DondeGo discovery JSON

The richer DondeGo-specific JSON is available separately:

https://dondego.es/api-catalog.json

This split is intentional.

The .well-known/api-catalog route is a compact machine-readable linkset. The /api-catalog.json route carries richer DondeGo-specific context.

Documentation-only Agent Skills

We also publish a documentation-only Agent Skills index:

https://dondego.es/.well-known/agent-skills/index.json

The important part is “documentation-only”.

There are no scripts. No executable code. No hidden tool access. No permission escalation. No OAuth. No MCP transport.

The skill exists to teach an AI agent how to discover and correctly use the DondeGo public API documentation.

It explains the stable discovery URLs, verified endpoint families, attribution requirement, and detail-first event rendering rule.

What we intentionally do not advertise

This is probably the most important architectural decision in the whole package.

We do not advertise OAuth or OIDC support, because DondeGo does not currently run an OAuth issuer.

We do not publish OAuth Protected Resource Metadata, because the current public discovery package does not expose OAuth-protected scopes.

We do not claim to have an MCP server.

We do not claim to have WebMCP tools.

We do not document date filters or the limit parameter in OpenAPI v0.1, because those still need separate verification.

We do not publish browser-only examples yet, because CORS behavior should be handled deliberately, not assumed.

Accurate discovery metadata is more useful than fake “agent-ready” metadata.

If a site publishes machine-readable discovery files, those files should describe real capabilities.

Postman documentation

For developers who prefer Postman, we published public documentation:

https://documenter.getpostman.com/view/55094507/2sBXwjvZRZ

The repository also includes a ready-to-import Postman Collection v2.1:

https://github.com/revanbcn/DondeGo-API/tree/main/postman

The collection uses only public GET requests. It does not include environments, secrets, API keys, cookies, bearer tokens, or OAuth settings.

What this enables

This discovery layer is useful for several types of builders:

  • local newsletters that want to enrich issues with cultural events
  • city guides that need venues and event details
  • travel or lifestyle apps building a Barcelona or Madrid experience layer
  • AI assistants that need structured local data instead of guessing
  • developers who want to explore the API through OpenAPI or Postman
  • partners who need clear attribution rules before building on the data

The package is not a huge platform launch.

It is a foundation.

But I think this foundation matters.

Local 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.

That is the direction we are taking with DondeGo.

Start here

GitHub repository:
https://github.com/revanbcn/DondeGo-API

Live OpenAPI:
https://dondego.es/openapi.json

Postman documentation:
https://documenter.getpostman.com/view/55094507/2sBXwjvZRZ

llms.txt:
https://dondego.es/llms.txt

API Catalog:
https://dondego.es/.well-known/api-catalog

If 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.

Partner access and integration discussions:
bcn@dondego.es

Top comments (0)