REST API

REST API-et er for pipelines, skript og alt som ikke er en agent. Hvis du kobler opp en modell i stedet, bruk MCP-serveren — den eksponerer de samme operasjonene som verktøy over den samme tillatelsesmodellen.

Basis-URL

fastsite er selvhostet, så basis-URL-en er din egen motor-vert. Alt bor under én opprinnelse: dashbordet, API-et, MCP-endepunktet og innkommende webhooks.

https://your-host/api/v1

Autentisering

Hver forespørsel bærer en API-nøkkel i en header. Det er ingen bearer-token og ingen økt på denne flaten — bearer-autentisering tilhører MCP.

X-API-Key: fs_<key_id>_<secret>

En nøkkel er en 44-tegns streng: det bokstavelige prefikset fs_, et offentlig id på 8 tegn, et understrek og en hemmelighet på 32 tegn. Hemmeligheten er hashet med argon2id i hvile og vises nøyaktig én gang, når nøkkelen opprettes.

php bin/fastsite key:create you@example.com \
  --name="Deploy pipeline" \
  --scopes=content:write,media:write,publish \
  --sites=blog

Bruk --sites=* for å tillate alle nettsteder. Nøkler administreres også fra dashbordet, og kan roteres eller tilbakekalles når som helst — en tilbakekalt nøkkel slutter å virke umiddelbart i stedet for ved slutten av et cache-vindu.

Svarkuvertet

Hvert JSON-svar har samme form, slik at en klient kan forgrene på ett felt.

{ "success": true, "data": { … } }

{ "success": false, "error": { "message": "…" } }

Listeendepunkter legger til en pagination-blokk ved siden av data, og data er en vanlig matrise i stedet for et objekt:

{
  "success": true,
  "data": [ … ],
  "pagination": { "total": 42, "page": 1, "per_page": 20, "total_pages": 3 }
}

To endepunkter bryter bevisst kuvertet, fordi det ville være meningsløst å pakke dem inn: lesing av en shell-fil returnerer de rå bytene som text/plain, og sletting av én returnerer 204 uten kropp.

Opprett et innlegg, deretter publiser

curl -X POST https://your-host/api/v1/sites/blog/content \
  -H "X-API-Key: $FASTSITE_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2f1c9a7e-…" \
  -d '{
    "type": "post",
    "title": "Hello, world",
    "body_html": "<p>Shipped in a single call.</p>",
    "status": "published"
  }'

Skriving av innhold publiserer det ikke. De to er separate operasjoner med hensikt — en pipeline kan opprette, revidere og korrigere så mye den trenger uten at noe av det når besøkende. Når innholdet er klart, publiser nettstedet:

curl -X POST https://your-host/api/v1/sites/blog/publish \
  -H "X-API-Key: $FASTSITE_KEY"
# → { "success": true, "data": { "job": "0f3c…" } }

Det returnerer 202 med en jobb-id; bygget kjører i køen. Poll GET /api/v1/jobs/0f3c… for resultatet.

title er det eneste obligatoriske feltet ved oppretting. type er som standard post, status er som standard draft, og slug-en avledes fra tittelen når du ikke sender en. Hvis den slug-en er tatt, legger motoren til en teller og returnerer slug-en den faktisk brukte — les den alltid tilbake i stedet for å anta.

Endepunkter

Innhold

Metode	Sti	Omfang
GET	/sites/{site}/content	content:read
POST	/sites/{site}/content	content:write
GET	/sites/{site}/content/{id}	content:read
PATCH	/sites/{site}/content/{id}	content:write
DELETE	/sites/{site}/content/{id}	content:write
GET	/sites/{site}/content/trash	content:read
POST	/sites/{site}/content/{id}/restore	content:write
DELETE	/sites/{site}/content/{id}/purge	content:write
POST	/sites/{site}/content/{id}/fact-check	content:read

Sletting er en myk sletting — elementet flyttes til papirkurven og kan gjenopprettes. purge er den ugjenkallelige.

