Skip to Content
API Reference

API Reference

The JSON Resume API provides programmatic access to resume data, themes, and job matching.

Base URL

https://jsonresume.org/api

Authentication

Most endpoints are public and don’t require authentication. For private resume access, you’ll need to authenticate with GitHub OAuth.

# Public resume access (no auth required)
GET https://jsonresume.org/[username]
 
# Private resume access (requires auth)
GET https://jsonresume.org/api/resume?token=YOUR_TOKEN

Endpoints

Get Resume

Fetch a resume by GitHub username.

GET /[username]

Parameters:

  • username (required) - GitHub username

Response:

{
  "basics": {
    "name": "John Doe",
    "label": "Software Engineer",
    ...
  },
  ...
}

Get Resume with Theme

Render a resume using a specific theme.

GET /[username]?theme=[theme-name]

Parameters:

  • username (required) - GitHub username
  • theme (optional) - Theme name (default: standard)

Supported formats:

  • .html - HTML rendering
  • .pdf - PDF export
  • .json - Raw JSON data

Examples:

# Get resume as HTML with professional theme
curl https://jsonresume.org/johndoe?theme=professional
 
# Get resume as PDF
curl https://jsonresume.org/johndoe.pdf
 
# Get raw JSON
curl https://jsonresume.org/johndoe.json

Validate Resume

Validate a resume against the JSON Resume schema.

POST /api/validate
Content-Type: application/json
 
{
  "basics": { ... },
  ...
}

Response:

{
  "valid": true,
  "errors": []
}

Or if invalid:

{
  "valid": false,
  "errors": [
    {
      "path": "basics.email",
      "message": "Invalid email format"
    }
  ]
}

Search Jobs

Search for jobs matched to your resume.

POST /api/jobs/search
Content-Type: application/json
 
{
  "resume": { ... },
  "filters": {
    "location": "San Francisco",
    "remote": true,
    "types": ["full-time"]
  }
}

Response:

{
  "jobs": [
    {
      "uuid": "abc-123",
      "company": "Acme Corp",
      "title": "Senior Software Engineer",
      "score": 0.95,
      ...
    }
  ],
  "total": 42
}

Rate Limiting

API requests are rate-limited to prevent abuse:

  • Anonymous: 60 requests per hour
  • Authenticated: 5000 requests per hour

Rate limit headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1640995200

Error Responses

The API uses standard HTTP status codes:

StatusDescription
200Success
400Bad Request - Invalid parameters
401Unauthorized - Authentication required
404Not Found - Resume not found
429Too Many Requests - Rate limit exceeded
500Internal Server Error

Error format:

{
  "error": {
    "code": "RESUME_NOT_FOUND",
    "message": "Resume not found for user: johndoe"
  }
}

SDK / Client Libraries

JavaScript / TypeScript

npm install @jsonresume/client
import { JSONResumeClient } from '@jsonresume/client';
 
const client = new JSONResumeClient();
 
// Get resume
const resume = await client.getResume('johndoe');
 
// Validate resume
const validation = await client.validate(resume);
 
// Search jobs
const jobs = await client.searchJobs(resume, {
  remote: true,
  location: 'San Francisco',
});

Python

pip install jsonresume
from jsonresume import Client
 
client = Client()
 
# Get resume
resume = client.get_resume('johndoe')
 
# Validate
validation = client.validate(resume)
 
# Search jobs
jobs = client.search_jobs(resume, remote=True)

Webhooks

Subscribe to resume updates and job matches.

POST /api/webhooks
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN
 
{
  "url": "https://yourapp.com/webhook",
  "events": ["resume.updated", "job.matched"]
}

Webhook payload:

{
  "event": "job.matched",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "job": { ... },
    "score": 0.92
  }
}

GraphQL API

For advanced queries, use the GraphQL API:

{
  resume(username: "johndoe") {
    basics {
      name
      email
      profiles {
        network
        url
      }
    }
    work {
      name
      position
      highlights
    }
  }
 
  jobs(first: 10, filters: { remote: true }) {
    edges {
      node {
        company
        title
        location {
          city
          remote
        }
      }
    }
  }
}

Examples

Full Resume Workflow

// 1. Fetch resume from GitHub Gist
const gistUrl =
  'https://gist.githubusercontent.com/johndoe/abc123/raw/resume.json';
const resume = await fetch(gistUrl).then((r) => r.json());
 
// 2. Validate
const validation = await fetch('https://jsonresume.org/api/validate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(resume),
}).then((r) => r.json());
 
if (!validation.valid) {
  console.error('Resume is invalid:', validation.errors);
  return;
}
 
// 3. Search for matching jobs
const jobs = await fetch('https://jsonresume.org/api/jobs/search', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ resume }),
}).then((r) => r.json());
 
console.log(`Found ${jobs.total} matching jobs`);

Next Steps

Support

For API issues or questions:

IntegrationArchitecture