Skip to main content
Overview

API Reference

The Gobi API lets you integrate Collections and Stories into your Content Management System (CMS), Applicant Tracking System (ATS), or other content systems. The API provides access to Teams, Collections, and Stories, which you can use to populate options in your content system.

API responses give you the information to build the user interface with relevant labels and values, display previews of Collections or Stories with our embed script, or create custom thumbnails for richer user interfaces.

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

Security

The API uses an API key for authentication. Please note the following:

  • Only use the API key for server-side requests or on pages where the user is authenticated and has access to the resources.
  • The API key provides access to all endpoints for a single organization in Gobi.
  • Never expose the API key in client-side code or public repositories.
⚠
Never expose the API key in client-side code, frontend applications, or public Git repositories. Always use a server-side proxy.
Overview

Authentication

To authenticate your requests, you need to include the API key in the Authorization header as a Bearer token:

Header 
Authorization: Bearer YOUR_API_KEY

Example — cURL

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

Example — JavaScript fetch

JavaScript 
const API_KEY = process.env.GOBI_API_KEY; // Never hardcode!

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

const data = await res.json();

HTTP status codes

Code Status Description
401 Unauthorized Invalid or missing API key
403 Forbidden The key does not have access to the resource
404 Not Found The resource does not exist
429 Too Many Requests Rate limit exceeded — wait and try again
Overview

Gobi SDK

If you have loaded the Gobi Web Integration script, you can use the Gobi SDK to interact with the API easily.

Initialization

JavaScript 
const api = gobi.api(apiKey);

Fetching data

Once you have an API client instance, you can use the following methods:

JavaScript 
// Fetch all teams
const teams = await api.teams();

// Fetch all collections
const collections = await api.collections();

// Fetch all stories
const stories = await api.stories();

// Fetch collections for a specific team
const collections = await api.collections(teamId);

// Fetch stories for a specific team
const stories = await api.stories(teamId);

Shorthand

If you only need all Collections or Stories for the account, you can use these shortcuts:

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

Error handling

SDK methods throw a GobiApiException on API errors or network issues. Always use try-catch:

JavaScript 
try {
  const collections = await api.collections();
  // ... process collections
} catch (error) {
  if (error instanceof GobiApiException) {
    console.error(`API error (${error.statusCode}): ${error.message}`);
  } else {
    console.error('An unexpected error occurred:', error);
  }
}
Endpoints

Teams

Fetch all teams. You can use teams to filter Collections and Stories.

GET /access/v1/teams Fetch all teams

Request

This endpoint requires no parameters.

Response fields

Field Type Description
id string Unique identifier for the team
name string Name of the team
organizationId string Identifier for the organization

Example response

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

Collections

Fetch all Collections, or all Collections for a specific team, sorted by title.

GET /access/v1/collections Fetch all collections

Query parameters

Parameter Type Required Description
teamId string No Identifier for the team to filter Collections by

Response fields

Field Type Description
id string Identifier for the Collection
teamId string ID of the team that the Collection belongs to
organizationId string Identifier for the organization
tag string Value that can be used with teamId to load a Collection instead of collectionId
title string Title of the Collection
embedType string Embed type for the Collection ("bubbles" or "cards")
storyIds string[] List of Story IDs included in the Collection
createdAt number UNIX timestamp (in seconds) for when the Collection was created
publishedAt number UNIX timestamp (in seconds) for when the Collection was published

Example response

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

Stories

Fetch all stories, or all stories for a specific team, sorted by title.

GET /access/v1/stories Fetch all stories

Query parameters

Parameter Type Required Description
teamId string No Identifier for the team to filter stories by

Response fields

Field Type Description
id string Unique identifier for the story (5-character alphanumeric string)
teamId string Identifier for the team that the Story belongs to
organizationId string Identifier for the organization
title string Title of the story as displayed in Studio
displayTitle string Display title as shown in embeds (same as title if not set)
thumbnailUrl string URL for small square thumbnail image (used for bubble thumbnails)
webmThumbnailUrl string WebM format URL for thumbnail video
mp4ThumbnailUrl string MP4 format URL for thumbnail video
coverUrl string URL for portrait thumbnail image (used for card thumbnails)
webmCoverUrl string WebM format URL for cover video
mp4CoverUrl string MP4 format URL for cover video
posterUrl string URL for the first frame of the Story video (placeholder for Story Player)
watchUrl string URL to watch the story on player.gobistories.com
createdAt number UNIX timestamp (in seconds) for when the Story was created
publishedAt number UNIX timestamp (in seconds) for when the Story was published

Example response

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

Build your own integration

Here is how you can build a CMS plugin or custom integration with the Gobi API.

Example — CMS plugin (JavaScript)

JavaScript 
// Fetch collections and display a picker
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;
}

Best practices

  • Never expose the API key in client-side code — always use a server-side proxy
  • Cache API responses for 5-15 minutes to reduce load
  • Use the Gobi Player for playback — do not build your own video player
  • Listen to Player events for analytics in your own system
ℹ
Use the tag field from the collections endpoint as the value for data-gobi-stories in the embed code.
Resources

Error handling

All API errors are returned as JSON with an error message and HTTP status code.

HTTP status codes

Code Status Description
200 OK The request was successful
401 Unauthorized Invalid or missing API key
403 Forbidden The key does not have access to the resource
404 Not Found The resource does not exist
429 Too Many Requests Rate limit exceeded — wait and try again

SDK error handling

Use GobiApiException to catch API-specific errors:

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

Need help with your API integration?

We are happy to help you get started.