Developer Portal & API Docs

What is the SkipTrek API?

La API pública de SkipTrek es una REST API de solo lectura que te permite consultar eventos, venues, artistas, organizadores, noticias y contenido destacado. Es ideal para integraciones ligeras, widgets, bots, dashboards internos y más.

Lectura de eventos, tickets públicos y metadatos.
Búsquedas combinadas por ciudad, categoría, texto, etc.
Sin exponer lógica de pagos, órdenes ni check-in.

Base URL & Version

Todos los endpoints viven bajo esta base:

/api

Actualmente estamos en Public API v1. No hay prefijo /v1, pero esta documentación define el contrato de la versión 1.

Formato, CORS & Clients

Formato	JSON (UTF-8)
Métodos	`GET` para endpoints públicos descritos aquí.
CORS	Habilitado para el dominio oficial de SkipTrek. Otros dominios deben usar un backend propio como proxy y autenticarse mediante API key.

Modelos de seguridad

Tu API combina tres capas:

First-party: Peticiones desde skiptrek.com y procesos internos.
JWT: Autenticación de usuarios finales (cuenta, órdenes, tickets).
API keys: Segunda capa obligatoria para clientes externos sin JWT.

En resumen: si la petición no viene de SkipTrek y no incluye JWT, necesitará una API key válida para acceder al catálogo público.

Authentication

JWT Bearer (usuarios finales)

La mayoría de los endpoints públicos no requieren autenticación de usuario. Sin embargo, flujos como favoritos, tickets, órdenes y notificaciones sí utilizan JWT estándar en el header:

Authorization: Bearer <TOKEN>

El token se obtiene mediante los endpoints de autenticación de SkipTrek, diseñados principalmente para nuestras aplicaciones oficiales web y móviles.

POST /auth/login First-party JSON body

Inicia sesión con email y password y devuelve un JWT y datos básicos de usuario.

Request:

{
  "email": "user@example.com",
  "password": "password123"
}

Response:

{
  "token": "eyJhbGciOi...",
  "user": {
    "id": 1,
    "name": "Demo User",
    "email": "user@example.com",
    "role": "user"
  }
}

POST /auth/register First-party

Registra nuevos usuarios dentro del ecosistema SkipTrek. No es obligatorio para consumir endpoints públicos, pero sí para flujos de tickets/órdenes desde nuestras apps.

API keys (segunda capa)

Obligatorias para clientes externos sin JWT

Para proteger el catálogo público de scraping y abusos, la API exige una API key en los endpoints de lectura cuando:

La petición no viene de skiptrek.com ni de IPs internas.
La petición es GET a un endpoint de catálogo (/events, /venues, etc.).
No se envía un JWT válido en Authorization: Bearer <TOKEN>.

La API key se envía mediante:

X-Api-Key: <YOUR_PUBLIC_API_KEY>

Alternativamente, puedes usar ?api_key=<YOUR_PUBLIC_API_KEY> como parámetro de query.

Para solicitar una clave o revocar una existente, visita la página de solicitud de API keys .

Tipos de clientes & reglas

Resumen de cuándo se exige API key

Cliente	Origen	JWT	API key
Web oficial	`https://skiptrek.com`	No	No requerida
App oficial	Backend propio	Sí	No (JWT)
Backend de partner	Otro dominio	No	Requerida
Widget en sitio externo	Navegador (otro dominio)	No	Requerida (y CORS mediante proxy backend)
Usuario autenticado	Cualquier origen	Sí	No (JWT)

Recuerda: CORS se aplica a navegadores. Para integraciones de servidor a servidor se recomienda llamar a la API desde tu backend usando tu API key.

Endpoint de prueba

Health check público

Usa este endpoint para verificar rápidamente si la API está arriba:

GET /health Public

Ejemplo de respuesta:

{
  "ok": true,
  "method": "GET",
  "path": "/health"
}

Endpoints como /me, /account, /orders, /tickets/mine, /notifications, etc. están fuera de esta documentación pública y se consideran endpoints internos / first-party para web y apps oficiales.

Events & Tickets

Endpoints para listar y consultar eventos públicos, así como tipos de tickets visibles al usuario.

GET /events Public Paginated Read-only

Lista de eventos disponibles. Soporta filtros por ciudad, texto, categoría, etc.

Parámetros típicos: ?page=1&per=20&city=&q=&category=&status=upcoming

GET /events/{slug} Public

Detalle completo de un evento (descripción, fechas, venue, artistas, organizer, tickets públicos, etc.).

GET /events/{slug}/tickets Public Tickets

Lista de tipos de tickets públicos para el evento (nombre, precio, moneda, estado). No expone información de órdenes, pagos ni check-in.

GET /events/last-minute Public Promo

Eventos que comienzan pronto o están en ventana de “última hora”.

GET /trending Public Ranking

Eventos destacados según popularidad, vistas o interacciones.

Venues

Lugares donde ocurren eventos.

GET /venues Public Paginated

Lista de venues con información básica y ubicación general.

GET /venues/{slug} Public

Detalle de venue e información relevante, incluyendo eventos asociados.

Artists

Artistas ligados a eventos en SkipTrek.

GET /artists Public Paginated

Lista de artistas. Permite filtros por nombre, género, país, etc.

GET /artists/{slug} Public

Detalle de un artista (bio pública, enlaces y eventos relacionados).

GET /events/{slug}/artists Public

Artistas asociados a un evento específico.

Organizers

Promotores, agencias o marcas que organizan eventos.

GET /organizers Public Paginated

Lista de organizadores activos con información pública.

GET /organizers/{slug} Public

