div#navbar img
{
    height: 20px;
}

table th{
    text-align: left;
}

/* 
** Allows dropdown to be sticky and hide other menu items on scroll and hover
*/

#navigation-items button{
    position: sticky; 
    top: 20px;
    box-shadow: 0 -10px 5px 25px rgb(var(--background-light))
}

#navigation-items button:is(.dark *){
    box-shadow: 0 -10px 5px 25px rgb(var(--background-dark));
}

#navigation-items button:hover{
    background-color: rgb(var(--gray-100));
}

#navigation-items button:hover:is(.dark *){
    background-color: rgb(var(--gray-800));
}

#!/usr/bin/env node

const fs = require('fs');
const path = require('path');
const https = require('https');
const http = require('http');

/**
 * Downloads an OpenAPI specification from a URL and saves it to the specified location
 * @param {string} url - The URL of the OpenAPI specification
 * @param {string} category - The category name (e.g., 'hris')
 */
function downloadOAS(url, category) {
    // Create the directory structure
    const outputFilename = category + '.json';
    const outputDir = path.join(category, 'api-reference');
    ensureDirectoryExists(outputDir);

    const outputPath = path.join(outputDir, outputFilename);

    console.log(`Downloading OpenAPI spec from: ${url}`);
    console.log(`Saving to: ${outputPath}`);

    // Determine if we need http or https
    const client = url.startsWith('https') ? https : http;
    
    // Set up request options with headers
    const options = {
        headers: {
            'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36',
            'Accept': 'application/json'
        }
    };

    // Create a file stream to save the downloaded content
    const fileStream = fs.createWriteStream(outputPath);

    // Download the file
    const request = client.get(url, options, (response) => {
        // Check if the request was successful        
        if (response.statusCode !== 200) {
            console.error(`Failed to download: ${response.statusCode} ${response.statusMessage}`);
            fileStream.close();
            fs.unlinkSync(outputPath); // Remove the file if download failed
            process.exit(1);
            return;
        }

        // Pipe the response to the file
        response.pipe(fileStream);

        // Handle completion
        fileStream.on('finish', () => {
            fileStream.close();
            console.log('Download completed successfully');

            // Validate the downloaded JSON
            try {
                const jsonContent = fs.readFileSync(outputPath, 'utf8');
                JSON.parse(jsonContent);
                console.log('OpenAPI specification is valid JSON');
            } catch (error) {
                console.error('Downloaded file is not valid JSON:', error.message);
                process.exit(1);
            }
        });
    });

    // Handle errors
    request.on('error', (error) => {
        console.error('Error downloading file:', error.message);
        fileStream.close();
        fs.unlinkSync(outputPath); // Remove the file if download failed
        process.exit(1);
    });

    fileStream.on('error', (error) => {
        console.error('Error writing file:', error.message);
        process.exit(1);
    });
}

/**
 * Ensures that a directory exists, creating it if necessary
 * @param {string} dirPath - The directory path to check/create
 */
function ensureDirectoryExists(dirPath) {
    if (!fs.existsSync(dirPath)) {
        fs.mkdirSync(dirPath, { recursive: true });
        console.log(`Created directory: ${dirPath}`);
    }
}

// Main execution
if (process.argv.length < 4) {
    console.error('Usage: node download-oas.js <url> <category>');
    console.error('Example: node download-oas.js https://example.com/api.json hris');
    process.exit(1);
}

const url = process.argv[2];
const category = process.argv[3];

downloadOAS(url, category); 

#!/usr/bin/env node

/**
 * OpenAPI Specification to MDX Converter
 * 
 * This script converts an OpenAPI specification JSON file to MDX files organized by tags.
 * 
 * Example usage:
 *   node scripts/oas-to-mdx.js path/to/openapi.json output/directory
 *   
 * Arguments:
 *   1. Path to OpenAPI JSON file (required)
 *   2. Output directory (optional, defaults to 'test')
 */

const fs = require('fs');
const path = require('path');

// Function to create directory if it doesn't exist
function ensureDirectoryExists(dirPath) {
  if (!fs.existsSync(dirPath)) {
    fs.mkdirSync(dirPath, { recursive: true });
  }
}

// Function to convert camelCase or snake_case to kebab-case
function toKebabCase(str) {
  return str
    .replace(/([a-z])([A-Z])/g, '$1-$2')  // Convert camelCase to kebab-case
    .replace(/_/g, '-')                   // Convert snake_case to kebab-case
    .replace(/\s+/g, '-')                 // Convert spaces to dashes
    .replace(/[^a-zA-Z0-9-]/g, '')        // Remove special characters
    .toLowerCase();                       // Convert to lowercase
}

