MercatoEsploraProvalo
Prezzi
AccediInizia
Sviluppatori

Riferimento API

Ogni endpoint qui accetta JSON su HTTPS e una chiave API nell’header Authorization. Una chiave funziona in un solo spazio di lavoro e raggiunge solo gli endpoint consentiti dai suoi permessi.

Aggiornata il 1 ottobre 2026

Documentazione per sviluppatori

  • Panoramica
  • MCP e assistenti IA
  • Riferimento API
  • Chiavi API e permessi

In questa pagina

URL di base e autenticazioneSpazio di lavoroBrandDesignCaricamentiVideo, audio e sottotitoliMarkIl DesignerErroriLimiti di frequenzaPaginazione

L’API è la stessa che usa l’app di Gradiently, quindi una chiave vede gli stessi dati e supera gli stessi controlli che supererebbe chi l’ha creata nell’app, limitata a un solo spazio di lavoro e ai suoi permessi. Una chiave che chiama un endpoint non coperto da nessuno dei suoi permessi riceve un 403.

URL di base e autenticazione

Tutti i percorsi qui sotto si trovano sotto https://gradiently.design. Invia la tua chiave come token bearer con ogni richiesta. I corpi sono JSON con Content-Type: application/json, tranne i caricamenti.

bash
curl https://gradiently.design/api/marks/mine \
  -H "Authorization: Bearer gr_live_…"
  • Una chiave è sempre legata allo spazio di lavoro in cui è stata creata. Non devi indicare lo spazio di lavoro; se invii X-Workspace o ?workspace=, deve essere quello della chiave, altrimenti la richiesta fallisce con 403.
  • I corpi delle richieste vengono controllati in modo rigoroso: un campo che l’endpoint non conosce fallisce con 422.
  • Le risposte sono JSON salvo dove indicato (immagini, reindirizzamenti e il flusso del Designer). I messaggi di errore per le chiavi API sono in inglese.
  • Una chiave agisce come chi l’ha creata. I design e i brand che crea appartengono allo spazio di lavoro; i Mark che riserva appartengono a chi l’ha creata.

Spazio di lavoro

GET/api/me

Permesso

workspaces:read e designs:read

Cosa fa

Tu, lo spazio di lavoro della chiave e i suoi brand.
GET/api/workspaces

Permesso

workspaces:read

Cosa fa

Lo spazio di lavoro della chiave e il tuo ruolo.
GET/api/workspaces/:id

Permesso

workspaces:read

Cosa fa

Un solo spazio di lavoro.
GET/api/workspaces/:id/members

Permesso

workspaces:read

Cosa fa

I membri con nome, email e ruolo.
GET/api/workspaces/:id/audit

Permesso

workspaces:read

Cosa fa

Il registro attività dello spazio di lavoro.
POST/api/workspaces/:id/invites

Permesso

members:write

Cosa fa

Invia via email un invito valido sette giorni.
MetodoPercorsoPermessoCosa fa
GET/api/meworkspaces:read e designs:readTu, lo spazio di lavoro della chiave e i suoi brand.
GET/api/workspacesworkspaces:readLo spazio di lavoro della chiave e il tuo ruolo.
GET/api/workspaces/:idworkspaces:readUn solo spazio di lavoro.
GET/api/workspaces/:id/membersworkspaces:readI membri con nome, email e ruolo.
GET/api/workspaces/:id/auditworkspaces:readIl registro attività dello spazio di lavoro.
POST/api/workspaces/:id/invitesmembers:writeInvia via email un invito valido sette giorni.
json
GET /api/me

{
  "viewer": { "id": "…", "name": "Ada Moss", "handle": "ada", "workspaceId": "…" },
  "workspaces": [{ "id": "…", "name": "Hearth", "role": "owner" }],
  "activeWorkspaceId": "…",
  "personalities": [{ "id": "…", "slug": "hearth", "name": "Hearth", "markId": "…" }]
}
Abbreviato. Nell’API i brand si chiamano personalities.
json
POST /api/workspaces/:id/invites
{ "email": "sam@example.com", "role": "editor" }

