# Een design-API voor developers: API en MCP-server

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

Eén sleutel, één werkruimte, acht scopes. Zo zoek je Marks, maak je ontwerpen op, maak je andere formaten en render je klare bestanden vanuit je eigen code of een AI-assistent, met de limieten en fouten die je onderweg tegenkomt.

## The short version

- Gradiently heeft een JSON-design-API onder https://gradiently.design/api en een gehoste MCP-server, en beide zijn gebouwd op dezelfde endpoints.
- Elk verzoek draagt een API-sleutel van de werkruimte, aangemaakt in Instellingen › API en agents door een eigenaar of beheerder van de werkruimte.
- Een sleutel werkt in precies één werkruimte, treedt op als de persoon die hem heeft aangemaakt en kan alleen de endpoints bereiken die zijn scopes toestaan.
- De API kan de Markt doorzoeken, ontwerpen op de Mark van een merk opmaken en bewerken, kopieën in andere formaten opslaan en opgeslagen ontwerpen naar PNG of PDF renderen.
- Een sleutel kan nooit sleutels beheren, bij facturatie komen, het account wijzigen of een Mark weggeven; daarvoor moet altijd een persoon ingelogd zijn.

Gradiently is zowel een tool als een **design-API**. Met één afgebakende sleutel zoek je Marks, maak je ontwerpen die de Mark van je merk dragen, wijzig je de woorden, sla je kopieën in andere formaten op en render je het resultaat naar PNG of PDF, alles als JSON via HTTPS. Dezelfde mogelijkheden worden aangeboden als gehoste MCP-server, zodat ChatGPT, Claude of elke assistent die externe MCP-servers ondersteunt het werk kan doen op basis van een gewoon verzoek en je een link geeft die in de Studio opent.

