Kehittäjäopas

Tunnistautuminen

Luo API-avain hallintapaneelin asetusten kohdassa API ja webhookit. Avaimet alkavat merkkijonolla ss_live_, kuuluvat yhteen työtilaan ja voidaan rajata tiettyihin projekteihin. Lähetä avain bearer-tunnuksena jokaisessa pyynnössä:

curl https://www.amaposta.com/api/v1/me \
  -H "Authorization: Bearer ss_live_…"

Vastaus nimeää avaimen, sen oikeudet ja työtilan. Jokaisella avaimella on vähintään yksi oikeus:

Kullakin avaimella voi tehdä 120 pyyntöä minuutissa. Sen jälkeen saat vastauksen 429 koodilla rate_limited; odota hetki ja yritä uudelleen.

Projektit ja kanavat

Julkaisut kuuluvat projektiin. Listaa avaimellesi näkyvät projektit ja sitten yhden projektin kanavat. Tarvitset kanavan tunnuksen kohdistaaksesi julkaisun siihen tai muuttaaksesi sen tekstiä.

curl https://www.amaposta.com/api/v1/projects \
  -H "Authorization: Bearer $AMAPOSTA_KEY"

curl https://www.amaposta.com/api/v1/projects/$PROJECT_ID/channels \
  -H "Authorization: Bearer $AMAPOSTA_KEY"

Kanavalla on provider (youtube, instagram, tiktok, x, facebook, custom tai sandbox), status (active, expiring, needs_reconnect, error tai disabled) ja tuetut julkaisutyypit kentässä supports.

Lataa mediaa

Kuvat ja videot ladataan kerran projektia kohti, ja niitä voi käyttää rajattomassa määrässä julkaisuja. Lataamiseen on kolme tapaa.

Suora lataus

Lähetä tiedosto multipart-lomakedatana kentässä file. Sopii parhaiten enintään muutaman sadan Mt:n tiedostoille.

curl https://www.amaposta.com/api/v1/projects/$PROJECT_ID/media \
  -H "Authorization: Bearer $AMAPOSTA_KEY" \
  -F "[email protected]"

Etukäteen allekirjoitettu lataus suurille tiedostoille

Pyydä latausosoite, lähetä tavut PUT-pyynnöllä suoraan tallennustilaan ja ilmoita sitten Amapostalle valmistumisesta.

# 1. Ask for an upload URL. The response is {"media": { … }, "upload_url": "…"}
curl https://www.amaposta.com/api/v1/projects/$PROJECT_ID/media/uploads \
  -H "Authorization: Bearer $AMAPOSTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "batch-142.mp4", "content_type": "video/mp4", "size_bytes": 48213844}'

# 2. Upload the bytes to upload_url
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: video/mp4" \
  --upload-file batch-142.mp4

# 3. Finish the upload
curl -X POST https://www.amaposta.com/api/v1/media/$MEDIA_ID/complete \
  -H "Authorization: Bearer $AMAPOSTA_KEY"

Tuo verkko-osoitteesta

Anna Amapostalle julkinen osoite, niin se lataa tiedoston taustalla. Voit myös ohittaa tämän vaiheen ja antaa kentän media_url julkaisua luodessasi.

curl https://www.amaposta.com/api/v1/projects/$PROJECT_ID/media/import \
  -H "Authorization: Bearer $AMAPOSTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://cdn.example.com/batch-142.mp4"}'

Jokainen lataus palauttaa mediaobjektin. Sen status muuttuu tilasta pending tilaan processing ja sitten ready (tai failed, jolloin mukana on error). Käsittelyn jälkeen mukana ovat width, height, duration_ms ja pikkukuva. Kysy tilaa kutsulla GET /api/v1/media/{id} tai kuuntele media.ready-webhookia. Palautettu url on allekirjoitettu ja voimassa 12 tuntia.

Luo julkaisu

