Referencia de API - Desarrolladores hoastnow

Resumen

Base URL https://www.hoastnow.com/api/v1

Content type application/json

Authentication Bearer token (Authorization header)

Códigos de estado HTTP

Código	Significado
`200`	OK — request succeeded, response body contains the result
`201`	Created — resource created successfully (e.g. new booking)
`204`	No Content — request succeeded, no response body (e.g. DELETE)
`400`	Bad Request — missing or malformed request body / query parameter
`401`	Unauthorized — API key missing or invalid
`403`	Forbidden — key does not have the required permission for this endpoint
`404`	Not Found — resource does not exist or is not accessible to this key
`422`	Unprocessable Entity — business rule violation (e.g. slot no longer available)
`500`	Internal Server Error — unexpected server-side failure

Autenticación

La API de hoastnow admite dos mecanismos de autenticación: OAuth 2.1 (recomendado para agentes de IA, integraciones de marketplace y clientes dinámicos) y API keys de larga duración (recomendado para integraciones fijas entre servidores). Ambos usan el mismo modelo de permisos — cada endpoint aplica los mismos indicadores ApiPermissions independientemente del método de autenticación.

HTTP Header

Authorization: Bearer <token>

OAuth 2.1

OAuth 2.1 / OIDC es la opción recomendada para cualquier cliente que autentique en nombre de un usuario, se registre dinámicamente o funcione en un contexto de marketplace. La app web de hoastnow es el servidor de autorización; los tokens son JWT validados contra el JWKS publicado.

PKCE (S256) is required on the authorization-code flow.
Refresh-token rotation on every use; refresh tokens are bound to the original client.
Dynamic Client Registration (RFC 7591) at /connect/register.
Resource indicators (RFC 8707) bind tokens to one audience — api or mcp.
JWT access tokens validated via JWKS — no introspection round-trip required.

Descubrimiento

Issuer https://www.hoastnow.com

OIDC config /.well-known/openid-configuration

JWKS /.well-known/jwks

MCP resource /.well-known/oauth-protected-resource/mcp

Endpoints

Ruta	Método	Propósito
`/connect/authorize`	GET	Authorization-code entry point (browser redirect)
`/connect/token`	POST	Exchange auth code, refresh token, or client credentials for an access token
`/connect/register`	POST	Dynamic Client Registration (RFC 7591)
`/connect/userinfo`	GET	OIDC user claims for the bearer token
`/connect/revoke`	POST	Revoke an access or refresh token
`/connect/introspect`	POST	Inspect a token's active state and metadata
`/connect/logout`	GET / POST	End the user's session at the authorization server

Alcances

Alcance	Permisos otorgados
`openid`	Required for OIDC; identifies the user
`profile`, `email`	Standard OIDC claims for `userinfo`
`offline_access`	Issues a refresh token
`hoastnow.api.read`	ReadAvailability, ReadBookings, ReadReviews
`hoastnow.api.write`	WriteBookings
`hoastnow.api.webhooks`	Webhooks
`hoastnow.mcp`	MCP tool access (use with `resource=mcp`)

Los indicadores de recurso son obligatorios. Cada solicitud de token debe incluir resource=api (REST) o resource=mcp (servidor MCP). Un token emitido para una audiencia no puede usarse con la otra — el uso cruzado es rechazado por los servidores de recursos.

Vigencia de los tokens

Token	Vigencia
Authorization code	5 minutes
Access token	60 minutes
Refresh token	30 days (rotates on use)

cURL — token exchange

curl -X POST https://www.hoastnow.com/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=$AUTH_CODE" \
  -d "client_id=$CLIENT_ID" \
  -d "code_verifier=$PKCE_VERIFIER" \
  -d "redirect_uri=https://your-app.com/callback" \
  -d "resource=api"

cURL — refresh token

curl -X POST https://www.hoastnow.com/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=$REFRESH_TOKEN" \
  -d "client_id=$CLIENT_ID" \
  -d "resource=api"

Calling the API

Authorization: Bearer <access_token>

API Keys

Las API keys de larga duración son la mejor opción para integraciones fijas entre servidores donde el sistema que se integra ya gestiona su propia identidad. Las claves están vinculadas a una sola Comunidad o Marca en el momento de emisión, no expiran hasta ser revocadas y usan el mismo encabezado Authorization: Bearer que OAuth.

Alcances de las claves

Alcance	Descripción
Community	Emitida para una comunidad. Accede a reservas y disponibilidad de los espacios de esa comunidad.
Brand	Emitida para una cuenta de marca. Puede crear solicitudes de reserva y leer solo sus propias reservas.

Indicadores de permisos

