API REST

La API REST permite a tu servidor leer formularios y envíos, mover envíos dentro y fuera del spam y eliminarlos. Es JSON por HTTPS en https://ikiform.com/api/v1. El documento OpenAPI 3.1 está en /api/v1/openapi.json.

Claves de API

Crea las claves en el panel, en API keys. Una clave pertenece a un espacio de trabajo y solo ve ese espacio de trabajo. La clave completa se muestra una sola vez; Ikiform solo guarda su hash.

Permisos

Autenticación

Envía la clave secreta como token Bearer. La API es solo de servidor a servidor: no envía cabeceras CORS y responde a los preflights del navegador con 405, así que una clave secreta nunca puede funcionar desde una página web.

curl https://ikiform.com/api/v1/forms \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

• Una clave ausente, mal formada, desconocida, revocada o caducada recibe 401 unauthorized con WWW-Authenticate: Bearer.
• Una clave publicable recibe 403 forbidden (Publishable keys can only submit forms.). Una clave sin el permiso necesario recibe 403 forbidden con el permiso indicado en el mensaje.
• Las respuestas se envían con Cache-Control: no-store.

Los ejemplos del SDK de abajo comparten un mismo cliente:

import { createClient } from "@ikiform/sdk";

const ikiform = createClient({ apiKey: process.env.IKIFORM_SECRET_KEY! });

Compositor de peticiones

curl "https://ikiform.com/api/v1/submissions?form_id=frm_xxxxxxxxxxxxxxxx&status=received&limit=50" \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

Endpoints

Lista los formularios

GET /forms con el permiso forms:read.

• De más reciente a más antiguo. Acepta limit (de 1 a 100, por defecto 25) y cursor.

curl "https://ikiform.com/api/v1/forms?limit=10" \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

Obtiene un formulario

GET /forms/:formId con el permiso forms:read.

• Un id de formulario de otro espacio de trabajo devuelve 404, exactamente igual que uno que no existe.

curl https://ikiform.com/api/v1/forms/frm_xxxxxxxxxxxxxxxx \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

Lista los envíos

GET /submissions con el permiso submissions:read.

• De más reciente a más antiguo. Un form_id de otro espacio de trabajo devuelve una lista vacía en lugar de un error, para que no se puedan sondear ids.

curl "https://ikiform.com/api/v1/submissions?form_id=frm_xxxxxxxxxxxxxxxx&status=received&limit=50" \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

Obtiene un envío

GET /submissions/:id con el permiso submissions:read.

• Los ids de otro espacio de trabajo devuelven 404, exactamente igual que los ids que no existen.

curl https://ikiform.com/api/v1/submissions/sub_01k7v2c9t3e8m5q4x6z0a1b2c3 \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

Marca como spam

POST /submissions/:id/spam con el permiso submissions:write.

• Mueve un envío recibido a spam, reduce el submission_count del formulario y cancela sus entregas de webhook pendientes.
• Llamarlo sobre un envío que ya es spam lo devuelve sin cambios.

curl -X POST https://ikiform.com/api/v1/submissions/sub_01k7v2c9t3e8m5q4x6z0a1b2c3/spam \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

Marca como no spam

POST /submissions/:id/not-spam con el permiso submissions:write.

• Lo devuelve a recibidos, borra su puntuación y sus motivos de spam, y envía submission.created a todos los endpoints de webhook correspondientes.
• Llamarlo sobre un envío recibido lo devuelve sin cambios.

curl -X POST https://ikiform.com/api/v1/submissions/sub_01k7v2c9t3e8m5q4x6z0a1b2c3/not-spam \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

Elimina un envío

DELETE /submissions/:id con el permiso submissions:write.

• Elimina de forma permanente el envío y sus entregas de webhook. No se puede deshacer. Eliminarlo otra vez devuelve 404.

curl -X DELETE https://ikiform.com/api/v1/submissions/sub_01k7v2c9t3e8m5q4x6z0a1b2c3 \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"

Objetos

Los objetos son JSON en snake_case con un campo object. Las marcas de tiempo están en ISO 8601 en UTC con milisegundos. Los ids de envío están ordenados por tiempo (sub_ más 26 caracteres); los ids de formulario son aleatorios (frm_ más 16 caracteres).

Paginación

Las listas van de más reciente a más antiguo y usan cursores opacos.

1. Haz la petición sin cursor.
2. Si has_more es true, envía next_cursor como cursor con los mismos filtros.
3. Para cuando next_cursor sea null.

Las páginas se mantienen estables mientras llegan envíos nuevos: los nuevos aparecen en la primera página, nunca como duplicados más abajo. No construyas ni analices los cursores tú mismo; uno no válido devuelve 400 invalid_request.

for await (const submission of ikiform.submissions.iterate({ formId: "frm_xxxxxxxxxxxxxxxx" })) {
  console.log(submission.id, submission.fields);
}

Errores

Los errores usan el mismo formato que los envíos de formularios. Cada respuesta tiene una cabecera X-Request-Id, que los errores repiten como request_id.

{
  "ok": false,
  "error": { "code": "forbidden", "message": "This API key is missing the forms:read scope." },
  "request_id": "req_01k7v2c9t3e8m5q4x6z0a1b2c3"
}

Límite de frecuencia

Cada clave puede hacer 100 peticiones cada 60 segundos. Por encima del límite, la API devuelve 429 rate_limited con una cabecera Retry-After en segundos. El SDK la expone como error.retryAfter.