SDK in abbonamento
OAuth per utente · limiti del piano condivisi tra le app · modello gestito da Pura.
Cerchi le API a consumo?Riferimento API
Endpoint, autenticazione, parametri e schemi del contratto implementato.
Base URL e autenticazione
Gli SDK ricevono https://ai.puradigital.it/v1 come apiBase. Nei path OpenAPI /v1 è già incluso. Usa token OAuth per l’inferenza e usage; la sessione della console è richiesta per registrazione delle app e pagamenti. Il client secret è inviato nel body form esclusivamente al token endpoint.
Formati e risposte
Usa JSON per gestione delle app e chat, form URL-encoded per lo scambio OAuth e multipart/form-data per l’audio. Apri un endpoint per consultare parametri e schemi; le guide OAuth, consumo e webhook spiegano il significato dei campi e gli errori da gestire.
Endpoint e schemi
Apri un endpoint per consultare autenticazione, parametri e schemi delle richieste e delle risposte.
27 / 27 endpoint
GET/v1/integrations/oauth/authorize
Browser Authorize
OAuth: endpoint pubblico; secret nel form per client confidential
Parametri path e query
[
{
"name": "client_id",
"in": "query",
"required": true,
"schema": {
"type": "string",
"title": "Client Id"
}
},
{
"name": "redirect_uri",
"in": "query",
"required": true,
"schema": {
"type": "string",
"title": "Redirect Uri"
}
},
{
"name": "code_challenge",
"in": "query",
"required": true,
"schema": {
"type": "string",
"title": "Code Challenge"
}
},
{
"name": "state",
"in": "query",
"required": true,
"schema": {
"type": "string",
"minLength": 16,
"maxLength": 512,
"title": "State"
}
},
{
"name": "scope",
"in": "query",
"required": false,
"schema": {
"type": "string",
"default": "inference usage:read",
"title": "Scope"
}
},
{
"name": "response_type",
"in": "query",
"required": false,
"schema": {
"const": "code",
"type": "string",
"default": "code",
"title": "Response Type"
}
},
{
"name": "code_challenge_method",
"in": "query",
"required": false,
"schema": {
"const": "S256",
"type": "string",
"default": "S256",
"title": "Code Challenge Method"
}
},
{
"name": "locale",
"in": "query",
"required": false,
"schema": {
"enum": [
"it",
"en"
],
"type": "string",
"default": "it",
"title": "Locale"
}
}
]Risposte e riferimenti agli schemi
{
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}POST/v1/integrations/oauth/authorize
Authorize
Sessione console dell’account proprietario
Body della richiesta
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConsentRequest"
}
}
}
}Risposte e riferimenti agli schemi
{
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}GET/v1/integrations/apps
List Apps
Sessione console dell’account proprietario
Risposte e riferimenti agli schemi
{
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
}
}POST/v1/integrations/apps
Register App
Sessione console dell’account proprietario
Risposte e riferimenti agli schemi
{
"201": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
}
}GET/v1/integrations/apps/{client_id}/icon
App Icon
Sessione console dell’account proprietario
Parametri path e query
[
{
"name": "client_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Client Id"
}
}
]Risposte e riferimenti agli schemi
{
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}POST/v1/integrations/apps/{client_id}/rotate-secret
Rotate App Secret
Sessione console dell’account proprietario
Parametri path e query
[
{
"name": "client_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Client Id"
}
}
]Risposte e riferimenti agli schemi
{
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}PATCH/v1/integrations/apps/{client_id}
Update App State
Sessione console dell’account proprietario
Parametri path e query
[
{
"name": "client_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Client Id"
}
}
]Body della richiesta
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AppState"
}
}
}
}Risposte e riferimenti agli schemi
{
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}DELETE/v1/integrations/apps/{client_id}
Delete App
Sessione console dell’account proprietario
Parametri path e query
[
{
"name": "client_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Client Id"
}
}
]Risposte e riferimenti agli schemi
{
"204": {
"description": "Successful Response"
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}GET/v1/integrations/connections
List Connections
Sessione console dell’account proprietario
Risposte e riferimenti agli schemi
{
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
}
}PUT/v1/integrations/apps/{client_id}/webhook
Configure Webhook
Sessione console dell’account proprietario
Parametri path e query
[
{
"name": "client_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Client Id"
}
}
]Body della richiesta
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookConfiguration"
}
}
}
}Risposte e riferimenti agli schemi
{
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}GET/v1/integrations/apps/{client_id}/webhook
Get Webhook
Sessione console dell’account proprietario
Parametri path e query
[
{
"name": "client_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Client Id"
}
}
]Risposte e riferimenti agli schemi
{
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}POST/v1/integrations/apps/{client_id}/webhook/test
Test Webhook
Sessione console dell’account proprietario
Parametri path e query
[
{
"name": "client_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Client Id"
}
}
]Risposte e riferimenti agli schemi
{
"202": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}GET/v1/integrations/apps/{client_id}/webhook/events
Webhook Events
Sessione console dell’account proprietario
Parametri path e query
[
{
"name": "client_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Client Id"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"default": 50,
"title": "Limit"
}
}
]Risposte e riferimenti agli schemi
{
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}POST/v1/integrations/apps/{client_id}/webhook/events/{event_id}/recover
Recover Webhook
Sessione console dell’account proprietario
Parametri path e query
[
{
"name": "client_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Client Id"
}
},
{
"name": "event_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Event Id"
}
}
]Body della richiesta
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookRecovery"
}
}
}
}Risposte e riferimenti agli schemi
{
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}DELETE/v1/integrations/connections/{client_id}
Disconnect
Sessione console dell’account proprietario
Parametri path e query
[
{
"name": "client_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Client Id"
}
}
]Risposte e riferimenti agli schemi
{
"204": {
"description": "Successful Response"
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}GET/v1/integrations/oauth/consent
Consent Details
Sessione console dell’account proprietario
Parametri path e query
[
{
"name": "client_id",
"in": "query",
"required": true,
"schema": {
"type": "string",
"title": "Client Id"
}
},
{
"name": "redirect_uri",
"in": "query",
"required": true,
"schema": {
"type": "string",
"title": "Redirect Uri"
}
},
{
"name": "scope",
"in": "query",
"required": true,
"schema": {
"type": "string",
"title": "Scope"
}
},
{
"name": "code_challenge",
"in": "query",
"required": true,
"schema": {
"type": "string",
"title": "Code Challenge"
}
},
{
"name": "code_challenge_method",
"in": "query",
"required": true,
"schema": {
"const": "S256",
"type": "string",
"title": "Code Challenge Method"
}
}
]Risposte e riferimenti agli schemi
{
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}POST/v1/integrations/oauth/token
Token
OAuth: endpoint pubblico; secret nel form per client confidential
Body della richiesta
{
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"$ref": "#/components/schemas/Body_token_v1_integrations_oauth_token_post"
}
}
},
"required": true
}Risposte e riferimenti agli schemi
{
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}GET/v1/integrations/usage
Integration Usage
Bearer OAuth; scope inference o usage:read secondo l’endpointusage:read
Risposte e riferimenti agli schemi
{
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
}
}POST/v1/integrations/inference/audio/transcriptions
Transcribe
Bearer OAuth; scope inference o usage:read secondo l’endpointinference
Body della richiesta
{
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"additionalProperties": false,
"properties": {
"language": {
"anyOf": [
{
"pattern": "^[a-z]{2}$",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Language"
},
"prompt": {
"anyOf": [
{
"maxLength": 4000,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Prompt"
},
"temperature": {
"anyOf": [
{
"maximum": 1,
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Temperature"
},
"response_format": {
"default": "json",
"enum": [
"json",
"verbose_json"
],
"title": "Response Format",
"type": "string"
},
"file": {
"type": "string",
"format": "binary",
"description": "One nonempty audio file, at most 25,000,000 bytes."
}
},
"title": "TranscriptionFields",
"type": "object",
"required": [
"file"
]
}
}
}
}Risposte e riferimenti agli schemi
{
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
}
}GET/v1/integrations/inference/capabilities
Capabilities
Bearer OAuth; scope inference o usage:read secondo l’endpointinference
Risposte e riferimenti agli schemi
{
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InferenceCapabilities"
}
}
}
}
}POST/v1/integrations/inference/chat/completions
Chat
Bearer OAuth; scope inference o usage:read secondo l’endpointinference
Body della richiesta
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChatRequest"
}
}
},
"required": true
}Risposte e riferimenti agli schemi
{
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}POST/v1/subscriptions/checkout/confirm
Confirm
Sessione console dell’account proprietario
Body della richiesta
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CheckoutConfirmation"
}
}
},
"required": true
}Risposte e riferimenti agli schemi
{
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}GET/v1/subscriptions
Current Subscription
Sessione console dell’account proprietario
Risposte e riferimenti agli schemi
{
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
}
}POST/v1/subscriptions/checkout
Checkout
Sessione console dell’account proprietario
Body della richiesta
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CheckoutRequest"
}
}
},
"required": true
}Risposte e riferimenti agli schemi
{
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}POST/v1/subscriptions/portal
Portal
Sessione console dell’account proprietario
Body della richiesta
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PortalRequest"
}
}
},
"required": true
}Risposte e riferimenti agli schemi
{
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}GET/v1/subscriptions/plans
Plans
Pubblico
Risposte e riferimenti agli schemi
{
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
}
}GET/v1/subscriptions/usage
Usage
Sessione console dell’account proprietario
Risposte e riferimenti agli schemi
{
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
}
}Definizioni degli schemi
AppState
json
{
"properties": {
"active": {
"type": "boolean",
"title": "Active"
}
},
"type": "object",
"required": [
"active"
],
"title": "AppState"
}Body_token_v1_integrations_oauth_token_post
json
{
"properties": {
"grant_type": {
"type": "string",
"title": "Grant Type"
},
"client_id": {
"type": "string",
"title": "Client Id"
},
"client_secret": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Client Secret"
},
"code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Code"
},
"redirect_uri": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Redirect Uri"
},
"code_verifier": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Code Verifier"
},
"refresh_token": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Refresh Token"
}
},
"type": "object",
"required": [
"grant_type",
"client_id"
],
"title": "Body_token_v1_integrations_oauth_token_post"
}ChatRequest
json
{
"properties": {
"messages": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array",
"minItems": 1,
"title": "Messages"
},
"stream": {
"type": "boolean",
"title": "Stream",
"default": false
},
"stream_options": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Stream Options"
},
"temperature": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Temperature"
},
"top_p": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Top P"
},
"max_tokens": {
"anyOf": [
{
"type": "integer",
"exclusiveMinimum": 0
},
{
"type": "null"
}
],
"title": "Max Tokens"
},
"max_completion_tokens": {
"anyOf": [
{
"type": "integer",
"exclusiveMinimum": 0
},
{
"type": "null"
}
],
"title": "Max Completion Tokens"
},
"stop": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Stop"
},
"tools": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tools"
},
"tool_choice": {
"anyOf": [
{
"type": "string"
},
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Tool Choice"
},
"parallel_tool_calls": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Parallel Tool Calls"
},
"response_format": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Response Format"
},
"reasoning_effort": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Reasoning Effort"
},
"seed": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Seed"
},
"presence_penalty": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Presence Penalty"
},
"frequency_penalty": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Frequency Penalty"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"messages"
],
"title": "ChatRequest"
}CheckoutConfirmation
json
{
"properties": {
"session_id": {
"type": "string",
"maxLength": 255,
"minLength": 1,
"title": "Session Id"
}
},
"type": "object",
"required": [
"session_id"
],
"title": "CheckoutConfirmation"
}CheckoutRequest
json
{
"properties": {
"plan_id": {
"type": "string",
"title": "Plan Id"
},
"success_url": {
"type": "string",
"maxLength": 2048,
"title": "Success Url"
},
"cancel_url": {
"type": "string",
"maxLength": 2048,
"title": "Cancel Url"
},
"target_employee_id": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "null"
}
],
"title": "Target Employee Id"
}
},
"type": "object",
"required": [
"plan_id",
"success_url",
"cancel_url"
],
"title": "CheckoutRequest"
}ConsentRequest
json
{
"properties": {
"client_id": {
"type": "string",
"title": "Client Id"
},
"redirect_uri": {
"type": "string",
"maxLength": 2048,
"title": "Redirect Uri"
},
"scope": {
"type": "string",
"title": "Scope",
"default": "inference usage:read"
},
"code_challenge": {
"type": "string",
"title": "Code Challenge"
},
"code_challenge_method": {
"type": "string",
"const": "S256",
"title": "Code Challenge Method"
},
"state": {
"type": "string",
"maxLength": 512,
"minLength": 16,
"title": "State"
},
"approved": {
"type": "boolean",
"title": "Approved"
}
},
"type": "object",
"required": [
"client_id",
"redirect_uri",
"code_challenge",
"code_challenge_method",
"state",
"approved"
],
"title": "ConsentRequest"
}HTTPValidationError
json
{
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}InferenceCapabilities
json
{
"properties": {
"object": {
"type": "string",
"const": "capabilities",
"title": "Object",
"default": "capabilities"
},
"services": {
"$ref": "#/components/schemas/ServiceCapabilities"
}
},
"type": "object",
"required": [
"services"
],
"title": "InferenceCapabilities"
}PortalRequest
json
{
"properties": {
"return_url": {
"type": "string",
"maxLength": 2048,
"title": "Return Url"
}
},
"type": "object",
"required": [
"return_url"
],
"title": "PortalRequest"
}ServiceCapabilities
json
{
"properties": {
"chat": {
"type": "boolean",
"title": "Chat"
},
"audio_transcription": {
"type": "boolean",
"title": "Audio Transcription"
}
},
"type": "object",
"required": [
"chat",
"audio_transcription"
],
"title": "ServiceCapabilities"
}ValidationError
json
{
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
}WebhookConfiguration
json
{
"properties": {
"url": {
"type": "string",
"maxLength": 2048,
"minLength": 1,
"title": "Url"
}
},
"type": "object",
"required": [
"url"
],
"title": "WebhookConfiguration"
}WebhookRecovery
json
{
"properties": {
"action": {
"type": "string",
"enum": [
"retry",
"skip"
],
"title": "Action"
}
},
"type": "object",
"required": [
"action"
],
"title": "WebhookRecovery"
}