POST /api/v1/projects/{project_id}/posts luo yhden julkaisun, jolla on toimitus kullekin kanavalle. Amaposta mukauttaa sen alustakohtaisesti: otsikot välitetään vain alustoille, joilla on otsikkokenttä, ja aihetunnisteet välitetään YouTubeen tunnisteina ja muualle tekstin osana.

curl https://www.amaposta.com/api/v1/projects/$PROJECT_ID/posts \
  -H "Authorization: Bearer $AMAPOSTA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: episode-142" \
  -d @- <<'JSON'
{
  "kind": "video",
  "title": "How we roast a batch in 12 minutes",
  "description": "From green beans to first crack. We filmed one batch start to finish.",
  "hashtags": ["coffee", "behindthescenes"],
  "media_url": "https://cdn.example.com/batch-142.mp4",
  "cover_url": "https://cdn.example.com/batch-142-cover.jpg",
  "overrides": {
    "<x-channel-id>": {
      "description": "Batch 142 is out: green beans to first crack in 12 minutes."
    },
    "<youtube-channel-id>": {
      "options": { "privacy": "unlisted" }
    }
  },
  "schedule": { "mode": "queue" },
  "external_ref": "episode-142",
  "metadata": {
    "pipeline": { "name": "nightly-cut", "run": "2026-10-17" }
  }
}
JSON

Kentät

Vastaus on julkaisu, jonka deliveries-kentässä on yksi tietue kanavaa kohti.

Turvalliset uusintayritykset

Verkoissa pyyntöjä katoaa. Lähetä Idempotency-Key-otsake julkaisua luodessasi, jolloin uusintayritys samalla avaimella palauttaa ensimmäisellä yrityksellä luodun julkaisun uuden luomisen sijaan. Käytä oman järjestelmäsi pysyvää arvoa, kuten työn tai jakson tunnusta. Avaimet katkaistaan 200 merkkiin.

Ajasta ja julkaise

Ajasta luonnos, julkaise se nyt, lisää jonoon tai poista kalenterista kutsulla POST /api/v1/posts/{post_id}/schedule.

curl https://www.amaposta.com/api/v1/posts/$POST_ID/schedule \
  -H "Authorization: Bearer $AMAPOSTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode": "at", "at": "2026-10-20T07:00:00Z"}'

• atJulkaisee annettuna aikana, enintään kahden vuoden päästä.
• nowJulkaisee heti.
• queueKäyttää julkaisun kanavien seuraavaa vapaata julkaisuaikaa seuraavien 12 viikon aikana.
• unscheduleSiirtää julkaisun takaisin luonnoksiin.

Ennen ajastamista suoritetaan samat tarkistukset kuin julkaisueditorissa. Jos jokin epäonnistuu, pyyntö palauttaa koodin 400 ja viestin, kuten Korjaa ennen ajastamista: YouTube vaatii otsikon. Ajastaminen vaatii posts:publish-oikeuden tai projektin, jossa hyväksynnät ovat käytössä. Tällöin julkaisu odottaa tarkistusjonossa.

Lue julkaisuja ja toimituksia

Listaa projektin julkaisut suodatettuina kentällä status (pilkuin erotetut tilat tai inbox, queue tai history), aikavälillä from/to sekä kentillä limit ja offset. Vastaus on {"items": […], "total": n}.

curl "https://www.amaposta.com/api/v1/projects/$PROJECT_ID/posts?status=queue" \
  -H "Authorization: Bearer $AMAPOSTA_KEY"

curl https://www.amaposta.com/api/v1/posts/$POST_ID \
  -H "Authorization: Bearer $AMAPOSTA_KEY"

Julkaisulla on yleinen status (draft, in_review, changes_requested, ready, scheduled, publishing, published, partial tai failed) ja yksi toimitus kanavaa kohti:

