{"openapi":"3.1.0","info":{"title":"Parchar.ai Event Data API","version":"2026-04-18","summary":"Infraestructura API-first para consultar eventos publicados en LatAm con trazabilidad, freshness y degradacion honesta.","description":"Esta especificacion cubre el contrato publico de lectura sobre /api/v1. La plataforma prioriza confiabilidad, cobertura y calidad del dato por encima de indexacion de milisegundos."},"servers":[{"url":"https://api.parchar.ai/api/v1"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"events"},{"name":"taxonomy"},{"name":"meta"},{"name":"changes"},{"name":"sources"}],"paths":{"/events":{"get":{"tags":["events"],"operationId":"listEvents","summary":"Lista eventos publicados","parameters":[{"$ref":"#/components/parameters/CountryCode"},{"$ref":"#/components/parameters/City"},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"venue_id","in":"query","schema":{"type":"string"}},{"name":"q","in":"query","schema":{"type":"string","maxLength":200},"description":"Busqueda textual sin SLA en free."},{"name":"bbox","in":"query","schema":{"type":"string"}},{"name":"date_from","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"date_to","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"updated_since","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"sort","in":"query","schema":{"type":"string","enum":["start_at","updated_at","rank"],"default":"start_at"}},{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100}}],"responses":{"200":{"description":"Listado exitoso","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/EventListResponse"}]},"example":{"success":true,"data":[{"id":"evt_01jz2x9w0m","title":"Concierto en Chapinero","status":"active","category":"concierto","subcategory":"indie","country_code":"CO","city":"bogota","timezone":"America/Bogota","start_at":"2026-04-20T20:00:00-05:00","end_at":"2026-04-20T23:00:00-05:00","description_short":"Noche de indie en Chapinero","description_long":"Concierto con aforo limitado y ticketing oficial.","language":"es","source_primary_url":"https://tickets.example.com/events/chapinero-indie","venue_id":"ven_01jy9w0m2k","venue":{"id":"ven_01jy9w0m2k","name":"Teatro ejemplo","country_code":"CO","city":"bogota","neighborhood":"Chapinero","address":"Calle 63 #10-20","latitude":4.6486,"longitude":-74.0628,"timezone":"America/Bogota","accessibility":{"wheelchair_access":true},"metadata":{},"updated_at":"2026-04-18T09:00:00Z"},"tags":["indie","live-music"],"artists":[{"id":"artist_1","name":"Banda Demo"}],"organizer":{"name":"Promotora Demo"},"ticket_url":"https://tickets.example.com/events/chapinero-indie/buy","ticket_options":[{"id":"ticket_general","label":"General","price_minor":85000,"currency":"COP","availability_status":"available","purchase_url":"https://tickets.example.com/events/chapinero-indie/buy"}],"image_url":"https://cdn.parchar.ai/eventos/chapinero-indie.jpg","latitude":4.6486,"longitude":-74.0628,"price_min":85000,"price_max":85000,"currency":"COP","is_free":false,"age_restriction":"18+","accessibility":{"wheelchair_access":true},"availability_status":"available","quality":{"confidence_score":0.94,"freshness_status":"fresh","last_checked_at":"2026-04-18T08:42:00Z","source_verified":true,"field_confidence":{"title":0.99,"start_at":0.98},"reported_or_inferred":{"title":"reported","venue":"verified"},"degraded_reason":null,"partial_data":false,"suppressed_fields":[]},"derived":{"event_rank_score":0.81,"commercial_intent_score":0.76,"starts_in_hours":52,"price_bucket":"mid","duplicate_cluster_id":null,"source_count":2},"source_trace":[{"source_id":"src_1","source_name":"Ticketing oficial","source_url":"https://tickets.example.com/events/chapinero-indie","provenance":"verified","field_confidence":{"title":0.99},"last_checked_at":"2026-04-18T08:42:00Z"}],"updated_at":"2026-04-18T08:45:00Z","published_at":"2026-04-18T08:45:00Z"}],"meta":{"plan":"free","page":1,"limit":20,"total":318,"has_more":true,"applied_future_horizon_days":30,"applied_date_to":"2026-05-18T00:00:00"}}}}},"401":{"description":"API key faltante o invalida","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]}}}}}}},"/events/{id}":{"get":{"tags":["events"],"operationId":"getEvent","summary":"Obtiene un evento publicado por id","parameters":[{"$ref":"#/components/parameters/EventId"}],"responses":{"200":{"description":"Evento encontrado","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/EventResponse"}]},"example":{"success":true,"data":{"id":"evt_01jz2x9w0m","title":"Concierto en Chapinero","status":"active","category":"concierto","subcategory":"indie","country_code":"CO","city":"bogota","timezone":"America/Bogota","start_at":"2026-04-20T20:00:00-05:00","end_at":"2026-04-20T23:00:00-05:00","description_short":"Noche de indie en Chapinero","description_long":"Concierto con aforo limitado y ticketing oficial.","language":"es","source_primary_url":"https://tickets.example.com/events/chapinero-indie","venue_id":"ven_01jy9w0m2k","venue":{"id":"ven_01jy9w0m2k","name":"Teatro ejemplo","country_code":"CO","city":"bogota","neighborhood":"Chapinero","address":"Calle 63 #10-20","latitude":4.6486,"longitude":-74.0628,"timezone":"America/Bogota","accessibility":{"wheelchair_access":true},"metadata":{},"updated_at":"2026-04-18T09:00:00Z"},"tags":["indie","live-music"],"artists":[{"id":"artist_1","name":"Banda Demo"}],"organizer":{"name":"Promotora Demo"},"ticket_url":"https://tickets.example.com/events/chapinero-indie/buy","ticket_options":[{"id":"ticket_general","label":"General","price_minor":85000,"currency":"COP","availability_status":"available","purchase_url":"https://tickets.example.com/events/chapinero-indie/buy"}],"image_url":"https://cdn.parchar.ai/eventos/chapinero-indie.jpg","latitude":4.6486,"longitude":-74.0628,"price_min":85000,"price_max":85000,"currency":"COP","is_free":false,"age_restriction":"18+","accessibility":{"wheelchair_access":true},"availability_status":"available","quality":{"confidence_score":0.94,"freshness_status":"fresh","last_checked_at":"2026-04-18T08:42:00Z","source_verified":true,"field_confidence":{"title":0.99,"start_at":0.98},"reported_or_inferred":{"title":"reported","venue":"verified"},"degraded_reason":null,"partial_data":false,"suppressed_fields":[]},"derived":{"event_rank_score":0.81,"commercial_intent_score":0.76,"starts_in_hours":52,"price_bucket":"mid","duplicate_cluster_id":null,"source_count":2},"source_trace":[{"source_id":"src_1","source_name":"Ticketing oficial","source_url":"https://tickets.example.com/events/chapinero-indie","provenance":"verified","field_confidence":{"title":0.99},"last_checked_at":"2026-04-18T08:42:00Z"}],"updated_at":"2026-04-18T08:45:00Z","published_at":"2026-04-18T08:45:00Z"}}}}},"404":{"description":"Evento no encontrado","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]}}}}}}},"/venues/{id}":{"get":{"tags":["events"],"operationId":"getVenue","summary":"Obtiene un venue canonico","parameters":[{"$ref":"#/components/parameters/EventId"}],"responses":{"200":{"description":"Venue encontrado","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/VenueResponse"}]},"example":{"success":true,"data":{"id":"ven_01jy9w0m2k","name":"Teatro ejemplo","country_code":"CO","city":"bogota","neighborhood":"Chapinero","address":"Calle 63 #10-20","latitude":4.6486,"longitude":-74.0628,"timezone":"America/Bogota","accessibility":{"wheelchair_access":true},"metadata":{},"updated_at":"2026-04-18T09:00:00Z"}}}}}}}},"/cities":{"get":{"tags":["taxonomy"],"operationId":"listCities","summary":"Lista ciudades publicadas","parameters":[{"$ref":"#/components/parameters/CountryCode"}],"responses":{"200":{"description":"Ciudades","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CitiesResponse"}]}}}}}}},"/categories":{"get":{"tags":["taxonomy"],"operationId":"listCategories","summary":"Lista categorias publicadas","parameters":[{"$ref":"#/components/parameters/CountryCode"}],"responses":{"200":{"description":"Categorias","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CategoriesResponse"}]}}}}}}},"/meta/status":{"get":{"tags":["meta"],"operationId":"getStatus","summary":"Resumen operativo partner-safe de freshness y publish health","parameters":[{"$ref":"#/components/parameters/CountryCode"},{"$ref":"#/components/parameters/City"},{"$ref":"#/components/parameters/WindowHours"}],"responses":{"200":{"description":"Estado operativo","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/FreshnessStatusResponse"}]}}}}}}},"/meta/freshness":{"get":{"tags":["meta"],"operationId":"getFreshnessBreakdown","summary":"Breakdown de freshness por tipo de fuente","parameters":[{"$ref":"#/components/parameters/CountryCode"},{"$ref":"#/components/parameters/City"}],"responses":{"200":{"description":"Freshness breakdown","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/FreshnessBreakdownResponse"}]}}}}}}},"/changes":{"get":{"tags":["changes"],"operationId":"listChanges","summary":"Feed incremental de cambios publicados","description":"Disponible desde plan Build o superior.","parameters":[{"name":"updated_since","in":"query","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","schema":{"type":"integer","default":100,"minimum":1,"maximum":200}}],"responses":{"200":{"description":"Cambios","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ChangesResponse"}]}}}},"403":{"description":"Plan insuficiente","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]}}}}}}},"/sources/{id}":{"get":{"tags":["sources"],"operationId":"getSource","summary":"Detalle de fuente y provenance","description":"Disponible desde plan Build o superior.","parameters":[{"$ref":"#/components/parameters/EventId"}],"responses":{"200":{"description":"Fuente encontrada","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SourceResponse"}]}}}},"403":{"description":"Plan insuficiente","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]}}}}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key del workspace. Tambien se acepta Authorization: Bearer <key>."}},"parameters":{"CountryCode":{"name":"country_code","in":"query","schema":{"type":"string","minLength":2,"maxLength":2}},"City":{"name":"city","in":"query","schema":{"type":"string","maxLength":100}},"WindowHours":{"name":"window_hours","in":"query","schema":{"type":"integer","minimum":1,"maximum":720,"default":24}},"EventId":{"name":"id","in":"path","required":true,"schema":{"type":"string"}}},"schemas":{"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":false},"QualityMetadata":{"type":"object","properties":{"confidence_score":{"type":"number"},"freshness_status":{"type":"string","enum":["fresh","stale","frozen"]},"last_checked_at":{"type":"string","format":"date-time","nullable":true},"source_verified":{"type":"boolean"},"field_confidence":{"type":"object","additionalProperties":{"type":"number"}},"reported_or_inferred":{"type":"object","additionalProperties":{"type":"string","enum":["reported","inferred","verified"]}},"degraded_reason":{"type":"string","enum":["source_unavailable","quality_hold","anti_bot","partial_source"],"nullable":true},"partial_data":{"type":"boolean"},"suppressed_fields":{"type":"array","items":{"type":"string"}}},"required":["confidence_score","freshness_status","source_verified","field_confidence","reported_or_inferred","partial_data","suppressed_fields"],"additionalProperties":false},"Venue":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"country_code":{"type":"string"},"city":{"type":"string"},"neighborhood":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true},"timezone":{"type":"string"},"accessibility":{"type":"object","additionalProperties":true},"metadata":{"type":"object","additionalProperties":true},"updated_at":{"type":"string","format":"date-time","nullable":true}},"required":["id","name","country_code","city","timezone","accessibility","metadata"],"additionalProperties":false},"TicketOption":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"price_minor":{"type":"integer","nullable":true},"currency":{"type":"string","nullable":true},"availability_status":{"type":"string","nullable":true},"purchase_url":{"type":"string","format":"uri","nullable":true}},"required":["id","label"],"additionalProperties":false},"SourceTrace":{"type":"object","properties":{"source_id":{"type":"string"},"source_name":{"type":"string"},"source_url":{"type":"string","format":"uri","nullable":true},"provenance":{"type":"string","enum":["reported","inferred","verified"]},"field_confidence":{"type":"object","additionalProperties":{"type":"number"}},"last_checked_at":{"type":"string","format":"date-time","nullable":true}},"required":["source_id","source_name","provenance","field_confidence"],"additionalProperties":false},"PublishedEvent":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"status":{"type":"string"},"category":{"type":"string"},"subcategory":{"type":"string","nullable":true},"country_code":{"type":"string"},"city":{"type":"string"},"timezone":{"type":"string"},"start_at":{"type":"string","format":"date-time"},"end_at":{"type":"string","format":"date-time","nullable":true},"description_short":{"type":"string","nullable":true},"description_long":{"type":"string","nullable":true},"language":{"type":"string"},"source_primary_url":{"type":"string","format":"uri"},"venue_id":{"type":"string","nullable":true},"venue":{"allOf":[{"$ref":"#/components/schemas/Venue"}],"nullable":true},"tags":{"type":"array","items":{"type":"string"}},"artists":{"type":"array","items":{"type":"object","additionalProperties":true}},"organizer":{"type":"object","additionalProperties":true,"nullable":true},"ticket_url":{"type":"string","format":"uri","nullable":true},"ticket_options":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/TicketOption"}]}},"image_url":{"type":"string","format":"uri","nullable":true},"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true},"price_min":{"type":"number","nullable":true},"price_max":{"type":"number","nullable":true},"currency":{"type":"string","nullable":true},"is_free":{"type":"boolean"},"age_restriction":{"type":"string","nullable":true},"accessibility":{"type":"object","additionalProperties":true},"availability_status":{"type":"string","nullable":true},"quality":{"allOf":[{"$ref":"#/components/schemas/QualityMetadata"}]},"derived":{"type":"object","additionalProperties":true},"source_trace":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/SourceTrace"}]}},"updated_at":{"type":"string","format":"date-time","nullable":true},"published_at":{"type":"string","format":"date-time","nullable":true}},"required":["id","title","status","category","country_code","city","timezone","start_at","language","source_primary_url","tags","artists","ticket_options","is_free","accessibility","quality","derived"],"additionalProperties":false},"ApiListMeta":{"type":"object","properties":{"plan":{"type":"string","enum":["free","build","growth","enterprise"]},"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"has_more":{"type":"boolean"},"applied_future_horizon_days":{"type":"integer"},"applied_date_to":{"type":"string","format":"date-time","nullable":true}},"required":["plan","page","limit","total","has_more","applied_future_horizon_days"],"additionalProperties":false},"EventListResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/PublishedEvent"}]}},"meta":{"allOf":[{"$ref":"#/components/schemas/ApiListMeta"}]}},"required":["success","data","meta"],"additionalProperties":false},"EventResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"allOf":[{"$ref":"#/components/schemas/PublishedEvent"}]}},"required":["success","data"],"additionalProperties":false},"VenueResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"allOf":[{"$ref":"#/components/schemas/Venue"}]}},"required":["success","data"],"additionalProperties":false},"CitiesResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"country_code":{"type":"string"},"country_name":{"type":"string"},"city":{"type":"string"},"city_name":{"type":"string"},"event_count":{"type":"integer"},"next_event_start_at":{"type":"string","format":"date-time","nullable":true},"freshness":{"type":"object","properties":{"fresh":{"type":"integer"},"stale":{"type":"integer"},"frozen":{"type":"integer"}},"required":["fresh","stale","frozen"],"additionalProperties":false},"updated_at":{"type":"string","format":"date-time","nullable":true}},"required":["country_code","country_name","city","city_name","event_count","freshness"],"additionalProperties":false}}},"required":["success","data"],"additionalProperties":false},"CategoriesResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"country_code":{"type":"string"},"category":{"type":"string"},"event_count":{"type":"integer"},"updated_at":{"type":"string","format":"date-time","nullable":true}},"required":["country_code","category","event_count"],"additionalProperties":false}}},"required":["success","data"],"additionalProperties":false},"FreshnessStatusResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"scope":{"type":"object","properties":{"country_code":{"type":"string","nullable":true},"city":{"type":"string","nullable":true}},"additionalProperties":false},"inventory":{"type":"object","additionalProperties":true},"freshness":{"type":"object","additionalProperties":true},"degraded_inventory":{"type":"object","additionalProperties":true},"publish_window":{"type":"object","additionalProperties":true},"repair_window":{"type":"object","additionalProperties":true}},"required":["scope","inventory","freshness","degraded_inventory","publish_window","repair_window"],"additionalProperties":false}},"required":["success","data"],"additionalProperties":false},"FreshnessBreakdownResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"primary_source_type":{"type":"string"},"freshness_status":{"type":"string"},"event_count":{"type":"integer"},"last_checked_at":{"type":"string","format":"date-time","nullable":true}},"required":["primary_source_type","freshness_status","event_count"],"additionalProperties":false}}},"required":["success","data"],"additionalProperties":false},"ChangesResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"published_event_id":{"type":"string"},"change_type":{"type":"string","enum":["upsert","freeze","delete"]},"changed_at":{"type":"string","format":"date-time"},"snapshot":{"type":"object","additionalProperties":true}},"required":["published_event_id","change_type","changed_at","snapshot"],"additionalProperties":false}}},"required":["success","data"],"additionalProperties":false},"SourceResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","additionalProperties":true}},"required":["success","data"],"additionalProperties":false}}}}