Documentation

Overview

Ciudad Viva's API integration is an automatic extraction(pull) system: Ciudad Viva periodically queries your API, gets the events and publishes them on the platform. Your system doesn't need to know that Ciudad Viva exists or send anything on its own.

How it works

The process has two actors: your system (which already exists and doesn't change) and Ciudad Viva (which queries it).

Your API requirements

Your API can have any structure, as long as it meets these basic requirements:

• ✓It responds with JSON (Content-Type: application/json).
• ✓It returns an array of events, either at the root of the response or inside some field.
• ✓Each event has at least a title and a start date.
• ✓The URL is reachable from the internet (it can't be localhost or a private internal network).
• ✓It accepts GET or POST as the HTTP method.

Step-by-step setup

Go to your organization's dashboard on Ciudad Viva and follow these steps:

1. 1

   Go to My organization → Integrations → New integration.

2. 2

   Enter a descriptive name (e.g. "Municipal events API").

3. 3

   Enter your API's URL.

4. 4

   Select the HTTP method (GET or POST).

5. 5

   If your API returns the events inside a field (e.g. data.results), enter that path in Path to the events array. If the array is at the root, leave this field empty.

6. 6

   Set up authentication if your API requires it (see the Authentication section).

7. 7

   Set up the field mapping, indicating which field of your API corresponds to each Ciudad Viva field (see the Field mapping section).

8. 8

   Click Test connection to check that everything works.

9. 9

   If the test succeeds, click Activate.

Authentication

Ciudad Viva supports four authentication methods. Choose the one your API uses. Credentials are stored encrypted with AES-256-GCM and are never exposed in logs or responses.

{
  "auth": {
    "type": "none"
  }
}

{
  "auth": {
    "type": "api_key",
    "apiKeyHeader": "X-API-Key",
    "apiKey": "your-secret-key"
  }
}

{
  "auth": {
    "type": "bearer",
    "bearerToken": "eyJhbGciOiJIUzI1NiJ9..."
  }
}

{
  "auth": {
    "type": "basic",
    "basicUsername": "my-username",
    "basicPassword": "my-password"
  }
}

Response format

Your API can return the events in any of these structures. The Path to the array field tells Ciudad Viva where to find the events array.

[
  {
    "title": "Summer Festival",
    "date": "2026-02-15",
    "location": "Parque O'Higgins"
  },
  {
    "title": "Theater Play",
    "date": "2026-02-20",
    "location": "Teatro Municipal"
  }
]

{
  "status": "ok",
  "total": 2,
  "events": [
    {
      "title": "Summer Festival",
      "date": "2026-02-15"
    }
  ]
}

{
  "meta": { "page": 1 },
  "data": {
    "results": [
      {
        "content": {
          "title": "Summer Festival",
          "start": "2026-02-15T20:00:00"
        }
      }
    ]
  }
}

Field mapping

The mapping tells Ciudad Viva which field of your API corresponds to each platform field. You can use dot notation to access nested fields (e.g. content.title, meta.date.start).

{
  "fieldMap": {
    "title": "content.name",
    "startDate": "meta.startAt",
    "endDate": "meta.endAt",
    "description": "content.body",
    "imageUrl": "content.coverImage",
    "venue": "location.name",
    "address": "location.address",
    "district": "location.commune",
    "price": "ticket.description",
    "eventUrl": "permalink",
    "externalId": "id"
  }
}

Connection test

Before activating the integration, you can test the connection from the setup form. Ciudad Viva will query your API right then and show:

• →Your API's HTTP response code.
• →How many events it found in the response.
• →A preview of the first 3 events with the mapping applied.
• →The error message if something fails (wrong URL, rejected authentication, field not found, etc.).

You can only activate the integration if the connection test succeeded. If you change the setup after activating it, the integration goes back to draft status and you'll need to test it again.

Webhook (optional)

In addition to the automatic daily sync, you can set up a webhook so Ciudad Viva syncs your events at the moment you need it. When you create a new event in your system, your system can notify Ciudad Viva immediately and the event will appear on the platform without waiting until the next day.

https://server.ciudad-viva.cl/api/webhooks/{your-webhook-key}

curl -X POST \
  "https://server.ciudad-viva.cl/api/webhooks/{your-webhook-key}"

# Successful response (HTTP 202):
{ "queued": true }

# If you exceed the limit:
HTTP 429 Too Many Requests
{ "error": "rate_limit_exceeded", "retryAfterMs": 8500 }

Sync

Every sync follows this process:

Coming soon