// Function to generate a descriptive filename based on the operation
function generateFilename(method, pathUrl, operation) {
  // Use the summary if available, otherwise fall back to the current naming scheme
  if (operation.summary) {
    return `${toKebabCase(operation.summary)}.mdx`;
  }

  // Fallback to the current method-based naming if no summary exists
  const pathSegments = pathUrl.split('/').filter(Boolean);
  const lastSegment = pathSegments[pathSegments.length - 1];
  
  // Check if the last segment is a parameter
  const isParameter = lastSegment && lastSegment.startsWith('{');
  
  // If it's a parameter, use the previous segment as the resource
  const resourceSegment = isParameter 
    ? pathSegments[pathSegments.length - 2] || 'resource'
    : lastSegment || 'resource';
  
  // Clean up the resource name
  const resource = resourceSegment.replace(/[{}]/g, '');
  
  // Determine the action based on the HTTP method
  let action;
  switch (method.toLowerCase()) {
    case 'get':
      action = isParameter ? 'get' : 'list';
      break;
    case 'post':
      action = 'create';
      break;
    case 'put':
    case 'patch':
      action = 'update';
      break;
    case 'delete':
      action = 'delete';
      break;
    default:
      action = method.toLowerCase();
  }
  
  return `${action}-${toKebabCase(resource)}.mdx`;
}

// Function to generate MDX content
function generateMdxContent(method, pathUrl, operation) {
  // START:Generate the header
  let content = `---
openapi: "${method.toLowerCase()} ${pathUrl}"`;

  // Add warning icon for deprecated operations
  if (operation.deprecated) {
    content += `
icon: "circle-exclamation"`;
  }

  content += `
---`;
  // END:Generate the header

  // Add warning block for deprecated operations
  if (operation.deprecated) {
    content += `

<Warning>
  **This endpoint is deprecated**   <Icon icon="triangle-exclamation" color="#fbbf24" size={19} />
</Warning>`;
  }

  return content;
}

// Main function to process the OpenAPI JSON
function processOpenApiJson(jsonFilePath, outputBasePath = 'test') {
  // Read and parse the JSON file
  const jsonData = JSON.parse(fs.readFileSync(jsonFilePath, 'utf8'));
  const { paths } = jsonData;

  // Process each path and method
  for (const [pathUrl, pathItem] of Object.entries(paths)) {
    for (const [method, operation] of Object.entries(pathItem)) {
      if (['get', 'post', 'put', 'delete', 'patch'].includes(method.toLowerCase())) {
        const { tags = [] } = operation;
        
        // Skip if no tags
        if (!tags.length) continue;
        
        // Determine the folder structure based on tags
        let folderPath = outputBasePath;
        
        // First tag is the parent folder, subsequent tags are subfolders
        for (let i = 0; i < tags.length; i++) {
          const tagFolder = toKebabCase(tags[i]);
          folderPath = path.join(folderPath, tagFolder);
        }
        
        // Create the folder if it doesn't exist
        ensureDirectoryExists(folderPath);
        
        // Generate a descriptive filename
        const fileName = generateFilename(method, pathUrl, operation);
        
        // Generate the MDX content with potential warning block
        const mdxContent = generateMdxContent(method, pathUrl, operation);
        
        // Write the MDX file
        const filePath = path.join(folderPath, fileName);
        fs.writeFileSync(filePath, mdxContent);
        
        console.log(`Created: ${filePath}`);
      }
    }
  }
}

// Check if a file path was provided
if (process.argv.length < 3) {
  console.error('Please provide the path to the OpenAPI JSON file');
  process.exit(1);
}

const jsonFilePath = process.argv[2];
const outputBasePath = process.argv[3] || 'test';

// Process the JSON file
processOpenApiJson(jsonFilePath, outputBasePath);
console.log('MDX generation complete!'); 

#!/usr/bin/env node

/**
 * OpenAPI Documentation Updater
 * 
 * Example usage:
 *   Process all categories:
 *     node scripts/update-oas-docs.js
 *   
 *   Process specific category:
 *     node scripts/update-oas-docs.js hris
 *   
 *   Process specific category with custom URL:
 *     node scripts/update-oas-docs.js hris https://example.com/custom-spec.json
 */

const { execSync } = require('child_process');
const path = require('path');
const fs = require('fs');
const { CATEGORIES } = require('./config');

// Hardcoded base URL for OpenAPI specifications
const BASE_OAS_URL = 'https://api.eu1.stackone.com/oas/';

/**
 * Downloads an OpenAPI spec and generates MDX files from it
 * @param {string} category - The category name (e.g., 'hris')
 * @param {string} customUrl - Optional custom URL to override the base URL + category
 */
