API reference
Endpoints, authentication, parameters and schemas of the implemented contract.
Base URL and authentication
SDKs receive https://ai.puradigital.it/v1 as apiBase. OpenAPI paths already include /v1. Use OAuth tokens for inference and usage; a console session is required for application registration and payments. The client secret is sent in the form body exclusively to the token endpoint.
Formats and responses
JSON for management APIs and chat; URL-encoded form for OAuth exchange; multipart for audio. Some dynamic backend responses do not have a complete schema: guide examples describe their application fields. Consult OAuth, usage and webhook sections for errors and invariants.
Endpoints and schemas
Reference generated from backend routers. Expand an endpoint for accepted fields and schemas.
27 / 27 endpoint
GET/v1/integrations/oauth/authorize
Browser Authorize
OAuth public endpoint; secret in form for confidential clients
[
{
"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"
}
}
]{
"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
Owner account console session
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConsentRequest"
}
}
}
}{
"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
Owner account console session
{
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
}
}POST/v1/integrations/apps
Register App
Owner account console session
{
"201": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
}
}GET/v1/integrations/apps/{client_id}/icon
App Icon
Owner account console session
[
{
"name": "client_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Client Id"
}
}
]{
"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
Owner account console session
[
{
"name": "client_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Client Id"
}
}
]{
"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
Owner account console session
[
{
"name": "client_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Client Id"
}
}
]{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AppState"
}
}
}
}{
"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
Owner account console session
[
{
"name": "client_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Client Id"
}
}
]{
"204": {
"description": "Successful Response"
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}GET/v1/integrations/connections
List Connections
Owner account console session
{
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
}
}PUT/v1/integrations/apps/{client_id}/webhook
Configure Webhook
Owner account console session
[
{
"name": "client_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Client Id"
}
}
]{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookConfiguration"
}
}
}
}{
"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
Owner account console session
[
{
"name": "client_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Client Id"
}
}
]{
"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
Owner account console session
[
{
"name": "client_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Client Id"
}
}
]{
"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
Owner account console session
[
{
"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"
}
}
]{
"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
Owner account console session
[
{
"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"
}
}
]{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookRecovery"
}
}
}
}{
"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
Owner account console session
[
{
"name": "client_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Client Id"
}
}
]{
"204": {
"description": "Successful Response"
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}GET/v1/integrations/oauth/consent
Consent Details
Owner account console session
[
{
"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"
}
}
]{
"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 public endpoint; secret in form for confidential clients
{
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"$ref": "#/components/schemas/Body_token_v1_integrations_oauth_token_post"
}
}
},
"required": true
}{
"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
OAuth bearer; inference or usage:read scope depending on endpointusage:read
{
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
}
}POST/v1/integrations/inference/audio/transcriptions
Transcribe
OAuth bearer; inference or usage:read scope depending on endpointinference
{
"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"
]
}
}
}
}{
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
}
}GET/v1/integrations/inference/capabilities
Capabilities
OAuth bearer; inference or usage:read scope depending on endpointinference
{
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InferenceCapabilities"
}
}
}
}
}POST/v1/integrations/inference/chat/completions
Chat
OAuth bearer; inference or usage:read scope depending on endpointinference
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChatRequest"
}
}
},
"required": true
}{
"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
Owner account console session
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CheckoutConfirmation"
}
}
},
"required": true
}{
"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
Owner account console session
{
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
}
}POST/v1/subscriptions/checkout
Checkout
Owner account console session
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CheckoutRequest"
}
}
},
"required": true
}{
"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
Owner account console session
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PortalRequest"
}
}
},
"required": true
}{
"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
Public
{
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
}
}GET/v1/subscriptions/usage
Usage
Owner account console session
{
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
}
}Schema definitions
AppState
{
"properties": {
"active": {
"type": "boolean",
"title": "Active"
}
},
"type": "object",
"required": [
"active"
],
"title": "AppState"
}Body_token_v1_integrations_oauth_token_post
{
"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
{
"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
{
"properties": {
"session_id": {
"type": "string",
"maxLength": 255,
"minLength": 1,
"title": "Session Id"
}
},
"type": "object",
"required": [
"session_id"
],
"title": "CheckoutConfirmation"
}CheckoutRequest
{
"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"
}
},
"type": "object",
"required": [
"plan_id",
"success_url",
"cancel_url"
],
"title": "CheckoutRequest"
}ConsentRequest
{
"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
{
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}InferenceCapabilities
{
"properties": {
"object": {
"type": "string",
"const": "capabilities",
"title": "Object",
"default": "capabilities"
},
"services": {
"$ref": "#/components/schemas/ServiceCapabilities"
}
},
"type": "object",
"required": [
"services"
],
"title": "InferenceCapabilities"
}PortalRequest
{
"properties": {
"return_url": {
"type": "string",
"maxLength": 2048,
"title": "Return Url"
}
},
"type": "object",
"required": [
"return_url"
],
"title": "PortalRequest"
}ServiceCapabilities
{
"properties": {
"chat": {
"type": "boolean",
"title": "Chat"
},
"audio_transcription": {
"type": "boolean",
"title": "Audio Transcription"
}
},
"type": "object",
"required": [
"chat",
"audio_transcription"
],
"title": "ServiceCapabilities"
}ValidationError
{
"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
{
"properties": {
"url": {
"type": "string",
"maxLength": 2048,
"minLength": 1,
"title": "Url"
}
},
"type": "object",
"required": [
"url"
],
"title": "WebhookConfiguration"
}WebhookRecovery
{
"properties": {
"action": {
"type": "string",
"enum": [
"retry",
"skip"
],
"title": "Action"
}
},
"type": "object",
"required": [
"action"
],
"title": "WebhookRecovery"
}