Silksong Developer APIs

Integrate Hollow Knight: Silksong data into your applications with our comprehensive REST API. Get real-time game status, manage subscriptions, and access timeline data.

Quick Start API Reference View on GitHub

Real-time Status

Get live countdown data and game release information

Rate Limited

Built-in protection with clear usage guidelines

Cached Responses

ETag caching for optimal performance

Developer-First

RESTful design with comprehensive documentation

Quick Start

Get up and running in under 5 minutes. No authentication required for public endpoints.

1. Make Your First Request

Quick Start ExampleJavaScript

// Quick Start - Get Game Status
fetch('https://silksong-nextjs.vercel.app/api/status')
  .then(response => response.json())
  .then(data => {
    console.log('Days until release:', data.daysRemaining);
    console.log('Latest updates:', data.timelineItems.slice(0, 5));
  })
  .catch(error => console.error('Error:', error));

2. Explore the Response

You'll get a comprehensive response with:

Release countdown data
Latest timeline updates
Caching headers for optimization
CORS enabled for web apps

Base URL

https://silksong-nextjs.vercel.app

All API endpoints are relative to this base URL.

Authentication

Public APIs

Currently, all endpoints are public and don't require authentication. Rate limits apply to ensure fair usage.

API Reference

Complete documentation for all available endpoints

GET

/api/status

Get Game Status

Returns comprehensive game release status including countdown data and timeline updates

Code Examples

Fetch APIJavaScript

// Basic request
fetch('https://silksong-nextjs.vercel.app/api/status')
  .then(response => response.json())
  .then(data => console.log(data));

// With caching support
const headers = {};
if (localStorage.getItem('status-etag')) {
  headers['If-None-Match'] = localStorage.getItem('status-etag');
}

fetch('https://silksong-nextjs.vercel.app/api/status', { headers })
  .then(response => {
    if (response.status === 304) {
      // Use cached data
      return JSON.parse(localStorage.getItem('status-data'));
    }
    // Store new ETag
    localStorage.setItem('status-etag', response.headers.get('ETag'));
    return response.json();
  })
  .then(data => {
    localStorage.setItem('status-data', JSON.stringify(data));
    console.log(data);
  });

Rate Limiting

Usage guidelines and limits to ensure fair access for all developers

100

Requests per 15min

Subscription per minute

∞

Cached responses

Response Headers

X-RateLimit-Limit: 100

X-RateLimit-Remaining: 95

X-RateLimit-Reset: 1692877845

Best Practices

Use ETag headers for caching to avoid unnecessary requests
Implement exponential backoff for rate limit errors
Cache responses locally to reduce API calls
Monitor rate limit headers in your applications

Error Handling

Common error scenarios and how to handle them gracefully

HTTP Status Codes

200

Success

Request completed successfully

201

Created

Resource created (subscription)

304

Not Modified

Use cached version

400

Bad Request

Invalid request data

429

Rate Limited

Too many requests

500

Server Error

Internal server error

Error Response Format

Error Response ExampleJSON

{
  "error": "Please enter a valid email address",
  "code": "VALIDATION_ERROR",
  "details": {
    "field": "email",
    "provided": "invalid-email"
  },
  "timestamp": "2024-08-24T10:30:45.123Z",
  "path": "/api/subscribe"
}

Handling Errors in Code

Robust Error HandlingJavaScript

async function handleApiCall(url, options = {}) {
  try {
    const response = await fetch(url, options);
    
    // Handle rate limiting
    if (response.status === 429) {
      const resetTime = response.headers.get('X-RateLimit-Reset');
      const waitTime = (resetTime * 1000) - Date.now();
      console.log(`Rate limited. Retry after ${Math.ceil(waitTime / 1000)} seconds`);
      
      // Implement exponential backoff
      await new Promise(resolve => setTimeout(resolve, waitTime));
      return handleApiCall(url, options); // Retry
    }
    
    // Handle not modified (use cache)
    if (response.status === 304) {
      return getCachedData(url);
    }
    
    // Parse response
    const data = await response.json();
    
    // Handle errors
    if (!response.ok) {
      throw new Error(`API Error (${response.status}): ${data.error}`);
    }
    
    // Cache successful response
    setCachedData(url, data, response.headers.get('ETag'));
    return data;
    
  } catch (error) {
    console.error('API call failed:', error);
    throw error;
  }
}

Community & Support

Join the developer community and get help when you need it

GitHub

Contribute, report issues, and view source code

