Gobi API Documentation

Overview

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

The API responses provide information for you to populate your UI with relevant labels and values, render previews of Collections or Stories using our embed script, or create your own custom thumbnails for richer user interfaces.

Security

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

Use the API key only for server-side requests or on pages where the user is authenticated and has permission to access the resources.
The API key grants access to all endpoints for a single organization within Gobi.
Never expose your API key in client-side code or public repositories.

Base URL

All API requests should be made to:

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

Authentication

To authenticate your requests, you need to include your API key in the Authorization header as a Bearer token. Here's how to format the header:

Authorization: Bearer YOUR_API_KEY

Replace YOUR_API_KEY with your actual API key.

Example using cURL:

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

Make sure to include this header in all your API requests to authenticate them properly.

Using the Gobi SDK

If you have loaded our Gobi Web Integration script, you can use the Gobi SDK to interact with the API easily. Here's how to use it:

Initializing the API Client

To create an API client instance, use the gobi.api() method with your API key:

const api = gobi.api(apiKey);

Fetching Data

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

Get All Teams

const teams = await api.teams();

Get All Collections

const collections = await api.collections();

Get All Stories

const stories = await api.stories();

Get Collections for a Specific Team

const collections = await api.collections(teamId);

Get Stories for a Specific Team

const stories = await api.stories(teamId);

Shorthand for Collections and Stories

If you just need all Collections or Stories for the account, you can use these shorthand methods:

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

Error Handling

The SDK methods will throw a GobiApiException if there's an API error or network issue. Make sure to wrap your calls in a try-catch block:

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

Endpoints

1. Get Teams

Retrieves all Teams. You can use Teams to filter Collections and Stories.

HTTP Method: GET
Endpoint: /teams

Request

This endpoint doesn't require any parameters.

Response

Field	Type	Description
id	string	Identifier for the Team
name	string	Name of the Team
organizationId	string	Identifier for the Organization

Example Response:

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

2. Get Collections

Retrieves all Collections, or all Collections for a specified Team, ordered by title.

HTTP Method: GET
Endpoint: /collections

Request

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

Response

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

Example Response:

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

3. Get Stories

Retrieves all stories, or all stories for a specified Team, ordered by title.

HTTP Method: GET
Endpoint: /stories

Request

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

Response

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
thumbnailUrl	string	URL for a small square image thumbnail (typically used to show a bubble style thumbnail)
webmThumbnailUrl	string	WebM format URL for the thumbnail video
mp4ThumbnailUrl	string	MP4 format URL for the thumbnail video
coverUrl	string	URL for a portrait thumbnail (typically used to show a card style thumbnail)
webmCoverUrl	string	WebM format URL for the cover video
mp4CoverUrl	string	MP4 format URL for the cover video
posterUrl	string	URL for the first frame of the Story video (typically as a placeholder for the Story Player before it starts playing)
createdAt	number	UNIX timestamp (in seconds) of when the Story was created
publishedAt	number	UNIX timestamp (in seconds) of when the Story was published

Example Response:

[
  {
    "id": "pg8bz",
    "teamId": "123e4567-e89b-12d3-a456-426614174000",
    "organizationId": "123e4567-e89b-12d3-a456-426614174001",
    "title": "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",
    "createdAt": 1633027200,
    "publishedAt": 1633113600
  }
]

Usage Notes

You can use the tag field in collections with a teamId to load a Collection instead of using the collection id. This is useful in a CMS or ATS where a collection is made for a particular content section or category and you match the tag to a section id.
The embedType field indicates how a Collection will be displayed when embedded (either as "bubbles" or "cards").
All timestamp fields (createdAt and publishedAt) are in UNIX timestamp format (seconds since epoch).
The various URL fields provide different options for thumbnails and previews:
thumbnailUrl, webmThumbnailUrl, and mp4ThumbnailUrl are for small square images typically shown as circles for 'bubbles'.
coverUrl, webmCoverUrl, and mp4CoverUrl are for portrait thumbnails usually used to show 'cards'.
posterUrl is always an image of the first frame of the Story video.
The base URL for thumbnail and cover images is not fixed and should not be hardcoded in your application. Always use the full URLs provided in the API responses.