REST API v1 per integrazioni programmatiche. Ogni endpoint richiede l'autenticazione tramite chiave API nell'header x-agent-api-key e applica scope specifici per risorsa.
Questa pagina e renderizzata direttamente da docs/openapi-v1.yaml. Se cambia la spec, cambia anche questo riferimento. L'endpoint della specifica raw resta GET /api/v1/openapi e la discovery e disponibile su GET /api/v1. Le route interne del prodotto non fanno parte di questo contratto pubblico.
/api/v1/usersElenca utenti
Parametri query
Risposte
cURL
curl -s -X GET "http://localhost:3000/api/v1/users"\
-H "x-agent-api-key: $API_KEY"/api/v1/usersCrea utente
Corpo della richiesta
application/jsonCreateUserRequestobbligatorioCampi
{
"identityId": "IDENTITY_ID",
"name": "Example name"
}Risposte
cURL
curl -s -X POST "http://localhost:3000/api/v1/users"\
-H "content-type: application/json"\
-H "x-agent-api-key: $API_KEY"\
-d '{
"identityId": "IDENTITY_ID",
"name": "Example name"
}'/api/v1/users/{userId}Recupera utente per ID
Parametri path
Risposte
cURL
curl -s -X GET "http://localhost:3000/api/v1/users/USER_ID"\
-H "x-agent-api-key: $API_KEY"/api/v1/users/{userId}Aggiorna utente
Parametri path
Corpo della richiesta
application/jsonUpdateUserRequestobbligatorioCampi
{
"identityId": "IDENTITY_ID",
"name": "Example name",
"email": "user@example.com",
"avatarUrl": "https://example.com/avatar.png",
"status": "online",
"customStatus": "example",
"lastSeenAt": 0
}Risposte
cURL
curl -s -X PATCH "http://localhost:3000/api/v1/users/USER_ID"\
-H "content-type: application/json"\
-H "x-agent-api-key: $API_KEY"\
-d '{
"identityId": "IDENTITY_ID",
"name": "Example name",
"email": "user@example.com",
"avatarUrl": "https://example.com/avatar.png",
"status": "online",
"customStatus": "example",
"lastSeenAt": 0
}'/api/v1/users/{userId}Elimina utente
Parametri path
Risposte
cURL
curl -s -X DELETE "http://localhost:3000/api/v1/users/USER_ID"\
-H "x-agent-api-key: $API_KEY"/api/v1/teamsElenca team
Parametri query
Risposte
cURL
curl -s -X GET "http://localhost:3000/api/v1/teams"\
-H "x-agent-api-key: $API_KEY"/api/v1/teamsCrea team
Corpo della richiesta
application/jsonCreateTeamRequestobbligatorioCampi
{
"name": "Example name",
"memberships": [
{
"userId": "USER_ID",
"role": "workspace_admin"
}
]
}Risposte
cURL
curl -s -X POST "http://localhost:3000/api/v1/teams"\
-H "content-type: application/json"\
-H "x-agent-api-key: $API_KEY"\
-d '{
"name": "Example name",
"memberships": [
{
"userId": "USER_ID",
"role": "workspace_admin"
}
]
}'/api/v1/teams/{teamId}Recupera team per ID
Parametri path
Risposte
cURL
curl -s -X GET "http://localhost:3000/api/v1/teams/TEAM_ID"\
-H "x-agent-api-key: $API_KEY"/api/v1/teams/{teamId}Aggiorna team
Parametri path
Corpo della richiesta
application/jsonUpdateTeamRequestobbligatorioCampi
{
"name": "Example name",
"description": "Example description",
"memberships": [
{
"userId": "USER_ID",
"role": "workspace_admin"
}
],
"settings": {
"allowMemberInvites": true,
"allowAiAssistants": true,
"aiAssistantName": "Example name",
"aiAssistantProvider": "openai",
"aiAssistantModel": "example",
"defaultTimezone": "Europe/Rome"
}
}Risposte
cURL
curl -s -X PATCH "http://localhost:3000/api/v1/teams/TEAM_ID"\
-H "content-type: application/json"\
-H "x-agent-api-key: $API_KEY"\
-d '{
"name": "Example name",
"description": "Example description",
"memberships": [
{
"userId": "USER_ID",
"role": "workspace_admin"
}
],
"settings": {
"allowMemberInvites": true,
"allowAiAssistants": true,
"aiAssistantName": "Example name",
"aiAssistantProvider": "openai",
"aiAssistantModel": "example",
"defaultTimezone": "Europe/Rome"
}
}'/api/v1/teams/{teamId}Elimina team
Parametri path
Risposte
cURL
curl -s -X DELETE "http://localhost:3000/api/v1/teams/TEAM_ID"\
-H "x-agent-api-key: $API_KEY"/api/v1/channelsElenca canali
Parametri query
Risposte
cURL
curl -s -X GET "http://localhost:3000/api/v1/channels"\
-H "x-agent-api-key: $API_KEY"/api/v1/channelsCrea canale
Corpo della richiesta
application/jsonCreateChannelRequestobbligatorioCampi
{
"teamId": "TEAM_ID",
"type": "public",
"createdBy": "example"
}Risposte
cURL
curl -s -X POST "http://localhost:3000/api/v1/channels"\
-H "content-type: application/json"\
-H "x-agent-api-key: $API_KEY"\
-d '{
"teamId": "TEAM_ID",
"type": "public",
"createdBy": "example"
}'/api/v1/channels/{channelId}Recupera canale per ID
Parametri path
Risposte
cURL
curl -s -X GET "http://localhost:3000/api/v1/channels/CHANNEL_ID"\
-H "x-agent-api-key: $API_KEY"/api/v1/channels/{channelId}Aggiorna canale
Parametri path
Corpo della richiesta
application/jsonUpdateChannelRequestobbligatorioCampi
{
"name": "Example name",
"icon": "example",
"description": "Example description",
"archived": true,
"memberIds": [
"MEMBER_ID"
]
}Risposte
cURL
curl -s -X PATCH "http://localhost:3000/api/v1/channels/CHANNEL_ID"\
-H "content-type: application/json"\
-H "x-agent-api-key: $API_KEY"\
-d '{
"name": "Example name",
"icon": "example",
"description": "Example description",
"archived": true,
"memberIds": [
"MEMBER_ID"
]
}'/api/v1/channels/{channelId}Elimina canale
Parametri path
Risposte
cURL
curl -s -X DELETE "http://localhost:3000/api/v1/channels/CHANNEL_ID"\
-H "x-agent-api-key: $API_KEY"/api/v1/channels/{channelId}/filesList shared files in a channel
Parametri path
Parametri query
Risposte
cURL
curl -s -X GET "http://localhost:3000/api/v1/channels/CHANNEL_ID/files?actorId=ACTOR_ID"\
-H "x-agent-api-key: $API_KEY"/api/v1/channels/{channelId}/filesUpload a file to a channel
Streams a multipart file payload into Convex storage, then creates a message attachment in the target channel.
Parametri path
Corpo della richiesta
multipart/form-dataUploadChannelFileRequestobbligatorioCampi
{
"actorId": "ACTOR_ID",
"file": "example"
}Risposte
cURL
curl -s -X POST "http://localhost:3000/api/v1/channels/CHANNEL_ID/files"\
-H "content-type: multipart/form-data"\
-H "x-agent-api-key: $API_KEY"\
-d '{
"actorId": "ACTOR_ID",
"file": "example"
}'/api/v1/dealsList CRM deals
Parametri query
Risposte
cURL
curl -s -X GET "http://localhost:3000/api/v1/deals?actorId=ACTOR_ID&workspaceId=WORKSPACE_ID"\
-H "x-agent-api-key: $API_KEY"/api/v1/dealsCreate CRM deal
Corpo della richiesta
application/jsonCreateDealRequestobbligatorioCampi
{
"actorId": "ACTOR_ID",
"workspaceId": "WORKSPACE_ID",
"name": "Example name",
"value": 1
}Risposte
cURL
curl -s -X POST "http://localhost:3000/api/v1/deals"\
-H "content-type: application/json"\
-H "x-agent-api-key: $API_KEY"\
-d '{
"actorId": "ACTOR_ID",
"workspaceId": "WORKSPACE_ID",
"name": "Example name",
"value": 1
}'/api/v1/deals/{dealId}Get CRM deal by ID
Parametri path
Parametri query
Risposte
cURL
curl -s -X GET "http://localhost:3000/api/v1/deals/DEAL_ID?actorId=ACTOR_ID"\
-H "x-agent-api-key: $API_KEY"/api/v1/deals/{dealId}Update CRM deal
Parametri path
Corpo della richiesta
application/jsonUpdateDealRequestobbligatorioCampi
{
"actorId": "ACTOR_ID"
}Risposte
cURL
curl -s -X PATCH "http://localhost:3000/api/v1/deals/DEAL_ID"\
-H "content-type: application/json"\
-H "x-agent-api-key: $API_KEY"\
-d '{
"actorId": "ACTOR_ID"
}'/api/v1/deals/{dealId}Delete CRM deal
Parametri path
Parametri query
Risposte
cURL
curl -s -X DELETE "http://localhost:3000/api/v1/deals/DEAL_ID?actorId=ACTOR_ID"\
-H "x-agent-api-key: $API_KEY"/api/v1/deals/{dealId}/activitiesList CRM deal activities
Parametri path
Parametri query
Risposte
cURL
curl -s -X GET "http://localhost:3000/api/v1/deals/DEAL_ID/activities?actorId=ACTOR_ID"\
-H "x-agent-api-key: $API_KEY"/api/v1/messagesElenca messaggi
Almeno uno tra channelId, authorId e threadId e obbligatorio, a meno che pinned=true. Con pinned=true sono obbligatori channelId e actorId, mentre authorId, threadId e before non sono ammessi.
Parametri query
Risposte
cURL
curl -s -X GET "http://localhost:3000/api/v1/messages"\
-H "x-agent-api-key: $API_KEY"/api/v1/messagesCrea messaggio
Corpo della richiesta
application/jsonCreateMessageRequestobbligatorioCampi
{
"channelId": "CHANNEL_ID",
"authorId": "AUTHOR_ID",
"content": "Example content"
}Risposte
cURL
curl -s -X POST "http://localhost:3000/api/v1/messages"\
-H "content-type: application/json"\
-H "x-agent-api-key: $API_KEY"\
-d '{
"channelId": "CHANNEL_ID",
"authorId": "AUTHOR_ID",
"content": "Example content"
}'/api/v1/messages/{messageId}Recupera messaggio per ID
Parametri path
Risposte
cURL
curl -s -X GET "http://localhost:3000/api/v1/messages/MESSAGE_ID"\
-H "x-agent-api-key: $API_KEY"/api/v1/messages/{messageId}Aggiorna messaggio
Parametri path
Corpo della richiesta
application/jsonUpdateMessageRequestobbligatorioCampi
{
"actorId": "ACTOR_ID",
"content": "Example content"
}Risposte
cURL
curl -s -X PATCH "http://localhost:3000/api/v1/messages/MESSAGE_ID"\
-H "content-type: application/json"\
-H "x-agent-api-key: $API_KEY"\
-d '{
"actorId": "ACTOR_ID",
"content": "Example content"
}'/api/v1/messages/{messageId}Elimina messaggio
Parametri path
Risposte
cURL
curl -s -X DELETE "http://localhost:3000/api/v1/messages/MESSAGE_ID"\
-H "x-agent-api-key: $API_KEY"/api/v1/messages/{messageId}/historyElenca le revisioni precedenti del messaggio
Parametri path
Parametri query
Risposte
cURL
curl -s -X GET "http://localhost:3000/api/v1/messages/MESSAGE_ID/history?actorId=ACTOR_ID"\
-H "x-agent-api-key: $API_KEY"/api/v1/messages/{messageId}/pinAggiungi un pin a un messaggio
Parametri path
Corpo della richiesta
application/jsonPinMessageRequestobbligatorioCampi
{
"actorId": "ACTOR_ID"
}Risposte
cURL
curl -s -X POST "http://localhost:3000/api/v1/messages/MESSAGE_ID/pin"\
-H "content-type: application/json"\
-H "x-agent-api-key: $API_KEY"\
-d '{
"actorId": "ACTOR_ID"
}'/api/v1/messages/{messageId}/pinRimuovi il pin da un messaggio
Parametri path
Corpo della richiesta
application/jsonPinMessageRequestobbligatorioCampi
{
"actorId": "ACTOR_ID"
}Risposte
cURL
curl -s -X DELETE "http://localhost:3000/api/v1/messages/MESSAGE_ID/pin"\
-H "content-type: application/json"\
-H "x-agent-api-key: $API_KEY"\
-d '{
"actorId": "ACTOR_ID"
}'/api/v1/messages/{messageId}/reactionsList reactions for a message
Parametri path
Parametri query
Risposte
cURL
curl -s -X GET "http://localhost:3000/api/v1/messages/MESSAGE_ID/reactions?actorId=ACTOR_ID"\
-H "x-agent-api-key: $API_KEY"/api/v1/messages/{messageId}/reactionsAdd a reaction to a message
Parametri path
Corpo della richiesta
application/jsonReactionMutationRequestobbligatorioCampi
{
"actorId": "ACTOR_ID",
"emoji": "example"
}Risposte
cURL
curl -s -X POST "http://localhost:3000/api/v1/messages/MESSAGE_ID/reactions"\
-H "content-type: application/json"\
-H "x-agent-api-key: $API_KEY"\
-d '{
"actorId": "ACTOR_ID",
"emoji": "example"
}'/api/v1/messages/{messageId}/reactionsRemove a reaction from a message
Parametri path
Corpo della richiesta
application/jsonReactionMutationRequestobbligatorioCampi
{
"actorId": "ACTOR_ID",
"emoji": "example"
}Risposte
cURL
curl -s -X DELETE "http://localhost:3000/api/v1/messages/MESSAGE_ID/reactions"\
-H "content-type: application/json"\
-H "x-agent-api-key: $API_KEY"\
-d '{
"actorId": "ACTOR_ID",
"emoji": "example"
}'/api/v1/searchSearch message history
Full-text search across workspace message history with optional channel filtering.
Parametri query
Risposte
cURL
curl -s -X GET "http://localhost:3000/api/v1/search?actorId=ACTOR_ID&teamId=TEAM_ID&query=example"\
-H "x-agent-api-key: $API_KEY"/api/v1/presenceList online users for a team or channel
Exactly one of teamId or channelId must be provided.
Parametri query
Risposte
cURL
curl -s -X GET "http://localhost:3000/api/v1/presence?actorId=ACTOR_ID"\
-H "x-agent-api-key: $API_KEY"/api/v1/typingUpdate typing indicator state
Corpo della richiesta
application/jsonTypingStateRequestobbligatorioCampi
{
"actorId": "ACTOR_ID",
"channelId": "CHANNEL_ID"
}Risposte
cURL
curl -s -X POST "http://localhost:3000/api/v1/typing"\
-H "content-type: application/json"\
-H "x-agent-api-key: $API_KEY"\
-d '{
"actorId": "ACTOR_ID",
"channelId": "CHANNEL_ID"
}'/api/v1/calendar-eventsElenca eventi di calendario
Parametri query
Risposte
cURL
curl -s -X GET "http://localhost:3000/api/v1/calendar-events"\
-H "x-agent-api-key: $API_KEY"/api/v1/calendar-eventsCrea evento di calendario
Corpo della richiesta
application/jsonCreateCalendarEventRequestobbligatorioCampi
{
"title": "Example title",
"organizerId": "ORGANIZER_ID",
"type": "personal",
"startAt": 0,
"endAt": 0
}Risposte
cURL
curl -s -X POST "http://localhost:3000/api/v1/calendar-events"\
-H "content-type: application/json"\
-H "x-agent-api-key: $API_KEY"\
-d '{
"title": "Example title",
"organizerId": "ORGANIZER_ID",
"type": "personal",
"startAt": 0,
"endAt": 0
}'/api/v1/calendar-events/conflictsAnalizza i conflitti di pianificazione per i partecipanti
Corpo della richiesta
application/jsonAnalyzeCalendarConflictsRequestobbligatorioCampi
{
"startAt": 0,
"endAt": 0,
"attendeeIds": [
"ATTENDEE_ID"
]
}Risposte
cURL
curl -s -X POST "http://localhost:3000/api/v1/calendar-events/conflicts"\
-H "content-type: application/json"\
-H "x-agent-api-key: $API_KEY"\
-d '{
"startAt": 0,
"endAt": 0,
"attendeeIds": [
"ATTENDEE_ID"
]
}'/api/v1/calendar-events/{eventId}Recupera evento di calendario per ID
Parametri path
Risposte
cURL
curl -s -X GET "http://localhost:3000/api/v1/calendar-events/EVENT_ID"\
-H "x-agent-api-key: $API_KEY"/api/v1/calendar-events/{eventId}Aggiorna evento di calendario
Parametri path
Corpo della richiesta
application/jsonUpdateCalendarEventRequestobbligatorioCampi
{
"title": "Example title",
"description": "Example description",
"organizerId": "ORGANIZER_ID",
"type": "personal",
"teamId": "TEAM_ID",
"startAt": 0,
"endAt": 0,
"attendeeIds": [
"ATTENDEE_ID"
],
"recurrence": {
"frequency": "daily",
"interval": 1
},
"reminderMinutesBefore": [
1
]
}Risposte
cURL
curl -s -X PATCH "http://localhost:3000/api/v1/calendar-events/EVENT_ID"\
-H "content-type: application/json"\
-H "x-agent-api-key: $API_KEY"\
-d '{
"title": "Example title",
"description": "Example description",
"organizerId": "ORGANIZER_ID",
"type": "personal",
"teamId": "TEAM_ID",
"startAt": 0,
"endAt": 0,
"attendeeIds": [
"ATTENDEE_ID"
],
"recurrence": {
"frequency": "daily",
"interval": 1
},
"reminderMinutesBefore": [
1
]
}'/api/v1/calendar-events/{eventId}Elimina evento di calendario
Parametri path
Risposte
cURL
curl -s -X DELETE "http://localhost:3000/api/v1/calendar-events/EVENT_ID"\
-H "x-agent-api-key: $API_KEY"/api/v1/notificationsList inbox notifications for a user
Parametri query
Risposte
cURL
curl -s -X GET "http://localhost:3000/api/v1/notifications?userId=USER_ID"\
-H "x-agent-api-key: $API_KEY"/api/v1/notifications/{notificationId}Mark a single inbox notification as read
Parametri path
Corpo della richiesta
application/jsonMarkNotificationReadRequestobbligatorioCampi
{
"userId": "USER_ID"
}Risposte
cURL
curl -s -X PATCH "http://localhost:3000/api/v1/notifications/NOTIFICATION_ID"\
-H "content-type: application/json"\
-H "x-agent-api-key: $API_KEY"\
-d '{
"userId": "USER_ID"
}'/api/v1/notifications/read-allMark inbox notifications as read in bulk
Corpo della richiesta
application/jsonMarkAllNotificationsReadRequestobbligatorioCampi
{
"userId": "USER_ID"
}Risposte
cURL
curl -s -X POST "http://localhost:3000/api/v1/notifications/read-all"\
-H "content-type: application/json"\
-H "x-agent-api-key: $API_KEY"\
-d '{
"userId": "USER_ID"
}'/api/v1/notifications/preferencesRecupera le preferenze di notifica di un utente
Parametri query
Risposte
cURL
curl -s -X GET "http://localhost:3000/api/v1/notifications/preferences?userId=USER_ID"\
-H "x-agent-api-key: $API_KEY"/api/v1/notifications/preferencesAggiorna le preferenze di notifica di un utente
Corpo della richiesta
application/jsonUpdateNotificationPreferencesRequestobbligatorioCampi
{
"userId": "USER_ID",
"quietHoursEnabled": true,
"quietHoursStart": "example",
"quietHoursEnd": "example",
"soundEnabled": true,
"suppressPushWhenActive": true,
"timeZone": "Europe/Rome",
"eventOverrides": [
{
"eventKey": "chat.mention"
}
]
}Risposte
cURL
curl -s -X PATCH "http://localhost:3000/api/v1/notifications/preferences"\
-H "content-type: application/json"\
-H "x-agent-api-key: $API_KEY"\
-d '{
"userId": "USER_ID",
"quietHoursEnabled": true,
"quietHoursStart": "example",
"quietHoursEnd": "example",
"soundEnabled": true,
"suppressPushWhenActive": true,
"timeZone": "Europe/Rome",
"eventOverrides": [
{
"eventKey": "chat.mention"
}
]
}'/api/v1/notifications/preferences/teams/{teamId}Recupera la preferenza di notifica a livello team
Parametri path
Parametri query
Risposte
cURL
curl -s -X GET "http://localhost:3000/api/v1/notifications/preferences/teams/TEAM_ID?userId=USER_ID"\
-H "x-agent-api-key: $API_KEY"/api/v1/notifications/preferences/teams/{teamId}Aggiorna la preferenza di notifica a livello team
Parametri path
Corpo della richiesta
application/jsonUpdateTeamNotificationPreferenceRequestobbligatorioCampi
{
"userId": "USER_ID",
"eventOverrides": [
{
"eventKey": "chat.mention"
}
]
}Risposte
cURL
curl -s -X PATCH "http://localhost:3000/api/v1/notifications/preferences/teams/TEAM_ID"\
-H "content-type: application/json"\
-H "x-agent-api-key: $API_KEY"\
-d '{
"userId": "USER_ID",
"eventOverrides": [
{
"eventKey": "chat.mention"
}
]
}'/api/v1/notifications/preferences/channels/{channelId}Get channel-level mute preference
Parametri path
Parametri query
Risposte
cURL
curl -s -X GET "http://localhost:3000/api/v1/notifications/preferences/channels/CHANNEL_ID?userId=USER_ID"\
-H "x-agent-api-key: $API_KEY"/api/v1/notifications/preferences/channels/{channelId}Update channel-level mute preference
Parametri path
Corpo della richiesta
application/jsonUpdateChannelNotificationPreferenceRequestobbligatorioCampi
{
"userId": "USER_ID",
"muted": true
}Risposte
cURL
curl -s -X PATCH "http://localhost:3000/api/v1/notifications/preferences/channels/CHANNEL_ID"\
-H "content-type: application/json"\
-H "x-agent-api-key: $API_KEY"\
-d '{
"userId": "USER_ID",
"muted": true
}'/api/v1/notifications/subscriptionsRegistra una sottoscrizione push
Corpo della richiesta
application/jsonRegisterPushSubscriptionRequestobbligatorioCampi
{
"userId": "USER_ID",
"endpoint": "https://example.com/resource",
"p256dh": "P256DH_PUBLIC_KEY",
"auth": "AUTH_SECRET"
}Risposte
cURL
curl -s -X POST "http://localhost:3000/api/v1/notifications/subscriptions"\
-H "content-type: application/json"\
-H "x-agent-api-key: $API_KEY"\
-d '{
"userId": "USER_ID",
"endpoint": "https://example.com/resource",
"p256dh": "P256DH_PUBLIC_KEY",
"auth": "AUTH_SECRET"
}'/api/v1/notifications/subscriptions/{subscriptionId}Rimuovi una sottoscrizione push
Parametri path
Parametri query
Risposte
cURL
curl -s -X DELETE "http://localhost:3000/api/v1/notifications/subscriptions/SUBSCRIPTION_ID?userId=USER_ID"\
-H "x-agent-api-key: $API_KEY"/api/v1Scopri la documentazione API e il contratto di autenticazione
Restituisce i link canonici alla documentazione della API pubblica e il contratto dell'header di autenticazione. La discovery endpoint per endpoint vive nel documento OpenAPI, non in questo payload.
Risposte
cURL
curl -s -X GET "http://localhost:3000/api/v1"\
-H "x-agent-api-key: $API_KEY"/api/v1/openapiLeggi la specifica OpenAPI v1
Risposte
cURL
curl -s -X GET "http://localhost:3000/api/v1/openapi"\
-H "x-agent-api-key: $API_KEY"