Hopp til hovedinnhold
Oversikt

API-referanse

Gobi API lar deg integrere Collections og Stories i ditt Content Management System (CMS), Applicant Tracking System (ATS), eller andre innholdssystemer. API-et gir tilgang til Teams, Collections og Stories, som du kan bruke til å populere valgmuligheter i ditt innholdssystem.

API-responsene gir deg informasjon til å bygge brukergrensesnittet med relevante etiketter og verdier, vise forhåndsvisninger av Collections eller Stories med vårt embed-script, eller lage egne thumbnails for rikere brukergrensesnitt.

Base URL: https://api.gobistories.com/access/v1

Sikkerhet

API-et bruker en API-nøkkel for autentisering. Vær oppmerksom på følgende:

  • Bruk API-nøkkelen kun for server-side forespørsler eller på sider der brukeren er autentisert og har tilgang til ressursene.
  • API-nøkkelen gir tilgang til alle endepunkter for en enkelt organisasjon i Gobi.
  • Eksponer aldri API-nøkkelen i klientkode eller offentlige repositorier.
Aldri eksponer API-nøkkelen i klientkode, frontend-applikasjoner eller offentlige Git-repositorier. Bruk alltid en server-side proxy.
Oversikt

Autentisering

For å autentisere forespørslene dine, må du inkludere API-nøkkelen i Authorization-headeren som en Bearer-token:

Header
Authorization: Bearer YOUR_API_KEY

Eksempel — cURL

Bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.gobistories.com/access/v1/teams

Eksempel — JavaScript fetch

JavaScript
const API_KEY = process.env.GOBI_API_KEY; // Aldri hardkod!

const res = await fetch('https://api.gobistories.com/access/v1/teams', {
  headers: {
    'Authorization': `Bearer ${API_KEY}`
  }
});

const data = await res.json();

HTTP-statuskoder

Kode Status Beskrivelse
401 Unauthorized Ugyldig eller manglende API-nøkkel
403 Forbidden Nøkkelen har ikke tilgang til ressursen
404 Not Found Ressursen finnes ikke
429 Too Many Requests Rate limit overskredet — vent og prøv igjen
Oversikt

Gobi SDK

Hvis du har lastet inn Gobi Web Integration-scriptet, kan du bruke Gobi SDK for å interagere med API-et enkelt.

Initialisering

JavaScript
const api = gobi.api(apiKey);

Hente data

Når du har en API-klientinstans, kan du bruke følgende metoder:

JavaScript
// Hent alle teams
const teams = await api.teams();

// Hent alle collections
const collections = await api.collections();

// Hent alle stories
const stories = await api.stories();

// Hent collections for et spesifikt team
const collections = await api.collections(teamId);

// Hent stories for et spesifikt team
const stories = await api.stories(teamId);

Snarvei

Hvis du bare trenger alle Collections eller Stories for kontoen, kan du bruke disse snarveiene:

JavaScript
const collections = await gobi.api(apiKey).collections();
const stories = await gobi.api(apiKey).stories();

Feilhåndtering

SDK-metodene kaster en GobiApiException ved API-feil eller nettverksproblemer. Bruk alltid try-catch:

JavaScript
try {
  const collections = await api.collections();
  // ... behandle collections
} catch (error) {
  if (error instanceof GobiApiException) {
    console.error(`API-feil (${error.statusCode}): ${error.message}`);
  } else {
    console.error('En uventet feil oppstod:', error);
  }
}
Endepunkter

Teams

Hent alle teams. Du kan bruke teams til å filtrere Collections og Stories.

GET /access/v1/teams Hent alle teams

Forespørsel

Dette endepunktet krever ingen parametre.

Responsfelt

Felt Type Beskrivelse
id string Unik identifikator for teamet
name string Navn på teamet
organizationId string Identifikator for organisasjonen

Eksempelrespons

JSON
[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Marketing Team",
    "organizationId": "123e4567-e89b-12d3-a456-426614174001"
  },
  {
    "id": "123e4567-e89b-12d3-a456-426614174002",
    "name": "Sales Team",
    "organizationId": "123e4567-e89b-12d3-a456-426614174001"
  }
]
Endepunkter

Collections

Hent alle Collections, eller alle Collections for et spesifikt team, sortert etter tittel.

GET /access/v1/collections Hent alle collections

Queryparametre

Parameter Type Påkrevd Beskrivelse
teamId string Nei Identifikator for teamet å filtrere Collections på

Responsfelt

Felt Type Beskrivelse
id string Identifikator for Collection
teamId string ID for teamet som Collection tilhører
organizationId string Identifikator for organisasjonen
tag string Verdi som kan brukes med teamId for å laste en Collection i stedet for collectionId
title string Tittel på Collection
embedType string Type embed for Collection ("bubbles" eller "cards")
storyIds string[] Liste med Story-ID-er inkludert i Collection
createdAt number UNIX-tidsstempel (i sekunder) for når Collection ble opprettet
publishedAt number UNIX-tidsstempel (i sekunder) for når Collection ble publisert

