Kull artiklu li niktbu għalik jista’ jinqara fuq HTTP: it-titlu, il-metadata, il-Markdown, l-HTML, l-immaġni hero u l-FAQ. Daħħalhom fis-sit Next.js, Astro jew custom tiegħek meta taħdem il-build tiegħek, ippubblikahom, u għidilna l-indirizz fejn spiċċa kull wieħed.
Bearer token waħda. JSON jidħol, JSON joħroġ. L-ebda SDK x’tinstalla u xejn x’tikkonfigura lil hinn minn key.
Iġorru l-istess artiklu fl-istess forma, għalhekk parser miktub għal waħda jaqra lill-oħra mingħajr tibdil. Id-differenza hija min jibda l-konversazzjoni.
Insejħu l-endpoint tagħkom fil-mument li artiklu jkun lest, u mill-ġdid meta jinbidel. Xejn x'tivverifikaw perjodikament, xejn x'tiskedaw. WordPress, Shopify, Ghost, trigger ta' Zapier, jew rotta li ktibtu intom stess.
Sit statiku ma jistax jaċċetta post fis-sitta u nofs ta’ filgħodu, l-ewwel trid issir rebuild. Għalhekk il-build tiegħek tistaqsi x’inhu qed jistenna, tieħdu, u wara tgħidilna l-indirizz. Inti tagħżel meta.
Huma konnessjonijiet separati u waħda ma teskludix lill-oħra. Webhook li jforni newsletter u API li tforni l-website huwa arranġament normali.
Agħmel key fid-dashboard taħt Settings, imbagħad Connections. Tintwera darba biss, meta tinħoloq, għax jinħażen biss il-hash tagħha: jekk titlefha, irrevokaha u agħmel oħra. Key taqra kull sit fil-kont u tiġi revokata mill-istess skrin.
Kull talba
Authorization: Bearer sns_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx Accept: application/json
Iċċekkja li jaħdem
curl https://seonis.ai/api/v1/me \ -H "Authorization: Bearer $SEONIS_API_KEY"
{
"organisation": { "id": 12, "name": "Peppervale", "country": "GB" },
"key": {
"name": "Production build",
"prefix": "sns_live_ab",
"created_at": "2026-09-06T09:12:44+00:00",
"last_used_at": "2026-09-06T09:31:02+00:00"
},
"sites": 2
}
Rate limit
120 talbiet kull minuta, magħduda mal-key aktar milli mal-indirizz li tiġi minnu, għax build runners jaqsmu l-indirizzi. Aktar minn hekk tirċievi 429 bl-headers standard Retry-After u X-RateLimit. Il-ġbid tal-artikli għal build huwa biss ftit talbiet, għalhekk dan mhux limitu li għandek tilħaq bi żball.
Żomm il-key barra mir-repository tiegħek
Taqra dak kollu li ktibna għall-kont tiegħek, inklużi artikli li għadhom mhumiex ippubblikati. Poġġiha fil-build environment tiegħek, mhux fis-source tiegħek. Irrevokaha hawnhekk malli tkun xi mkien fejn m’għandhiex tkun, u kull ħaġa li tużaha tieħu 401 minnufih.
Kollox jinsab taħt /api/v1/. Il-verżjoni tinsab fil-path mill-ewwel jum, sabiex xi darba tkun tista’ teżisti v2 mingħajr ma tkisser dak li tikteb illum.
Il-kont li tappartjeni għalih iċ-ċavetta, u l-isem u l-prefiss taċ-ċavetta nnifisha. Utli fuq kollox għal ħaġa waħda: biex jgħidilkom li ċ-ċavetta f'dan l-ambjent hija ċ-ċavetta li taħsbu li hi.
Eżempju
curl https://seonis.ai/api/v1/me \ -H "Authorization: Bearer $SEONIS_API_KEY"
Kull sit fil-kont. L-id huwa dak li fuqu tiffiltra l-lista tal-artikli, u d-domain qiegħed hemm biex build script tkun tista’ tqabbel ma’ xi ħaġa li diġà taf minflok iġġorr id.
Eżempju
curl https://seonis.ai/api/v1/sites \ -H "Authorization: Bearer $SEONIS_API_KEY"
{
"sites": [
{
"id": 5,
"name": "Peppervale",
"domain": "peppervale.co.uk",
"url": "https://peppervale.co.uk",
"language": "en",
"country": "GB",
"market": "en-GB",
"status": "active",
"articles_published": 34,
"created_at": "2026-06-02T11:04:19+00:00"
}
]
}
Paġna ta’ artikli, bl-aktar bidla reċenti l-ewwel, mingħajr il-kitba. Ordnat skont meta kull artiklu nbidel l-aħħar aktar milli meta nkiteb, u għalhekk updated_since huwa utli: artiklu li diġà huwa live jista’ jiġi editjat aktar tard, meta link tiddaħħal fih jew terġa’ titneħħa.
Parametri tal-query
| Isem | X'jagħmel |
|---|---|
| site_id | Sit wieħed, minn /sites. Id li mhijiex fil-kont tiegħek twieġeb 404. |
| status | Waħda minn draft, qa, needs_repair, review, ready, published, failed. Kull ħaġa oħra hija 422 aktar milli paġna vojta. "ready" huwa dak li trid build: miktub, iċċekkjat, u għadu mkien imkien. |
| updated_since | ISO 8601, bħal 2026-09-06T00:00:00Z. Ftakar it-timestamp tal-aħħar run tiegħek u erġa’ għaddih f’dik ta’ wara. |
| per_page | Sa 100. Il-valur awtomatiku huwa 25. |
| page | Minn 1. meta.has_more jgħidlek jekk għandekx titlob oħra. |
Eżempju
curl -G https://seonis.ai/api/v1/articles \ -H "Authorization: Bearer $SEONIS_API_KEY" \ -d site_id=5 \ -d status=ready \ -d updated_since=2026-09-01T00:00:00Z \ -d per_page=50
{
"articles": [
{
"id": 918,
"site_id": 5,
"language": "en",
"status": "ready",
"title": "How to choose a pepper grinder",
"slug": "how-to-choose-a-pepper-grinder",
"meta_title": "How to choose a pepper grinder | Peppervale",
"meta_description": "Burr or blade, ceramic or steel: what matters in a grinder.",
"meta_keywords": ["pepper grinder", "burr grinder"],
"tags": ["Kitchen"],
"excerpt": "A burr grinder gives an even grind; a blade one does not.",
"key_takeaways": ["A burr grinder gives an even grind; a blade one does not."],
"faq": [{ "question": "Ceramic or steel?", "answer": "Steel for pepper, ceramic for salt." }],
"hero_image": { "url": "https://seonis.ai/storage/images/5/918.jpg", "alt": "A pepper grinder" },
"infographic_url": null,
"word_count": 1812,
"published_url": null,
"published_at": null,
"updated_at": "2026-09-06T06:31:12+00:00",
"created_at": "2026-09-05T02:14:55+00:00",
"quality": { "seo_score": 88, "language_score": 96, "language_findings": [] }
}
],
"meta": { "page": 1, "per_page": 50, "total": 1, "last_page": 1, "has_more": false }
}
Artiklu wieħed, b’dak kollu li l-lista tħalli barra: content_markdown, content_html, il-FAQ bħala schema.org JSON-LD lest biex tiddaħħlu fil-paġna, u kull exchange link li jġorr l-artiklu.
L-ismijiet tal-oqsma huma dawk li jibgħat il-webhook tagħna, apposta. Jekk diġà għandkom riċevitur tal-webhook, l-istess parser jaqra dan.
Eżempju
curl https://seonis.ai/api/v1/articles/918 \ -H "Authorization: Bearer $SEONIS_API_KEY"
{
"article": {
"id": 918,
"site_id": 5,
"language": "en",
"status": "ready",
"title": "How to choose a pepper grinder",
"slug": "how-to-choose-a-pepper-grinder",
"meta_description": "Burr or blade, ceramic or steel: what matters in a grinder.",
"content_markdown": "Grinders differ.\n\n## Burr or blade\n\nA **burr** grinder ...",
"content_html": "<p>Grinders differ.</p>\n<h2>Burr or blade</h2> ...",
"faq_schema": { "@context": "https://schema.org", "@type": "FAQPage", "mainEntity": [] },
"hero_image": { "url": "https://seonis.ai/storage/images/5/918.jpg", "alt": "A pepper grinder" },
"word_count": 1812,
"published_url": null,
"updated_at": "2026-09-06T06:31:12+00:00",
"quality": { "seo_score": 88, "language_score": 96, "language_findings": [] },
"exchange_links": []
}
}
Intom ittellgħu l-artiklu live; hawnhekk tgħidulna l-indirizz. Dan huwa l-uniku endpoint li jibdel xi ħaġa.
Tagħmel eżatt dak li tagħmel delivery li nagħmlu aħna stess: l-artiklu jiġi mmarkat bħala published, l-allokazzjoni ta’ kull xahar tiegħek tgħoddu, l-oġġett tal-pjan jingħalaq, kull exchange link fih tieħu l-indirizz li l-verifier kien qed jistenna, u l-Facebook Page tiegħek tiġi infurmata jekk tkun qabbadt waħda. Mingħajr din is-sejħa l-artiklu jibqa’ ready għal dejjem u xejn minn dan ma jiġri.
Eżempju
curl -X POST https://seonis.ai/api/v1/articles/918/published \
-H "Authorization: Bearer $SEONIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://peppervale.co.uk/blog/how-to-choose-a-pepper-grinder"}'
Tweġibiet
| 200 | Irreġistrat. L-artiklu jiġi lura bl-istatus il-ġdid tiegħu, published_at u published_url. |
| 422 | Il-url nieqes jew mhuwiex indirizz sħiħ http:// jew https://. |
| 409 | L-artiklu mhux lest biex jiġi ppubblikat, jew diġà huwa rreġistrat bħala ppubblikat. L-artiklu jerġa' jiġi bir-rifjut, sabiex tkunu tistgħu taraw liema minnhom hu. |
Taħt Settings, imbagħad Publishing, hemm magna bl-isem "REST API: you fetch and publish". Ma titlob xejn, għax m'hemm xejn x'nibagħtu. Dak li tbiddel huwa dak li jiġri kull filgħodu: artiklu lest jibqa' lest mingħajr indirizz, u l-iskrin tal-pubblikazzjoni jgħid li qed jistenna li tiġbruh intom minflok ma juri kunsinna li falliet.
Tistgħu tużaw l-API mingħajr ma tqabbduha: l-endpoints jaħdmu għal kwalunkwe kont b'ċavetta. Li tqabbduha huwa kif il-bqija tal-prodott ikun jaf li għandu jieqaf jistenna indirizz tiegħu stess, u huwa dak li jwaqqaf artiklu li tippubblikaw intom stess milli jingħadd bħala falliment.
Forma waħda kullimkien, kemm jekk ir-rifjut ġie mill-key check kif ukoll mill-validator, sabiex xejn ma jkollu jparseja tnejn.
{ "message": "That API key is not valid, or it has been revoked." }
| Status | Xi jfisser |
|---|---|
| 401 | L-ebda key, key li mhijiex tagħna, jew key li ġiet revokata. |
| 404 | M’hemmx artiklu jew sit bħal dan f’dan il-kont. Artiklu ta’ kont ieħor iwieġeb 404 aktar milli 403: API li tgħid "dak mhux tiegħek" tkun ikkonfermat li l-ħaġa teżisti. |
| 409 | It-talba kienet tajba iżda l-artiklu mhux fi stat adattat għal dan. |
| 422 | Parametru nieqes jew ħażin. It-tweġiba ġġorr errors object li jsemmi l-field, kif ukoll il-messaġġ. |
| 429 | Qabeż ir-rate limit. Retry-After jgħid kemm għandek tistenna. |
#!/usr/bin/env bash
set -euo pipefail
# 1. What is finished and not yet on the site?
ready=$(curl -sG https://seonis.ai/api/v1/articles \
-H "Authorization: Bearer $SEONIS_API_KEY" \
-d site_id=5 -d status=ready -d per_page=100)
for id in $(echo "$ready" | jq -r '.articles[].id'); do
# 2. Take the article, body and all.
curl -s https://seonis.ai/api/v1/articles/$id \
-H "Authorization: Bearer $SEONIS_API_KEY" \
| jq -r '.article.content_markdown' > "content/posts/$id.md"
# 3. Your build puts it live, and you know where it landed.
slug=$(echo "$ready" | jq -r ".articles[] | select(.id==$id) | .slug")
curl -s -X POST https://seonis.ai/api/v1/articles/$id/published \
-H "Authorization: Bearer $SEONIS_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"url\": \"https://peppervale.co.uk/blog/$slug\"}"
done
Il-prova hija biżżejjed biex taqraw l-API: l-artikli miktuba matulha huma artikli reali, u jerġgħu jiġu lura minn dawn l-endpoints bħal kwalunkwe oħrajn.
Ibda prova bla ħlas