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.
https://api.gobistories.com/access/v1Sikkerhet
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.
Autentisering
For å autentisere forespørslene dine, må du inkludere API-nøkkelen i Authorization-headeren som en Bearer-token:
Authorization: Bearer YOUR_API_KEY Eksempel — cURL
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://api.gobistories.com/access/v1/teams Eksempel — JavaScript fetch
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 |
Gobi SDK
Hvis du har lastet inn Gobi Web Integration-scriptet, kan du bruke Gobi SDK for å interagere med API-et enkelt.
Initialisering
const api = gobi.api(apiKey); Hente data
Når du har en API-klientinstans, kan du bruke følgende metoder:
// 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:
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:
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);
}
} Teams
Hent alle teams. Du kan bruke teams til å filtrere Collections og Stories.
/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
[
{
"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"
}
] Collections
Hent alle Collections, eller alle Collections for et spesifikt team, sortert etter tittel.
/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
[
{
"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
}
] Stories
Hent alle stories, eller alle stories for et spesifikt team, sortert etter tittel.
/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
[
{
"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
}
] Bygg egen integrasjon
Slik kan du bygge en CMS-plugin eller tilpasset integrasjon med Gobi API.
Eksempel — CMS-plugin (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
tag-feltet fra collections-endepunktet som verdi for data-gobi-stories i embed-koden.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:
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.