API V1 · PRIVAT BETA

Pliing API

Base-URL: https://api.pliing.app/v1. JSON inn og ut, med Bearer-token i Authorization-headeren.

Prøv et eget varsel

ID alene er ikke nok. Bruk en API key fra appen eller konsollen. Nøkkelen sendes bare direkte til Pliing API og lagres ikke av prøvesenderen.

Din PliingID

API key

Tittel

MeldingDette er ditt eget testvarsel.

NivåInformasjonViktigKritisk

LydSystemlydPlingChimeDropPulseAlert

Pliing

Nivået omgår ikke Fokus eller stillemodus. Push følger tillatelsene på enhetene dine.

Send ekte varselTøm nøkkelKopier curl

Prøvesenderen sender et ekte varsel. Mottakeren må ha godkjent prosjektet. Appnøkler er låst til din egen ID.

Vis JSON

API-svar

Mottaker og tilgang er to ulike ting

Pliing-ID er mottakerens adresse, for eksempel pliing-7m3k9-xr2n8-q4v6. Den er ikke en hemmelighet og gir ingen senderett. API key-en autentiserer integrasjonen, og gir bare rettigheter for ett prosjekt. Mottakeren må godkjenne prosjektet før sending.

ID-formatet er pliing-xxxxx-xxxxx-xxxx, og mottakeren kopierer den fra innboksen i Pliing-appen. Ikke bruk Apple-ID, e-post eller et APNs-enhetstoken som to.

Koble til en annen tjeneste

For tjenester som skal varsle sine egne brukere. Opprett en organisasjon og API keys i konsollen på console.pliing.li. Nøkler krever et aktivt månedlig abonnement.

1. Brukeren velger Pliing i tjenestens varselinnstillinger og limer inn sin Pliing-ID.
2. Tjenestens backend bruker sin egen API key til å opprette en samtykkeforespørsel. Brukerens API key skal aldri etterspørres.
3. Vis «Venter på godkjenning» hos tjenesten. Brukeren åpner Pliing → Avsendere og godkjenner forespørselen.
4. Tjenesten sjekker GET /v1/consent-requests/{id} med sin API key. Vis «Tilkoblet» først når status er approved og notifications er true.
5. Send til brukerens ID. Ved senere consent_required, stopp sending og vis at forbindelsen trenger godkjenning.

En tjeneste får bare lese status for egne forespørsler. Status revoked gir ingen senderett; en ny POST godkjenner ikke avsenderen på nytt. Koder krever separat tillatelse.

Egne scripts

Opprett et prosjekt og en API key i Pliing-appen. Nøkler fra appen er låst til din egen Pliing-ID og kan ikke sende til andre. ID-en din går i to; nøkkelen er hemmelig og går i Authorization.

Send et varsel

Bruk en API key med notifications:send. Hold nøkkelen på serveren din, utenfor klientkode og versjonskontroll.

curl https://api.pliing.app/v1/notifications \
  -H "Authorization: Bearer $PLIING_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: deploy-prod-1842" \
  -d '{
    "to": "pliing-7m3k9-xr2n8-q4v6",
    "title": "Deploy ferdig",
    "body": "main → production. Alt er oppe.",
    "level": "info"
  }'

title: maks 160 tegn. body: maks 4000 tegn. level: info, important eller critical; standard er info. Dette er visningsnivåer og gir ikke Apples særskilte Critical Alerts-rettighet.

Lyd

Valgfritt felt sound velger varsellyden på mottakerens enheter. Utelatt eller default bruker systemlyden. Ukjent verdi gir HTTP 422.

curl https://api.pliing.app/v1/notifications \
  -H "Authorization: Bearer $PLIING_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: deploy-prod-1843" \
  -d '{"to": "pliing-7m3k9-xr2n8-q4v6", "title": "Deploy feilet", "body": "main → production", "level": "important", "sound": "alert"}'

