Agency pakett

Husly API

Halda saite, lehti, blogi ja meediat oma skriptist, Zapierist või agentuuri tööriistast. Versioonitud REST-liides, autentimine API-võtmega.

Loo API-võti

Mida on vaja

API kuulub Agency-paketti. Võtme saab luua konto omanik: Minu konto -> API-võtmed. Täisvõtit näidatakse ainult ÜHEL korral - salvesta see kohe.

Alusta

1. Loo võti

Minu konto -> API-võtmed -> Uus võti. Anna talle nimi, mille järgi hiljem ära tunned.

2. Vali õigused

Märgi ainult need moodulid, mida see võti vajab. Kirjutamisõigus võtab lugemise kaasa.

3. Tee esimene päring

Saada võti Authorization-päises. Alusta /api/v1/me pealt - see ütleb, mida su võti tohib.

4. Ehita

Iga endpoint tagastab JSON-i kujul { data: ... }. Vead on { error: "kood" }.

curl
# Who am I? Returns the account id and the key's scopes.
curl https://api.husly.app/api/v1/me \
  -H "Authorization: Bearer hsly_live_ab12cd34ef56_..."

# List the sites on this account.
curl https://api.husly.app/api/v1/sites \
  -H "Authorization: Bearer hsly_live_ab12cd34ef56_..."

Autentimine

Iga päring kannab API-võtit. Kaks vormi töötavad ühtemoodi - vali see, mida sinu tööriist toetab. Võti algab alati eesliitega hsly_live_. Ilma võtmeta või tühistatud võtmega päring saab 401.

HTTP
Authorization: Bearer hsly_live_ab12cd34ef56_XXXXXXXXXXXXXXXXXXXXXXXX

# or

X-Api-Key: hsly_live_ab12cd34ef56_XXXXXXXXXXXXXXXXXXXXXXXX

Võti on saladus

Ära pane võtit brauseris jooksvasse koodi ega avalikku repositooriumi - see annab ligipääsu kogu kontole. Hoia seda serveri keskkonnamuutujas. Lekkinud võtme saab kohe tühistada ja uue luua.