Permiso	Valor	Descripción
`ReadAvailability`	1	Consultar horarios disponibles para los espacios
`ReadBookings`	2	Listar reservas (según el tipo de clave)
`WriteBookings`	4	Crear solicitudes de reserva (solo claves de marca)
`ReadReviews`	8	Leer reseñas de comunidades y espacios
`Webhooks`	16	Registrar y gestionar endpoints de webhook

Las API keys solo son aceptadas por la API REST. El servidor MCP requiere OAuth 2.1 — consulta la página MCP para más detalles.

HTTP Header

Authorization: Bearer hoa_live_xxxxxxxxxxxxxxxxxxxx

cURL

curl https://www.hoastnow.com/api/v1/spaces/42/availability \
  -H "Authorization: Bearer hoa_live_xxxxxxxxxxxxxxxxxxxx" \
  -G --data-urlencode "date=2026-04-15"

Disponibilidad

GET /spaces/{spaceId}/availability ReadAvailability

Devuelve los horarios disponibles para un espacio en una fecha específica. La respuesta incluye la ventana de reserva de la comunidad, la duración por evento y un array de slots por hora que indica disponibilidad.

Parámetros de consulta

Parámetro	Tipo	Requerido	Descripción
`date`	string	required	Date to check in `YYYY-MM-DD` format. Must be today or a future date.

Modelo de respuesta — `AvailabilityResponse`

Campo	Tipo	Descripción
`spaceId`	integer	Unique identifier of the space
`spaceName`	string	Display name of the space
`date`	string (date)	The queried date in YYYY-MM-DD format
`windowStart`	integer (0–23)	Earliest available hour for this space
`windowEnd`	integer (0–23)	Latest hour in the booking window
`durationHours`	number	Fixed event duration defined by the community
`timeSlots`	array	Array of `TimeSlot` objects (see below)

Objeto TimeSlot

Campo	Tipo	Descripción
`hour`	integer (0–23)	The starting hour in 24-hour format
`label`	string	Human-readable label, e.g. `"9:00 AM"`
`isAvailable`	boolean	Whether this slot is open for booking

cURL

curl "https://www.hoastnow.com/api/v1/spaces/42/availability?date=2026-04-15" \
  -H "Authorization: Bearer hoa_live_xxxxxxxxxxxxxxxxxxxx"

JSON — 200 OK

{
  "spaceId": 42,
  "spaceName": "Sunset Clubhouse",
  "date": "2026-04-15",
  "windowStart": 9,
  "windowEnd": 21,
  "durationHours": 3,
  "timeSlots": [
    { "hour": 9,  "label": "9:00 AM",  "isAvailable": true  },
    { "hour": 10, "label": "10:00 AM", "isAvailable": true  },
    { "hour": 11, "label": "11:00 AM", "isAvailable": false },
    { "hour": 12, "label": "12:00 PM", "isAvailable": true  },
    { "hour": 13, "label": "1:00 PM",  "isAvailable": true  },
    { "hour": 14, "label": "2:00 PM",  "isAvailable": false },
    { "hour": 15, "label": "3:00 PM",  "isAvailable": true  }
  ]
}

Reservas

GET /bookings ReadBookings

Devuelve una lista de reservas visibles para la clave autenticada. Las claves de comunidad ven todas las reservas de sus espacios. Las claves de marca solo ven las reservas que crearon.

Parámetros de consulta

Parámetro	Tipo	Requerido	Descripción
`startDate`	string	optional	Filter bookings on or after this date (`YYYY-MM-DD`)
`endDate`	string	optional	Filter bookings on or before this date (`YYYY-MM-DD`)
`status`	string	optional	Filter by status: `Pending`, `Approved`, `Cancelled`, `Completed`

cURL

curl "https://www.hoastnow.com/api/v1/bookings?startDate=2026-04-01&status=Approved" \
  -H "Authorization: Bearer hoa_live_xxxxxxxxxxxxxxxxxxxx"

JSON — 200 OK

[
  {
    "id": 1001,
    "spaceId": 42,
    "spaceName": "Sunset Clubhouse",
    "date": "2026-04-15",
    "startHour": 10,
    "endHour": 13,
    "status": "Approved",
    "totalPrice": 345.00,
    "createdAt": "2026-04-01T14:22:00Z"
  }
]

POST /bookings WriteBookings

Envía una solicitud de reserva para un espacio en nombre de la clave de Marca autenticada. La reserva entra en estado Pendiente y debe ser aprobada por la comunidad. Este endpoint solo está disponible para claves de alcance Marca.

Precios: El total es la tarifa fija por evento más la tarifa de servicio de la marca (según la configuración de pagos, normalmente 15%). La duración no cambia la tarifa. El campo totalPrice de la respuesta es el importe que se cobra a la marca al aprobar.

