REST API Quick Start

Overview

The f2d REST API lets you search for jobs using natural language. Send a query like "machine learning engineer in Seattle" and get back a ranked list of the most relevant job postings.

Prerequisites

An API Key (contact the f2d team to obtain one)

Step 1: Make Your First Request

Copy and run the following command in your terminal:

curl -s -X POST "<your-api-url>/v1/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{"q": "machine learning engineer in Seattle", "top_k": 3}' | jq .

Replace <your-api-url> with your API endpoint and <your-api-key> with your API key.

The first request may take 3-5 seconds due to cold start. Subsequent requests are faster.

Step 2: Understand the Response

A successful response looks like this:

{
  "total": 3,
  "results": [
    {
      "score": 0.92,
      "job_title": "Machine Learning Engineer",
      "city": "Seattle",
      "company_name": "Tech Corp",
      "publish_time": "2026-03-15 10:30:00",
      "base_salary": "150000.0-200000.0 USD/YEAR",
      "job_url": "https://www.indeed.com/viewjob?jk=example"
    }
  ]
}

Field	Description
`score`	Semantic relevance score (0-1, higher is better)
`job_title`	Job title
`city`	City where the job is located
`company_name`	Hiring company
`publish_time`	When the job was posted
`base_salary`	Salary range (if available)
`job_url`	Link to the full job posting

Step 3: Try Different Queries

f2d uses semantic search, so you can describe jobs naturally:

# Search by skill
curl -s -X POST "<your-api-url>/v1/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{"q": "I want to work with Python and data pipelines", "top_k": 5}' | jq .

# Filter by city
curl -s -X POST "<your-api-url>/v1/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{"q": "product manager", "city": "New York", "top_k": 5}' | jq .

# Get full job descriptions
curl -s -X POST "<your-api-url>/v1/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{"q": "AI researcher", "detail": "full", "top_k": 3}' | jq .

For all available parameters including city, country, since, and detail, see the API Reference.

Troubleshooting

Error	Cause	Solution
`403 Invalid API key`	API key is missing or incorrect	Check the `x-api-key` header value
`400 q is required`	Missing search query	Add the `q` field to your request body
`429 Rate limit exceeded`	Too many requests	Wait for the time specified in the `Retry-After` header

Next Steps

See the full API Reference for all endpoints and parameters
See Error Codes for a complete error reference
Try the CLI for a faster terminal experience