function updateOASDocs(category, customUrl = null) {
  try {
    console.log(`=== Processing OpenAPI spec for ${category} ===`);
    
    // Determine the URL to use
    const url = customUrl || `${BASE_OAS_URL}${category}.json`;
    console.log(`Using URL: ${url}`);
    
    // Step 1: Delete existing files from the api-reference folder
    const apiRefPath = path.join(category, 'api-reference');
    console.log(`\n--- Cleaning existing API reference files ---`);
    if (fs.existsSync(apiRefPath)) {
      const files = fs.readdirSync(apiRefPath);
      for (const file of files) {
        const filePath = path.join(apiRefPath, file);
        if (fs.lstatSync(filePath).isFile()) {
          fs.unlinkSync(filePath);
          console.log(`Deleted: ${filePath}`);
        }
      }
    } else {
      fs.mkdirSync(apiRefPath, { recursive: true });
      console.log(`Created directory: ${apiRefPath}`);
    }
    
    // Step 2: Download the OpenAPI spec
    console.log(`\n--- Downloading OpenAPI spec ---`);
    execSync(`node scripts/download-oas.js "${url}" "${category}"`, { stdio: 'inherit' });
    
    // Step 3: Generate MDX files from the downloaded spec
    console.log(`\n--- Generating MDX files ---`);
    const jsonPath = path.join(category, 'api-reference', `${category}.json`);
    const outputPath = path.join(category, 'api-reference');
    execSync(`node scripts/oas-to-mdx.js "${jsonPath}" "${outputPath}"`, { stdio: 'inherit' });
    
    console.log(`\n=== Processing complete for ${category} ===`);
  } catch (error) {
    console.error(`Error processing OpenAPI spec: ${error.message}`);
    process.exit(1);
  }
}

// Main execution
if (process.argv.length < 3) {
  // No category specified - process all categories
  console.log('No category specified - processing all categories\n');
  for (const category of CATEGORIES) {
    updateOASDocs(category);
  }
} else {
  // Process specific category
  const category = process.argv[2];
  const customUrl = process.argv[3] || null;
  updateOASDocs(category, customUrl);
} 

const CATEGORIES = [
    'hris',
    'ats',
    'crm',
    'marketing',
    'documents',
    'lms',
    'iam',
    'screening',
];

module.exports = {
    CATEGORIES
}; 

#!/usr/bin/env node

const fs = require('fs');
const path = require('path');
const { CATEGORIES } = require('./config');

/**
 * Reads and parses a JSON file
 * @param {string} filePath - Path to the JSON file
 * @returns {Object} Parsed JSON content
 */
function readJsonFile(filePath) {
    try {
        const content = fs.readFileSync(filePath, 'utf8');
        return JSON.parse(content);
    } catch (error) {
        console.error(`Error reading ${filePath}:`, error.message);
        return null;
    }
}

/**
 * Creates a nested navigation structure from MDX files
 * @param {string} directory - Directory to scan
 * @param {string} category - The API category (e.g., 'marketing', 'hris')
 * @returns {Array} Navigation structure
 */
function createNavigationStructure(directory, category) {
    const entries = fs.readdirSync(directory, { withFileTypes: true });
    const result = [];

    // Sort entries to ensure consistent order
    const files = entries.filter(e => e.isFile() && e.name.endsWith('.mdx')).sort();
    const dirs = entries.filter(e => e.isDirectory()).sort();

    // Add files
    for (const file of files) {
        const relativePath = path.relative(category, path.join(directory, file.name));
        result.push(`${category}/${relativePath.replace(/\.mdx$/, '')}`);
    }

    // Process subdirectories
    for (const dir of dirs) {
        const nestedContent = createNavigationStructure(
            path.join(directory, dir.name),
            category
        );

        if (nestedContent.length > 0) {
            result.push({
                group: dir.name.split('-').map(word => 
                    word.charAt(0).toUpperCase() + word.slice(1)
                ).join(' '),
                pages: nestedContent
            });
        }
    }

    return result;
}

/**
 * Updates docs.json with API reference navigation
 */
