REST API
L’API REST di UserJot offre al tuo codice accesso agli stessi dati dell’area di lavoro usati dalla dashboard: metadati dell’area di lavoro, bacheche, richieste (incluse fusioni, richieste simili, tag, iscrizioni e allegati), commenti, voti, voci del changelog, membri (inclusa la cancellazione ai sensi del GDPR), aziende, conversazioni, asset e raccolte e articoli del Centro assistenza.
Il riferimento interattivo completo, con ogni endpoint, schema ed esempio, è disponibile all’indirizzo userjot.com/docs/api e direttamente su https://api.userjot.com/v1/docs. Il documento OpenAPI alla base del riferimento è disponibile su https://api.userjot.com/v1/openapi.json (e in una copia su https://userjot.com/docs/api/openapi.json), così puoi generare client tipizzati nella tua lingua.
URL di base e autenticazione
Base URL: https://api.userjot.com/v1
Authorization: Bearer YOUR_USERJOT_API_TOKENUserJot accetta due tipi di token Bearer sulle route /v1/*:
Token API: crea un token in Impostazioni → MCP & API (solo amministratori e proprietari). I token hanno il prefisso
uj_live_, appartengono a una sola area di lavoro, non scadono finché non vengono revocati e possono essere rinominati. Usa Tieni premuto per revocare (tieni premuto) per revocare immediatamente un token; i token revocati restano nell’elenco a fini di verifica.Token di accesso OAuth 2.0: supportano PKCE (
S256), la registrazione dinamica dei client (/oauth/register), i documenti dei metadati dell’ID client (CIMD), la revoca dei token (/oauth/revoke) e i metadati di discovery suhttps://api.userjot.com/.well-known/oauth-authorization-serverehttps://api.userjot.com/.well-known/oauth-protected-resource/v1/mcp. I token di accesso durano 1 ora e sono accompagnati da token di aggiornamento rotanti validi 30 giorni (ambitiworkspaceeoffline_access); restano validi solo finché l’utente che ha autorizzato l’accesso mantiene il ruolo di proprietario o amministratore di quell’area di lavoro.
Una prima richiesta
curl https://api.userjot.com/v1/boards \
-H "Authorization: Bearer YOUR_USERJOT_API_TOKEN"Limiti di frequenza
Le richieste API e MCP condividono un unico limite di frequenza per spazio di lavoro:
Piano | Al minuto | All’ora |
|---|---|---|
Free | 10 richieste | 150 richieste |
Starter | 60 richieste | 1.500 richieste |
Professional | 120 richieste | 5.000 richieste |
Si applicano budget aggiuntivi specifici per operazione:
Asset: le importazioni di asset, i caricamenti multipart e le immagini Markdown importate automaticamente condividono un budget separato per area di lavoro di 20 richieste al minuto e 300 all’ora (oltre a 20 al minuto e 300 all’ora per il completamento dei caricamenti).
Conversazioni in uscita (
POST /v1/conversations): disponibili solo nei piani a pagamento, con un limite di 5 al giorno nel piano Starter e di 15 al giorno nel piano Professional (nel piano Free restituiscono409 plan_feature_unavailable).
Quando viene superato un limite, l’API restituisce HTTP 429 con un’intestazione Retry-After e error.details.retry_after_seconds.
Paginazione, errori e idempotenza
Paginazione tramite cursore. Gli endpoint per gli elenchi accettano
cursorelimit(fino a100; i valori predefiniti variano a seconda dell’endpoint, ad esempio10per gli elenchi ricchi di dati come/v1/requestse/v1/changelogs) e restituiscononext_cursorper passare alla pagina successiva.Struttura delle risposte di errore. Le risposte di errore restituiscono
{ "error": { "code", "message", "details" } }e includono un’intestazione di rispostaX-Request-Idin ogni risposta. Tra i codici più comuni figurano422 validation_error(condetails.issues),409 plan_limit_reached,409 plan_feature_unavailable,409 request_merged,410 member_erased(suGET/PATCH /v1/members/{member_id}dopo la cancellazione ai sensi del GDPRDELETE /v1/members/{member_id}),409 member_erased(sugli endpoint che fanno riferimento a un membro cancellato),409 help_slug_takene409 help_version_conflict.Idempotenza. Invia un’intestazione
Idempotency-Key(memorizzata per 24 ore insieme all’impronta del corpo della richiesta) per riprovare in sicurezza le richieste di creazione su otto endpoint:/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.
Risorse e immagini
Carica immagini (PNG, JPEG, GIF o WebP fino a 10 MiB) in tre modi:
Caricamento multipart:
POST /v1/assets(createAsset, solo REST) carica un’immagine con una singola richiestamultipart/form-data.Importazione da URL:
POST /v1/assets/importscarica un’immagine HTTPS pubblica nello spazio di archiviazione dell’area di lavoro.Caricamento in tre passaggi con URL presigned:
POST /v1/assets/uploads(fornendo il valore esatto disize_bytes; fino a 100 sessioni di caricamento aperte per area di lavoro) →PUTbyte all’URL presigned valido 30 minuti →POST /v1/assets/uploads/{upload_id}/complete.
Fai riferimento agli asset caricati in Markdown con asset:<id>. Anche gli URL HTTPS pubblici di immagini incorporati nel Markdown inviato agli endpoint del changelog e degli articoli del Centro assistenza vengono importati automaticamente (fino a 10 immagini in linea per richiesta del changelog e 20 per richiesta di un articolo del Centro assistenza) e conteggiati nel budget degli asset dell’area di lavoro.
Webhook
I webhook in uscita per i clienti non sono ancora disponibili. Per ricevere avvisi in tempo reale per il team, usa Connect Slack o Connect Discord, oppure controlla periodicamente le modifiche tramite l’API REST.
REST o MCP
Il server MCP si basa su questa API ed espone 98 delle 100 operazioni REST come strumenti MCP (POST /v1/assets per il caricamento multipart e DELETE /v1/members/{member_id} per la cancellazione ai sensi del GDPR sono disponibili solo tramite REST). Usa l’API REST dal tuo backend, dalle tue automazioni o dal codice della tua applicazione quando vuoi il pieno controllo su richieste e risposte. Usa MCP per connetterti a un client AI che supporta il Model Context Protocol.
Gestione dei token
Tratta il tuo token API come qualsiasi altro segreto:
Non inserirlo direttamente nei file di configurazione inclusi nei commit.
Preferisci le variabili di ambiente o un gestore di segreti.
Quando possibile, usa token diversi per ambienti o collaboratori diversi.
Revoca i token che non ti servono più da Impostazioni → MCP & API usando Tieni premuto per revocare.