Lyden hører til varselet og inngår i idempotens-sjekken: samme nøkkel med en annen lyd gir HTTP 409. Engangskoder bruker alltid systemlyden. Brukerens Ikke forstyrr, Fokus og lydinnstillinger i iOS gjelder fortsatt.

Ikon

Valgfritt felt icon_url gir varselet et ikon i mottakerens innboks, for eksempel logoen til tjenesten din. Adressen må være en offentlig HTTPS-adresse rett til et bilde på nøyaktig 128 × 128 piksler, i PNG, JPEG eller WebP, på maks 64 KB. Videresending følges ikke.

Pliing henter bildet én gang når varselet sendes, kontrollerer det og lagrer en kopi. Mottakerens enhet laster ikonet fra Pliing og ikke fra serveren din, så du ser ikke når eller hvor et varsel åpnes. Samme adresse hentes på nytt først etter 24 timer, så bruk en ny adresse når du bytter ikon. Ikonet vises i innboksen og lesevisningen. Det sendes ikke i push-varselet og brukes ikke for engangskoder.

curl https://api.pliing.app/v1/notifications \
  -H "Authorization: Bearer $PLIING_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: deploy-prod-1844" \
  -d '{"to": "pliing-7m3k9-xr2n8-q4v6", "title": "Deploy ferdig", "body": "main → production", "icon_url": "https://example.com/pliing-icon.png"}'

Kan ikke ikonet hentes eller godkjennes, avvises hele forespørselen med HTTP 422, og message er én av disse kodene: icon_unavailable (kunne ikke hentes, er for stort eller er ikke en offentlig HTTPS-adresse), icon_invalid_format (ikke PNG, JPEG eller WebP) eller icon_invalid_size (ikke 128 × 128 piksler). Ikonet inngår i idempotens-sjekken: samme nøkkel med et annet ikon gir HTTP 409.

Handlinger

Valgfritt felt actions legger opptil tre knapper på varselet. Hver knapp har title (1–30 tegn, uten linjeskift), url (HTTPS, maks 2048 tegn) og type.

• trigger (standard): når mottakeren trykker knappen, kaller Pliing adressen din med en POST fra våre servere. Adressen må være offentlig. Mottakerens IP-adresse og konto røpes ikke, og adressen sendes aldri til enheten, så du kan legge en hemmelig token i den.
• open: knappen åpner adressen i mottakerens nettleser.

curl https://api.pliing.app/v1/notifications \
  -H "Authorization: Bearer $PLIING_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: deploy-prod-1845" \
  -d '{"to": "pliing-7m3k9-xr2n8-q4v6", "title": "Deploy venter", "body": "Godkjenn utrullingen til production.", "actions": [
    {"title": "Godkjenn", "url": "https://ci.example.com/hooks/approve/9f3a"},
    {"title": "Avvis", "url": "https://ci.example.com/hooks/deny/9f3a", "type": "trigger"},
    {"title": "Se logg", "url": "https://ci.example.com/runs/1845", "type": "open"}
  ]}'

Forespørselen til en trigger-adresse er JSON med event (pliing.action), notification_id, idempotency_key (nøkkelen du sendte varselet med), action (0, 1 eller 2), action_title og pressed_at. Overskriften Idempotency-Key: pliing-action-{notification_id}-{action} er den samme ved nye forsøk. Svar med et 2xx-svar innen 8 sekunder. Videresending følges ikke, og svaret leses ikke.

En knapp som har lyktet kan ikke trykkes igjen for det varselet. Svarer adressen med noe annet enn 2xx, eller ikke i tide, får mottakeren en feil og kan prøve på nytt. Bruk engangsadresser eller adresser som utløper for handlinger som godkjenner noe, siden knappene ligger i innboksen i 90 dager. Knappene virker bare så lenge mottakeren har godkjent avsenderen, og følger ikke med engangskoder.

Ugyldige handlinger gir HTTP 422, med feltet i errors, for eksempel actions.0.url. Handlingene inngår i idempotens-sjekken. Knappene vises i appen når varselet åpnes. Knapper direkte i push-varselet på låseskjermen støttes ikke ennå.

