API Documentation

Welcome to the JobSphere API. Our RESTful API allows you to programmatically access and manage job listings, candidate applications, and company data. All endpoints return JSON and require HTTPS.

Authentication

JobSphere uses API keys to authenticate requests. You can generate and manage your keys from the Developer Dashboard.

Include your API key in the Authorization header as a Bearer token:

Authorization: Bearer YOUR_API_KEY

Base URL & Format

All API requests should be made to:

https://api.jobsphere.com/v1

The API accepts and returns application/json payloads.

List Jobs

GET /jobs

Returns a paginated list of active job listings. Supports filtering by category, location, and employment type.

Query Parameters

Parameter	Type	Description
pageOptional	integer	Page number (default: 1)
limitOptional	integer	Items per page (default: 20, max: 100)
categoryOptional	string	Filter by job category slug
remoteOptional	boolean	Filter remote-only positions

Example Request

curl -X GET "https://api.jobsphere.com/v1/jobs?page=1&limit=10&remote=true" \ 
-H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "data": [
    {
      "id": "job_8f3k29d",
      "title": "Senior Frontend Engineer",
      "company": { "name": "JobSphere", "logo": "https://cdn.jobsphere.com/logos/js.png" },
      "location": "Remote",
      "type": "full-time",
      "salary": { "min": 120000, "max": 160000, "currency": "USD" },
      "posted_at": "2025-01-15T09:00:00Z"
    }
  ],
  "meta": { "total": 142, "page": 1, "limit": 10 }
}

Get Job by ID

GET /jobs/{job_id}

Retrieves detailed information about a specific job listing.

Example Response

{
  "id": "job_8f3k29d",
  "title": "Senior Frontend Engineer",
  "description": "We're looking for an experienced React developer...",
  "requirements": ["5+ years JavaScript", "React/Next.js", "TypeScript"],
  "benefits": ["Health insurance", "Unlimited PTO", "Remote-first"],
  "status": "active",
  "created_at": "2025-01-15T09:00:00Z"
}

Create Job

POST /jobs

Publishes a new job listing. Requires write scope.

Request Body

Field	Type	Required	Description
title	string	Yes	Job title
description	string	Yes	HTML or markdown description
company_id	string	Yes	Linked company identifier
location	string	Yes	City, Country or "Remote"
type	enum	Yes	full-time, part-time, contract, freelance
category	string	No	Category slug

Example Request

curl -X POST https://api.jobsphere.com/v1/jobs \ 
-H "Authorization: Bearer YOUR_API_KEY" \ 
-H "Content-Type: application/json" \ 
-d '{
  "title": "Backend Developer",
  "description": "Join our team to build scalable APIs...",
  "company_id": "comp_92a",
  "location": "Berlin, DE",
  "type": "full-time",
  "category": "engineering"
}'

Update Job

PUT /jobs/{job_id}

Updates an existing job listing. Partial updates use PATCH. Supports all fields from creation.

Delete Job

DELETE /jobs/{job_id}

Permanently removes a job listing. Returns 204 No Content on success.

Submit Application

POST /applications

Allows candidates to apply to a job. Accepts resume URLs and cover letters.

Request Body

job_id	string	Yes	Target job identifier
name	string	Yes	Candidate full name
email	string	Yes	Contact email
resume_url	string	Yes	Publicly accessible PDF/DOCX link
cover_letter	string	No	Optional message

List Applications

GET /jobs/{job_id}/applications

Retrieves all applications for a specific job. Requires company admin access.

Error Responses

JobSphere uses standard HTTP status codes and returns detailed error objects:

Code	Meaning	Example Message
400	Bad Request	"Invalid request body: missing required field 'title'"
401	Unauthorized	"Invalid or expired API key"
403	Forbidden	"Insufficient permissions for this resource"
404	Not Found	"Job with ID 'job_99x' not found"
429	Too Many Requests	"Rate limit exceeded. Retry after 60s"
500	Server Error	"Internal server error. Reference: req_8a2f"

Rate Limits

API requests are rate-limited to ensure fair usage. Limits are applied per API key:

Free Tier: 100 requests/hour
Pro Tier: 2,000 requests/hour
Enterprise: Custom limits with dedicated support

Rate limit headers are included in every response:
X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset