Authentication

The Storyteller Public API uses API key authentication to secure all requests. This page explains how to obtain and use your API key.

Getting Your API Key

Your API key can be obtained through the Storyteller CMS:

1. Navigate to the Apps section in the Storyteller CMS
2. Create an app for your target platform - Use the platform you intend to distribute content against (e.g., create an Android app if displaying content on Android, an iOS app for iOS, etc.)
3. Copy your API key from the app settings

Platform-Specific API Keys

Create an API key for each platform where you will display content. Use an Android API key for Android apps, an iOS API key for iOS apps, and so on.

Keep Your API Key Secure

Your API key identifies your application and tenant. Keep it secure and follow your organization's security practices for managing credentials.

Using Your API Key

Pass the API key as a query parameter in all API requests:

GET /api/app/clips/{collectionId}/clips/paged?x-storyteller-api-key=your-api-key-here&ClientPlatform=ios&ClientVersion=11.0.0 HTTP/1.1
Host: api.usestoryteller.com

Required Query Parameters

The following query parameters must be included in your requests:

Parameter	Required	Description
x-storyteller-api-key	Yes	Your API key for authentication
ClientPlatform	Yes	Platform identifier: ios, android, or web
ClientVersion	Yes	Must be set to 11.0.0

Platform Parameter

The ClientPlatform parameter tells the API which platform is making the request, enabling platform-specific optimizations:

• ios - For iOS applications
• android - For Android applications
• web - For web applications

Version Parameter

The ClientVersion parameter must be set to 11.0.0.

Code Examples

JavaScriptPythonC#cURL

const apiKey = 'your-api-key-here';
const baseUrl = 'https://api.usestoryteller.com';

async function getPagedClips(collectionId, pageNumber = 0) {
  const params = new URLSearchParams({
    'x-storyteller-api-key': apiKey,
    'ClientPlatform': 'web',
    'ClientVersion': '11.0.0',
    'pageNumber': pageNumber.toString()
  });

  const response = await fetch(
    `${baseUrl}/api/app/clips/${collectionId}/clips/paged?${params}`,
    { method: 'GET' }
  );

  if (!response.ok) {
    throw new Error(`Request failed: ${response.status}`);
  }

  return await response.json();
}

import requests

api_key = 'your-api-key-here'
base_url = 'https://api.usestoryteller.com'

def get_paged_clips(collection_id: str, page_number: int = 0):
    response = requests.get(
        f'{base_url}/api/app/clips/{collection_id}/clips/paged',
        params={
            'x-storyteller-api-key': api_key,
            'ClientPlatform': 'android',
            'ClientVersion': '11.0.0',
            'pageNumber': page_number
        },
        timeout=30
    )
    response.raise_for_status()
    return response.json()

using System.Net.Http;
using System.Text.Json;

public class StorytellerClient : IDisposable
{
    private readonly HttpClient _httpClient;
    private readonly string _baseUrl = "https://api.usestoryteller.com";
    private readonly string _apiKey;
    private readonly string _platform;

    public StorytellerClient(string apiKey, string platform)
    {
        _apiKey = apiKey;
        _platform = platform;
        _httpClient = new HttpClient();
    }

    public async Task<JsonDocument> GetPagedClipsAsync(
        string collectionId,
        int pageNumber = 0)
    {
        var response = await _httpClient.GetAsync(
            $"{_baseUrl}/api/app/clips/{collectionId}/clips/paged?x-storyteller-api-key={_apiKey}&ClientPlatform={_platform}&ClientVersion=11.0.0&pageNumber={pageNumber}");

        response.EnsureSuccessStatusCode();
        var json = await response.Content.ReadAsStringAsync();
        return JsonDocument.Parse(json);
    }

    public void Dispose()
    {
        _httpClient?.Dispose();
    }
}

// Usage
using var client = new StorytellerClient("your-api-key", "ios");
var clips = await client.GetPagedClipsAsync("my-collection");

curl -X GET "https://api.usestoryteller.com/api/app/clips/my-collection/clips/paged?x-storyteller-api-key=your-api-key-here&ClientPlatform=ios&ClientVersion=11.0.0&pageNumber=0"

Authentication Errors

Missing API Key

If no API key is provided, the request will fail with authentication errors.

Invalid API Key

If an invalid API key is provided:

{
  "status": 401,
  "title": "Unauthorized",
  "detail": "Invalid or missing API key"
}

Common Issues

Issue	Solution
Missing API key	Ensure x-storyteller-api-key query parameter is set
Invalid API key	Verify the API key is correct and active
Wrong platform API key	Use an API key created for your target platform
Missing platform parameter	Add ClientPlatform query parameter with valid value
Missing version parameter	Add ClientVersion query parameter set to 11.0.0

Need Help?

• Need an API Key? Create one in the Apps section of the Storyteller CMS
• Invalid API Key? Contact [email protected] or reach out via Slack
• Authentication Issues? Check that all required headers and query parameters are included in your request