Convenciones de la API · Developers
Convenciones que valen para todo endpoint de la API de Dailybot: identificadores, timestamps, casing, paginación, búsqueda, rango de fechas y versionado.
Todo endpoint de la API pública de Dailybot sigue las mismas convenciones para identificadores, timestamps, casing, paginación, búsqueda, rango de fechas y versionado. Aprende esto una vez y cada página de referencia se leerá exactamente como esperas.
Identificadores
Todo recurso tiene un UUID globalmente único (RFC 4122 v4). Según el modelo, la API lo devuelve como uuid (Form, Form Response, User) o como id (Kudo, Check-in, Workflow) — en ambos casos el valor es un UUID y sirve como clave estable y opaca para tu integración.
Regla: si el recurso tiene una columna UUID dedicada separada de su clave primaria interna, la API devuelve uuid; si la clave primaria misma es un UUID, la API devuelve id. Ambos son UUIDs.
| Recurso | Campo identificador |
|---|---|
| Form | uuid |
| Form Response | uuid |
| Agent Report | uuid (también devuelve id con el mismo valor por retrocompatibilidad) |
| Agent Message | uuid (también devuelve id con el mismo valor por retrocompatibilidad) |
| Usuario | uuid |
| Kudo | id (UUID) |
| Check-in (Follow-up) | id (UUID) |
| Workflow | id (UUID) |
Timestamps
Todos los timestamps son ISO-8601 en UTC con precisión de milisegundos (p.ej. 2026-07-02T14:33:19.412Z). Los campos que terminan en _at son timestamps; los que terminan en _date son solo fecha (YYYY-MM-DD). Nunca emitimos strings de hora local.
Casing de campos
Todas las claves JSON son snake_case (first_name, created_at). Los segmentos de path son kebab-case (/pending-invitations/, /agent-reports/). Los parámetros de query son snake_case (include_email, only_active).
Paginación
Todo endpoint de lista /v1/* devuelve el mismo envelope de respuesta:
{
"count": 152,
"next": "https://api.dailybot.com/v1/...?page=2&page_size=50",
"previous": null,
"results": [ ... ]
}Parámetros de query
| Parámetro | Tipo | Default | Máx. | Descripción |
|---|---|---|---|---|
page |
integer | 1 | — | Número de página (indexado desde 1) |
page_size |
integer | 25 | 100 | Ítems por página. Valores > 100 se reducen silenciosamente. |
Aliases heredados (retrocompatibles)
| Parámetro heredado | Equivale a |
|---|---|
limit |
page_size |
offset |
Paginación por offset |
Estos aliases devuelven el mismo envelope. Las URLs next/previous reflejan el estilo que usó el llamante.
Paginación opt-in eliminada: El parámetro de query
?paginated=truey el header de solicitudX-Dailybot-Paginate: truese ignoran. Todo endpoint de lista devuelve siempre el envelope.
Campos del envelope de respuesta
| Campo | Tipo | Descripción |
|---|---|---|
count |
integer | Total de ítems que coinciden (a través de todas las páginas) |
next |
string | null | URL completa de la siguiente página, o null si es la última |
previous |
string | null | URL completa de la página anterior, o null si es la primera |
results |
array | Ítems de esta página (siempre un array, nunca null) |
Iterar todas las páginas
PAGE=1
while true; do
RESP=$(curl -s "https://api.dailybot.com/v1/forms/?page=$PAGE&page_size=100" \
-H "X-API-KEY: $DAILYBOT_API_KEY")
echo "$RESP" | jq '.results[]'
NEXT=$(echo "$RESP" | jq -r '.next')
[ "$NEXT" = "null" ] && break
PAGE=$((PAGE + 1))
doneBúsqueda
El parámetro ?search=<término> está disponible en endpoints de lista que exponen contenido de texto. Realiza una coincidencia de subcadena sin distinción de mayúsculas/minúsculas aplicada tras el alcance de rol. Combina con paginación y filtros de rango de fechas.
Longitud máxima: 256 caracteres. Las solicitudes que exceden este límite devuelven 400 con code: "search_query_too_long".
Endpoints que soportan búsqueda
| Endpoint | Campos buscados |
|---|---|
GET /v1/forms/?search=<término> |
Nombre del form |
GET /v1/checkins/?search=<término> |
Nombre del check-in |
GET /v1/forms/{uuid}/responses/?search=<término> |
Contenido de respuestas |
GET /v1/checkins/{uuid}/responses/?search=<término> |
Contenido de respuestas |
GET /v1/kudos/?search=<término> |
Mensaje del kudo |
GET /v1/kudos/organization/?search=<término> |
Mensaje del kudo |
GET /v1/workflows/?search=<término> |
Nombre del workflow |
GET /v1/followups/?search=<término> |
Nombre del check-in (alias deprecado de /v1/checkins/) |
GET /v1/users/?search=<término> |
Nombre completo, email |
curl "https://api.dailybot.com/v1/forms/?search=retro&page_size=10" \
-H "X-API-KEY: $DAILYBOT_API_KEY"Rango de fechas
Un filtro de rango de fechas consciente de la zona horaria está disponible en todo endpoint paginado.
Parámetros canónicos
| Parámetro | Formato | Descripción |
|---|---|---|
start_date |
YYYY-MM-DD |
Inicio inclusivo — 00:00:00 en la zona horaria del llamante |
end_date |
YYYY-MM-DD |
Fin inclusivo — 23:59:59.999999 en la zona horaria del llamante |
Comportamiento de zona horaria: Las fechas se interpretan en la zona horaria del usuario autenticado (de su perfil). Cae en UTC si no tiene zona horaria configurada.
También aceptados (aliases heredados)
| Parámetros heredados | Equivalente |
|---|---|
date_start / date_end |
start_date / end_date |
date_from / date_to |
start_date / end_date |
Composición
Se combina con ?search= y paginación:
curl "https://api.dailybot.com/v1/checkins/{uuid}/responses/?start_date=2026-07-01&end_date=2026-07-31&search=blocker&page_size=100" \
-H "X-API-KEY: $DAILYBOT_API_KEY"Error: Fechas mal formadas devuelven 400 con code: "invalid_date_range".
Filtros sin distinción de mayúsculas
Los parámetros de query con estilo enum aceptan cualquier capitalización. Por ejemplo, ?filter=kudos_received, ?filter=KUDOS_RECEIVED y ?filter=Kudos_Received se resuelven todos a kudos_received. Los valores inválidos devuelven 400 con code: "invalid_kudos_filter".
Versionado
La API pública se versiona por prefijo de URL (/v1/). Cambios aditivos (nuevos endpoints, nuevos campos opcionales, nuevos valores de enum con fallback) pueden aterrizar en cualquier momento. Los cambios rompedores viajan en un prefijo nuevo (/v2/) con una ventana mínima de sunset de 6 meses sobre la versión previa. Ver /es/developers/api-changelog.
Idempotencia
Todo GET, PATCH, DELETE es idempotente por semántica HTTP — reintentarlos es seguro. Los POST que crean un recurso, en el general caso, no son idempotentes; un reintento ingenuo tras un blip de red puede crear recursos duplicados. Cuando reintentes tras un 5xx o error de red, primero relee el recurso por su clave natural (email, nombre, id externo) y solo re-créalo si el read devuelve 404. La política de reintentos vive en /es/developers/errors#retry-policy.
null vs. ausente
Un campo puesto en null significa explícitamente “este atributo no tiene valor”. Un campo ausente de la respuesta significa “el llamante no tiene permiso para verlo” o “el campo no se pidió vía un include-flag”. No los trates igual.