{ "id": "…", "expiresInDays": 7 }
role è admin, editor o viewer. La persona deve verificare lo stesso indirizzo email prima di accettare.

Brand

GET/api/personalities

Permesso

designs:read

Cosa fa

I brand dello spazio di lavoro, come { items }.
POST/api/personalities

Permesso

personalities:write

Cosa fa

Crea un brand.
PATCH/api/personalities/:id

Permesso

personalities:write

Cosa fa

Rinomina un brand, ne imposta il Mark, il profilo o lo stile.
DELETE/api/personalities/:id

Permesso

personalities:write

Cosa fa

Elimina un brand e i suoi design. Uno spazio di lavoro ne mantiene almeno uno.
GET/api/personalities/:id/designs

Permesso

designs:read

Cosa fa

I design di un brand, dal più recente.
GET/api/personalities/:id/brand

Permesso

designs:read

Cosa fa

I font, i loghi e i colori salvati di un brand. Una chiave può leggerli, mai modificarli.
MetodoPercorsoPermessoCosa fa
GET/api/personalitiesdesigns:readI brand dello spazio di lavoro, come { items }.
POST/api/personalitiespersonalities:writeCrea un brand.
PATCH/api/personalities/:idpersonalities:writeRinomina un brand, ne imposta il Mark, il profilo o lo stile.
DELETE/api/personalities/:idpersonalities:writeElimina un brand e i suoi design. Uno spazio di lavoro ne mantiene almeno uno.
GET/api/personalities/:id/designsdesigns:readI design di un brand, dal più recente.
GET/api/personalities/:id/branddesigns:readI font, i loghi e i colori salvati di un brand. Una chiave può leggerli, mai modificarli.
json
POST /api/personalities
{ "name": "Hearth Bakery", "markId": "…" }

PATCH /api/personalities/:id
{ "profile": { "about": "A neighbourhood bakery", "voice": "warm, plain" } }

{ "id": "…", "slug": "hearth-bakery", "name": "Hearth Bakery", "markId": "…", "profile": { … } }
markId alla creazione è facoltativo. Un profilo può contenere anche audience, uses, keywords, dos, donts, website, handle e fonts.

L’elenco dei design accetta ?q= per cercare nei titoli e ?mark= per filtrare per Mark. Ogni elemento ha id, personalityId, markId, title, form, thumb, shared e updatedAt, senza il documento.

Design

POST/api/agent/compose

Permesso

designs:write

Cosa fa

Impagina i testi, rielabora un modello o applica modifiche, e salva.
POST/api/designs

Permesso

designs:write

Cosa fa

Crea un design da un documento.
GET/api/designs/:id

Permesso

designs:read

Cosa fa

Un design con il suo documento.
PATCH/api/designs/:id

Permesso

designs:write

Cosa fa

Ne cambia il titolo, il documento, il Mark o la condivisione.
DELETE/api/designs/:id

Permesso

designs:write

Cosa fa

Elimina un design.
POST/api/designs/:id/duplicate

Permesso

designs:write

Cosa fa

Ne salva una copia accanto.
GET/api/designs/:id/thumb

Permesso

designs:read

Cosa fa

La sua immagine in miniatura.
POST/api/designs/:id/render

Permesso

designs:read

Cosa fa

Lo genera in PNG o PDF.
MetodoPercorsoPermessoCosa fa
POST/api/agent/composedesigns:writeImpagina i testi, rielabora un modello o applica modifiche, e salva.
POST/api/designsdesigns:writeCrea un design da un documento.
GET/api/designs/:iddesigns:readUn design con il suo documento.
PATCH/api/designs/:iddesigns:writeNe cambia il titolo, il documento, il Mark o la condivisione.
DELETE/api/designs/:iddesigns:writeElimina un design.
POST/api/designs/:id/duplicatedesigns:writeNe salva una copia accanto.
GET/api/designs/:id/thumbdesigns:readLa sua immagine in miniatura.
POST/api/designs/:id/renderdesigns:readLo genera in PNG o PDF.

