# Design-API for utviklere: API og MCP-server fra Gradiently

[Canonical HTML page](https://gradiently.design/nb/guide/gradiently-for-developers)

Én nøkkel, ett arbeidsområde, åtte tillatelser. Slik søker du etter Marks, setter opp design, lager andre størrelser og rendrer ferdige filer fra din egen kode eller en AI-assistent, med grensene og feilene du møter underveis.

## The short version

- Gradiently har et JSON-basert design-API under https://gradiently.design/api og en driftet MCP-server, og begge bygger på de samme endepunktene.
- Hver forespørsel har med en API-nøkkel for arbeidsområdet, opprettet i Innstillinger › API og agenter av en eier eller admin.
- En nøkkel virker i nøyaktig ett arbeidsområde, handler som personen som opprettet den og når bare endepunktene tillatelsene gir tilgang til.
- API-et kan søke i Markedet, sette opp og redigere design på et merkes Mark, lagre kopier i andre størrelser og rendre lagrede design til PNG eller PDF.
- En nøkkel kan aldri administrere nøkler, nå fakturering, endre kontoen eller gi bort en Mark; det krever alltid en innlogget person.

Gradiently er et **design-API** i tillegg til et designverktøy. Med én avgrenset nøkkel kan du søke etter Marks, lage design som bærer merkets Mark, endre ordene, lagre kopier i andre størrelser og rendre resultatet til PNG eller PDF, alt som JSON over HTTPS. De samme mulighetene finnes som en driftet MCP-server, så ChatGPT, Claude eller en hvilken som helst assistent som støtter eksterne MCP-servere, kan gjøre jobben ut fra en vanlig forespørsel og gi deg en lenke som åpnes i Studio.

Denne siden er utviklerens oversikt: hva API-et er til, hvordan nøkler og tillatelser virker, en første forespørsel og grensene det lønner seg å planlegge rundt. Den fullstendige referansen finner du på [/developers](https://gradiently.design/nb/developers).

## Dette kan Gradiently-API-et gjøre

API-et er det samme som Gradiently-appen selv bruker, så en nøkkel ser de samme dataene og går gjennom de samme kontrollene som skaperen ville gjort i nettleseren. De nyttige jobbene faller i fem grupper.

- **Finn en look.** Søk i det offentlige Markedet etter navn, fargeord eller kode, og les hele oppskriften til en hvilken som helst offentlig Mark.
- **Lag design.** Beskriv innhold og layout og la layoutmotoren plassere det på merkets Mark, remiks en av Gradiently sine maler, eller send et komplett designdokument.
- **Endre design.** Rediger element for element, bytt ut ordene i utvalgte tekstelementer, sett en annen Mark på et design og lagre kopier i andre størrelser.
- **Rendre.** Gjør et lagret design om til PNG eller PDF med Studios egen motor, eller publiser en visningslenke til det.
- **Les arbeidsområdet.** List opp merker, designene deres, opplastinger og medlemmer, og les et merkes fonter, logoer og farger.

Typiske bruksområder: en nettbutikk som rendrer et produktkort for hver ny vare, en redaksjon som gjør hver overskrift om til et [forhåndsvisningsbilde for lenker](https://gradiently.design/nb/guide/link-preview-image), eller et internt verktøy som lager ukens innlegg fra en innholdskalender. Ligger kildedataene dine allerede i et regneark, kan [masseoppretting](https://gradiently.design/nb/guide/bulk-create-from-spreadsheet) i Studio gjøre jobben helt uten kode.

## API eller MCP-server

### MCP-server

- For AI-assistenter som støtter eksterne MCP-servere.
- Claude: `https://gradiently.design/api/mcp`. ChatGPT: `https://gradiently.design/api/mcp/chatgpt`.
- Verktøyene slår opp merket ditt, lagrer design og returnerer lenker til Studio.
- Best når du vil be om arbeid med vanlige ord.

### HTTP-API

- For skript, backend og automatiseringer.
- JSON over HTTPS under `https://gradiently.design/api`.
- Du velger merket, sender innholdet og håndterer hvert svar.
- Best når du trenger nøyaktig, repeterbart resultat.

Et verktøykall gjør de samme forespørslene som koden din ville gjort, med den samme nøkkelen, så det teller mot de samme grensene og feiler med de samme meldingene. Er MCP nytt for deg, forklarer [hva er MCP](https://gradiently.design/nb/guide/what-is-mcp) det med enkle ord, og [koble til en AI-assistent](https://gradiently.design/nb/guide/connect-ai-assistant) viser oppsettet for ChatGPT og Claude.

## API-nøkler og tillatelser

Nøkler opprettes i **Innstillinger › API og agenter**, og bare eiere og admin i et arbeidsområde kan lage dem. En nøkkel vises én gang, starter med `gr_live_`, utløper aldri og kan ikke redigeres: vil du endre hva den kan gjøre, lager du en ny og tilbakekaller den gamle. Den handler som personen som opprettet den, i det ene arbeidsområdet den ble laget for, og slutter å virke hvis personen forlater arbeidsområdet eller får en lavere rolle.

| Tillatelse | I Innstillinger | Hva den gir lov til |
| --- | --- | --- |
| `designs:read` | Lese design | Merker, design, miniatyrbilder, opplastinger og rendringer |
| `designs:write` | Lage og redigere design | Lage, endre, duplisere og slette design, laste opp bilder, kjøre Designer |
| `marks:read` | Søke etter Marks | Søke i Markedet og lese Marks |
| `marks:claim` | Sikre seg Marks | Sikre seg en ledig Mark for nøkkelens skaper |
| `brand:generate` | Generere merker | Endepunkter for merkegenerering |
| `workspaces:read` | Lese arbeidsområdet | Arbeidsområdet, medlemmene og revisjonsloggen |
| `personalities:write` | Redigere merker | Lage, gi nytt navn til og slette merker, bytte et merkes Mark |
| `members:write` | Invitere medlemmer | Sende invitasjoner til arbeidsområdet |

De åtte tillatelsene. En ny nøkkel starter med de fem det meste arbeidet trenger; Sikre seg Marks er av til du velger den, fordi det å sikre deg en Mark gjør deg til innehaver av den.

> **En nøkkel er et passord** Oppbevar den i en miljøvariabel eller et hemmelighetslager, én nøkkel per verktøy, med færrest mulig tillatelser som gjør jobben. Legg aldri en nøkkel i en nettside, en mobilapp eller et repository: Gradiently lagrer bare en hash, så en lekket nøkkel må tilbakekalles og erstattes.

## Din første forespørsel

1. **Opprett en nøkkel** Åpne **Innstillinger › API og agenter**, velg arbeidsområdet, gi nøkkelen navn etter hvor den skal kjøre, og kopier den når den vises.
2. **Søk i Markedet** En `GET` mot `/api/marks` med `?q=` returnerer 24 Marks per side og en `nextCursor` for neste side.
3. **Sett opp et design** Send tekst til `POST /api/agent/compose` med en forhåndsinnstilt størrelse og en layout. Du får en design-id, en lenke til Studio og eventuelle funn fra gjennomgangen.
4. **Rendre det** Kall `POST /api/designs/:id/render` med bredde, høyde og format, og dekod base64-filen du får tilbake.

```bash
export GRADIENTLY_API_KEY="gr_live_…"

curl "https://gradiently.design/api/marks?q=deep%20teal" \
  -H "Authorization: Bearer $GRADIENTLY_API_KEY"
```

Søk i Markedet krever `marks:read`. Koder virker med eller uten punktene, med store eller små bokstaver.

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

Merker heter personalities i API-et. Layoutene omfatter statement, editorial, poster, split, stat, quote, list, event og minimal.

Et stående Instagram-innlegg med teksten Ferskt brød fra kl. 7 og en liten linje Velkommen innom, på en levende gradientbakgrunn

Det forespørselen gir: ordene plassert av layoutmotoren på merkets Mark, i Instagrams stående format på 1080×1350.

Fordi designet ligger på en Mark, er lesbarheten tatt hånd om: Markens roligste område flytter seg bak ordene, og Automatisk blekk velger lys eller mørk tekst for hver linje. Skal det samme innlegget ut som story og som X-innlegg, lagrer MCP-verktøyet `resize_copies` kopier i opptil åtte størrelser på én gang, omflytet slik Studio gjør det. [Kopier til størrelser](https://gradiently.design/nb/guide/copy-to-sizes) forklarer omflytingen.

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

{ "data": "iVBORw0KGgo…", "encoding": "base64", "mimeType": "image/png", "width": 1080, "height": 1350, "pages": 1 }
```

Bredde og høyde går fra 1 til 4096. Rendring krever den samme eksportlisensen for designets Mark som i Studio; uten den blir svaret 402.

## Kreditter, grenser og feil

Når din egen assistent setter opp et design med tegne- og redigeringsverktøyene, brukes ingen AI-kreditter fra Gradiently. Ber du Gradiently sin egen Designer om hjelp, via `/api/agent`, `/api/batches` eller verktøyet `design`, brukes arbeidsområdets kreditter akkurat som i Studio. [AI-kreditter forklart](https://gradiently.design/nb/guide/ai-credits-explained) går gjennom kvoten.

| Grense | Kvote |
| --- | --- |
| Alle forespørsler med en nøkkel | 120 i minuttet per nøkkel |
| Skriving (POST, PATCH, DELETE) | 90 i minuttet per konto, delt med appen |
| Rendringer | 10 i minuttet per konto |
| Nye design og duplikater | 60 i minuttet per konto |
| Opplastinger | 60 i minuttet per konto |

Glidende vinduer på ett minutt. Går du over, blir svaret 429 med en `Retry-After`-header i sekunder: vent så lenge, ikke prøv igjen med en gang.

Feil kommer tilbake som en statuskode med en lesbar `error`-melding. De du oftest ser: 401 for en manglende eller tilbakekalt nøkkel, 403 for en manglende tillatelse, 402 når det trengs eksportlisens eller kreditter, 409 når et design er endret siden du leste det, og 422 når et felt ikke består valideringen. Send `baseUpdatedAt` med en `PATCH` for å få den 409-feilen i stedet for å overskrive en kollegas endring.

## Dette kan en nøkkel aldri gjøre

Noen handlinger krever alltid en person som er logget inn i Gradiently, uansett tillatelser. En nøkkel kan ikke opprette eller tilbakekalle nøkler, endre kontoen, nå fakturering eller betale for noe, overføre, legge ut eller frigi en Mark, endre medlemmers roller eller nå andre arbeidsområder enn sitt eget. Å sikre seg en Mark som krever betaling, stopper opp og ber om kassen i Gradiently. Grensene er bevisste: en automatisering kan lage og rendre arbeid, men eierskap og penger blir hos mennesker. Roller er forklart i [roller i arbeidsområdet](https://gradiently.design/nb/guide/workspace-roles).

## FAQ

### Har Gradiently et API?

Ja. Det har et JSON-API under `https://gradiently.design/api` og en driftet MCP-server, begge brukt med en API-nøkkel for arbeidsområdet eller, for ChatGPT og Claude, innlogging med OAuth.

### Hvem kan opprette en API-nøkkel i Gradiently?

Eiere og admin i et arbeidsområde, i Innstillinger › API og agenter. Nøkkelen vises én gang og virker bare i det arbeidsområdet.

### Kan jeg rendre et design til PNG med API-et?

Ja. `POST /api/designs/:id/render` returnerer en PNG eller PDF som base64, opptil 4096 piksler per side, så lenge du har eksportlisensen for designets Mark.

### Bruker API-et AI-kreditter?

Å sette opp, redigere og rendre design gjør ikke det. Å be Gradiently sin egen Designer om hjelp via API-et eller verktøyet `design` bruker arbeidsområdets AI-kreditter.

### Hva er grensene for API-forespørsler?

120 forespørsler i minuttet per nøkkel, med lavere grenser for skriving, rendringer og opplastinger. Over en grense får du 429 med en `Retry-After`-header.