API Documentation

Build integrations with the Skydeca API.

Quick Start

1. Get an API Key

Create an API key in your settings

2. Make a Request

Include your key in the Authorization header

3. Build Something

Search, fetch media, tags, and transcripts

Authentication

All API requests require authentication via an API key. Include your key in the Authorization header.

curl -H "Authorization: Bearer sk_your_api_key" \
  https://skydeca.com/api/v1/search?q=example

Alternatively, you can use the X-API-Key header.

Endpoints

GET/api/v1/search

Search across decks, media, tags, and more

Scope: search

Parameters

q(string) required - Search query

filters(string) - Comma-separated: decks,tags,media,profiles,stacks,tag_maps

limit(number) - Results per page (max 50)

offset(number) - Pagination offset

Example

curl -H "Authorization: Bearer sk_xxx" \
  "https://skydeca.com/api/v1/search?q=technology&filters=media,tags&limit=10"

GET/api/v1/media/:mediaId

Get details for a specific media item

Scope: read, media

Parameters

mediaId(uuid) required - Media ID (path parameter)

Example

curl -H "Authorization: Bearer sk_xxx" \
  "https://skydeca.com/api/v1/media/123e4567-e89b-12d3-a456-426614174000"

GET/api/v1/media/:mediaId/tags

Get all tags for a media item

Scope: read, tags

Parameters

mediaId(uuid) required - Media ID (path parameter)

Example

curl -H "Authorization: Bearer sk_xxx" \
  "https://skydeca.com/api/v1/media/123e4567-e89b-12d3-a456-426614174000/tags"

GET/api/v1/media/:mediaId/transcript

Get the transcript for a media item. Supports JSON, SRT, and VTT formats.

Scope: read

Parameters

mediaId(uuid) required - Media ID (path parameter)

format(string) - Output format: json (default), srt, vtt

timestamps(boolean) - Include timestamps (default: true)

Example

curl -H "Authorization: Bearer sk_xxx" \
  "https://skydeca.com/api/v1/media/123e4567-e89b-12d3-a456-426614174000/transcript?format=srt"

GET/api/v1/tags

List and search tags

Scope: read, tags

Parameters

q(string) - Search query

type(string) - Filter by tag type (person, place, topic, etc.)

sort(string) - Sort by: usage (default), alpha, recent

limit(number) - Results per page (max 100)

offset(number) - Pagination offset

Example

curl -H "Authorization: Bearer sk_xxx" \
  "https://skydeca.com/api/v1/tags?q=AI&type=topic&sort=usage&limit=20"

GET/api/v1/decks/:deckId

Get deck details. Accepts deck ID (UUID) or deck name.

Scope: read

Parameters

deckId(string) required - Deck ID or deck name (path parameter)

Example

curl -H "Authorization: Bearer sk_xxx" \
  "https://skydeca.com/api/v1/decks/my-deck"

GET/api/v1/user/usage

Get API usage statistics for your API key

Scope: read

Example

curl -H "Authorization: Bearer sk_xxx" \
  "https://skydeca.com/api/v1/user/usage"

Scopes

API keys can be created with specific scopes to limit access:

Scope	Access
`read`	Base read access to all GET endpoints
`search`	Access to search endpoint
`tags`	Access to tags endpoints
`media`	Access to media endpoints
`analytics`	Access to analytics data
`admin`	Full access to all endpoints

Rate Limits

API requests are rate limited per API key. Default limits:

60 requests per minute
10,000 requests per day

Rate limit headers are included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1702656000000
X-RateLimit-Daily-Limit: 10000
X-RateLimit-Daily-Remaining: 9998

Code Examples

JavaScript / TypeScript

const response = await fetch('https://skydeca.com/api/v1/search?q=AI', {
  headers: {
    'Authorization': 'Bearer sk_your_api_key'
  }
});

const data = await response.json();
console.log(data.data.results);

Python

import requests

response = requests.get(
    'https://skydeca.com/api/v1/search',
    params={'q': 'AI'},
    headers={'Authorization': 'Bearer sk_your_api_key'}
)

data = response.json()
print(data['data']['results'])

Ready to start building?

Create an API key and start integrating with Skydeca today.

Create API Key

Endpoints

GET/api/v1/search

Search across decks, media, tags, and more

Scope: search

Parameters

q(string) required - Search query

filters(string) - Comma-separated: decks,tags,media,profiles,stacks,tag_maps

limit(number) - Results per page (max 50)

offset(number) - Pagination offset

Example

curl -H "Authorization: Bearer sk_xxx" \
  "https://skydeca.com/api/v1/search?q=technology&filters=media,tags&limit=10"

GET/api/v1/media/:mediaId

Get details for a specific media item

Scope: read, media

Parameters

mediaId(uuid) required - Media ID (path parameter)

Example

curl -H "Authorization: Bearer sk_xxx" \
  "https://skydeca.com/api/v1/media/123e4567-e89b-12d3-a456-426614174000"

GET/api/v1/media/:mediaId/tags

Get all tags for a media item

Scope: read, tags

Parameters

mediaId(uuid) required - Media ID (path parameter)

Example

curl -H "Authorization: Bearer sk_xxx" \
  "https://skydeca.com/api/v1/media/123e4567-e89b-12d3-a456-426614174000/tags"

GET/api/v1/media/:mediaId/transcript

Get the transcript for a media item. Supports JSON, SRT, and VTT formats.

Scope: read

Parameters

mediaId(uuid) required - Media ID (path parameter)

format(string) - Output format: json (default), srt, vtt

timestamps(boolean) - Include timestamps (default: true)

Example

curl -H "Authorization: Bearer sk_xxx" \
  "https://skydeca.com/api/v1/media/123e4567-e89b-12d3-a456-426614174000/transcript?format=srt"

GET/api/v1/tags

List and search tags

Scope: read, tags

Parameters

q(string) - Search query

type(string) - Filter by tag type (person, place, topic, etc.)

sort(string) - Sort by: usage (default), alpha, recent

limit(number) - Results per page (max 100)

offset(number) - Pagination offset

Example

curl -H "Authorization: Bearer sk_xxx" \
  "https://skydeca.com/api/v1/tags?q=AI&type=topic&sort=usage&limit=20"

GET/api/v1/decks/:deckId

Get deck details. Accepts deck ID (UUID) or deck name.

Scope: read

Parameters

deckId(string) required - Deck ID or deck name (path parameter)

Example

curl -H "Authorization: Bearer sk_xxx" \
  "https://skydeca.com/api/v1/decks/my-deck"

GET/api/v1/user/usage

Get API usage statistics for your API key

Scope: read

Example

curl -H "Authorization: Bearer sk_xxx" \
  "https://skydeca.com/api/v1/user/usage"

Scope

Access

read

Base read access to all GET endpoints

search

Access to search endpoint

tags

Access to tags endpoints

media

Access to media endpoints

analytics

Access to analytics data

admin

Full access to all endpoints

Code Examples

JavaScript / TypeScript

const response = await fetch('https://skydeca.com/api/v1/search?q=AI', {
  headers: {
    'Authorization': 'Bearer sk_your_api_key'
  }
});

const data = await response.json();
console.log(data.data.results);

Python

import requests

response = requests.get(
    'https://skydeca.com/api/v1/search',
    params={'q': 'AI'},
    headers={'Authorization': 'Bearer sk_your_api_key'}
)

data = response.json()
print(data['data']['results'])