Skip to main content

API Reference

Complete reference for the Scaffald SDK - explore documentation by resource type.

Quick Navigation​

Browse the API documentation organized by resource:

🔧 Client Configuration​

Configure the SDK client with API keys, OAuth tokens, retry settings, and custom headers.

Topics:

  • Authentication methods
  • Base URL configuration
  • Retry and timeout settings
  • Custom HTTP headers

View Documentation →

💼 Jobs API​

Search, retrieve, and filter job listings with advanced querying capabilities.

Methods:

  • list() - Search and filter jobs
  • retrieve() - Get job details
  • similar() - Find similar jobs
  • filterOptions() - Get filter values

View Documentation →

📝 Applications API​

Submit quick or full applications and manage application lifecycle.

Methods:

  • create() / createQuick() - Quick apply
  • createFull() - Full application
  • retrieve() - Get application status
  • update() - Update application
  • withdraw() - Withdraw application

View Documentation →

👤 Profiles API​

Retrieve public user, organization, and employer profiles.

Methods:

  • user() - Get user profile
  • organization() - Get organization
  • employer() - Get employer profile

Rate Limit: 100 requests / 15 min

View Documentation →

🔐 OAuth API​

Implement OAuth 2.0 with PKCE for secure user authentication.

Methods:

  • getAuthorizationUrl() - Start OAuth
  • exchangeCode() - Get access token
  • refreshToken() - Refresh tokens

Flow: Authorization Code + PKCE

View Documentation →

⏱️ Rate Limiting​

Monitor and manage API rate limits to ensure optimal usage.

Methods:

  • getRateLimitInfo() - Check status
  • isRateLimitApproaching() - Monitor
  • getSecondsUntilReset() - Time to reset
  • onRateLimitUpdate() - Subscribe

View Documentation →

📘 Type Definitions​

Complete TypeScript type reference for all SDK interfaces and types.

Types:

  • Job, Application, Profile
  • Request/Response interfaces
  • OAuth types
  • Error types

View Documentation →

Getting Started​

1. Install the SDK​

npm install @scaffald/sdk

2. Initialize Client​

import Scaffald from '@scaffald/sdk'

// Server-side (API key)
const client = new Scaffald({
  apiKey: process.env.SCAFFALD_API_KEY
})

// Client-side (OAuth)
const client = new Scaffald({
  accessToken: userAccessToken
})

3. Make Your First Request​

// Search for jobs
const jobs = await client.jobs.list({
  employmentType: 'full_time',
  remoteOption: 'remote',
  limit: 20
})

// Submit a quick application
const application = await client.applications.create({
  jobId: jobs.data[0].id,
  currentLocation: 'San Francisco, CA'
})

Common Use Cases​

Search and Filter Jobs​

// Get remote full-time jobs in tech
const jobs = await client.jobs.list({
  status: 'published',
  employmentType: 'full_time',
  remoteOption: 'remote',
  limit: 50
})

console.log(`Found ${jobs.pagination.total} jobs`)

Full Jobs API Documentation →

Submit an Application​

// Quick application
const app = await client.applications.create({
  jobId: 'job_abc123',
  currentLocation: 'San Francisco, CA',
  availableStartDate: '2025-03-01'
})

// Full application with details
const fullApp = await client.applications.createFull({
  jobId: 'job_abc123',
  currentLocation: 'San Francisco, CA',
  coverLetter: 'I am excited...',
  resumeUrl: 'https://example.com/resume.pdf',
  yearsExperience: 5
})

Full Applications API Documentation →

Implement OAuth​

// Step 1: Get authorization URL
const { url, codeVerifier, state } = await client.oauth.getAuthorizationUrl({
  clientId: 'your_client_id',
  redirectUri: 'https://yourapp.com/callback',
  scope: ['read:jobs', 'write:applications']
})

// Store and redirect
sessionStorage.setItem('pkce_verifier', codeVerifier)
window.location.href = url

// Step 2: Exchange code for token (in callback)
const tokens = await client.oauth.exchangeCode({
  code,
  codeVerifier: sessionStorage.getItem('pkce_verifier'),
  clientId: 'your_client_id',
  redirectUri: 'https://yourapp.com/callback'
})

Full OAuth API Documentation →

Monitor Rate Limits​

// Subscribe to rate limit updates
client.onRateLimitUpdate((info) => {
  console.log(`${info.remaining}/${info.limit} requests remaining`)

  if (client.isRateLimitApproaching(0.1)) {
    console.warn('Less than 10% remaining - slow down!')
  }
})

// Make requests
await client.jobs.list()

Full Rate Limiting Documentation →

API Resources​

ResourceEndpointDescription
Client-SDK configuration and initialization
Jobs/api/v1/jobsSearch and retrieve job listings
Applications/api/v1/applicationsSubmit and manage applications
Profiles/api/v1/profilesUser and organization profiles
OAuth/oauthOAuth 2.0 authentication
Types-TypeScript type definitions

Rate Limits​

Endpoint TypeLimit
Standard endpoints1000 requests / hour
Profile endpoints100 requests / 15 min
OAuth endpoints20 requests / min

Learn more about rate limiting →

Authentication​

The SDK supports two authentication methods:

API Key (Server-side)

const client = new Scaffald({
  apiKey: process.env.SCAFFALD_API_KEY
})

OAuth Token (Client-side)

const client = new Scaffald({
  accessToken: userAccessToken
})

View OAuth API documentation →

Error Handling​

The SDK throws typed errors for easy handling:

import { APIError } from '@scaffald/sdk'

try {
  const jobs = await client.jobs.list()
} catch (error) {
  if (error instanceof APIError) {
    if (error.status === 429) {
      console.log('Rate limited')
    } else if (error.status === 401) {
      console.log('Unauthorized')
    }
  }
}

View rate limiting documentation →

TypeScript Support​

The SDK is written in TypeScript with full type definitions:

import type {
  Job,
  Application,
  JobsListParams,
  JobsListResponse
} from '@scaffald/sdk'

const params: JobsListParams = {
  employmentType: 'full_time',
  limit: 20
}

const response: JobsListResponse = await client.jobs.list(params)
const jobs: Job[] = response.data

View all type definitions →

Next Steps​

Need Help?​