Il modo più semplice per creare un design da codice è POST /api/agent/compose: descrivi il contenuto e il motore di impaginazione lo posiziona con il Mark del brand. Lo stesso endpoint rielabora un modello (template con text, photos, icons, hide) oppure, con designId e ops, modifica un design salvato.

json
POST /api/agent/compose
{
  "personalityId": "…",
  "composition": {
    "size": "ig-post",
    "layout": "statement",
    "blocks": [
      { "role": "headline", "text": "Fresh bread from 7am" },
      { "role": "cta", "text": "Visit us" }
    ]
  }
}

{ "id": "…", "url": "/studio/…", "issues": [ … ], "elements": [ … ] }
issues elenca cosa ha trovato la verifica (margini, sovrapposizioni, gerarchia, contrasto).
json
POST /api/designs
{
  "personalityId": "…",
  "form": "blank",
  "title": "Launch post",
  "doc": { "ratio": "custom", "width": 1080, "height": 1350, "shift": [0.5, 0.5, 0.5, 0.5], "elements": [] }
}

{ "id": "…", "personalityId": "…", "markId": null, "title": "Launch post", "form": "blank", "doc": { … }, "updatedAt": "…", "thumb": null, "shared": false }
markId è facoltativo; senza, il design usa il Mark del brand. Leggi un design da GET /api/designs/:id per vedere un documento completo.

PATCH /api/designs/:id accetta uno qualsiasi tra title, doc, markId e shared. Impostare shared a true pubblica un link di visualizzazione su /d/:id. Invia baseUpdatedAt, l’ultimo updatedAt che hai letto, per far rifiutare il salvataggio con 409 se qualcuno ha cambiato il design nel frattempo.

json
POST /api/designs/:id/render
{ "width": 1080, "height": 1350, "format": "png", "page": 0 }

{ "id": "…", "data": "iVBORw0KGgo…", "encoding": "base64", "mimeType": "image/png", "width": 1080, "height": 1350, "pages": 1 }
Larghezza e altezza vanno da 1 a 4096. page parte da 0; un PDF senza page contiene tutte le pagine, ciascuna al suo formato nello Studio, a cui la richiesta deve corrispondere. Prevedi fino a tre minuti.

La generazione richiede la stessa licenza di esportazione per il Mark del design richiesta dallo Studio; senza, la risposta è 402. La generazione non pubblica mai il design né archivia un file.

Caricamenti

POST/api/uploads

Permesso

designs:write

Cosa fa

Carica un’immagine per i design.
GET/api/uploads

Permesso

designs:read

Cosa fa

I caricamenti dello spazio di lavoro, dal più recente.
GET/api/uploads/:id

Permesso

designs:read

Cosa fa

Reindirizza all’immagine. ?w= chiede una larghezza.
DELETE/api/uploads/:id

Permesso

designs:write

Cosa fa

Elimina uno dei tuoi caricamenti.
MetodoPercorsoPermessoCosa fa
POST/api/uploadsdesigns:writeCarica un’immagine per i design.
GET/api/uploadsdesigns:readI caricamenti dello spazio di lavoro, dal più recente.
GET/api/uploads/:iddesigns:readReindirizza all’immagine. ?w= chiede una larghezza.
DELETE/api/uploads/:iddesigns:writeElimina uno dei tuoi caricamenti.
bash
curl https://gradiently.design/api/uploads \
  -H "Authorization: Bearer $GRADIENTLY_API_KEY" \
  -F "file=@shopfront.jpg;type=image/jpeg"

# { "id": "…", "url": "/api/uploads/…" }
Un solo file nel campo file: PNG, JPEG, WebP, GIF o AVIF, al massimo 8 MB, con un tipo che corrisponde al contenuto. Usa l’url restituito come src di un’immagine o come foto di un modello.

