JobSphere API Documentation

Welcome to the JobSphere API. Our RESTful API allows you to programmatically access job listings, company data, and posting capabilities. This guide provides everything you need to integrate with our platform.

The API uses standard HTTP methods, JSON payloads, and returns HTTP status codes to indicate success or failure.

Base URL

All API requests should be made to:

https://api.jobsphere.com/v1

Authentication

JobSphere uses API keys to authenticate requests. You can view and manage your API keys in the developer dashboard.

Include your API key in the Authorization header using Bearer token format:

Authorization: Bearer YOUR_API_KEY

Keep your API keys secure. Do not share them in client-side code or public repositories.

Rate Limits

To ensure fair usage, API requests are rate-limited based on your plan:

Plan	Requests / Hour	Burst Limit
Free	1,000	10
Pro	10,000	50
Enterprise	Unlimited	Custom

When you exceed the rate limit, you will receive a 429 Too Many Requests response.

Endpoints

GET /jobs

Retrieve a paginated list of active job postings.

Query Parameters

Parameter	Type	Description
`q`	string	Search query (title, skills, company)
`location`	string	Filter by city, state, or country
`type`	enum	full_time, part_time, contract, remote
`page`	integer	Page number (default: 1)
`limit`	integer	Results per page (default: 20, max: 100)

Example Request

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

fetch('https://api.jobsphere.com/v1/jobs?q=frontend&location=remote&limit=10', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
})
.then(res => res.json())
.then(data => console.log(data));

import requests

response = requests.get(
    'https://api.jobsphere.com/v1/jobs',
    params={'q': 'frontend', 'location': 'remote', 'limit': 10},
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
print(response.json())

GET /jobs/:id

Get detailed information about a specific job posting.

Path Parameters

Parameter	Type	Description
`id`	string	Unique job identifier Required

Response

{
  "id": "job_8f3k29d",
  "title": "Senior Frontend Engineer",
  "company": {
    "id": "comp_92x",
    "name": "TechCorp",
    "logo_url": "https://cdn.jobsphere.com/logos/techcorp.png"
  },
  "location": "San Francisco, CA",
  "type": "full_time",
  "salary_min": 140000,
  "salary_max": 190000,
  "currency": "USD",
  "description": "We're looking for an experienced React developer...",
  "skills": ["React", "TypeScript", "GraphQL", "Tailwind"],
  "posted_at": "2025-01-10T08:00:00Z",
  "expires_at": "2025-03-10T08:00:00Z"
}

POST /jobs

Create a new job posting. Requires write scope.

Request Body

Field	Type	Description
`title`	string	Job title Required
`company_id`	string	Company ID Required
`location`	string	Job location
`type`	enum	full_time, part_time, contract, remote
`description`	string	HTML or Markdown description
`skills`	array	List of required skills
`salary_range`	object	{ min: number, max: number, currency: string }

Example Request

curl -X POST "https://api.jobsphere.com/v1/jobs" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "title": "DevOps Engineer",
    "company_id": "comp_92x",
    "location": "Remote",
    "type": "full_time",
    "description": "Looking for an AWS/Kubernetes expert...",
    "skills": ["AWS", "Docker", "K8s", "Terraform"],
    "salary_range": { "min": 130000, "max": 175000, "currency": "USD" }
  }'

GET /companies

Search and list companies hiring on JobSphere.

Query Parameters

Parameter	Type	Description
`q`	string	Search by company name
`industry`	string	Filter by industry tag
`limit`	integer	Results per page (default: 20)

Error Handling

JobSphere uses standard HTTP status codes to indicate the success or failure of a request. Errors are returned as JSON objects with descriptive messages.

400 Bad Request

Invalid parameters or malformed JSON.

401 Unauthorized

Missing or invalid API key.

403 Forbidden

Insufficient permissions for this endpoint.

404 Not Found

Resource does not exist.

429 Rate Limited

Too many requests. Wait before retrying.

500 Server Error

Internal error. Contact support if persistent.

Error Response Format

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is expired or revoked.",
    "status": 401
  }
}

SDKs & Libraries

We maintain official SDKs for popular languages. Check our GitHub organization for examples, changelogs, and community support.

JavaScript Python Ruby Java