View Repository

Discord

Join the developer community chat

Join Server

Examples

Community-built integrations and examples

Browse Examples

SDKs

Official and community SDK libraries

View SDKs

SDKs & Libraries

Official and community-maintained libraries to get you started quickly

JavaScript/TypeScript

silksong-api

Official

Official TypeScript SDK with full type safety and caching support.

Bash

npm install silksong-api

@silksong/react-hooks

Community

React hooks for easy integration in React applications.

Bash

npm install @silksong/react-hooks

Python

silksong-python

Official

Official Python SDK with async support and automatic retry logic.

Bash

pip install silksong-api

silksong-cli

Community

Command-line tool for monitoring and notifications.

Bash

pip install silksong-cli

Quick SDK Example

Official SDK UsageJavaScript

import { SilksongAPI } from 'silksong-api';

// Initialize client
const api = new SilksongAPI({
  baseUrl: 'https://silksong-nextjs.vercel.app',
  cache: true, // Enable automatic caching
  retries: 3   // Automatic retry on failures
});

// Get game status with full TypeScript support
const status = await api.getStatus();
console.log(`${status.daysRemaining} days remaining!`);

// Subscribe to updates with validation
try {
  const result = await api.subscribe('user@example.com');
  console.log('Subscribed successfully!', result.subscription.id);
} catch (error) {
  if (error.code === 'ALREADY_SUBSCRIBED') {
    console.log('Email already subscribed');
  }
}

// Get RSS feed as structured data
const feed = await api.getRSSFeed();
console.log('Latest updates:', feed.items.slice(0, 5));

Built with ❤️ for the Hollow Knight community

API Docs Timeline Status GitHub

// Quick Start - Get Game Status fetch('https://silksong-nextjs.vercel.app/api/status') .then(response => response.json()) .then(data => { console.log('Days until release:', data.daysRemaining); console.log('Latest updates:', data.timelineItems.slice(0, 5)); }) .catch(error => console.error('Error:', error));

// Basic request fetch('https://silksong-nextjs.vercel.app/api/status') .then(response => response.json()) .then(data => console.log(data)); // With caching support const headers = {}; if (localStorage.getItem('status-etag')) { headers['If-None-Match'] = localStorage.getItem('status-etag'); } fetch('https://silksong-nextjs.vercel.app/api/status', { headers }) .then(response => { if (response.status === 304) { // Use cached data return JSON.parse(localStorage.getItem('status-data')); } // Store new ETag localStorage.setItem('status-etag', response.headers.get('ETag')); return response.json(); }) .then(data => { localStorage.setItem('status-data', JSON.stringify(data)); console.log(data); });

{ "error": "Please enter a valid email address", "code": "VALIDATION_ERROR", "details": { "field": "email", "provided": "invalid-email" }, "timestamp": "2024-08-24T10:30:45.123Z", "path": "/api/subscribe" }

async function handleApiCall(url, options = {}) { try { const response = await fetch(url, options); // Handle rate limiting if (response.status === 429) { const resetTime = response.headers.get('X-RateLimit-Reset'); const waitTime = (resetTime * 1000) - Date.now(); console.log(`Rate limited. Retry after ${Math.ceil(waitTime / 1000)} seconds`); // Implement exponential backoff await new Promise(resolve => setTimeout(resolve, waitTime)); return handleApiCall(url, options); // Retry } // Handle not modified (use cache) if (response.status === 304) { return getCachedData(url); } // Parse response const data = await response.json(); // Handle errors if (!response.ok) { throw new Error(`API Error (${response.status}): ${data.error}`); } // Cache successful response setCachedData(url, data, response.headers.get('ETag')); return data; } catch (error) { console.error('API call failed:', error); throw error; } }

import { SilksongAPI } from 'silksong-api'; // Initialize client const api = new SilksongAPI({ baseUrl: 'https://silksong-nextjs.vercel.app', cache: true, // Enable automatic caching retries: 3 // Automatic retry on failures }); // Get game status with full TypeScript support const status = await api.getStatus(); console.log(`${status.daysRemaining} days remaining!`); // Subscribe to updates with validation try { const result = await api.subscribe('user@example.com'); console.log('Subscribed successfully!', result.subscription.id); } catch (error) { if (error.code === 'ALREADY_SUBSCRIBED') { console.log('Email already subscribed'); } } // Get RSS feed as structured data const feed = await api.getRSSFeed(); console.log('Latest updates:', feed.items.slice(0, 5));