Video, audio e sottotitoli

Carica video e audio nel campo multipart file di POST /api/media. I limiti sono 100 MB per i video, 25 MB per l’audio e un’ora per sorgente. La risposta include l’url privata e la duration verificata. GET /api/media elenca i contenuti multimediali dello spazio di lavoro; GET /api/media/:id/metadata verifica i metadati reali. La lettura richiede designs:read; il caricamento e l’eliminazione richiedono designs:write.

Mark

GET/api/marks

Permesso

marks:read

Cosa fa

Cerca nel Mercato.
GET/api/marks/:code

Permesso

marks:read

Cosa fa

Un Mark con la sua ricetta, per codice o id.
GET/api/marks/mine

Permesso

marks:read

Cosa fa

I Mark riservati per lo spazio di lavoro, e le tue bozze al suo interno.
POST/api/agent/mark

Permesso

marks:read

Cosa fa

Costruisce o modifica una ricetta e la verifica. Non salva nulla.
POST/api/marks

Permesso

brand:generate

Cosa fa

Salva una ricetta come Mark in bozza.
PATCH/api/marks/:id

Permesso

brand:generate

Cosa fa

Modifica una bozza che hai creato.
POST/api/marks/:code/claim

Permesso

marks:claim

Cosa fa

Riserva un Mark disponibile.
POST/api/marks/:code/buy

Permesso

marks:claim

Cosa fa

Riserva un Mark che un altro titolare ha messo in vendita.
MetodoPercorsoPermessoCosa fa
GET/api/marksmarks:readCerca nel Mercato.
GET/api/marks/:codemarks:readUn Mark con la sua ricetta, per codice o id.
GET/api/marks/minemarks:readI Mark riservati per lo spazio di lavoro, e le tue bozze al suo interno.
POST/api/agent/markmarks:readCostruisce o modifica una ricetta e la verifica. Non salva nulla.
POST/api/marksbrand:generateSalva una ricetta come Mark in bozza.
PATCH/api/marks/:idbrand:generateModifica una bozza che hai creato.
POST/api/marks/:code/claimmarks:claimRiserva un Mark disponibile.
POST/api/marks/:code/buymarks:claimRiserva un Mark che un altro titolare ha messo in vendita.

GET /api/marks accetta q (nome o codice), tone (dark o light), material, status (listed, house o sale) e cursor. Risponde { "items": [ … ], "nextCursor": "…" } con 24 Mark per pagina. Un Mark ha id, code, name, recipe, status, creator, holder e createdAt.

Una riserva viene fatta per chi ha creato la chiave, mai per lo spazio di lavoro. Le riserve gratuite, e quelle coperte da un credito di riserva, si completano subito. Una riserva che richiede un pagamento risponde 402 con checkout: true, e buy risponde 409 con checkout: true; completale in Gradiently, perché una chiave non può pagare. buy accetta { "priceCents": … }, il prezzo di vendita che hai visto, e fallisce con 409 se è cambiato.

Il Designer

POST/api/agent

Permesso

designs:write

Cosa fa

Un turno del Designer, in streaming come JSON delimitato da a capo.
POST/api/batches

Permesso

designs:write

Cosa fa

Avvia una serie di design da un solo brief.
GET/api/batches

Permesso

designs:read

Cosa fa

Le tue serie, in corso e recenti.
GET/api/batches/:id

Permesso

designs:read

Cosa fa

L’avanzamento di una serie.
DELETE/api/batches/:id

Permesso

designs:write

Cosa fa

Ferma una serie. I design già disegnati restano.
GET/api/agent/runs?designId=

Permesso

designs:read

Cosa fa

I turni del Designer ancora in corso per un design.
DELETE/api/agent/runs/:id

Permesso

designs:write

Cosa fa

