Riferimento API

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.

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

{
  "viewer": { "id": "…", "name": "Ada Moss", "handle": "ada", "workspaceId": "…" },
  "workspaces": [{ "id": "…", "name": "Hearth", "role": "owner" }],
  "activeWorkspaceId": "…",
  "personalities": [{ "id": "…", "slug": "hearth", "name": "Hearth", "markId": "…" }]
}

POST /api/workspaces/:id/invites
{ "email": "sam@example.com", "role": "editor" }

{ "id": "…", "expiresInDays": 7 }

Brand

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": { … } }

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

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.

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": [ … ] }

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 }

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.

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 }

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

curl https://gradiently.design/api/uploads \
  -H "Authorization: Bearer $GRADIENTLY_API_KEY" \
  -F "file=@shopfront.jpg;type=image/jpeg"

# { "id": "…", "url": "/api/uploads/…" }

Mark

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.

POST /api/marks
{ "name": "Night Harbour", "recipe": { … }, "personalityId": "…" }

{ "id": "…", "code": "GR·K7Q2·MX", "name": "Night Harbour", "status": "draft", "recipe": { … } }

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.

Versioni dei Mark

Generazione del brand

POST /api/brand/generate
{ "name": "Hearth", "description": "A neighbourhood bakery", "tone": ["calm", "warm"], "count": 4 }

[{ "key": "…", "name": "Hearth One", "recipe": { … }, "personality": { "name": "Hearth", "handle": "…" }, "starters": [ … ], "why": "…" }]

POST /api/brand/adopt
{ "input": { "name": "Hearth", "description": "A neighbourhood bakery", "tone": ["calm", "warm"], "count": 4 }, "key": "…" }

{ "mark": { … }, "personality": { … }, "designs": [ … ] }

Il Designer

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": "…" }] }

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" } }.

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

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.

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.