FAQ do Desenvolvedor

FAQ

API - Geral

Qual é a URL base da API?

A URL base segue o formato da sua instância do Prodgy. Todas as requisições usam JSON (UTF-8) como formato de dados. A documentação interativa está disponível via Swagger UI na própria instância.

Quais recursos estão disponíveis na API?

A API oferece 8 recursos principais:

Recurso	Descrição
Agents	Gerenciar agentes (listar, criar, atualizar, deletar)
Executions	Executar agentes e consultar resultados
Integrations	Gerenciar conexões com ferramentas externas
Knowledge Base	Importar documentos e gerenciar a base de conhecimento
Triggers	Configurar gatilhos automatizados
Webhooks	Registrar e gerenciar webhooks
Transcription	Transcrever audio (formatos suportados, máximo 25 MB)
API Tokens	Gerenciar tokens de autenticação

Quais são os limites de taxa (rate limiting)?

Padrão: 10 requisições por minuto
Estrito: 5 requisições por minuto (para endpoints de alta carga)

Ao exceder o limite, a API retorna status 429 Too Many Requests.

Como funciona a paginação?

Use os parâmetros page, pageSize e limit nas requisições de listagem para controlar a paginação dos resultados.

Autenticação

Como me autentico na API?

Ha dois métodos de autenticação:

API Token: para integrações de sistema — envie no header X-API-Token ou Authorization: Bearer {token}
JWT: para sessões de usuário autenticado

Como crio um token de API?

Via interface: em Configurações do Workspace > Tokens de API, clique em criar. Via API: use o endpoint de criação de tokens. O formato do token é prodgy_{caracteres_aleatórios}.

Posso definir data de expiração nos tokens?

Sim. Ao criar ou renovar um token, você pode definir uma data de expiração. Tokens expirados param de funcionar automaticamente.

Como revogo ou regenero um token?

Use os endpoints de revogação ou regeneração da API, ou faça pela interface em Tokens de API. Ao regenerar, o token anterior é invalidado imediatamente.

Como monitoro o uso dos tokens?

A API registra auditoria de todas as operações com tokens, incluindo 6 tipos de ação: criado, utilizado, revogado, expirado, renovado e regenerado.

Quais são as boas práticas de segurança?

Sempre use HTTPS
Nunca exponha tokens em código-fonte ou logs
Defina datas de expiração
Rotacione tokens periodicamente
Use tokens diferentes por ambiente (dev, staging, produção)

Webhooks

O que são webhooks no Prodgy?

Webhooks permitem que sistemas externos enviem eventos para o Prodgy via HTTP POST. O endpoint genérico e POST /api/webhook/{caminho_customizado}.

Qual formato o payload deve ter?

O payload deve ser enviado como JSON com Content-Type: application/json. A estrutura inclui metadados do evento e os dados específicos.

Existem webhooks especializados para comunicadores?

Sim:

Plataforma	Endpoint
Slack / Google Chat	`/api/communicator/webhook/{integration_base_id}`
Microsoft Teams	`/api/communicator/botframework/{integration_base_id}/messages`

Quais são as boas práticas para webhooks?

Valide os dados recebidos antes de processar
Responda rapidamente (evite processamento longo na requisição)
Implemente retries com backoff exponencial
Use HTTPS para todos os endpoints
Monitore falhas e configure alertas

Endpoints e Recursos

Como executo um agente via API?

Use o endpoint de Executions com o ID do agente e os parâmetros necessários. A resposta inclui o resultado da execução ou um ID para consulta assíncrona.

Como importo documentos pela API?

Use os endpoints da Knowledge Base para enviar arquivos. Formatos suportados: CSV, PDF, DOCX, TXT, MD, JSON, XML. Tamanho máximo: 50 MB por arquivo.

Como transcrevo audio pela API?

Envie o arquivo de audio via multipart/form-data para o endpoint de Transcription. Tamanho máximo: 25 MB. O resultado e retornado em texto.

Onde encontro a documentação completa dos endpoints?

Acesse o Swagger UI na sua instância do Prodgy. La você encontra todos os endpoints documentados com exemplos de requisição e resposta, e pode testar diretamente.

MCP Gateway

O que é o MCP Gateway?

O MCP Gateway é um servidor MCP (Model Context Protocol) que permite conectar assistentes de codificação como Claude Code, Cursor e Windsurf ao Prodgy. Através dele, seu assistente de IA acessa ferramentas de busca de conhecimento, agentes, integrações e o contexto do workspace.

Como conecto meu assistente de codificação ao MCP Gateway?

Adicione a configuração MCP no arquivo do seu cliente (.mcp.json para Claude Code, .cursor/mcp.json para Cursor, etc.) com a URL do seu Prodgy seguida de /mcp e seu API Token no header de autorização. Consulte a seção MCP Gateway > Ativando o MCP Server no Guia do Desenvolvedor.

Preciso instalar algo para usar o MCP Gateway?

Não. O MCP Gateway é um serviço remoto via HTTP. Basta configurar a URL no seu cliente MCP — não há instalação local necessária.

Quais ferramentas estão disponíveis no MCP Gateway?

As ferramentas se dividem em dois grupos:

Ferramentas da plataforma: get_my_profile, get_workspace_info, update_my_ai_preferences, search_knowledge, list_agents, invoke_agent, gerenciamento do catálogo de integrações e configurações MCP
Ferramentas de integração: carregadas dinamicamente das integrações ativas da sua organização (ex: create_ticket, list_issues, send_message)

O que é o contexto do workspace e como ele é injetado?

O get_workspace_info retorna um README dinâmico do seu workspace/produto, montado a partir do Main do Prodgy. Ele é injetado automaticamente na primeira chamada de ferramenta de cada sessão MCP — junto com get_my_profile para a identidade do usuário autenticado. Você não precisa chamá-los explicitamente.

Como faço busca semântica na base de conhecimento?

Use a ferramenta search_knowledge com uma descrição em linguagem natural do que procura. Prefira frases descritivas a palavras-chave soltas. Ajuste o top_k conforme a necessidade (3 para resultados focados, 10 para exploração ampla).

Como executo um agente do Prodgy pelo MCP?

Use list_agents para descobrir os agentes disponíveis, e invoke_agent com a query desejada. Se você não especificar um agent_id, o Prodgy seleciona automaticamente o agente mais apropriado.

O que é o Integration Builder?

É o fluxo que permite criar templates de integração diretamente do assistente de codificação usando create_integration. Você descreve o serviço que quer conectar, a IA constrói o template completo, e o administrador ativa no Prodgy com as credenciais reais. As novas ferramentas aparecem automaticamente no MCP de toda a organização.

Preciso de uma role especial para gerenciar integrações via MCP?

Sim. As ferramentas create_integration, update_integration, delete_integration, get_mcp_settings e update_mcp_settings requerem a role SYSTEM no API Token.

Duas integrações têm ferramentas com o mesmo nome. Como resolver?

O Gateway detecta automaticamente colisões de nomes e adiciona um parâmetro _integration para desambiguação. O assistente de IA recebe uma mensagem listando as opções disponíveis.

Solução de Problemas

Recebi erro 401. O que fazer?

Verifique se o token está correto, ativo e não expirado. Confirme que está enviando no header X-API-Token ou Authorization: Bearer {token}.

Recebi erro 429. O que fazer?

Você excedeu o limite de taxa. Aguarde antes de enviar novas requisições. Considere implementar um mecanismo de retry com backoff exponencial.

Recebi erro 500. O que fazer?

Erro interno do servidor. Tente novamente após alguns segundos. Se persistir, verifique os logs do sistema ou entre em contato com o suporte em support@prodgy.ai.