function updateDocsNavigation() {
    // Read the main docs.json file
    const docsData = readJsonFile('docs.json');
    if (!docsData) {
        process.exit(1);
    }

    // Find the "Unified APIs" tab
    const unifiedApisTab = docsData.navigation?.tabs?.find(tab => tab.tab === 'Unified APIs');
    if (!unifiedApisTab) {
        console.error('Error: Could not find "Unified APIs" tab in docs.json');
        process.exit(1);
    }

    // Process each API category
    for (const category of CATEGORIES) {
        console.log(`\nProcessing ${category}...`);
        
        const apiRefPath = path.join(category, 'api-reference');
        
        if (!fs.existsSync(apiRefPath)) {
            console.log(`No api-reference directory found for ${category}, skipping...`);
            continue;
        }

        // Generate navigation structure
        const navigationStructure = createNavigationStructure(apiRefPath, category);
        
        if (navigationStructure.length === 0) {
            console.log(`No MDX files found for ${category}, skipping...`);
            continue;
        }

        // Find the corresponding dropdown in the Unified APIs tab
        const dropdown = unifiedApisTab.dropdowns?.find(
            d => d.dropdown?.toLowerCase() === category.toLowerCase() ||
                (category === 'admin' && d.dropdown === 'Admin')
        );

        if (!dropdown) {
            console.log(`No dropdown found for ${category}, skipping...`);
            continue;
        }

        // Find the API Reference group in the dropdown's groups
        const apiRefGroup = dropdown.groups?.find(g => g.group === 'API Reference');
        if (!apiRefGroup) {
            console.log(`No API Reference group found for ${category}, skipping...`);
            continue;
        }

        // Update the API Reference pages
        apiRefGroup.pages = navigationStructure;
        console.log(`Updated API Reference structure for ${category}`);
    }

    // Write the updated docs.json
    try {
        fs.writeFileSync('docs.json', JSON.stringify(docsData, null, 2));
        console.log('\nSuccessfully updated docs.json');
    } catch (error) {
        console.error('Error writing docs.json:', error.message);
        process.exit(1);
    }
}

// Run the update
updateDocsNavigation(); 

Sample URL

Sample Response

Stackone

Overview

Welcome to StackOne's Unified API for HRIS, ATS, CRM and more!

Getting Started with StackOne

Connect your Frontend via the StackOne React Hub

Connect your Backend with StackOne

A basic introduction to the dashboard, logging in etc

Dashboard Overview

Browse and take actions on any of the project's linked accounts

Accounts

Get your customer to connect their tool with only a link!

Auth Link

API Keys

Request Logs

Enable, disable and manage integrations for any StackOne Project

Managing Integration

Managing Projects

Webhooks

Managing your Organization

Custom Unified Fields enable users to create and unify bespoke fields to extend the existing Unified API models & resources.

Introduction

Define what source fields, the custom unified field will use for each integration.

Integration Field Mapping

Custom unified fields use an expression language that can be used to create more complex field mappings

Expression language syntax

Outline the list of supported SDKs to use the API with language-native libraries

Postman is a tool that allows developers to send API requests and receive responses to verify whether an API works correctly. This document describes how to use Postman to call the StackOne Unified API.

Using Postman

Using Expand & Include API Parameters

Use filters that are supported by the underlying provider requests

Using the Passthrough (Proxy) query parameters

StackOne Unified API: Error Codes & Resolution Guide

Unified API Error Codes and Troubleshooting  Guide

Making your first API request

Pagination

StackOne Identifiers

Transform HR operations with StackOne's HRIS API, providing intelligent tools for employee management, payroll tracking, and workforce insights across platforms.

Automate bringing users into your application from your customer HRIS

User Syncing from HRIS

Automate the creation and update of employees in your customer's HRIS

Automated Employee Provisioning

Unify and transform recruitment workflows across multiple platforms with StackOne's comprehensive ATS API, enabling data integration, real-time synchronization, and intelligent candidate management.

Learn how StackOne simplifies job board integrations with multiple ATS platforms, reducing custom code and maintenance

Job Board - Easy Apply

Learn how to integrate real-time interview data into your SaaS to deliver intelligent insights and seamlessly sync back to your customers’ ATS

Interview Intelligence

Automated application and candidate screening or scoring (eg. for AI-powered resume scoring).

Automated Application Screening

Learn how to integrate real-time assessment data, AI insights, and ATS syncing to simplify user workflows and improve candidate evaluation

Assessment & Background Checks

Automated candidate screening and scoring to simplify application management and HR decisions

Intelligent Candidate Screening

Accelerate CRM operations with StackOne's Unified API, connecting disparate platforms to unlock intelligent customer data management and real-time insights.

Amplify marketing performance with StackOne's Marketing API, delivering intelligent tools for campaign management, lead tracking, and multi-channel engagement across platforms

Essential details about the StackOne Documents API and its capabilities for organizing, managing, and accessing digital content efficiently within a document management system

Optimize learning management with StackOne's LMS API, delivering powerful tools for content creation, user tracking, and educational process integration across platforms.

Elevate identity security with StackOne's IAM API, providing comprehensive tools for managing user access, roles, and permissions across diverse platforms

The Admin API provides essential tools for managing and interacting with accounts and connectors

HRIS

Common Guides

API Reference

​Sample URL

​Sample Response

Sample URL

Sample Response