Developer APIQuick Start

Quick Start Guide

Follow this guide to create your first content using the Firstage API in 5 minutes.

Before You Start

What you’ll need:

  • Node.js 18 or higher
  • Firstage account (sign up at app.firstage.ai)
  • Workspace (create one in the dashboard if you don’t have one)

Step 1: Generate API Key

Create Key in Dashboard

  1. Log in to app.firstage.ai
  2. Select Developer → API Keys in the left sidebar
  3. Click Create API Key button
  4. Enter information:
    • Name: “My First API Key”
    • Permissions: Select contents:read, contents:write, schedules:read, schedules:write
  5. Click Create
  6. Copy the displayed API key (can’t be viewed again!)
fak_Abc123XyZ789...

Step 2: Project Setup

Create New Project

mkdir firstage-api-demo
cd firstage-api-demo
npm init -y

Install SDK

npm install @seolhun/firstage-sdk

TypeScript Setup (Optional)

npm install -D typescript @types/node
npx tsc --init

Configure Environment Variables

Create .env file:

FIRSTAGE_API_KEY=fak_your_api_key_here
WORKSPACE_SLUG=your-workspace-slug

Add to .gitignore:

.env
node_modules/

Step 3: First API Call

Initialize Client

Create index.ts (or index.js) file:

import { FirstageClient } from '@seolhun/firstage-sdk';
 
// Load API key from environment variable
const client = new FirstageClient({
  apiKey: process.env.FIRSTAGE_API_KEY,
});
 
console.log('Firstage client initialized!');

Create Content

import { FirstageClient } from '@seolhun/firstage-sdk';
 
const client = new FirstageClient({
  apiKey: process.env.FIRSTAGE_API_KEY,
});
 
async function createContent() {
  try {
    // Create content
    const content = await client.contents.create({
      format: 'markdown',
      content: '# Hello, Firstage!\\n\\nThis is my first content created via API.',
      title: 'My First API Post',
    });
 
    console.log('Content created successfully!');
    console.log('ID:', content.id);
    console.log('Title:', content.title);
    console.log('URL:', `https://app.firstage.ai/contents/${content.id}`);
  } catch (error) {
    console.error('Error occurred:', error.message);
  }
}
 
createContent();

Run It

# TypeScript
npx ts-node index.ts
 
# JavaScript
node index.js

Expected output:

Content created successfully!
ID: clx123abc...
Title: My First API Post
URL: https://app.firstage.ai/contents/clx123abc...

Step 4: Retrieve Content

Fetch the content you created:

async function getContent(contentId: string) {
  try {
    const content = await client.contents.get(contentId);
 
    console.log('Content retrieved successfully!');
    console.log('Title:', content.title);
    console.log('Content:', content.content);
    console.log('Created:', content.createdAt);
  } catch (error) {
    console.error('Error occurred:', error.message);
  }
}
 
// Usage example
getContent('clx123abc...');

Step 5: List Content

Retrieve all content:

async function listContents() {
  try {
    const contents = await client.contents.list({
      limit: 10,
      sort: 'createdAt',
      order: 'desc',
    });
 
    console.log(`Found ${contents.length} content items`);
 
    contents.forEach((content) => {
      console.log(`- ${content.title} (${content.id})`);
    });
  } catch (error) {
    console.error('Error occurred:', error.message);
  }
}
 
listContents();

Step 6: Schedule Posts

Schedule content publication to social media:

async function schedulePost(contentId: string) {
  try {
    // Schedule for 1 hour from now
    const scheduledAt = new Date(Date.now() + 60 * 60 * 1000);
 
    const schedule = await client.schedules.create({
      contentId,
      scheduledAt: scheduledAt.toISOString(),
      platforms: ['instagram', 'threads'],
    });
 
    console.log('Schedule created successfully!');
    console.log('Scheduled time:', schedule.scheduledAt);
    console.log('Platforms:', schedule.platforms);
  } catch (error) {
    console.error('Error occurred:', error.message);
  }
}
 
schedulePost('clx123abc...');

Complete Example

A complete example using all the features above:

import { FirstageClient } from '@seolhun/firstage-sdk';
import * as dotenv from 'dotenv';
 
// Load environment variables
dotenv.config();
 
const client = new FirstageClient({
  apiKey: process.env.FIRSTAGE_API_KEY,
});
 
async function main() {
  try {
    // 1. Create content
    console.log('1. Creating content...');
    const content = await client.contents.create({
      format: 'markdown',
      content: '# Firstage API Tutorial\\n\\nThis is an example using the API.',
      title: 'API Tutorial',
    });
    console.log('✓ Content created:', content.id);
 
    // 2. Retrieve content
    console.log('\\n2. Retrieving content...');
    const fetchedContent = await client.contents.get(content.id);
    console.log('✓ Retrieved:', fetchedContent.title);
 
    // 3. List content
    console.log('\\n3. Listing content...');
    const contents = await client.contents.list({ limit: 5 });
    console.log(`✓ Found ${contents.length} content items`);
 
    // 4. Schedule publication
    console.log('\\n4. Scheduling publication...');
    const scheduledAt = new Date(Date.now() + 60 * 60 * 1000);
    const schedule = await client.schedules.create({
      contentId: content.id,
      scheduledAt: scheduledAt.toISOString(),
      platforms: ['instagram'],
    });
    console.log('✓ Schedule created:', schedule.id);
 
    console.log('\\n🎉 All tasks completed!');
  } catch (error) {
    console.error('❌ Error occurred:', error.message);
  }
}
 
main();

Error Handling

Errors that may occur during API calls:

Authentication Errors

try {
  await client.contents.create({ ... });
} catch (error) {
  if (error.status === 401) {
    console.error('API key is invalid');
  }
}

Permission Errors

try {
  await client.contents.create({ ... });
} catch (error) {
  if (error.status === 403) {
    console.error('You do not have permission for this operation');
  }
}

Rate Limit Errors

try {
  await client.contents.create({ ... });
} catch (error) {
  if (error.status === 429) {
    console.error('Rate limit exceeded');
    console.error('Retry after:', error.retryAfter, 'seconds');
  }
}

Comprehensive Error Handling

async function safeApiCall(fn: () => Promise<any>) {
  try {
    return await fn();
  } catch (error) {
    switch (error.status) {
      case 400:
        console.error('Bad request:', error.message);
        break;
      case 401:
        console.error('Authentication failed:', error.message);
        break;
      case 403:
        console.error('Permission denied:', error.message);
        break;
      case 404:
        console.error('Resource not found:', error.message);
        break;
      case 429:
        console.error('Rate limit exceeded:', error.message);
        break;
      case 500:
        console.error('Server error:', error.message);
        break;
      default:
        console.error('Unknown error:', error.message);
    }
    throw error;
  }
}
 
// Usage example
await safeApiCall(() => client.contents.create({ ... }));

Next Steps

Now that you’ve learned the basics of API usage, explore these topics:

Full Code Repository

Complete example code is available on GitHub:

github.com/firstage-ai/api-examples

Need Help?

OverviewAPI Key Management