Õigused (scope'id)

Võti kannab täpselt neid õigusi, mille sa loomisel märkisid. Puuduv õigus annab 403 insufficient_scope. Anna igale võtmele ainult see, mida ta päriselt vajab: Zapieri võti, mis loeb vormivastuseid, ei pea saama saite kustutada.

Scope	Allows
sites:read	List the account's sites and read one site's details
sites:write	Create a new site (counts against the plan's site quota)
pages:read	List pages, read a page including its block tree
pages:write	Create, update and delete pages; publish and unpublish
blog:read	List and read blog posts, categories and tags
blog:write	Create, update and delete posts and terms
media:read	List the media library
media:write	Import an image by URL, retitle it, move it, trash it
forms:read	List forms and their submissions
forms:write	Mark a submission read, delete a submission
redirects:read	List the site's URL redirects
redirects:write	Create, update and delete redirects
navigation:read	Read the header and footer menu trees
navigation:write	Replace a menu's items
analytics:read	Read daily traffic totals and dimension breakdowns
webhooks:read	List webhooks and their delivery attempts
webhooks:write	Create, update and delete webhooks

Endpointid

Kõik teed algavad https://api.husly.app pealt. :siteId on saidi id, mille saad GET /api/v1/sites vastusest. Sait peab kuuluma sinu kontole - võõra saidi id vastab 404, mitte 403, sest võti ei tohi teada teiste kontode olemasolust.

Konto

Method	Path	Scope
GET	/api/v1/me	any valid key
GET	/api/v1/webhook-events	webhooks:read

Saidid

Method	Path	Scope
GET	/api/v1/sites	sites:read
GET	/api/v1/sites/:siteId	sites:read
POST	/api/v1/sites	sites:write

Lehed

Method	Path	Scope
GET	/api/v1/sites/:siteId/pages	pages:read
GET	/api/v1/sites/:siteId/pages/:pageId	pages:read
POST	/api/v1/sites/:siteId/pages	pages:write
PUT	/api/v1/sites/:siteId/pages/:pageId	pages:write
DELETE	/api/v1/sites/:siteId/pages/:pageId	pages:write

Blogi

Method	Path	Scope
GET	/api/v1/sites/:siteId/posts	blog:read
GET	/api/v1/sites/:siteId/posts/:postId	blog:read
POST	/api/v1/sites/:siteId/posts	blog:write
PUT	/api/v1/sites/:siteId/posts/:postId	blog:write
DELETE	/api/v1/sites/:siteId/posts/:postId	blog:write
GET	/api/v1/sites/:siteId/terms	blog:read
POST	/api/v1/sites/:siteId/terms	blog:write
PUT	/api/v1/sites/:siteId/terms/:termId	blog:write
DELETE	/api/v1/sites/:siteId/terms/:termId	blog:write

Meedia

Method	Path	Scope
GET	/api/v1/sites/:siteId/media	media:read
POST	/api/v1/sites/:siteId/media	media:write
PATCH	/api/v1/sites/:siteId/media/:mediaId	media:write
DELETE	/api/v1/sites/:siteId/media/:mediaId	media:write

Vormid

Method	Path	Scope
GET	/api/v1/sites/:siteId/forms	forms:read
GET	/api/v1/sites/:siteId/form-submissions	forms:read
GET	/api/v1/forms/submissions?siteId=	forms:read
PATCH	/api/v1/sites/:siteId/form-submissions/:id	forms:write
DELETE	/api/v1/sites/:siteId/form-submissions/:id	forms:write

Suunamised

Method	Path	Scope
GET	/api/v1/sites/:siteId/redirects	redirects:read
POST	/api/v1/sites/:siteId/redirects	redirects:write
PUT	/api/v1/sites/:siteId/redirects/:id	redirects:write
DELETE	/api/v1/sites/:siteId/redirects/:id	redirects:write

Menüüd

Method	Path	Scope
GET	/api/v1/sites/:siteId/menus	navigation:read
GET	/api/v1/sites/:siteId/menus/:key	navigation:read
PUT	/api/v1/sites/:siteId/menus/:key	navigation:write

Statistika

Method	Path	Scope
GET	/api/v1/sites/:siteId/analytics	analytics:read
GET	/api/v1/sites/:siteId/analytics/breakdown	analytics:read

Veebihaagid

Method	Path	Scope
GET	/api/v1/sites/:siteId/webhooks	webhooks:read
GET	/api/v1/sites/:siteId/webhooks/:id/deliveries	webhooks:read
POST	/api/v1/sites/:siteId/webhooks	webhooks:write
PUT	/api/v1/sites/:siteId/webhooks/:id	webhooks:write
DELETE	/api/v1/sites/:siteId/webhooks/:id	webhooks:write

Näide: avalda blogipostitus

Postituse sisu on plokipuu - sama kuju, mida builder salvestab. Lihtsaim algus on üks richtext-plokk. Kui jätad layoutJson andmata, tekib tühi postitus, mille sisu saad builderis edasi toimetada.

curl
curl -X POST https://api.husly.app/api/v1/sites/SITE_ID/posts \
  -H "Authorization: Bearer hsly_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "kevadised-pakkumised",
    "title":   { "et": "Kevadised pakkumised", "en": "Spring offers" },
    "excerpt": { "et": "Lühike sissejuhatus.", "en": "A short intro." },
    "status": "published",
    "authorName": "Mari Maasikas",
    "layoutJson": {
      "contentWidth": "narrow",
      "blocks": [
        { "id": "b1", "type": "richtext", "props": {
            "content": { "et": "<p>Tere tulemast!</p>", "en": "<p>Welcome!</p>" } } }
      ]
    }
  }'

Vead

Viga tuleb alati JSON-ina kujul { "error": "kood" }, vahel koos lisaväljadega (nt required, limit). Kood on masinloetav ja püsiv - kirjuta oma loogika koodi, mitte teksti järgi.

HTTP	error	What it means
400	invalid_input	The body failed validation; the details field lists what failed
401	unauthorized	No key was sent
401	invalid_key	Unknown or revoked key
401	key_expired	The key passed its expiry date
402	plan_required	The plan does not include this feature; the feature field names it
402	site_quota_exceeded	The plan's site limit is reached
402	storage_quota_exceeded	The media upload would exceed the storage quota
403	api_not_entitled	The account's plan has no API access
403	insufficient_scope	The key lacks the scope named in the required field
403	forbidden_widget	The block tree uses a widget this account may not place
404	site_not_found	No such site, or it belongs to another account
409	slug_taken	That slug already exists on this site
413	file_too_large	The imported file is over the size limit
415	unsupported_type	The imported file is not an allowed image type
429	rate_limited	Too many requests; retry after the Retry-After header

Piirangud

Päringute arv on piiratud võtme kohta minutis. Üle piiri minek annab 429 koos Retry-After päisega ja vastuses on limit-väli, mis ütleb, milline piir kehtis. Paketi kvoodid - saitide arv, lehtede arv, meediamaht - kehtivad ka API kaudu: neid ei saa skriptiga mööda hiilida.

Versioon

Praegune versioon on v1. Me ei muuda v1 vastuste kuju viisil, mis su integratsiooni katki teeb - uued väljad võivad lisanduda, olemasolevad ei kao. Murrav muudatus tähendaks uut teed (/api/v2/).

Korduma kippuvad küsimused

Kes saab API-võtme luua?

Konto omanik. Võti kuulub kontole, mitte üksikule saidile, ja ulatub kõigi selle konto saitideni.

Kas ma näen võtit hiljem uuesti?

Ei. Me hoiame ainult võtme räsi, mitte võtit ennast. Loendis on näha vaid eesliide (nt hsly_live_ab12cd34). Kadunud võtme asemel loo uus ja tühista vana.

Mis saab, kui ma võtme tühistan?

Ta lakkab kohe töötamast - järgmine päring saab 401. Rida jääb loendisse alles, et jääks jälg, millal ja kust seda kasutati.

Kas API pääseb CRM-i andmetele?

Ei. CRM on platvormi enda tööriist ja seda ei avata klientidele. API katab saidi-poole: saidid, lehed, blogi, meedia, vormid, suunamised, menüüd, statistika ja veebihaagid.

Kas saan asendada pollimise teavitustega?

Jah - loo veebihaak. Sinu server saab POST-i kohe, kui vorm täidetakse või postitus avaldatakse, ja sa ei pea API-t taimeriga küsitlema.

Kas võtmel saab olla aegumiskuupäev?

Jah. Aegunud võti annab 401 key_expired. See on hea mõte lühiajalise töö jaoks, nt ühekordse migratsiooni-skripti puhul.

Valmis alustama?

API kuulub Agency-paketti. Kui sul on juba konto, loo võti mõne klikiga.

Loo API-võti