REST API
A API REST do UserJot dá ao seu código acesso aos mesmos dados do espaço de trabalho que o painel de controlo utiliza: metadados do espaço de trabalho, painéis, pedidos (incluindo fusões, pedidos semelhantes, etiquetas, subscrições e anexos), comentários, votos, entradas do registo de alterações, membros (incluindo o apagamento ao abrigo do RGPD), empresas, conversas, recursos e coleções e artigos do centro de ajuda.
A referência interativa completa, com todas as rotas, esquemas e exemplos, está disponível em userjot.com/docs/api e diretamente em https://api.userjot.com/v1/docs. O documento OpenAPI que lhe serve de base encontra-se em https://api.userjot.com/v1/openapi.json (também disponível em https://userjot.com/docs/api/openapi.json), para que possa gerar clientes com tipagem na sua linguagem.
URL base e autenticação
Base URL: https://api.userjot.com/v1
Authorization: Bearer YOUR_USERJOT_API_TOKENO UserJot aceita dois tipos de token Bearer nas rotas /v1/*:
Tokens de API: Crie um token em Definições → MCP & API (apenas administradores e proprietários). Os tokens começam pelo prefixo
uj_live_, pertencem a um único espaço de trabalho, não expiram até serem revogados e podem ser renomeados. Utilize Mantenha premido para revogar para revogar imediatamente um token; os tokens revogados continuam listados para fins de auditoria.Tokens de acesso OAuth 2.0: Suporta PKCE (
S256), Registo Dinâmico de Clientes (/oauth/register), Documentos de Metadados de ID de Cliente (CIMD), revogação de tokens (/oauth/revoke) e metadados de descoberta emhttps://api.userjot.com/.well-known/oauth-authorization-serverehttps://api.userjot.com/.well-known/oauth-protected-resource/v1/mcp. Os tokens de acesso são válidos durante 1 hora, com tokens de atualização rotativos de 30 dias (âmbitosworkspaceeoffline_access), e só permanecem válidos enquanto o utilizador que autorizou continuar a ser proprietário ou administrador desse espaço de trabalho.
Um primeiro pedido
curl https://api.userjot.com/v1/boards \
-H "Authorization: Bearer YOUR_USERJOT_API_TOKEN"Limites de pedidos
Os pedidos da API e do MCP partilham o mesmo limite de pedidos do espaço de trabalho:
Plano | Por minuto | Por hora |
|---|---|---|
Free | 10 pedidos | 150 pedidos |
Starter | 60 pedidos | 1 500 pedidos |
Professional | 120 pedidos | 5 000 pedidos |
Aplicam-se também limites adicionais específicos a determinadas operações:
Recursos: As importações de recursos, os carregamentos multipartes e as imagens Markdown importadas automaticamente partilham um limite separado por espaço de trabalho de 20 pedidos por minuto e 300 por hora (além de 20 por minuto e 300 por hora para a conclusão do carregamento).
Conversas de saída (
POST /v1/conversations): Disponíveis apenas nos planos pagos, com um limite de 5 por dia no Starter e de 15 por dia no Professional (devolve409 plan_feature_unavailableno plano Free).
Quando um limite é excedido, a API devolve HTTP 429 com um cabeçalho Retry-After e error.details.retry_after_seconds.
Paginação, erros e idempotência
Paginação por cursor. Os endpoints de listagem aceitam
cursorelimit(até100; os valores predefinidos variam consoante o endpoint, por exemplo10em listas detalhadas como/v1/requestse/v1/changelogs) e devolvemnext_cursorpara avançar na paginação.Estrutura de erro. As respostas de erro devolvem
{ "error": { "code", "message", "details" } }e incluem um cabeçalho de respostaX-Request-Idem todas as respostas. Os códigos mais comuns incluem422 validation_error(comdetails.issues),409 plan_limit_reached,409 plan_feature_unavailable,409 request_merged,410 member_erased(emGET/PATCH /v1/members/{member_id}após o apagamento ao abrigo do RGPD deDELETE /v1/members/{member_id}),409 member_erased(em rotas que fazem referência a um membro apagado),409 help_slug_takene409 help_version_conflict.Idempotência. Envie um cabeçalho
Idempotency-Key(armazenado durante 24 horas com uma impressão digital do corpo do pedido) para repetir pedidos de criação em segurança em oito rotas:/v1/requests,/v1/changelogs,/v1/conversations,/v1/conversations/{conversation_id}/replies,/v1/conversations/{conversation_id}/notes,/v1/assets/import,/v1/help/articlese/v1/help/collections.
Recursos e imagens
Carregue imagens (PNG, JPEG, GIF ou WebP até 10 MiB) de três formas:
Carregamento multipartes:
POST /v1/assets(createAsset, apenas REST) carrega uma imagem num único pedidomultipart/form-data.Importação por URL:
POST /v1/assets/importtransfere uma imagem HTTPS pública para o armazenamento do espaço de trabalho.Carregamento pré-assinado em três etapas:
POST /v1/assets/uploads(fornecendosize_bytesexatos; até 100 sessões de carregamento abertas por espaço de trabalho) →PUTbytes para o URL pré-assinado válido por 30 minutos →POST /v1/assets/uploads/{upload_id}/complete.
Faça referência aos recursos carregados em Markdown com asset:<id>. Os URLs públicos de imagens HTTPS incorporados em Markdown enviado para os endpoints do registo de alterações e dos artigos de ajuda também são importados automaticamente (até 10 imagens em linha por pedido do registo de alterações e 20 por pedido de artigo do centro de ajuda), sendo contabilizados no limite de recursos do espaço de trabalho.
Webhooks
Os webhooks de saída para clientes ainda não estão disponíveis. Para receber alertas da equipa em tempo real, utilize Connect Slack ou Connect Discord, ou consulte as alterações através da REST API.
REST ou MCP
O servidor MCP é desenvolvido com base nesta API e disponibiliza 98 das 100 operações REST como ferramentas MCP (POST /v1/assets carregamento multipartes e DELETE /v1/members/{member_id} apagamento ao abrigo do RGPD são exclusivos da REST). Utilize a API REST a partir do seu próprio backend, das suas automatizações ou do código da sua aplicação quando pretender controlo total sobre os pedidos e as respostas. Utilize MCP para ligar um cliente de IA compatível com o Model Context Protocol.
Gestão de tokens
Trate o seu token de API como qualquer outro segredo:
Não o inclua diretamente em ficheiros de configuração submetidos ao repositório.
Prefira variáveis de ambiente ou um gestor de segredos.
Sempre que possível, utilize tokens separados para ambientes ou membros da equipa diferentes.
Revogue os tokens de que já não precisa em Definições → MCP & API, utilizando Mantenha premido para revogar.