Ferma un turno in corso.
MetodoPercorsoPermessoCosa fa
POST/api/agentdesigns:writeUn turno del Designer, in streaming come JSON delimitato da a capo.
POST/api/batchesdesigns:writeAvvia una serie di design da un solo brief.
GET/api/batchesdesigns:readLe tue serie, in corso e recenti.
GET/api/batches/:iddesigns:readL’avanzamento di una serie.
DELETE/api/batches/:iddesigns:writeFerma una serie. I design già disegnati restano.
GET/api/agent/runs?designId=designs:readI turni del Designer ancora in corso per un design.
DELETE/api/agent/runs/:iddesigns:writeFerma un turno in corso.
json
POST /api/batches
{
  "personalityId": "…",
  "see": false,
  "plan": {
    "brief": "Autumn menu launch, Saturday 4 October",
    "items": [
      { "size": "ig-post", "brief": "The announcement" },
      { "size": "ig-story", "brief": "Three new loaves, one line each" }
    ]
  }
}

{ "id": "…", "state": "running", "items": [{ "index": 0, "title": "…", "state": "…" }] }
Fino a dodici elementi. Interroga GET /api/batches/:id; ogni elemento riceve un designId e un url una volta salvato. state termina come done, stopped o failed.

Il Designer consuma i crediti IA dello spazio di lavoro. Quando il saldo è inferiore a quanto richiede un turno, /api/agent e /api/batches rispondono 402 con code: "credits". Al massimo due serie per persona vengono eseguite insieme. Lo strumento design in MCP e assistenti IA legge il flusso del Designer e salva il risultato per te, il che è più semplice che gestire il flusso da solo.

Errori

Un errore risponde con un codice di stato e un corpo JSON con un messaggio error leggibile. Alcuni aggiungono campi, indicati qui sotto. L’unica eccezione è /api/mcp: un corpo che non è JSON valido risponde 400 con un oggetto di errore JSON-RPC al suo posto, { "jsonrpc": "2.0", "id": null, "error": { "code": -32700, "message": "Parse error" } }.

json
{ "error": "API key lacks required scope for this endpoint." }
401

Quando

Nessuna chiave, una chiave malformata, oppure una chiave revocata o il cui creatore non è più proprietario o amministratore.
402

Quando

Serve un pagamento o un credito: una riserva a pagamento (checkout: true), nessuna licenza di esportazione, o crediti IA insufficienti (code: "credits").
403

Quando

Alla chiave manca un permesso, appartiene a un altro spazio di lavoro, oppure il ruolo di chi l’ha creata non consente l’azione.
404

Quando

L’elemento non esiste o la chiave non può vederlo.
409

Quando

Un conflitto: l’elemento è cambiato da quando l’hai letto, un nome è già in uso, oppure l’azione richiede il checkout.
422

Quando

La richiesta non ha superato la validazione. Il messaggio indica quale campo e perché.
429

Quando

Troppe richieste. Attendi i secondi indicati in Retry-After e riprova.
503

Quando

Occupato o temporaneamente non disponibile, ad esempio il Designer o le esportazioni. Rispetta Retry-After.
504

Quando

Una generazione ha richiesto troppo tempo. Prova un formato più piccolo o una sola pagina.
StatoQuando
401Nessuna chiave, una chiave malformata, oppure una chiave revocata o il cui creatore non è più proprietario o amministratore.
402Serve un pagamento o un credito: una riserva a pagamento (checkout: true), nessuna licenza di esportazione, o crediti IA insufficienti (code: "credits").
403Alla chiave manca un permesso, appartiene a un altro spazio di lavoro, oppure il ruolo di chi l’ha creata non consente l’azione.
404L’elemento non esiste o la chiave non può vederlo.
409Un conflitto: l’elemento è cambiato da quando l’hai letto, un nome è già in uso, oppure l’azione richiede il checkout.
422La richiesta non ha superato la validazione. Il messaggio indica quale campo e perché.
429Troppe richieste. Attendi i secondi indicati in Retry-After e riprova.
503Occupato o temporaneamente non disponibile, ad esempio il Designer o le esportazioni. Rispetta Retry-After.
504Una generazione ha richiesto troppo tempo. Prova un formato più piccolo o una sola pagina.