"deliveries": [
  {
    "id": "0192b7d4-…",
    "channel_id": "0192b7a1-…",
    "status": "published",
    "url": "https://www.youtube.com/watch?v=…",
    "error": null,
    "published_at": "2026-10-20T07:00:41Z"
  },
  {
    "id": "0192b7d4-…",
    "channel_id": "0192b7a9-…",
    "status": "failed",
    "url": null,
    "error": {
      "code": "endpoint_unavailable",
      "message": "Your endpoint returned 503 Service Unavailable",
      "hint": "Amaposta will retry with backoff."
    },
    "published_at": null
  }
]

Toimituksen tilat ovat pending, scheduled, publishing, processing, published, failed ja cancelled. DELETE /api/v1/posts/{post_id} poistaa julkaisun.

Virheet

Jokaisella virheellä on sama rakenne: error-objekti, jossa on pysyvä code, käyttäjälle näytettävä message sekä joskus fields (kenttäkohtaiset viestit) ja hint.

{
  "error": {
    "code": "validation",
    "message": "Please fix the highlighted fields.",
    "fields": {
      "kind": "Use text, image or video."
    }
  }
}

Webhookit

Lisää päätepiste asetusten API ja webhookit -kohtaan, valitse haluamasi tapahtumat ja kopioi allekirjoitussalaisuus. Amaposta lähettää jokaisen tapahtuman osoitteeseesi POST-pyyntönä JSON-muodossa. Jos vastaus on muu kuin 2xx tai sitä ei tule 15 sekunnissa, pyyntöä yritetään uudelleen pitenevin välein. Jatkuvasti epäonnistuvat päätepisteet poistetaan käytöstä ja ylläpitäjille ilmoitetaan.

POST /your/webhook HTTP/1.1
Content-Type: application/json
User-Agent: Amaposta-Webhooks/1.0
X-Amaposta-Event: post.published
X-Amaposta-Event-Id: 0192b7e0-…
X-Amaposta-Signature: t=1792479641,v1=5f2b0c…

{
  "id": "0192b7e0-…",
  "type": "post.published",
  "created_at": "2026-10-20T07:00:41Z",
  "project_id": "0192a3f1-…",
  "data": {
    "post_id": "0192b7c8-…",
    "delivery_id": "0192b7d4-…",
    "channel_id": "0192b7a1-…",
    "provider": "youtube",
    "external_id": "…",
    "url": "https://www.youtube.com/watch?v=…"
  }
}

Varmista allekirjoitus

X-Amaposta-Signature on t=<unix seconds>,v1=<hex>, jossa v1 on raa'asta pyynnön rungosta laskettu HMAC_SHA256(secret, t + "." + body). Laske se itse, vertaa vakioaikaisesti ja hylkää vanhat aikaleimat uudelleentoistohyökkäysten estämiseksi.

import crypto from "node:crypto";

// rawBody: the request body exactly as received (string or Buffer).
export function verifySignature(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=", 2)));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest();
  const given = Buffer.from(parts.v1 ?? "", "hex");
  return given.length === expected.length && crypto.timingSafeEqual(given, expected);
}

import hashlib
import hmac
import time


