Documentazione

Modelli 3D

Carica, elenca ed elimina i modelli 3D dell'organizzazione. I binari vivono sullo storage a oggetti; un'anteprima viene generata automaticamente all'upload.

Carichi un modello (binario sullo storage + anteprima generata), poi lo assegni a un viewer che lo scarica e lo mostra.

Modelli 3D

Caricamento, elenco ed eliminazione dei modelli 3D dell'organizzazione. I binari risiedono sul server delle risorse, i metadati nel database locale.

Catalogo e caricamento

Elenca i modelli 3D dell'organizzazione e caricane di nuovi.

GEThttps://api.spectraholo.it/v1/organization/{id}/modelsAuthority ≥ 0 · Lettura

Elenco dei modelli

Recupera un elenco paginato dei modelli 3D appartenenti all'organizzazione. I risultati vengono letti dal database locale.

Autenticazione: Token utente (Bearer) — qualsiasi membro

Parametri del percorso

id* ID dell'organizzazione (numerico, parametro di percorso)

Parametri query

`limit`facolt.	Numero di modelli da restituire (default: 50, max: 150)
`offset`facolt.	Numero di modelli da saltare dall'inizio (base 0, default: 0)

Esempio di richiesta

GET https://api.spectraholo.it/v1/organization/42/models?limit=50&offset=0

Risposta200

{
  "success": true,
  "models": [
    {
      "id": 42,
      "name": "Dragon",
      "description": "Low-poly glTF model"
    },
    {
      "id": 41,
      "name": "Spaceship",
      "description": null
    }
  ]
}

Errori

401Autenticazione mancante o non valida (né token di sessione valido né backend API key corretta)
403Sessione valida ma il livello di authority dell'utente è inferiore a 0 (è principalmente una nota di documentazione; il livello 0 è sempre sufficiente)
502Il server di autenticazione è irraggiungibile durante la validazione della sessione

POSThttps://api.spectraholo.it/v1/organization/{id}/modelsAuthority ≥ 2 · Gestione

Carica un modello 3D

Carica un nuovo modello 3D in un'organizzazione. Il binario del modello viene memorizzato sul server delle risorse, mentre i metadati (nome, descrizione, createdAt) vengono salvati nel database locale. Il caricamento è atomico: se l'inserimento locale fallisce, il binario viene rimosso dal server delle risorse.

Autenticazione: Token utente (Bearer) — authority ≥ 2 (Gestione)

Parametri del percorso

id* ID dell'organizzazione (numerico, parametro di percorso)

Corpo della richiesta · multipart/form-data

`name`* string	Nome del modello (1–128 caratteri)
`description`facolt. string	Descrizione del modello (0–1024 caratteri). Se vuota o omessa, viene memorizzata come null
`model`* binary file	Il file binario del modello 3D (max 1 GiB, Content-Type predefinito: application/octet-stream)

Esempio di richiesta

POST https://api.spectraholo.it/v1/organization/42/models

# Campi del modulo (multipart/form-data)
name        = Dragone
description = Modello glTF low-poly
model       = @dragone.glb

Risposta201

{
  "success": true,
  "model": {
    "id": 42,
    "name": "Dragon",
    "description": "Low-poly glTF model",
    "createdAt": "2026-06-15T10:30:00Z"
  }
}

Errori

400Corpo multipart/form-data non valido, campo 'name' o 'model' mancante, oppure vincoli di lunghezza di name/description violati
401Autenticazione mancante o non valida (né token di sessione valido né backend API key corretta)
403Sessione valida ma il livello di authority dell'utente è inferiore a 2 (AUTHORITY_MANAGE)
404Organizzazione non trovata nel database locale
413Il file del modello supera il limite di 1 GiB (verificato prima del buffering se il Content-Length è dichiarato)
502Il server delle risorse è irraggiungibile o la richiesta fallisce

Eliminazione

Rimuovi un modello 3D dal catalogo e dallo storage.

DELETEhttps://api.spectraholo.it/v1/organization/{id}/models/{modelId}Authority ≥ 2 · Gestione

Elimina un modello 3D

Rimuove un modello 3D dall'organizzazione: elimina i metadati locali e rimuove il binario dal server delle risorse. I viewer che stanno mostrando questo modello passano immediatamente allo stato 'nessun modello' (FK ON DELETE SET NULL) e, se connessi, ricevono in best-effort un comando SHOW NOTHING.

Autenticazione: Token utente (Bearer) — authority ≥ 2 (Gestione)

Parametri del percorso

`id`*	ID dell'organizzazione (intero non negativo in forma canonica: '0' oppure cifre senza zeri iniziali)
`modelId`*	ID del modello dal server delle risorse (intero positivo in forma canonica, >= 1)

Esempio di richiesta

DELETE https://api.spectraholo.it/v1/organization/42/models/42

Risposta200

{
  "success": true,
  "message": "Model successfully deleted!",
  "modelId": 42
}

Errori

400ID dell'organizzazione o del modello non valido nel percorso (forma non canonica o non intero)
401Nessuna autenticazione valida fornita: né backend API key (header x-backend-api-key) né token di sessione valido (Authorization: Bearer)
403Sessione valida ma authority insufficiente dell'utente (livello < 2 MANAGE)
404Organizzazione non trovata o modello non trovato in questa organizzazione
502Il server delle risorse è irraggiungibile o non è riuscito a eliminare il binario del modello
500Errore interno del server (eccezione non gestita)

PrecedenteMembri & utenti SuccessivoViewer