Cuerpo de la solicitud

Campo	Tipo	Requerido	Descripción
`spaceId`	integer	required	The ID of the space to book
`startTime`	string (date)	required	Requested date in `YYYY-MM-DD` format
`startHour`	integer (0–23)	required	Requested start hour in 24-hour format
`message`	string	optional	Optional note to the community (max 500 characters)

cURL

curl -X POST https://www.hoastnow.com/api/v1/bookings \
  -H "Authorization: Bearer hoa_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "spaceId": 42,
    "startTime": "2026-04-15",
    "startHour": 10,
    "message": "Launching our new product line."
  }'

JSON — 201 Created

{
  "id": 1002,
  "spaceId": 42,
  "spaceName": "Sunset Clubhouse",
  "date": "2026-04-15",
  "startHour": 10,
  "endHour": 13,
  "status": "Pending",
  "totalPrice": 345.00,
  "createdAt": "2026-04-02T09:14:00Z"
}

Reseñas

GET /communities/{communityId}/reviews ReadReviews

Devuelve todas las reseñas de una comunidad. Las claves de comunidad solo pueden acceder a las reseñas de su propia comunidad. Las claves de marca pueden acceder a las reseñas de cualquier comunidad con la que tengan una reserva completada.

Parámetros de ruta

Parámetro	Tipo	Descripción
`communityId`	integer	The ID of the community whose reviews to retrieve

cURL

curl https://www.hoastnow.com/api/v1/communities/7/reviews \
  -H "Authorization: Bearer hoa_live_xxxxxxxxxxxxxxxxxxxx"

JSON — 200 OK

[
  {
    "id": 55,
    "propertyId": 7,
    "spaceId": 42,
    "rating": 5,
    "title": "Perfect venue for our product launch",
    "content": "The space was immaculate and the community team was responsive throughout.",
    "isVerifiedBooking": true,
    "createdAt": "2026-03-20T11:30:00Z"
  }
]

Webhooks

Los webhooks envían notificaciones en tiempo real a tu servidor cuando ocurren eventos en hoastnow. Registra un endpoint HTTPS y selecciona los tipos de eventos que deseas recibir. Cada entrega incluye un encabezado de firma para verificación.

GET /webhooks Webhooks

Lista todos los endpoints de webhook registrados para esta API key.

cURL

curl https://www.hoastnow.com/api/v1/webhooks \
  -H "Authorization: Bearer hoa_live_xxxxxxxxxxxxxxxxxxxx"

POST /webhooks Webhooks

Registra un nuevo endpoint de webhook. La respuesta incluye un signingSecret que se muestra solo una vez — guárdalo de forma segura. Se usa para verificar que las entregas de webhook provienen de hoastnow.

Tipos de evento (máscara de bits)

Evento	Valor	Descripción
`BookingRequested`	1	A new booking request was submitted
`BookingApproved`	2	A booking request was approved by the community
`BookingCancelled`	4	A booking was cancelled by either party
`ReviewPosted`	8	A new review was submitted for a space

Pasa una suma de máscara de bits para suscribirte a múltiples eventos. Por ejemplo, events: 3 suscribe a BookingRequested (1) y BookingApproved (2). Usa 15 para suscribirte a todos los eventos.

Cuerpo de la solicitud

Campo	Tipo	Requerido	Descripción
`url`	string (URL)	required	Your HTTPS endpoint that will receive webhook deliveries
`events`	integer	required	Bitmask of event types to subscribe to (see table above)

cURL

curl -X POST https://www.hoastnow.com/api/v1/webhooks \
  -H "Authorization: Bearer hoa_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://your-server.com/hooks/hoastnow", "events": 7 }'

JSON — 201 Created

{
  "id": "wh_abc123",
  "url": "https://your-server.com/hooks/hoastnow",
  "events": 7,
  "signingSecret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "createdAt": "2026-04-01T10:00:00Z"
}

Guarda el secreto de firma inmediatamente. El signingSecret se muestra solo una vez en la respuesta de creación. No se puede recuperar después. Si se pierde, elimina el webhook y crea uno nuevo.

DELETE /webhooks/{id} Webhooks

Elimina permanentemente un registro de webhook. hoastnow dejará de enviar eventos a la URL asociada. Devuelve 204 No Content en caso de éxito.

cURL

curl -X DELETE https://www.hoastnow.com/api/v1/webhooks/wh_abc123 \
  -H "Authorization: Bearer hoa_live_xxxxxxxxxxxxxxxxxxxx"

Verificación de firma

Cada entrega de webhook incluye un encabezado X-Hoastnow-Signature con una firma HMAC-SHA256 del cuerpo bruto de la solicitud, calculada con tu secreto de firma. Siempre verifica esta firma antes de procesar un payload.