Media

Metode	Sti	Omfang
GET	/sites/{site}/media	media:read
POST	/sites/{site}/media	media:write
DELETE	/sites/{site}/media/{id}	media:write
POST	/sites/{site}/media/{id}/restore	media:write
DELETE	/sites/{site}/media/{id}/purge	media:write

Opplasting aksepterer enten et multipart-skjema med et felt kalt file, eller JSON med en url å hente. Ikke begge — hvis en fil er til stede ignoreres URL-en.

curl -X POST https://your-host/api/v1/sites/blog/media \
  -H "X-API-Key: $FASTSITE_KEY" \
  -F file=@hero.jpg \
  -F alt="Sunrise over the harbour"

Alt-tekst er påkrevd for bilder med mindre du eksplisitt sender decorative=true. Det er ikke en stilpreferanse — manglende alt-tekst feiler byggerevisjonen, så API-et avviser det ved inngangen i stedet for å la det ødelegge en publisering senere. URL-importer er SSRF-beskyttet: private adresseområder avvises, omdirigeringer revalideres, og nedlastingen er byte-begrenset.

Filtrer biblioteket med ?kind=image,video,file. Bilder og video kjøres gjennom variantpipelinen; alt annet lagres som en nedlastbar fil.

Shell

Metode	Sti	Omfang
GET	/sites/{site}/shell/files	shell:read
GET	/sites/{site}/shell/file/{path}	shell:read
PUT	/sites/{site}/shell/file/{path}	shell:write
DELETE	/sites/{site}/shell/file/{path}	shell:write
POST	/sites/{site}/shell/snapshot	shell:write
POST	/sites/{site}/shell/restore/{rev}	shell:write

Kroppen er filen, ikke JSON. Det er ikke noe innpakningsobjekt og ingen feltnavn — du sender bytene og du får bytene tilbake.

curl -X PUT https://your-host/api/v1/sites/blog/shell/file/templates/base.html.twig \
  -H "X-API-Key: $FASTSITE_KEY" \
  --data-binary @base.html.twig

Stien kan inneholde skråstreker. Skrivinger er begrenset til shell-katalogen, begrenset til 5 MB og begrenset til en tillatelsesl liste for utvidelser (twig, css, js, json, woff2, svg og de vanlige bildetypene). I motsetning til innhold setter en shell-skriving i gang et nybygg — designet endret seg, så resultatet må det også. En rekke redigeringer slås sammen til ett bygg i stedet for ett per fil.

Ta et øyeblikksbilde før en risikabel endring. Gjenoppretting tar et øyeblikksbilde først, så en gjenoppretting er i seg selv angrbar.

Komponenter, omdirigeringer, skript

Metode	Sti	Omfang
PUT	/sites/{site}/components/{handle}	components:write
GET · POST	/sites/{site}/redirects	sites:read · sites:write
DELETE	/sites/{site}/redirects/{id}	sites:write
GET · POST	/sites/{site}/scripts	sites:read · sites:write
DELETE	/sites/{site}/scripts/{id}	sites:write

En komponent er {type: "html"|"react", source_code, css?, variables_schema?}. React kompileres ved opplasting, så en ødelagt komponent gir en 422 på forespørselen din i stedet for en ødelagt side senere.

Språk, publisering, nettsteder

Metode	Sti	Omfang
POST	/sites/{site}/languages	translations:manage
DELETE	/sites/{site}/languages/{locale}	translations:manage
POST	/sites/{site}/publish	publish
GET	/jobs/{uuid}	jobs:read
GET	/sites	sites:read
POST	/sites	admin
PATCH	/sites/{site}	sites:write
GET · POST	/sites/{site}/webhooks	sites:read · sites:write
GET	/sites/{site}/webhooks/{id}/deliveries	sites:read
DELETE	/sites/{site}/webhooks/{id}	sites:write
GET	/authoring-guide	sites:read
GET	/sites/{site}/authoring-guide	sites:read

