Referência da API do FluoTest
A API pública do FluoTest é servida pelo endpoint MCP, uma API JSON-RPC 2.0 sobre HTTPS simples que funciona com curl ou qualquer cliente HTTP, sem precisar de biblioteca MCP. Você se autentica com uma chave de API pessoal.
Última atualização
Como chamo a API do FluoTest?
Gere uma chave de API em Configurações → Segurança → Chaves de API e depois envie requisições JSON-RPC via POST para https://fluotest.com/api/mcp com a chave em um cabeçalho "Authorization: Bearer". Hoje há onze ferramentas disponíveis: list_quizzes, create_quiz, import_quiz, get_quiz_questions, get_quiz_settings, update_quiz, publish_quiz, unpublish_quiz, duplicate_quiz, get_results e delete_quiz.
Como obter uma chave de API#
As chaves de API são pessoais: toda requisição feita com uma chave age como a sua conta de usuário, com as mesmas permissões que você tem no app.
- Abra Configurações → Segurança → Chaves de API no seu painel do FluoTest.
- Digite um nome que indique onde a chave será usada (por exemplo, "Script do Zapier").
- Clique em Gerar chave e copie o valor fluo_… imediatamente.
- Guarde-a em um lugar seguro: um gerenciador de senhas ou o armazenamento de segredos da sua ferramenta.
- Exibida uma vez: Só um hash SHA-256 da chave é armazenado. Se você a perder, revogue-a e gere uma nova.
- Até 10 chaves: Crie chaves separadas para cada ferramenta ou script, assim você pode revogar uma sem quebrar as outras.
- Revogável a qualquer momento: A revogação de uma chave vale imediatamente a partir da próxima requisição.
- Acompanhamento de uso: Cada chave mostra quando foi usada pela última vez, então fica fácil identificar e remover chaves antigas.
Autenticação#
Envie a chave em toda requisição no cabeçalho Authorization:
Authorization: Bearer fluo_YOUR_API_KEY
Vai conectar um assistente de IA em vez de escrever código? Veja o guia do servidor MCP →
Formato das requisições#
O endpoint é https://fluotest.com/api/mcp. Envie requisições POST com "Content-Type: application/json", um cabeçalho Accept com "application/json, text/event-stream" e um corpo JSON-RPC 2.0. Não é preciso fazer o handshake de initialize: você pode chamar tools/list e tools/call diretamente.
As respostas voltam como um corpo de server-sent events: o resultado JSON-RPC fica na linha "data:", e o payload de cada ferramenta é uma string JSON dentro de result.content[0].text:
event: message
data: {"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"{\n \"quiz_id\": \"…\",\n \"status\": \"draft\", …}"}]}}Exemplos#
Listar as ferramentas disponíveis
curl -X POST https://fluotest.com/api/mcp \
-H "Authorization: Bearer fluo_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'Listar seus quizzes
curl -X POST https://fluotest.com/api/mcp \
-H "Authorization: Bearer fluo_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": { "name": "list_quizzes", "arguments": {} }
}'Criar um quiz em rascunho
curl -X POST https://fluotest.com/api/mcp \
-H "Authorization: Bearer fluo_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "create_quiz",
"arguments": {
"title": "Customer readiness check",
"questions": [
{ "text": "Do you have a budget?", "type": "yes_no", "points": 2 },
{
"text": "Company size?",
"type": "multiple_choice",
"options": [
{ "label": "1-10", "score": 1 },
{ "label": "11-50", "score": 2 },
{ "label": "50+", "score": 3 }
]
}
]
}
}
}'Obter as perguntas de um quiz
curl -X POST https://fluotest.com/api/mcp \
-H "Authorization: Bearer fluo_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 4,
"method": "tools/call",
"params": {
"name": "get_quiz_questions",
"arguments": { "quiz_id": "Customer readiness check" }
}
}'Obter as configurações de um quiz
curl -X POST https://fluotest.com/api/mcp \
-H "Authorization: Bearer fluo_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 8,
"method": "tools/call",
"params": {
"name": "get_quiz_settings",
"arguments": { "quiz_id": "Customer readiness check" }
}
}'Editar um quiz
curl -X POST https://fluotest.com/api/mcp \
-H "Authorization: Bearer fluo_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 5,
"method": "tools/call",
"params": {
"name": "update_quiz",
"arguments": {
"quiz_id": "Customer readiness check",
"questions": [
{ "text": "Do you have a budget?", "type": "yes_no", "points": 2 },
{ "text": "What's your budget range?", "type": "multiple_choice",
"options": [
{ "label": "Under $1k", "score": 1 },
{ "label": "$1k-$10k", "score": 2 },
{ "label": "$10k+", "score": 3 }
]
}
]
}
}
}'Publicar um quiz em rascunho
curl -X POST https://fluotest.com/api/mcp \
-H "Authorization: Bearer fluo_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 6,
"method": "tools/call",
"params": {
"name": "publish_quiz",
"arguments": { "quiz_id": "Customer readiness check" }
}
}'Obter os resultados de um quiz
curl -X POST https://fluotest.com/api/mcp \
-H "Authorization: Bearer fluo_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "get_results",
"arguments": { "quiz_id": "Customer readiness check" }
}
}'Excluir um quiz (com confirmação)
curl -X POST https://fluotest.com/api/mcp \
-H "Authorization: Bearer fluo_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 7,
"method": "tools/call",
"params": {
"name": "delete_quiz",
"arguments": { "quiz_id": "Customer readiness check", "confirm": true }
}
}'Erros#
Problemas de autenticação usam códigos de status HTTP com um corpo de erro OAuth (RFC 6750) e um cabeçalho WWW-Authenticate. Outros erros HTTP (endpoint desconhecido, limite de requisições) retornam application/problem+json (RFC 9457) com um código estável e uma dica. Problemas dentro de uma chamada de ferramenta voltam como uma resposta JSON-RPC normal com isError definido e a explicação no texto do content.
| Status | Significado |
|---|---|
| 401 | Chave de API ausente, inválida ou revogada. Confira o cabeçalho Authorization e se a chave ainda existe nas Configurações. |
| 400 | Corpo JSON-RPC malformado. Confira os campos jsonrpc, id, method e params. |
| 404 | Não há endpoint nesse caminho. O corpo é application/problem+json com o código not_found. |
| 429 | Limite de requisições excedido. O corpo é application/problem+json com o código rate_limited; espere o número de segundos indicado em Retry-After. |
| 200 + isError | A própria chamada da ferramenta falhou, por exemplo um nome/ID de quiz que não é seu, um nome de quiz que corresponde a mais de um dos seus quizzes, editar um quiz publicado sem confirm_edit_published: true, excluir um quiz sem confirm: true ou uma pergunta multiple_choice com menos de 2 opções. O conteúdo em texto explica o que corrigir. |
Códigos de erro (application/problem+json)
Todo corpo de problema tem type, title, status, code e geralmente detail e hint. A URI de type aponta para a entrada correspondente abaixo.
- not_found
- O caminho não é um endpoint da API. Veja /openapi.json para os endpoints documentados.
- rate_limited
- Requisições demais na janela atual. Espere os segundos de Retry-After e tente de novo.
Limites de requisições e versionamento#
Cada chave de API ou token OAuth pode enviar 120 requisições por minuto para /api/mcp (requisições sem credencial são contadas por endereço IP). Toda resposta traz RateLimit-Policy e RateLimit (formato do rascunho da IETF), além de RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset, para você diminuir o ritmo antes de atingir o limite. Acima do limite, você recebe um 429 com Retry-After.
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
RateLimit-Policy: "default";q=120;w=60
RateLimit: "default";r=0;t=17
Retry-After: 17
{"type":"https://fluotest.com/en/docs/api-reference#error-rate_limited","title":"Too Many Requests","status":429,"code":"rate_limited","hint":"Wait 17 seconds (Retry-After) before retrying."}O transporte é versionado pelo cabeçalho de requisição MCP-Protocol-Version, negociado durante o initialize. O conjunto de ferramentas segue o versionamento semântico (o campo version em /openapi.json): novas ferramentas e novos argumentos opcionais são aditivos e nunca quebram chamadas existentes.
Uma mudança incompatível é lançada com um novo nome de ferramenta. A ferramenta antiga continua funcionando por pelo menos 90 dias; as respostas que a usam trazem um cabeçalho Deprecation e um cabeçalho Sunset com a data de remoção, e a mudança é anunciada no changelog.
Perguntas frequentes#
Existe um limite de requisições?
Sim: 120 requisições por minuto por chave de API ou token OAuth em /api/mcp. Toda resposta inclui cabeçalhos RateLimit com o que ainda resta, e uma resposta 429 informa em Retry-After quanto tempo esperar.
Posso usar OAuth em vez de uma chave de API?
Sim, o OAuth é a forma recomendada de conectar assistentes de IA como o Claude, em que o usuário aprova o acesso em uma tela de consentimento. As chaves de API são a opção mais simples para scripts e clientes que só enviam cabeçalhos. Veja o guia do servidor MCP para configurar o OAuth.
O que a API consegue fazer hoje?
Oito operações: list_quizzes, create_quiz, get_quiz_questions, get_quiz_settings, update_quiz (com uma etapa de confirmação para editar quizzes publicados), publish_quiz, get_results e delete_quiz (com uma etapa de confirmação). Todo argumento que referencia um quiz aceita um título, slug ou ID. Mais operações estão planejadas. Conte o que você precisa pelo formulário de feedback no painel.