Deze pagina is het overzicht voor developers: waarvoor de API dient, hoe sleutels en scopes werken, een eerste verzoek en de limieten waar je rekening mee moet houden. De volledige referentie staat op [/developers](https://gradiently.design/nl/developers).

## Wat de Gradiently-API kan

De API is dezelfde die de Gradiently-app zelf gebruikt, dus een sleutel ziet dezelfde gegevens en doorloopt dezelfde controles als de maker in de browser. De bruikbare taken vallen in vijf groepen.

- **Een look vinden.** Zoek in de openbare Markt op naam, kleurwoorden of code en lees het volledige recept van elke openbare Mark.
- **Ontwerpen maken.** Beschrijf inhoud en een lay-out en laat de lay-outengine het op de Mark van het merk plaatsen, remix een van de templates van Gradiently of stuur een volledig ontwerpdocument.
- **Ontwerpen wijzigen.** Bewerk per element, vervang de woorden van gekozen tekstelementen, zet een andere Mark op een ontwerp en sla kopieën in andere formaten op.
- **Renderen.** Zet een opgeslagen ontwerp om naar PNG of PDF met de eigen engine van de Studio, of publiceer er een weergavelink voor.
- **De werkruimte lezen.** Toon merken, hun ontwerpen, uploads en leden en lees de lettertypen, logo’s en kleuren van een merk.

Typische toepassingen: een winkel die voor elk nieuw artikel een productkaart rendert, een redactie die van elke kop een [linkvoorbeeldafbeelding](https://gradiently.design/nl/guide/link-preview-image) maakt, of een interne tool die de posts van de week uit een contentkalender maakt. Staan je brongegevens al in een spreadsheet, dan kan [bulk aanmaken](https://gradiently.design/nl/guide/bulk-create-from-spreadsheet) in de Studio het werk misschien zonder code doen.

## API of MCP-server

### MCP-server

- Voor AI-assistenten die externe MCP-servers ondersteunen.
- Claude: `https://gradiently.design/api/mcp`. ChatGPT: `https://gradiently.design/api/mcp/chatgpt`.
- Tools zoeken je merk op, slaan ontwerpen op en geven Studio-links terug.
- Het best als je in gewone woorden om werk wilt vragen.

### HTTP-API

- Voor scripts, back-ends en automatiseringen.
- JSON via HTTPS onder `https://gradiently.design/api`.
- Jij kiest het merk, stuurt de inhoud en verwerkt elk antwoord.
- Het best als je exacte, herhaalbare uitvoer nodig hebt.

Een toolaanroep doet dezelfde verzoeken als je code, met dezelfde sleutel, dus telt mee voor dezelfde limieten en faalt met dezelfde meldingen. Is MCP nieuw voor je, dan legt [wat is MCP](https://gradiently.design/nl/guide/what-is-mcp) het in gewone woorden uit en loopt [een AI-assistent koppelen](https://gradiently.design/nl/guide/connect-ai-assistant) de installatie voor ChatGPT en Claude door.

## API-sleutels en scopes

Sleutels maak je aan in **Instellingen › API en agents**, en alleen eigenaren en beheerders van een werkruimte kunnen ze maken. Een sleutel wordt één keer getoond, begint met `gr_live_`, verloopt nooit en kan niet worden bewerkt: om te wijzigen wat hij kan, maak je een nieuwe en trek je de oude in. Hij treedt op als de persoon die hem heeft gemaakt, binnen de ene werkruimte waarvoor hij is gemaakt, en werkt niet meer als die persoon vertrekt of lager in rang wordt gezet.

| Scope | In Instellingen | Wat hij toestaat |
| --- | --- | --- |
| `designs:read` | Ontwerpen lezen | Merken, ontwerpen, miniaturen, uploads en renders |
| `designs:write` | Ontwerpen maken en bewerken | Ontwerpen maken, wijzigen, dupliceren en verwijderen, afbeeldingen uploaden, de Designer draaien |
| `marks:read` | Marks zoeken | De Markt doorzoeken en Marks lezen |
| `marks:claim` | Marks claimen | Een beschikbare Mark claimen voor de maker van de sleutel |
| `brand:generate` | Merken genereren | Endpoints voor merkgeneratie |
| `workspaces:read` | De werkruimte lezen | De werkruimte, haar leden en het auditlogboek |
| `personalities:write` | Merken bewerken | Merken maken, hernoemen en verwijderen, de Mark van een merk wijzigen |
| `members:write` | Leden uitnodigen | Uitnodigingen naar de werkruimte sturen |

De acht scopes. Een nieuwe sleutel begint met de vijf die het meeste werk nodig heeft; Marks claimen blijft uit tot je het kiest, omdat een claim je de houder van een Mark maakt.

> **Een sleutel is een wachtwoord** Bewaar hem in een omgevingsvariabele of secret store, één sleutel per tool, met zo min mogelijk scopes voor de taak. Zet een sleutel nooit in een webpagina, een mobiele app of een repository: Gradiently bewaart alleen een hash, dus een gelekte sleutel moet worden ingetrokken en vervangen.

## Je eerste verzoek

1. **Maak een sleutel** Open **Instellingen › API en agents**, kies de werkruimte, noem de sleutel naar waar hij gaat draaien en kopieer hem zodra hij verschijnt.
2. **Doorzoek de Markt** Een `GET` naar `/api/marks` met `?q=` geeft 24 Marks per pagina en een `nextCursor` voor de volgende.
3. **Maak een ontwerp op** Stuur tekst naar `POST /api/agent/compose` met een formaatpreset en een lay-out. Je krijgt een ontwerp-id, een Studio-link en eventuele reviewpunten terug.
4. **Render het** Roep `POST /api/designs/:id/render` aan met een breedte, hoogte en formaat en decodeer het base64-bestand dat het teruggeeft.

```bash
export GRADIENTLY_API_KEY="gr_live_…"

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

Voor het doorzoeken van de Markt is `marks:read` nodig. Codes werken met of zonder de punten, in elke letterstand.

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

Merken heten personalities in de API. Lay-outs zijn onder meer statement, editorial, poster, split, stat, quote, list, event en minimal.

Een staande Instagrampost met de tekst Vers brood vanaf 7 uur en een kleine regel Kom langs, op een levende verloopachtergrond

Wat dat verzoek oplevert: de woorden door de lay-outengine op de Mark van het merk geplaatst, op het staande Instagramformaat van 1080×1350.

Omdat het ontwerp op een Mark staat, is leesbaarheid voor je geregeld: het rustigste gebied van de Mark schuift achter de woorden en Auto-inkt kiest per regel lichte of donkere letters. Om dezelfde post als story en als X-post te leveren, slaat de MCP-tool `resize_copies` kopieën op in maximaal acht formaten tegelijk, opnieuw opgemaakt zoals de Studio dat doet. [Kopiëren naar formaten](https://gradiently.design/nl/guide/copy-to-sizes) legt de herindeling uit.

```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 }
```

Breedte en hoogte lopen van 1 tot 4096. Voor renderen is dezelfde exportlicentie nodig voor de Mark van het ontwerp als in de Studio; zonder die licentie is het antwoord 402.

## Credits, limieten en fouten

Als je eigen assistent een ontwerp opmaakt via de teken- en bewerktools, worden er geen AI-credits van Gradiently uitgegeven. Vraag je de eigen Designer van Gradiently, via `/api/agent`, `/api/batches` of de tool `design`, dan gaan de credits van de werkruimte op, precies zoals in de Studio. [AI-credits uitgelegd](https://gradiently.design/nl/guide/ai-credits-explained) behandelt het tegoed.

| Limiet | Toegestaan |
| --- | --- |
| Elk verzoek met een sleutel | 120 per minuut per sleutel |
| Schrijfacties (POST, PATCH, DELETE) | 90 per minuut per account, gedeeld met de app |
| Renders | 10 per minuut per account |
| Nieuwe ontwerpen en duplicaten | 60 per minuut per account |
| Uploads | 60 per minuut per account |

Voortschrijdende vensters van een minuut. Overschrijding geeft 429 met een `Retry-After`-header in seconden: wacht zolang, probeer het niet direct opnieuw.

Fouten komen terug als statuscode met een leesbare `error`-melding. De meest voorkomende: 401 voor een ontbrekende of ingetrokken sleutel, 403 voor een ontbrekende scope, 402 als een exportlicentie of credits nodig zijn, 409 als een ontwerp is gewijzigd sinds je het las en 422 als een veld de validatie niet doorstaat. Stuur `baseUpdatedAt` mee met een `PATCH` om die 409 te krijgen in plaats van de bewerking van een collega te overschrijven.

## Wat een sleutel nooit kan

Sommige acties vereisen altijd een persoon die bij Gradiently is ingelogd, wat de scopes ook zijn. Een sleutel kan geen sleutels maken of intrekken, het account niet wijzigen, niet bij facturatie komen of ergens voor betalen, geen Mark overdragen, tonen of vrijgeven, geen rollen van leden wijzigen en geen andere werkruimte bereiken dan de eigen. Een claim waarvoor betaling nodig is stopt en vraagt om afrekenen in Gradiently. Deze grenzen zijn bewust: een automatisering kan werk maken en renderen, maar eigendom en geld blijven bij mensen. Rollen staan in [werkruimterollen](https://gradiently.design/nl/guide/workspace-roles).

## FAQ

### Heeft Gradiently een API?

Ja. Het heeft een JSON-API onder `https://gradiently.design/api` en een gehoste MCP-server, beide te gebruiken met een API-sleutel van de werkruimte of, voor ChatGPT en Claude, met OAuth-inloggen.

### Wie kan een Gradiently API-sleutel maken?

Eigenaren en beheerders van een werkruimte, in Instellingen › API en agents. De sleutel wordt één keer getoond en werkt alleen in die werkruimte.

### Kan ik een ontwerp met de API naar PNG renderen?

Ja. `POST /api/designs/:id/render` geeft een PNG of PDF als base64 terug, tot 4096 pixels per zijde, mits je de exportlicentie voor de Mark van het ontwerp hebt.

### Kost de API AI-credits?

Ontwerpen opmaken, bewerken en renderen niet. De eigen Designer van Gradiently vragen via de API of de tool `design` kost wel AI-credits van de werkruimte.

### Wat zijn de rate limits van de API?

120 verzoeken per minuut per sleutel, met lagere limieten voor schrijfacties, renders en uploads. Boven een limiet krijg je een 429 met een `Retry-After`-header.