# indeed-skills: Indeed job postings API skills for AI agents

[![License: MIT-0](https://img.shields.io/badge/License-MIT--0-blue.svg)](LICENSE)
[![Python 3.8+](https://img.shields.io/badge/Python-3.8%2B-green.svg)](https://www.python.org/)
[![RolesAPI](https://img.shields.io/badge/API-rolesapi.com-orange.svg)](https://rolesapi.com)

**Agent skills for live Indeed job postings data.** Three drop-in skills that give Claude, ChatGPT, Cursor, or any custom agent loop a job postings API: search Indeed listings by keyword and location, fetch normalized role details, and look up salaries, descriptions, company info, and benefits over the [RolesAPI](https://rolesapi.com) REST API. If you have been looking for an Indeed API or an Indeed data API alternative that returns clean JSON, this is the fastest way to wire jobs data into an AI agent.

Free to start. [Grab a key](https://rolesapi.com/app/keys) (100 credits at signup, no card required) and you are searching live job postings from your agent in under two minutes.

Pure Python standard library. No dependencies. MIT-0 licensed.

## Install

```bash
# OpenClaw (via ClawHub)
npx clawhub@latest install indeed-full

# Hermes Agent
hermes skills install skills-sh/nikhonit/indeed-skills/skills/indeed-full

# Generic agent skills (Claude Code, Cursor, Cline)
npx skills add nikhonit/indeed-skills
```

Swap `indeed-full` for `indeed-search` or `indeed-salary` to install a focused variant.

## Skills in this repo

| Skill | What it does | Credit cost |
|---|---|---|
| [`indeed-full`](skills/indeed-full) | Complete toolkit: search listings, full role details by job key or pasted URL, salary, description, company, and benefits slices, account check | 1 credit per call |
| [`indeed-search`](skills/indeed-search) | Lightweight search: listings by keyword and location, plus posted-today, posted-this-week, and remote-only presets | 1 credit per results page |
| [`indeed-salary`](skills/indeed-salary) | Salary-only lookups by job key or pasted Indeed URL | 1 credit per lookup |

Install `indeed-full` for agents that need broad coverage. Install the focused variants when you want minimum tool surface.

## Quickstart

1. Sign up at [rolesapi.com](https://rolesapi.com) and create a key at [rolesapi.com/app/keys](https://rolesapi.com/app/keys). The free plan includes 100 credits, no card required.
2. Export the key and run a script:

```bash
export ROLESAPI_KEY="rk_live_..."
python3 skills/indeed-search/scripts/search_listings.py "registered nurse" "Chicago, IL"
```

Real output, trimmed to one of the 35 results:

```json
{
  "data": [
    {
      "job_key": "7dcf172c8d7fc756",
      "title": "Nursing",
      "company": { "name": "Golden Healthcare Services Inc" },
      "location": "Olympia Fields, IL 60461",
      "employment_type": "Full-time",
      "salary": { "min": 30, "max": 45, "period": "hour", "currency": "USD", "source": "employer" },
      "posted_at": "2026-06-26",
      "url": "https://www.indeed.com/viewjob?jk=7dcf172c8d7fc756"
    }
  ],
  "meta": { "count": 35 },
  "request_id": "a18e4ef88ad4b00b"
}
```

Feed any `job_key` into the detail scripts:

```bash
python3 skills/indeed-full/scripts/get_role.py 7dcf172c8d7fc756
python3 skills/indeed-salary/scripts/get_salary.py 7dcf172c8d7fc756
```

Full walkthrough: [rolesapi.com quickstart](https://rolesapi.com/getting-started/quickstart/).

## Works with

- **Claude Code / Claude Skills**: drop a skill folder into your skills directory and Claude picks it up from the SKILL.md.
- **ChatGPT and custom GPTs**: call the scripts from a code interpreter or wrap them as actions.
- **Cursor, Cline, and other coding agents**: the scripts are plain CLI tools, so any agent that can run Python can use them.
- **Any agent loop**: each script is a self-contained stdin-free CLI that prints JSON, easy to shell out to from Node, Go, or Rust.
- **Zero-install option**: RolesAPI ships a hosted MCP server at `https://api.rolesapi.com/mcp`. Point your MCP client at it and skip the scripts entirely.

There is also an [llms.txt](https://rolesapi.com/llms.txt) (and [llms-full.txt](https://rolesapi.com/llms-full.txt)) if you want to hand the whole API surface to a model.

## What you get back

Normalized role objects across 60+ Indeed country editions: title, company with rating, location, employment type, salary (min, max, currency, period, employer vs estimate), benefits, full description, posted date, and canonical URL. Every response is an envelope of `{ "data": ..., "request_id": "..." }`. See the [roles API docs](https://rolesapi.com/api/roles/), [search API docs](https://rolesapi.com/api/search/), [listings API docs](https://rolesapi.com/api/listings/), and the [OpenAPI spec](https://rolesapi.com/openapi.json).

For bulk work, the API also offers async search and batch enrichment of up to 500 postings per job, with completion events delivered via signed webhooks.

## Authentication

Set the `ROLESAPI_KEY` environment variable to your RolesAPI key (format `rk_live_...`).

```bash
export ROLESAPI_KEY="rk_live_..."
```

**[Get a free key](https://rolesapi.com/app/keys)**: 100 credits at signup, no card required. The same key works for these skills, the hosted MCP server, and direct REST calls.

## Pricing

| Plan | Price | Credits | Rate limit |
|---|---|---|---|
| Free | $0 | 100 (one time at signup) | 20/min |
| Monthly | $5/mo | 1,000/month | 200/min |
| Annual | $54/yr | 12,000 upfront | 300/min |

One credit equals one role detail or one search results page. Failed calls are not charged. Full pricing: [rolesapi.com/pricing](https://rolesapi.com/pricing/).

## FAQ

**How do I get Indeed job postings as JSON?**
Sign up at [rolesapi.com](https://rolesapi.com), export `ROLESAPI_KEY`, and call `GET /v1/listings?keyword=...&location=...` (or run `search_listings.py` from this repo). You get back normalized JSON role summaries with job keys for follow-up detail calls.

**Is there a free Indeed jobs API?**
The RolesAPI free plan includes 100 credits at signup with no card required, enough for 100 searches or role lookups. Paid plans start at $5/month for 1,000 credits.

**How much does it cost?**
1 credit per role detail or search results page. $5/month for 1,000 credits, or $54/year for 12,000. Failed calls are not charged.

**Does this work outside the United States?**
Yes. Pass `--country` (for example `gb`, `de`, `in`) to search any of the 60+ Indeed country editions.

**Can I get the salary for a specific Indeed posting?**
Yes. `GET /v1/roles/{job_key}/salary` returns min, max, currency, period, and whether the figure came from the employer or an estimate. The `indeed-salary` skill wraps exactly this, and also accepts a pasted Indeed URL.

**Can my agent use this without installing anything?**
Yes. Point an MCP client at the hosted server, `https://api.rolesapi.com/mcp`, and the same search and role tools are available with zero install.

**Is this an official Indeed API?**
No. RolesAPI is an independent product. See the disclaimer below.

## Issues and contributions

See [CONTRIBUTING.md](CONTRIBUTING.md). Security reports: [SECURITY.md](SECURITY.md).

## License

[MIT No Attribution](LICENSE). Fork, ship, sublicense. No attribution required.

## Disclaimer

RolesAPI is an independent product and is not affiliated with, endorsed by, or sponsored by Indeed. Indeed is a trademark of its owner.