Omfang

Nøkler og OAuth-tildelinger deler ett omfangsordforråd, slik at et endepunkt og et verktøy håndhever tilgang identisk.

Omfang	Gir
sites:read	Se nettsteder og innstillingene deres
sites:write	Endre nettstedsinnstillinger, omdirigeringer, skript, webhooks
content:read	Les innlegg og sider
content:write	Opprett og rediger innlegg og sider
media:read	Vis mediebiblioteket
media:write	Last opp bilder, video og filer
components:write	Opprett og oppdater komponenter
shell:read	Les maler og tema
shell:write	Rediger maler og tema
translations:manage	Administrer lokaliteter og oversettelser
publish	Bygg og publiser
jobs:read	Les bygge- og jobbstatus
backup:read · backup:run · backup:restore	Sikkerhetskopieringsoperasjoner
admin	Alt

Bare admin innebærer noe annet. Det er ikke noe lese/skrive-hierarki — content:write gir ikke content:read, så be om begge hvis du trenger begge. Nøkler er også låst til en nettstedsliste, og en forespørsel om et nettsted utenfor den avvises før den når en behandler.

Idempotens

Send en Idempotency-Key-header på enhver POST og motoren registrerer resultatet mot den.

• Den samme nøkkelen med samme metode, sti og kropp spiller av det lagrede svaret, med Idempotency-Replayed: true på det.
• Den samme nøkkelen med en annen kropp er en 422 — det er slik du finner ut at forsøkslogikken din endret nyttelasten.
• Et nytt forsøk som ankommer mens det første fortsatt kjører, får 409 og en Retry-After.
• Hvis behandleren kaster, eller svaret er en 5xx eller en 429, frigjøres nøkkelen slik at et ekte nytt forsøk kan lykkes.

Andre metoder ignorerer headeren helt.

Hastighetsbegrensninger

To faste vindusbegrensninger, begge per minutt: 60 forespørsler per IP og 120 per API-nøkkel. Å overskride en av dem returnerer 429 med en Retry-After. Per-IP-bøtten er den du vanligvis møter først, siden én klient er én adresse.

JSON-forespørselskropper er begrenset til 4 MiB. Opplastinger er unntatt fra den kontrollen og begrenset av per-type mediegrensene i stedet.

Statuskoder

Kode	Betydning
200 · 201 · 202 · 204	Vellykket. 202 betyr satt i kø — poll jobben.
401	Manglende, feilformatert, ukjent eller tilbakekalt nøkkel.
403	Gyldig nøkkel, men omfanget eller nettstedet er ikke tillatt.
404	Ingen slik rute, nettsted eller post.
409	Duplikat, eller en idempotent forespørsel fremdeles under behandling.
413	Kropp over grensen.
422	Validering mislyktes — les error.message.
429	Hastighetsbegrenset.

Detaljer verdt å vite før du bygger mot det

• Tidsstempler er strenge. scheduled_at og published_at må være YYYY-MM-DDTHH:MM:SSZ — UTC, stor T, avsluttende Z. Forskyvninger som +02:00 avvises i stedet for å konverteres.
• Statusverdier er draft, scheduled, published og archived. Planlegging krever scheduled_at, og planleggeren publiserer det for deg når tiden kommer.
• Sideveksling er ?page= og ?per_page=, med standard 20 og begrenset til 100.
• Kropp-HTML desinfiseres på alle stier. Innebygde stiler fjernes, skript og iframes fjernes, og resultatet kommer tilbake med en warnings-matrise. Innholdsproblemer feiler aldri forespørselen din — de rapporteres, normaliseres og publiseres.
• Noen ting er ikke på REST. Sikkerhetskopier, team og API-nøkkeladministrasjon er CLI- og dashbordoperasjoner; sikkerhetskopier og gjenopprettinger er også tilgjengelige over MCP.

Neste: MCP-serveren for agentdrevet publisering, eller webhooks for å skyve innhold inn fra et oppstrøms system.