Udviklervejledning

Godkendelse

Opret en API-nøgle i kontrolpanelet under Indstillinger, API og webhooks. Nøgler begynder med ss_live_, tilhører ét arbejdsområde og kan begrænses til bestemte projekter. Send nøglen som et bearer-token med hver anmodning:

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

Svaret angiver nøglen, dens tilladelser og arbejdsområdet. Hver nøgle har en eller flere tilladelser:

Hver nøgle kan sende 120 anmodninger i minuttet. Derefter får du 429 med koden rate_limited; vent et øjeblik, og prøv igen.

Projekter og kanaler

Opslag hører til i et projekt. Hent de projekter, din nøgle kan se, og derefter kanalerne i et af dem. Du skal bruge en kanals id for at udgive på den eller tilpasse dens tekst.

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"

En kanal har en provider (youtube, instagram, tiktok, x, facebook, custom eller sandbox), en status (active, expiring, needs_reconnect, error eller disabled) og de opslagstyper, den supports.

Upload medier

Billeder og videoer uploades én gang pr. projekt og kan bruges i et vilkårligt antal opslag. Der er tre veje ind.

Direkte upload

Send filen som multipart-formulardata i et felt med navnet file. Bedst til filer på op til nogle få hundrede MB.

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

Forhåndssigneret upload til store filer

Anmod om en upload-URL, send dataene direkte til lageret med PUT, og giv derefter Amaposta besked om, at du er færdig.

# 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"

Importér fra en URL

Giv Amaposta en offentlig URL, så downloades filen i baggrunden. Du kan også springe dette trin over og angive media_url, når du opretter opslaget.

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"}'

Hver upload returnerer et medieobjekt. Dets status går fra pending til processing til ready (eller failed med en error). Efter behandling indeholder det width, height, duration_ms og et miniaturebillede. Forespørg løbende på GET /api/v1/media/{id}, eller lyt efter webhooken media.ready. Den returnerede url er signeret og gyldig i 12 timer.

Opret et opslag

POST /api/v1/projects/{project_id}/posts opretter ét opslag med en levering til hver kanal. Amaposta tilpasser det til hver platform: Titler sendes kun, hvor der er et titelfelt, hashtags bliver til tags på YouTube og til tekst andre steder.

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

Felter

Svaret er opslaget med én post i deliveries pr. kanal.

Sikre gentagne forsøg

Netværk kan miste anmodninger. Send en Idempotency-Key-header, når du opretter et opslag, så returnerer et nyt forsøg med samme nøgle opslaget fra første forsøg i stedet for at oprette endnu et. Brug noget stabilt fra dit system, f.eks. et opgave- eller episode-id. Nøgler afkortes til 200 tegn.

Planlæg og udgiv

Planlæg en kladde, udgiv den nu, føj den til køen, eller fjern den fra kalenderen med 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"}'

• atUdgiver på det angivne tidspunkt, op til to år frem.
• nowUdgiver med det samme.
• queueTager den næste ledige udgivelsestid for opslagets kanaler i de næste 12 uger.
• unscheduleFlytter opslaget tilbage til kladder.

Før noget planlægges, køres de samme kontroller som i redigeringsværktøjet. Hvis en kontrol fejler, returnerer anmodningen 400 med en besked såsom Ret dette før planlægning: YouTube kræver en titel. Planlægning kræver tilladelsen posts:publish eller et projekt med godkendelser slået til, hvor opslaget venter i indbakken til gennemgang.

Læs opslag og leveringer

Vis et projekts opslag filtreret efter status (kommaseparerede statusser eller inbox, queue eller history), en periode med from/to, limit og offset. Svaret er {"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"

Et opslag har en samlet status (draft, in_review, changes_requested, ready, scheduled, publishing, published, partial eller failed) og én levering pr. kanal:

"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
  }
]

Leveringsstatusser er pending, scheduled, publishing, processing, published, failed og cancelled. DELETE /api/v1/posts/{post_id} fjerner et opslag.

Fejl

Alle fejl har samme struktur: et error-objekt med en stabil code, en message, du kan vise til brugere, og nogle gange fields (beskeder pr. felt) og et hint.

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

Webhooks

Tilføj et endepunkt under Indstillinger, API og webhooks, vælg de ønskede hændelser, og kopiér signeringshemmeligheden. Amaposta sender JSON med POST til din URL for hver hændelse. Alle svar, der ikke er 2xx, eller manglende svar inden for 15 sekunder forsøges igen med stigende intervaller, og endepunkter, der bliver ved med at fejle, slås fra med besked til administratorer.

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=…"
  }
}

Kontrollér signaturen

X-Amaposta-Signature er t=<unix seconds>,v1=<hex>, hvor v1 er HMAC_SHA256(secret, t + "." + body) over anmodningens rå indhold. Beregn den selv, sammenlign i konstant tid, og afvis gamle tidsstempler for at forhindre genafspilning.

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", ""))

En kanal med eget API udgiver til et HTTPS-endepunkt, du driver: dit CMS, et nyhedsbrevsværktøj eller en platform, Amaposta endnu ikke dækker. Den findes i kalenderen og får kontroller, godkendelser og gentagne forsøg som alle andre kanaler. Når et opslag udgives, sender Amaposta én POST pr. levering:

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

Din API-nøgle. Headernavnet og præfikset (Bearer som standard) angives på kanalen.

Idempotency-Key

Leverings-id'et. Et nyt forsøg på samme levering sender samme nøgle, så du kan springe allerede udført arbejde over.

X-Amaposta-Delivery

Leverings-id'et igen, til dine logs.

X-Amaposta-Signature

Signeret som webhooks med kanalens egen signeringshemmelighed.

Sådan svarer du

• 2xxUdgivet. Returnér eventuelt {"id": "…", "url": "…"}, så vises linket på opslaget.
• 401, 403Nøglen blev afvist. Kanalen markeres til genoprettelse af forbindelse, og administratorer får besked. Brug ikke disse til en forkert signatur.
• 5xx, 408, 429Midlertidigt. Amaposta prøver igen med stigende intervaller.
• Andre 4xxOpslaget markeres som mislykket med din besked, og en person kan rette det og trykke på Prøv igen.

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 });
});

Dit endepunkt skal kunne nås fra internettet; omdirigeringer følges ikke. Når du tilslutter kanalen, kontrollerer Amaposta den med GET til din kontrol-URL, hvis du har angivet en, eller med en OPTIONS-anmodning til endepunktet.

En Sandbox-kanal opfører sig som en rigtig kanal, men intet forlader Amaposta. Brug den til at bygge og teste din integration fra ende til ende: Opslag planlægges, går i luften, udgives eller mislykkes og udløser de samme webhooks. Sandbox-kanaler er gratis på alle abonnementer og tæller ikke med i kanalgrænser.

Vælg, hvordan den skal opføre sig, når du tilføjer den:

• Lykkes altidAlle opslag udgives.
• Fejl af og tilSe fejl og gentagne forsøg uden at vente på et rigtigt nedbrud.
• Fejler altidTest din håndtering af post.failed.
• Udløbet forbindelseSe, hvordan advarsler og links til genoprettelse af forbindelse ser ud, når adgang udløber.