Eksempelrespons

JSON
[
  {
    "id": "123e4567-e89b-12d3-a456-426614174003",
    "teamId": "123e4567-e89b-12d3-a456-426614174000",
    "organizationId": "123e4567-e89b-12d3-a456-426614174001",
    "tag": "summer-campaign",
    "title": "Summer Campaign Collection",
    "embedType": "bubbles",
    "storyIds": ["story1", "story2", "story3"],
    "createdAt": 1633027200,
    "publishedAt": 1633113600
  }
]
Endepunkter

Stories

Hent alle stories, eller alle stories for et spesifikt team, sortert etter tittel.

GET /access/v1/stories Hent alle stories

Queryparametre

Parameter Type Påkrevd Beskrivelse
teamId string Nei Identifikator for teamet å filtrere stories på

Responsfelt

Felt Type Beskrivelse
id string Unik identifikator for story (5-tegns alfanumerisk streng)
teamId string Identifikator for teamet som Story tilhører
organizationId string Identifikator for organisasjonen
title string Tittel på story slik den vises i Studio
displayTitle string Visningstittelen slik den vises i embeds (samme som title hvis ikke satt)
thumbnailUrl string URL for lite kvadratisk miniatyrbilde (brukes til bubble-thumbnails)
webmThumbnailUrl string WebM-format URL for miniatyrvideo
mp4ThumbnailUrl string MP4-format URL for miniatyrvideo
coverUrl string URL for portrettminiatyrbilde (brukes til card-thumbnails)
webmCoverUrl string WebM-format URL for covervideo
mp4CoverUrl string MP4-format URL for covervideo
posterUrl string URL for første frame av Story-videoen (placeholder for Story Player)
watchUrl string URL for å se story på player.gobistories.com
createdAt number UNIX-tidsstempel (i sekunder) for når Story ble opprettet
publishedAt number UNIX-tidsstempel (i sekunder) for når Story ble publisert

Eksempelrespons

JSON
[
  {
    "id": "pg8bz",
    "teamId": "123e4567-e89b-12d3-a456-426614174000",
    "organizationId": "123e4567-e89b-12d3-a456-426614174001",
    "title": "New Product Launch",
    "displayTitle": "New Product Launch",
    "thumbnailUrl": ".../thumbnail/pg8bz.jpg",
    "webmThumbnailUrl": ".../thumbnail/pg8bz.webm",
    "mp4ThumbnailUrl": ".../thumbnail/pg8bz.mp4",
    "coverUrl": ".../cover/pg8bz.jpg",
    "webmCoverUrl": ".../cover/pg8bz.webm",
    "mp4CoverUrl": ".../cover/pg8bz.mp4",
    "posterUrl": ".../poster/pg8bz.jpg",
    "watchUrl": "https://player.gobistories.com/demo01",
    "createdAt": 1633027200,
    "publishedAt": 1633113600
  }
]
Ressurser

Bygg egen integrasjon

Slik kan du bygge en CMS-plugin eller tilpasset integrasjon med Gobi API.

Eksempel — CMS-plugin (JavaScript)

JavaScript
// Hent collections og vis en velger
async function renderCollectionPicker(apiKey) {
  const res = await fetch(
    'https://api.gobistories.com/access/v1/collections',
    { headers: { 'Authorization': `Bearer ${apiKey}` } }
  );
  const collections = await res.json();

  const select = document.createElement('select');
  collections.forEach(col => {
    const opt = document.createElement('option');
    opt.value = col.tag;
    opt.textContent = col.title;
    select.appendChild(opt);
  });
  return select;
}

Beste praksis

  • Eksponer aldri API-nøkkelen i klientkode — bruk alltid en server-side proxy
  • Cache API-responser i 5–15 minutter for å redusere belastning
  • Bruk Gobi Player for visning — ikke bygg egen videospiller
  • Lytt på Player-events for analytics i eget system
Bruk tag-feltet fra collections-endepunktet som verdi for data-gobi-stories i embed-koden.
Ressurser

Feilhåndtering

Alle API-feil returneres som JSON med en feilmelding og HTTP-statuskode.

HTTP-statuskoder

Kode Status Beskrivelse
200 OK Forespørselen var vellykket
401 Unauthorized Ugyldig eller manglende API-nøkkel
403 Forbidden Nøkkelen har ikke tilgang til ressursen
404 Not Found Ressursen finnes ikke
429 Too Many Requests Rate limit overskredet — vent og prøv igjen

SDK-feilhåndtering

Bruk GobiApiException for å fange API-spesifikke feil:

JavaScript
try {
  const teams = await gobi.api('DIN_API_NOKKEL').teams();
} catch (err) {
  if (err instanceof GobiApiException) {
    console.error('API-feil:', err.statusCode, err.message);
  }
}

Trenger du hjelp med API-integrasjonen?

Vi hjelper deg gjerne med å komme i gang.