API-referenssi

API on sama, jota Gradientlyn sovellus käyttää, joten avain näkee samat tiedot ja käy läpi samat tarkistukset kuin sen luoja sovelluksessa, rajattuna yhteen työtilaan ja avaimen oikeuksiin. Avain, joka kutsuu päätepistettä, jota mikään sen oikeuksista ei kata, saa vastaukseksi 403.

Perus-URL ja tunnistautuminen

Kaikki alla olevat polut ovat osoitteen https://gradiently.design alla. Lähetä avaimesi bearer-tunnisteena jokaisen pyynnön mukana. Rungot ovat JSONia otsakkeella Content-Type: application/json, latauksia lukuun ottamatta.

curl https://gradiently.design/api/marks/mine \
  -H "Authorization: Bearer gr_live_…"

• Avain on aina sidottu työtilaan, jossa se luotiin. Työtilaa ei tarvitse nimetä; jos lähetät X-Workspace- tai ?workspace=-arvon, sen on oltava avaimen oma työtila, tai pyyntö epäonnistuu koodilla 403.
• Pyyntöjen rungot tarkistetaan tiukasti: kenttä, jota päätepiste ei tunne, epäonnistuu koodilla 422.
• Vastaukset ovat JSONia, ellei toisin mainita (kuvat, uudelleenohjaukset ja Designerin virta). API-avaimille palautettavat virheilmoitukset ovat englanniksi.
• Avain toimii luojansa nimissä. Sen tekemät designit ja brändit kuuluvat työtilalle; sen lunastamat Markit ovat sen luojan hallussa.

Työtila

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 }

Brändit

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

Designilistaus hyväksyy parametrin ?q= otsikoiden hakemiseen ja ?mark= Markin mukaan suodattamiseen. Jokaisella kohteella on id, personalityId, markId, title, form, thumb, shared ja updatedAt, ilman dokumenttia.

Designit

Helpoin tapa tehdä design koodista on POST /api/agent/compose: kuvailet sisällön, ja asettelumoottori sijoittaa sen brändin Markin päälle. Sama päätepiste muokkaa mallipohjaa (template yhdessä arvojen text, photos, icons ja hide kanssa) tai muokkaa tallennettua designia, kun annat designId- ja ops-arvot.

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 hyväksyy minkä tahansa kentistä title, doc, markId ja shared. Kun shared on true, osoitteeseen /d/:id julkaistaan katselulinkki. Lähetä baseUpdatedAt eli viimeksi lukemasi updatedAt, niin tallennus hylätään koodilla 409, jos joku on muuttanut designia sen jälkeen.

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 }

Renderöinti vaatii designin Markille saman vientilisenssin kuin Studio; ilman sitä vastaus on 402. Renderöinti ei koskaan julkaise designia eikä tallenna tiedostoa.

Lataukset

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

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

Markit

GET /api/marks hyväksyy parametrit q (nimi tai koodi), tone (dark tai light), material, status (listed, house tai sale) ja cursor. Se vastaa muodossa { "items": [ … ], "nextCursor": "…" }, 24 Markia sivulla. Markilla on id, code, name, recipe, status, creator, holder ja createdAt.

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

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

Lunastus tehdään aina avaimen luojalle, ei koskaan työtilalle. Ilmaiset lunastukset ja lunastuskrediitillä katetut lunastukset valmistuvat heti. Maksua vaativa lunastus vastaa koodilla 402 ja arvolla checkout: true, ja buy vastaa koodilla 409 ja arvolla checkout: true; viimeistele ne Gradientlyssä, koska avain ei voi maksaa. buy ottaa { "priceCents": … } eli näkemäsi listahinnan ja epäonnistuu koodilla 409, jos hinta on muuttunut.

Markien versiot

Brändien luominen

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

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

Designer kuluttaa työtilan AI-krediittejä. Kun saldo on pienempi kuin vuoro vaatii, /api/agent ja /api/batches vastaavat koodilla 402 ja arvolla code: "credits". Kullakin henkilöllä voi olla käynnissä enintään kaksi sarjaa kerrallaan. Sivun MCP ja tekoälyavustajat design-työkalu lukee Designerin virran ja tallentaa tuloksen puolestasi, mikä on yksinkertaisempaa kuin virran käsitteleminen itse.

Virheet

Virhe palauttaa tilakoodin ja JSON-rungon, jossa on luettava error-viesti. Joissakin on lisäkenttiä, jotka nimetään alla. Ainoa poikkeus on /api/mcp: jos runko ei ole kelvollista JSONia, vastaus on 400 ja sen sijaan JSON-RPC-virheolio, { "jsonrpc": "2.0", "id": null, "error": { "code": -32700, "message": "Parse error" } }.

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

Pyyntörajat

Rajat lasketaan liukuvassa yhden minuutin ikkunassa, ellei toisin mainita. Rajan ylittäminen palauttaa koodin 429, sekunteina ilmoitetun Retry-After-otsakkeen ja rungossa retryAfter-kentän. Hidasta ja yritä uudelleen vasta sen ajan jälkeen; älä yritä heti uudelleen.

Vienneillä ja Designerilla on lisäksi yhteinen kapasiteetti. Kun se on täynnä, vastaus on 503 tai 429 ja Retry-After, vaikka omat rajasi eivät olisi täynnä. MCP:n kautta työkalukutsu lasketaan kerran MCP-pyynnöstä ja kerran jokaisesta työkalun tekemästä API-pyynnöstä.

Sivutus

Luettelot palautetaan sivu kerrallaan. Pyydä seuraava sivu parametrilla ?cursor=.

• Markkinoiden haku (/api/marks): 24 sivulla. Välitä vastauksen nextCursor; viimeisellä sivulla se on null.
• Markien versiot: välitä vastauksen next-arvo; viimeisellä sivulla se on null.
• Brändin designit: 100 sivulla, uusin ensin. Välitä viimeisen saamasi designin id.
• Lataukset: 60 sivulla, uusin ensin. Välitä viimeisen latauksen id.
• Brändit, työtilat, jäsenet ja tapahtumaloki: 100 sivulla. Välitä viimeisen kohteen id (jäsenillä userId). Brändit luetellaan osoitteesta /api/personalities muodossa { items }.

Avaimet, oikeudet ja avainten vaihtaminen ovat sivulla API-avaimet ja oikeudet. Jos tarvitsemasi päätepiste puuttuu täältä, kerro meille.