JSON payload

{
  "event": "BookingApproved",
  "timestamp": "2026-04-15T10:30:00Z",
  "data": {
    "bookingId": 1002,
    "spaceId": 42,
    "spaceName": "Sunset Clubhouse",
    "date": "2026-04-15",
    "startHour": 10,
    "endHour": 13,
    "status": "Approved",
    "totalPrice": 345.00
  }
}

cURL

# Compute the expected signature locally:
echo -n '{"event":"BookingApproved",...}' \
  | openssl dgst -sha256 -hmac "$HOASTNOW_WEBHOOK_SECRET"

Modelos

Fichas de referencia de esquemas para todos los objetos devueltos por la API.

BookingDto

Field	Type	Description
`id`	integer	Unique booking identifier
`spaceId`	integer	ID of the booked space
`spaceName`	string	Display name of the space
`date`	string (date)	Booking date in YYYY-MM-DD format
`startHour`	integer (0–23)	Event start time in 24-hour format
`endHour`	integer (0–23)	Event end time in 24-hour format
`status`	string	`Pending` \| `Approved` \| `Cancelled` \| `Completed`
`totalPrice`	number	Total amount charged (flat event fee plus brand service fee; duration does not change the fee)
`createdAt`	string (ISO 8601)	UTC timestamp when the booking was created

AvailabilityResponse

Field	Type	Description
`spaceId`	integer	Space identifier
`spaceName`	string	Space display name
`date`	string (date)	Queried date
`windowStart`	integer	Community booking window open hour
`windowEnd`	integer	Community booking window close hour
`durationHours`	number	Fixed event duration defined by the community
`timeSlots`	array<TimeSlot>	Start-slot availability array

ReviewDto

Field	Type	Description
`id`	integer	Review identifier
`propertyId`	integer	Community (property) the review belongs to
`spaceId`	integer	Specific space reviewed
`rating`	integer (1–5)	Star rating
`title`	string	Review headline
`content`	string	Full review body text
`isVerifiedBooking`	boolean	Whether the reviewer completed a booking
`createdAt`	string (ISO 8601)	UTC timestamp of submission

WebhookDto

Field	Type	Description
`id`	string	Webhook registration identifier
`url`	string	Registered HTTPS endpoint URL
`events`	integer	Subscribed events bitmask
`createdAt`	string (ISO 8601)	UTC registration timestamp

WebhookCreatedDto

Solo se devuelve en POST /webhooks. Extiende WebhookDto con el secreto de firma de uso único.

Field	Type	Description
`id`	string	Webhook identifier
`url`	string	Registered endpoint URL
`events`	integer	Events bitmask
`signingSecret`	string	HMAC-SHA256 secret for signature verification. Shown once only.
`createdAt`	string (ISO 8601)	UTC registration timestamp

Errores

Todas las respuestas de error usan un cuerpo JSON consistente. Revisa primero el código de estado HTTP, luego inspecciona el campo error para un mensaje legible por máquina y details para contexto adicional.

Códigos de error comunes

Código de error	Estado HTTP	Descripción
`InvalidApiKey`	401	API key is missing, malformed, or revoked
`InsufficientPermissions`	403	Key exists but lacks the required permission flag
`ResourceNotFound`	404	The requested resource does not exist or is not accessible to this key
`ValidationError`	400	Required field missing or parameter value is invalid
`SlotUnavailable`	422	The requested time slot is already booked or outside the booking window
`BookingNotAllowed`	422	Business rule prevents the booking (e.g. space inactive, date in the past)
`ScopeViolation`	403	Brand key attempted an action only available to Community keys, or vice versa
`InternalError`	500	Unexpected server error — safe to retry with exponential backoff

JSON — 422 Unprocessable Entity

{
  "error": "SlotUnavailable",
  "details": "The requested time slot (hour 10) on 2026-04-15 is no longer available."
}

Resumen

Códigos de estado HTTP

Autenticación

OAuth 2.1

Descubrimiento

Endpoints

Alcances

Vigencia de los tokens

API Keys

Alcances de las claves

Indicadores de permisos

Disponibilidad

Parámetros de consulta

Modelo de respuesta — AvailabilityResponse

Objeto TimeSlot

Reservas

Parámetros de consulta

Cuerpo de la solicitud

Reseñas

Parámetros de ruta

Webhooks

Tipos de evento (máscara de bits)

Cuerpo de la solicitud

Verificación de firma

Modelos

BookingDto

AvailabilityResponse

ReviewDto

WebhookDto

WebhookCreatedDto

Errores

Códigos de error comunes

Modelo de respuesta — `AvailabilityResponse`