API Documentation

Everything you need to integrate AgentJobs into your AI agent, app, or platform.

Base URL: https://agentjobsai.com

Authentication

All API requests require an API key passed via the X-API-Key header.

API Key Tiers

Tier	Rate Limit	Results / Query	Price
Free	100 req/day	20	$0
Pro	10,000 req/day	100	$49/mo
Enterprise	Unlimited	Unlimited	$499/mo

cURLbash

curl -H "X-API-Key: aj_your_api_key_here" \
  https://agentjobsai.com/api/v1/jobs?role=engineer

Pythonpython

import requests

response = requests.get(
    "https://agentjobsai.com/api/v1/jobs",
    headers={"X-API-Key": "aj_your_api_key_here"},
    params={"role": "engineer"}
)
jobs = response.json()["jobs"]

JavaScriptjavascript

const response = await fetch(
  "https://agentjobsai.com/api/v1/jobs?role=engineer",
  { headers: { "X-API-Key": "aj_your_api_key_here" } }
);
const { jobs } = await response.json();

Endpoints

The API provides five core endpoints. All return JSON with consistent response envelopes.

GET

/api/v1/jobs

Search and filter jobs

GET

/api/v1/jobs/:id

Get a single job by ID

GET

/api/v1/industries

List all industries

GET

/api/v1/roles/suggest

Expand a role to related titles

GET

/api/v1/taxonomy

Full taxonomy tree

Search Jobs

GET/api/v1/jobs

Search for jobs with full-text search, industry/role filters, remote filtering, and pagination. Featured listings appear first.

Parameters

Name	Type	Required	Description
q	string	No	Free-text search across title, company, description
role	string	No	Role taxonomy slug (e.g. creative-director)
industry	string	No	Industry slug (e.g. crypto, ai-ml)
remote	boolean	No	Filter to remote-only jobs
region	string	No	Region filter (e.g. US, EU, APAC)
posted_after	ISO date	No	Only jobs posted after this date
page	integer	No	Page number (default: 1)
per_page	integer	No	Results per page (default: 20, max: 100)
sort	string	No	Sort by: posted, freshness, or relevance

Examples

cURLbash

curl -H "X-API-Key: aj_your_key" \
  "https://agentjobsai.com/api/v1/jobs?q=creative+director&industry=crypto&remote=true"

Pythonpython

response = requests.get(
    "https://agentjobsai.com/api/v1/jobs",
    headers={"X-API-Key": "aj_your_key"},
    params={"q": "creative director", "industry": "crypto", "remote": True}
)

JavaScriptjavascript

const params = new URLSearchParams({
  q: "creative director",
  industry: "crypto",
  remote: "true"
});

const res = await fetch(`https://agentjobsai.com/api/v1/jobs?${params}`, {
  headers: { "X-API-Key": "aj_your_key" }
});

Response

{
  "jobs": [
    {
      "id": "a1b2c3d4-...",
      "title": "Senior Creative Director",
      "company": "Acme Protocol",
      "location": "Remote",
      "salary": "$180k-$220k",
      "isRemote": true,
      "isFeatured": true,
      "freshness": { "score": 0.92, "label": "2 days ago", "tier": "fresh" },
      "industry": { "name": "Crypto", "slug": "crypto" },
      "taxonomy": { "canonicalTitle": "Creative Director", "slug": "creative-director" }
    }
  ],
  "pagination": { "page": 1, "per_page": 20, "total": 23, "total_pages": 2, "has_next": true, "has_prev": false },
  "meta": { "query_expanded_to": "creative director", "sort": "posted", "filters": {} }
}

Get Job by ID

GET/api/v1/jobs/:id

Retrieve a single job by its UUID. Returns full details including description and freshness score.

Parameters

Name	Type	Required	Description
id	UUID	Yes	The job's unique identifier

Examples

cURLbash

curl -H "X-API-Key: aj_your_key" \
  https://agentjobsai.com/api/v1/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890

Response

{
  "job": {
    "id": "a1b2c3d4-...",
    "title": "Senior Creative Director",
    "company": "Acme Protocol",
    "description": "We are looking for a Senior Creative Director to lead...",
    "salary": "$180k-$220k",
    "link": "https://acme.com/careers/creative-director",
    "freshness": { "score": 0.95, "label": "Fresh", "tier": "fresh" }
  }
}

List Industries

GET/api/v1/industries

List all available industries. Use industry slugs to filter job searches.

Examples

cURLbash

curl -H "X-API-Key: aj_your_key" \
  https://agentjobsai.com/api/v1/industries

Response

