# API Overview

The [Web3.career API](https://web3.career/web3-jobs-api) provides programmatic access to one of the largest aggregated databases of Web3, blockchain, and cryptocurrency job listings. It serves as a single endpoint that returns structured job data with powerful filtering capabilities.

### What the API Can Do <a href="#what-the-api-can-do" id="what-the-api-can-do"></a>

* **Search Web3 job listings** across hundreds of companies in the blockchain/crypto space
* **Filter by technology** — target specific languages (Solidity, Rust, TypeScript), frameworks (React, Hardhat), or ecosystems (Ethereum, Solana, Polkadot)
* **Filter by role type** — engineering, marketing, design, research, product, community, legal, finance, and more
* **Filter by geography** — search by country using slug-based identifiers
* **Filter for remote positions** — isolate fully remote roles
* **Control response size** — retrieve between 1 and 100 listings per request
* **Toggle descriptions** — include or exclude full job descriptions to control payload size

### Key Characteristics <a href="#key-characteristics" id="key-characteristics"></a>

| Property          | Detail                                     |
| ----------------- | ------------------------------------------ |
| **Base URL**      | `https://web3.career/api/v1`               |
| **Protocol**      | HTTPS only                                 |
| **Method**        | `GET`                                      |
| **Auth**          | API token as query parameter               |
| **Formats**       | JSON (`.../v1`) and RSS XML (`.../v1.xml`) |
| **Rate Limiting** | Yes (429 responses when exceeded)          |
| **Max Results**   | 100 per request                            |
| **Pagination**    | Via `limit` parameter (no cursor/offset)   |

### Getting an API Token <a href="#getting-an-api-token" id="getting-an-api-token"></a>

1. Visit <https://web3.career/web3-jobs-api>
2. Sign up or log in to your account
3. Generate your API token
4. Store it securely — treat it like a password

### Quick Example <a href="#quick-example" id="quick-example"></a>

```bash
# Fetch 5 remote Solidity jobs (JSON)
curl "https://web3.career/api/v1?token=YOUR_TOKEN&tag=solidity&remote=true&limit=5"

# Same query as RSS XML
curl "https://web3.career/api/v1.xml?token=YOUR_TOKEN&tag=solidity&remote=true&limit=5"
```

### Terms of Use <a href="#terms-of-use" id="terms-of-use"></a>

The API has mandatory requirements that must be followed to maintain access:

1. **Link attribution is required.** When displaying jobs, you must link to the job using the `apply_url` field with a **follow link** (`rel="follow"` or no `rel` attribute). Do **not** use `rel="nofollow"`. Failure to provide follow links back to web3.career will result in API access suspension.
2. **Do not modify `apply_url`.** Do not append tracking parameters (e.g., `utm_source`, `utm_medium`, `ref`) to the URL. Required tracking parameters are already embedded in the URL by web3.career.
3. **Keep your token private.** Your token is for your use only. Do not share it, commit it to version control, or expose it in client-side code.

### Documentation Index <a href="#documentation-index" id="documentation-index"></a>

| Document                                                                                                                            | Description                                                                             |
| ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| [API Reference](https://file+.vscode-resource.vscode-cdn.net/Users/paulmartin/Github/Web3-career-mcp/docs/API-Reference.md)         | Complete endpoint specification, parameters, response format, and field definitions     |
| [Filtering Guide](https://file+.vscode-resource.vscode-cdn.net/Users/paulmartin/Github/Web3-career-mcp/docs/API-Filtering-Guide.md) | Deep dive into tags, countries, combining filters, and practical search strategies      |
| [Best Practices](https://file+.vscode-resource.vscode-cdn.net/Users/paulmartin/Github/Web3-career-mcp/docs/API-Best-Practices.md)   | Rate limiting, caching, error handling, response parsing, and production tips           |
| [OpenAPI Spec](https://file+.vscode-resource.vscode-cdn.net/Users/paulmartin/Github/Web3-career-mcp/docs/openapi.yaml)              | Machine-readable OpenAPI 3.1 specification for code generation, Swagger UI, and tooling |