Limiti di frequenza

I limiti si contano su una finestra mobile di un minuto, salvo dove indicato. Superarli dà una risposta 429 con un header Retry-After in secondi e un campo retryAfter nel corpo. Rallenta e riprova dopo quel tempo; non riprovare subito.

Ogni richiesta con una chiave

Quota

120 al minuto per chiave
Scritture (POST, PATCH, DELETE)

Quota

90 al minuto per account, condivisi con l’app
Generazioni

Quota

10 al minuto per account
Nuovi design e duplicati

Quota

60 al minuto per account
Caricamenti

Quota

60 al minuto per account
Riserve

Quota

20 ogni dieci minuti e 100 al giorno per account
Inviti

Quota

30 all’ora per account
LimiteQuota
Ogni richiesta con una chiave120 al minuto per chiave
Scritture (POST, PATCH, DELETE)90 al minuto per account, condivisi con l’app
Generazioni10 al minuto per account
Nuovi design e duplicati60 al minuto per account
Caricamenti60 al minuto per account
Riserve20 ogni dieci minuti e 100 al giorno per account
Inviti30 all’ora per account

Le esportazioni e il Designer hanno anche una capacità condivisa. Quando è piena la risposta è 503 o 429 con Retry-After, anche se sei entro i tuoi limiti. Tramite MCP, una chiamata a uno strumento conta una volta per la richiesta MCP e una volta per ogni richiesta API fatta dallo strumento.

Paginazione

Gli elenchi restituiscono una pagina alla volta. Chiedi la pagina successiva con ?cursor=.

  • Ricerca nel Mercato (/api/marks): 24 per pagina. Passa il nextCursor della risposta; è null nell’ultima pagina.
  • Versioni dei Mark: passa il valore next della risposta; è null nell’ultima pagina.
  • Design di un brand: 100 per pagina, dal più recente. Passa l’id dell’ultimo design ricevuto.
  • Caricamenti: 60 per pagina, dal più recente. Passa l’id dell’ultimo caricamento.
  • Brand, spazi di lavoro, membri e registro attività: 100 per pagina. Passa l’id dell’ultimo elemento (userId per i membri). I brand sono elencati da /api/personalities come { items }.

Chiavi, permessi e rotazione sono in Chiavi API e permessi. Se un endpoint che ti serve non è qui, diccelo.

Ti serve una mano?

Inviaci una richiesta con l’argomento API e MCP, e ti risponderà una persona.

Invia una richiesta

Trova lo stile che è solo tuo.

Ogni Mark è uno sfondo vivo con un solo proprietario. Prova un Mark ancora disponibile e riserva il tuo quando ti senti pronto.

Inizia a progettareVedi l’offerta di lancio

Mark ancora da riservare

50su 1000

950 riservati finoraTrova il tuo

Verifica un certificato

Scrivi il numero di un certificato o il codice di un Mark per scoprire di chi è.

Funziona con ChatGPT e Claude

Chiedi un design alla tua AI. Lo crea nel tuo Mark, pronto da modificare.

ChatGPTClaude
Come collegarla

Prodotto

  • Mercato
  • Esplora
  • Prezzi
  • Pacchetti di lancio
  • Certificati

Scopri

  • Guida pratica
  • Centro assistenza
  • Novità

Sviluppatori

  • Panoramica
  • ChatGPT e Claude
  • Riferimento API
  • Chiavi API

Azienda

  • Chi siamo
  • Contattaci
  • Accedi

Note legali

  • Termini
  • Privacy
  • Rimborsi
  • Protezione dei Mark
  • Cookie
  • Tutte le policy
Passa sopra le lettere. Ognuna indossa un vero Mark.Tocca una lettera per vedere il suo Mark.Un nome. Dieci Mark al suo interno.
© 2026 Gradiently