def verify_signature(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t = int(parts.get("t", "0"))
    if abs(time.time() - t) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

Custom API -kanava julkaisee ylläpitämääsi HTTPS-päätepisteeseen: sisällönhallintajärjestelmään, uutiskirjetyökaluun tai alustalle, jota Amaposta ei vielä tue. Se näkyy kalenterissa, ja siihen sovelletaan tarkistuksia, hyväksyntöjä ja uusintayrityksiä kuten muihinkin kanaviin. Julkaisuhetkellä Amaposta lähettää yhden POST-pyynnön toimitusta kohti:

POST /amaposta/publish HTTP/1.1
Authorization: Bearer <your API key>
Content-Type: application/json
Idempotency-Key: 0192b7d4-…
X-Amaposta-Delivery: 0192b7d4-…
X-Amaposta-Signature: t=1792479600,v1=9ac41e…

{
  "id": "0192b7d4-…",
  "type": "post.publish",
  "created_at": "2026-10-20T07:00:00Z",
  "content": {
    "kind": "video",
    "title": "How we roast a batch in 12 minutes",
    "text": "From green beans to first crack. We filmed one batch start to finish.",
    "hashtags": ["coffee", "behindthescenes"],
    "media": {
      "url": "https://…",
      "content_type": "video/mp4",
      "size_bytes": 48213844,
      "width": 1080,
      "height": 1920,
      "duration_ms": 58000,
      "filename": "batch-142.mp4"
    },
    "cover": null,
    "options": {}
  },
  "post": {
    "id": "0192b7c8-…",
    "external_ref": "episode-142",
    "scheduled_at": "2026-10-20T07:00:00Z",
    "metadata": {
      "pipeline": { "name": "nightly-cut" }
    }
  },
  "project": { "id": "0192a3f1-…", "name": "Spring launch" },
  "channel": { "id": "0192b7a9-…", "name": "api.example.com" }
}

Authorization

API-avaimesi. Otsakkeen nimi ja etuliite (oletuksena Bearer) määritetään kanavalla.

Idempotency-Key

Toimituksen tunnus. Saman toimituksen uusintayritys lähettää saman avaimen, joten voit ohittaa jo tehdyn työn.

X-Amaposta-Delivery

Toimituksen tunnus uudelleen lokitusta varten.

X-Amaposta-Signature

Allekirjoitetaan kuten webhookit, kanavan omalla allekirjoitussalaisuudella.

Vastaaminen

• 2xxJulkaistu. Voit palauttaa arvon {"id": "…", "url": "…"}, jolloin linkki näkyy julkaisussa.
• 401, 403Avain hylättiin. Kanava merkitään uudelleenyhdistettäväksi ja ylläpitäjille ilmoitetaan. Älä käytä näitä koodeja virheelliselle allekirjoitukselle.
• 5xx, 408, 429Tilapäinen. Amaposta yrittää uudelleen pitenevin välein.
• Muu 4xxJulkaisu merkitään epäonnistuneeksi viestisi kera, ja käyttäjä voi korjata sen ja painaa Yritä uudelleen.

app.post("/amaposta/publish", express.raw({ type: "application/json" }), async (req, res) => {
  const signature = req.get("X-Amaposta-Signature") ?? "";
  if (!verifySignature(req.body, signature, process.env.AMAPOSTA_SIGNING_SECRET)) {
    return res.status(400).json({ message: "Bad signature" });
  }
  const delivery = JSON.parse(req.body);
  const item = await publishToYourSystem(delivery.content, req.get("Idempotency-Key"));
  res.json({ id: item.id, url: item.url });
});

Päätepisteesi on oltava saavutettavissa internetistä; uudelleenohjauksia ei seurata. Kanavaa yhdistettäessä Amaposta tarkistaa sen GET-pyynnöllä määrittämääsi yhteystarkistuksen osoitteeseen tai OPTIONS-pyynnöllä päätepisteeseen.

Sandbox-kanava toimii oikean kanavan tavoin, mutta mitään ei siirry Amapostan ulkopuolelle. Rakenna ja testaa sillä integraatiosi alusta loppuun: julkaisut ajastetaan, siirtyvät lähetykseen, julkaistaan tai epäonnistuvat ja laukaisevat samat webhookit. Sandbox-kanavat ovat maksuttomia kaikissa tilauksissa, eikä niitä lasketa kanavarajaan.

Valitse, miten kanava toimii lisäämisen jälkeen:

• Onnistu ainaJokainen julkaisu onnistuu.
• Epäonnistu silloin tällöinTutustu virheisiin ja uusintayrityksiin odottamatta oikeaa käyttökatkoa.
• Epäonnistu ainaTestaa post.failed-käsittelysi.
• Vanhentunut yhteysKatso, miltä uudelleenyhdistämisen ilmoitukset ja linkit näyttävät käyttöoikeuden vanhetessa.