API REST

A API REST permite que o seu servidor leia formulários e envios, mova envios para dentro e para fora do spam e os exclua. Ela usa JSON via HTTPS em https://ikiform.com/api/v1. O documento OpenAPI 3.1 está em /api/v1/openapi.json.

Chaves de API

Crie chaves no painel em API keys. Uma chave pertence a um workspace e só enxerga esse workspace. A chave completa é exibida uma única vez; o Ikiform guarda só o hash dela.

Escopos

Autenticação

Envie a chave secreta como token Bearer. A API é só de servidor para servidor: ela não envia headers de CORS e responde preflights do navegador com 405, então uma chave secreta nunca funciona a partir de uma página web.

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

• Uma chave ausente, malformada, desconhecida, revogada ou expirada recebe 401 unauthorized com WWW-Authenticate: Bearer.
• Uma chave publicável recebe 403 forbidden (Publishable keys can only submit forms.). Uma chave sem o escopo necessário recebe 403 forbidden com o escopo indicado na mensagem.
• As respostas são enviadas com Cache-Control: no-store.

Os exemplos com o SDK abaixo compartilham um único client:

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

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

Montador de requisições

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

Endpoints

Lista formulários

GET /forms com o escopo forms:read.

• Mais recentes primeiro. Aceita limit (de 1 a 100, padrão 25) e cursor.

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

Obtém um formulário

GET /forms/:formId com o escopo forms:read.

• Um id de formulário de outro workspace retorna 404, exatamente como um que não existe.

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

Lista envios

GET /submissions com o escopo submissions:read.

• Mais recentes primeiro. Um form_id de outro workspace retorna uma lista vazia em vez de um erro, para que ids não possam ser sondados.

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

Obtém um envio

GET /submissions/:id com o escopo submissions:read.

• Ids de outro workspace retornam 404, exatamente como ids que não existem.

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

Marca como spam

POST /submissions/:id/spam com o escopo submissions:write.

• Move um envio recebido para spam, diminui o submission_count do formulário e cancela as entregas de webhook pendentes dele.
• Chamar em um envio que já é spam o retorna sem mudanças.

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

Marca como não spam

POST /submissions/:id/not-spam com o escopo submissions:write.

• Move o envio de volta para recebido, limpa a pontuação e os motivos de spam e envia submission.created para todos os endpoints de webhook correspondentes.
• Chamar em um envio recebido o retorna sem mudanças.

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

Exclui um envio

DELETE /submissions/:id com o escopo submissions:write.

• Remove permanentemente o envio e as entregas de webhook dele. Não há como desfazer. Excluir de novo retorna 404.

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

Objetos

Os objetos são JSON em snake_case com um campo object. Timestamps são ISO 8601 em UTC com milissegundos. Ids de envio são ordenados por tempo (sub_ mais 26 caracteres); ids de formulário são aleatórios (frm_ mais 16 caracteres).

Paginação

As listas vêm das mais recentes para as mais antigas e usam cursores opacos.

1. Faça a requisição sem cursor.
2. Se has_more for true, envie next_cursor como cursor com os mesmos filtros.
3. Pare quando next_cursor for null.

As páginas ficam estáveis enquanto novos envios chegam: os novos aparecem na primeira página, nunca como duplicados mais abaixo. Não monte nem interprete cursores você mesmo; um cursor inválido retorna 400 invalid_request.

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

Erros

Os erros usam o mesmo envelope dos envios de formulário. Toda resposta tem um header X-Request-Id, que os erros repetem como request_id.

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

Limite de taxa

Cada chave pode fazer 100 requisições a cada 60 segundos. Acima do limite, a API retorna 429 rate_limited com um header Retry-After em segundos. O SDK o expõe como error.retryAfter.