{
  "industries": [
    { "slug": "crypto", "name": "Crypto", "description": "Blockchain, DeFi, and Web3" },
    { "slug": "ai-ml", "name": "AI / ML", "description": "Artificial Intelligence and ML" },
    { "slug": "fintech", "name": "Fintech", "description": "Financial Technology" }
  ]
}

Suggest Roles

GET/api/v1/roles/suggest

Given a role query, returns the matching taxonomy entry with all related titles. Powers the Role Explorer page.

Parameters

Name	Type	Required	Description
q	string	Yes	Role name to look up

Examples

cURLbash

curl -H "X-API-Key: aj_your_key" \
  "https://agentjobsai.com/api/v1/roles/suggest?q=creative+director"

Response

{
  "taxonomy": {
    "slug": "creative-director",
    "canonicalTitle": "Creative Director",
    "relatedTitles": [
      "Brand Director", "Head of Design", "Design Director",
      "VP of Creative", "Chief Creative Officer", "Associate Creative Director",
      "Group Creative Director", "Executive Creative Director", "Creative Lead",
      "Brand Creative Director", "Sr. Creative Director", "Digital Creative Director",
      "Art Director", "Design Lead"
    ]
  }
}

Taxonomy

GET/api/v1/taxonomy

Returns the full role taxonomy tree grouped by industry. Useful for building search UIs.

Examples

cURLbash

curl -H "X-API-Key: aj_your_key" \
  https://agentjobsai.com/api/v1/taxonomy

Rate Limits & Pricing

Rate limits are enforced per API key on a daily basis. When you exceed your limit, the API returns 429 Too Many Requests.

Rate Limit Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1711036800

See the Pricing page for full tier comparison. Rate limits reset daily at midnight UTC.

Response Schema

All API responses follow a consistent envelope. Successful responses return the data directly. Errors return a standard error object.

Success (200)

{
  "jobs": [...],
  "pagination": {...},
  "meta": {...}
}

Error (4xx)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid parameter",
    "details": [...]
  }
}

MCP Server (Claude)

Install the AgentJobs MCP server to give Claude native access to job search. Claude can then search for jobs, filter by industry, and return structured results directly in conversation.

Installation

Terminalbash

npx agentjobs-mcp

Claude Desktop Config

claude_desktop_config.jsonjson

{
  "mcpServers": {
    "agentjobs": {
      "command": "npx",
      "args": ["agentjobs-mcp"],
      "env": {
        "AGENTJOBS_API_KEY": "aj_your_key_here"
      }
    }
  }
}

Available MCP Tools

search_jobsSearch for jobs with natural language queries and filters

get_jobGet full details for a specific job by ID

list_industriesList all available industries

suggest_rolesExpand a role into related titles

ChatGPT Actions

Import our OpenAPI specification as a ChatGPT Action to enable job search in custom GPTs and ChatGPT conversations.

Setup Steps

1Go to ChatGPT > Explore GPTs > Create a GPT
2Under "Actions", click "Import from URL"
3Paste the OpenAPI spec URL below
4Set Authentication to "API Key" with header "X-API-Key"
5Save and test with a job search query

OpenAPI Spec URLtext

https://agentjobsai.com/api/openapi.json

OpenAI / ChatGPT Plugin Guide

For custom GPT builders, our OpenAPI spec can be imported directly. This enables any custom GPT to search for jobs using natural language.

Plugin manifestjson

{
  "schema_version": "v1",
  "name_for_human": "AgentJobs",
  "name_for_model": "agentjobs",
  "description_for_human": "Search for AI-curated job listings across 400+ companies.",
  "description_for_model": "Search for job listings. Supports filtering by role, industry, region, and remote status.",
  "auth": {
    "type": "service_http",
    "authorization_type": "bearer",
    "verification_tokens": {}
  },
  "api": {
    "type": "openapi",
    "url": "https://agentjobsai.com/api/openapi.json"
  }
}

Embeddable Widget

Embed a live job feed on your website with a single script tag. See the Widget page for a live preview and configuration tool.

HTMLhtml

<script
  src="https://agentjobsai.com/api/widget?industry=crypto&role=creative-director&max=5&theme=dark"
  async>
</script>

For Employers

Featured listings get priority placement when AI agents search for matching roles. Your job appears first across Claude, ChatGPT, and every platform using our API.

Featured Listing Benefits

Priority placement in all API search results
Featured badge shown across all platforms and widgets
Real-time analytics dashboard with AI impression tracking
Schema.org structured data for maximum AI discoverability
Direct apply link served to candidates via AI

See Pricing for featured listing rates, or visit the Employer Dashboard to manage your listings.