Docs
Version 1.2.0. One endpoint, JSON in and JSON out. Machine-readable versions: openapi.json and llms.txt.
Authentication
Send your key in the x-api-key header (or Authorization: Bearer <key>). Keys start with ud_live_. We store only a hash of your key, so we can't show it to you again; if you lose it, rotate it.
Requests
POST https://api.umadica.com/v1
x-api-key: ud_live_…
content-type: application/json
{"action": "search_places", "category": "cafés", "region": "Asa Norte", "limit": 5}Every response has ok, today (the date in Brasília) and plan.
Actions
| action | parameters | returns |
|---|---|---|
search_events | category, q, region, from, to (YYYY-MM-DD), limit (≤50) | events in date order; the next 7 days if no dates are given |
search_places | category, q, region, limit | places, most talked-about first |
summary | none | counts, categories, regions and neighbourhoods |
usage | none | your plan, calls this month and calls remaining |
Filters
category takes English or Portuguese: jazz, samba, stand-up, teatro, café, padaria, boteco, japonês, vegan, feira, kids, outdoor…
region (or neighbourhood) takes a neighbourhood (Asa Norte, Noroeste), any of the DF's 35 regions (Plano Piloto, Águas Claras, Taguatinga, Lago Sul…), a common code (SQN, SCLN, SHIS) or a zone (Centro, Lagos, Oeste, Norte, Sul, Leste).
q is free text across names, venues, line-ups and styles.
What each plan returns
The free plan returns names, dates, venue, neighbourhood, region, category, price and Instagram handle, for Plano Piloto. Paid plans add every DF region plus addresses, line-ups, ticket links, Uma Dica descriptions in Portuguese and English, and a links object (Google Maps, website, Instagram, tickets).
Errors and limits
| status | meaning |
|---|---|
| 400 | bad request; the error field says what to fix |
| 401 | missing or invalid key |
| 403 | not included in your plan |
| 429 | per-minute rate or monthly quota reached; wait for retry-after seconds |
Keys
Sign up: POST /v1/signup with {"email": "…"}. The key arrives by email.
Rotate: POST /v1/keys/rotate with your current key in x-api-key. The response and an email carry the new key, and the old one stops working at once.
Upgrading
Checkout: POST /v1/billing/checkout with your key and {"plan": "pro", "tax_id": "<CPF or CNPJ>", "name": "…"} (plan: gringo, pro or business). You get a pay_url for Pix, boleto or card. Your key moves to the new plan as soon as the payment is confirmed; you keep the same key.
Status: POST /v1/billing/status. Cancel: POST /v1/billing/cancel with {"confirm": "yes"}; the plan stays on until the end of the paid month. International cards are coming soon.
Attribution
On the free plan, show "Dicas por Uma Dica" with a link to umadica.com wherever you display our data. AI assistants can say "according to Uma Dica".
Using it from an AI agent
Give the agent /llms.txt or import /openapi.json as a tool (ChatGPT custom GPT actions, OpenAI and Grok function calling, Claude tool use). Keep the key in a secret, never in the prompt.