HTTP 202
{"id":1842,"status":"accepted","duplicate":false}

Idempotency-Key er påkrevd: 8–128 tegn, bokstaver, tall eller _.:-. Samme nøkkel og innhold gir samme ID med HTTP 200. Samme nøkkel med annet innhold gir HTTP 409. Nøkkelen er avgrenset til prosjektet.

AI-varsler med MCP

Koble til assistenten for å sende fremdrift, stille spørsmål med handlingsknapper og hente mottakerens svar. Bruk en egen nøkkel som er bundet til ett prosjekt og én godkjent mottaker.

MCP-oppsett og komplette eksempler →

Send en engangskode

Bruk det egne endepunktet POST /v1/codes. Mottakeren må godkjenne koder separat under Avsendere; tillatelse til vanlige varsler er ikke nok. Be om codes: true når integrasjonen ber om samtykke.

Har avsenderen allerede tillatelse til varsler? Send en ny samtykkeforespørsel med koder aktivert. Eksisterende varseltillatelse beholdes, men mottakeren må åpne avsenderen under Avsendere og slå på Engangskoder. Vent til status viser både godkjenning og kodetillatelse før sending; et tidligere avslag oppheves ikke.

curl https://api.pliing.app/v1/codes \
  -H "Authorization: Bearer $PLIING_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: login-code-001" \
  -d '{"to":"pliing-7m3k9-xr2n8-q4v6","title":"Innloggingskode","code":"123456","ttl_seconds":300}'

code: 3–64 tegn. ttl_seconds: 30–600 sekunder, standard 300. Samme hendelsesnøkkel og innhold gir samme kodevarsel uten duplikater.

Kodevarsler har egen låst visning i appen, med utløpstid og kopierknapp etter enhetsautentisering. Koden lagres kryptert og sendes aldri i push-payloaden eller den vanlige innboksresponsen. Etter utløp kan den ikke hentes.

Pliing leverer koden. Tjenesten som utsteder den må kontrollere koden og sørge for at den bare kan brukes én gang.

Be om lov før du sender

curl https://api.pliing.app/v1/consent-requests \
  -H "Authorization: Bearer $PLIING_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to":"pliing-7m3k9-xr2n8-q4v6","notifications":true,"codes":false}'

HTTP 201
{"id":42,"status":"pending"}

Mottakeren godkjenner under Avsendere i appen. Før godkjenning, og etter tilbakekalling, avvises nye leveranser med HTTP 403 og {"message":"consent_required"}. En ny forespørsel opphever ikke et avslag.

curl https://api.pliing.app/v1/consent-requests/42 \
  -H "Authorization: Bearer $PLIING_TOKEN"

HTTP 200
{"id":42,"status":"approved","notifications":true,"codes":false,
 "requested_notifications":true,"requested_codes":false}

Sjekk status med noen sekunders mellomrom mens brukeren godkjenner. Respekter HTTP 429. En tjeneste uten Pliing-støtte kan ikke bruke ID-en alene; den må integrere dette API-et.

Endepunkter

Alle endepunkter unntatt /v1/health krever en API key i Authorization. Nøkkelen kan bare sende; den gir ikke tilgang til mottakerens innboks, engangskoder eller andre avsendere.

Hva betyr levert?

Accepted: API-et har lagret varselet. APNs accepted: Apple har tatt imot pushen. Read: mottakeren har markert innholdet lest i appen. APNs-kvitteringen bekrefter ikke at en banner faktisk er vist eller lest.

Standard push er en generell beskjed om nytt innhold. Mottakeren bestemmer selv om tittel og tekst kan vises på låseskjermen, og kan skru av push per enhet. Engangskoder ligger aldri i push-payloaden. Innboksen i appen er alltid tilgjengelig.

Feil og grenser

Sending er rate-begrenset per nøkkel. Ved 429, vent i henhold til Retry-After. Ved nettverksfeil og midlertidige serverfeil: prøv igjen med ventetid og samme idempotensnøkkel.

← Tilbake til Pliing