Perfil de un organizador, incluyendo eventos relevantes y enlaces oficiales.

News & Pages

Contenido editorial y páginas estáticas (about, terms, etc.).

GET /news Public Paginated

Lista de noticias, anuncios y artículos.

GET /news/{slug} Public

Detalle de una noticia (título, cuerpo, tags, metadatos).

GET /pages Public

Lista de páginas informativas publicadas.

GET /pages/{slug} Public

Contenido HTML / rich text de una página específica (por ejemplo, /about).

Featured & Search

Contenido destacado para héroes y búsqueda global.

GET /featured Public Hero

Ítems destacados para sliders, banners o secciones hero.

GET /search Public Multi-index

Búsqueda global sobre eventos, artistas, venues, organizers y news.

Parámetros típicos: ?q=edc&page=1&per=10

Error responses

Respuestas estándar que puedes esperar.

Status	Meaning
`400`	Parámetros inválidos.
`401`	Token o API key faltante/incorrecta (en endpoints que lo requieren).
`404`	Recurso no encontrado.
`429`	Rate limit excedido.
`500`	Error interno inesperado.

Ejemplo de payload de error:

{
  "error": "Not Found"
}

cURL – Listar eventos (first-party)

Ejemplo simple desde el propio dominio.

curl "/api/events?page=1&per=10" \
  -H "Accept: application/json"

cURL – Listar eventos (cliente externo)

Requiere API key cuando la petición no proviene de SkipTrek.

curl "https://skiptrek.com/api/events?page=1&per=10" \
  -H "Accept: application/json" \
  -H "X-Api-Key: YOUR_PUBLIC_API_KEY"

cURL – Detalle de evento

curl "https://skiptrek.com/api/events/miami-sunset-festival" \
  -H "Accept: application/json" \
  -H "X-Api-Key: YOUR_PUBLIC_API_KEY"

JavaScript – Backend propio

Ejemplo en Node/Next/Nest llamando a SkipTrek con API key.

import fetch from 'node-fetch';

async function loadEvents() {
  const res = await fetch('https://skiptrek.com/api/events?per=6', {
    headers: {
      'Accept': 'application/json',
      'X-Api-Key': process.env.SKIPTREK_API_KEY
    }
  });
  if (!res.ok) throw new Error('API error ' + res.status);
  const data = await res.json();
  console.log('Events:', data);
}

PHP – Servidor a servidor

<?php
$opts = [
  'http' => [
    'method'  => 'GET',
    'header'  => "Accept: application/json\r\n" .
                 "X-Api-Key: YOUR_PUBLIC_API_KEY\r\n",
  ]
];
$context = stream_context_create($opts);
$json = file_get_contents('https://skiptrek.com/api/events', false, $context);
$data = json_decode($json, true);
foreach ($data['data'] ?? [] as $event) {
    echo $event['title'] . PHP_EOL;
}

Event

Modelo típico devuelto por /events y /events/{slug}.

{
  "id": 183,
  "slug": "miami-sunset-festival",
  "title": "Miami Sunset Festival",
  "description": "Celebrate...",
  "city": "Miami, FL",
  "country": "US",
  "start_at": "2025-11-30T18:00:00Z",
  "end_at": "2025-12-01T02:00:00Z",
  "status": "on_sale",
  "cover_url": "https://skiptrek.com/media/events/183.jpg",
  "images": [
    "https://skiptrek.com/media/events/183-1.jpg"
  ],
  "venue": {
    "name": "Bayside Arena",
    "slug": "bayside-arena"
  },
  "organizer": {
    "name": "Sunset Live",
    "slug": "sunset-live"
  },
  "artists": [
    { "name": "DJ Example", "slug": "dj-example" }
  ],
  "tickets": [
    {
      "id": 31,
      "name": "General Admission",
      "price": 59.0,
      "currency": "USD",
      "status": "available"
    }
  ]
}

Venue

Modelo para /venues y /venues/{slug}.

{
  "id": 12,
  "slug": "bayside-arena",
  "name": "Bayside Arena",
  "city": "Miami",
  "country": "US",
  "address": "123 Ocean Drive",
  "lat": 25.774,
  "lng": -80.19,
  "capacity": 12000
}

Artist

Modelo para /artists y /artists/{slug}.

{
  "id": 91,
  "slug": "dj-example",
  "name": "DJ Example",
  "country": "US",
  "genres": ["EDM", "House"],
  "avatar_url": "https://skiptrek.com/media/artists/dj-example.jpg",
  "socials": {
    "instagram": "https://instagram.com/djexample"
  }
}

Organizer

Modelo para /organizers y /organizers/{slug}.

{
  "id": 7,
  "slug": "sunset-live",
  "name": "Sunset Live",
  "city": "Miami",
  "country": "US",
  "logo_url": "https://skiptrek.com/media/organizers/sunset-live.png",
  "website": "https://sunsetlive.com",
  "socials": {
    "instagram": "https://instagram.com/sunsetlive"
  }
}

News

Modelo para /news y /news/{slug}.

{
  "id": 55,
  "slug": "skiptrek-announces-partnerships",
  "title": "SkipTrek announces new partnerships",
  "excerpt": "We are happy to announce...",
  "body_html": "<p>Full article...</p>",
  "cover_url": "https://skiptrek.com/media/news/55.jpg",
  "tags": ["announcement", "partners"],
  "published_at": "2025-10-01T10:00:00Z"
}

¿Necesitas campos adicionales, contratos más estrictos o documentación OpenAPI/Swagger? Contáctanos en dev@skiptrek.com.

Notifications

API Documentation