Skip to main content

​
Introduction

The Pipeline Job Tracker API provides programmatic access to manage job applications, track your job search pipeline, and leverage AI-powered insights. The API follows RESTful principles and uses JSON for request and response bodies.

​
Base URL

The API is available at the following base URLs:
​
Development
string
http://localhost:3000
Used for local development and testing
​
Production
string
https://api.pipeline.local
Production environment for live applications

​
API Version

The current API version is v1.0.0. All endpoints are prefixed with /api/.

​
Request Format

​
Headers

All API requests should include the following headers:
​
Content-Type
string
required
Set to application/json for requests with a body
​
Authorization
string
required
Bearer token for authenticated endpoints (see Authentication)
Authorization: Bearer <your-jwt-token>

​
Request Body

Request bodies must be valid JSON. Example: 
{
  "company_name": "Acme Corp",
  "job_title": "Senior Software Engineer",
  "status": "applied",
  "source": "linkedin"
}

​
Response Format

​
Success Responses

Successful responses return JSON with a data field containing the requested resource(s):
​
data
object | array
The requested resource or array of resources
​
total
integer
Total count of resources (for paginated list endpoints)
​
page
integer
Current page number (for paginated endpoints)
​
limit
integer
Number of items per page (for paginated endpoints)
​
has_more
boolean
Whether more pages are available (for paginated endpoints)

​
Example Success Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "company_name": "Acme Corp",
      "job_title": "Senior Software Engineer",
      "status": "applied",
      "created_at": "2026-03-01T10:30:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 100,
  "has_more": false
}

​
Error Responses

Error responses include an error object with details about what went wrong:
​
error.code
string
Machine-readable error code (e.g., UNAUTHORIZED, VALIDATION_ERROR, NOT_FOUND)
​
error.message
string
Human-readable error message
​
error.details
array
Additional validation error details (for VALIDATION_ERROR responses)
​
error.request_id
string
Unique request identifier for debugging (optional)
​
error.retry_after
integer
Seconds to wait before retrying (for rate limit errors)

​
HTTP Status Codes

The API uses standard HTTP status codes to indicate the success or failure of requests:
Status CodeMeaningDescription
200OKRequest succeeded
201CreatedResource created successfully
202AcceptedRequest accepted for processing (async operations)
400Bad RequestInvalid request format or parameters
401UnauthorizedAuthentication required or invalid credentials
403ForbiddenAuthenticated but not authorized for this resource
404Not FoundResource does not exist
409ConflictResource conflict (e.g., email already exists)
429Too Many RequestsRate limit exceeded
500Internal Server ErrorUnexpected server error
503Service UnavailableService temporarily unavailable

​
Common Error Examples

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "No valid session found",
    "request_id": "req_abc123"
  }
}

​
Rate Limiting

The API implements rate limiting to ensure fair usage and prevent abuse:
Endpoint TypeLimitWindow
Standard100 requestsper minute
Authentication5 requestsper minute
Scraper endpoints10 requestsper hour
AI endpoints20 requestsper hour

​
Rate Limit Headers

All responses include rate limit information in headers:
​
X-RateLimit-Limit
integer
Maximum number of requests allowed in the current window
​
X-RateLimit-Remaining
integer
Number of requests remaining in the current window
​
X-RateLimit-Reset
integer
Unix timestamp when the rate limit resets
When you exceed the rate limit, the API returns a 429 Too Many Requests response with a retry_after field indicating how long to wait.

​
Pagination

List endpoints support pagination using query parameters:
​
page
integer
default:"1"
Page number to retrieve (1-indexed)
​
limit
integer
default:"100"
Number of items per page (maximum: 500)

​
Pagination Example

GET /api/jobs?page=2&limit=50
Response includes pagination metadata: 
{
  "data": [...],
  "total": 150,
  "page": 2,
  "limit": 50,
  "has_more": true
}

​
Filtering and Sorting

Many list endpoints support filtering and sorting:
​
sort
string
Field to sort by (e.g., created_at, updated_at, company_name)
​
order
string
default:"desc"
Sort order: asc or desc
​
search
string
Search query (searches across relevant fields)

​
Filtering Example

GET /api/jobs?status=applied,interviewing&sort=updated_at&order=desc&search=engineer

​
Public Endpoints

The following endpoints do not require authentication:
  • POST /api/auth/signup - Create account
  • POST /api/auth/login - Login
  • GET /api/health - Health check
All other endpoints require a valid Bearer token in the Authorization header.

​
Next Steps

Authentication

Learn how to authenticate and manage sessions

Jobs API

Create, update, and manage job applications

AI Features

Get AI-powered insights and job scoring

Analytics

Access dashboard and timeline analytics

Build docs developers (and LLMs) love

Get started for freeTalk to us