# isbul.net — Full AI/Agent Documentation

> Version: 1.0 | Updated: 2026-05 | Language: Turkish (tr-TR)

## About

isbul.net is Turkey's leading job board and employment platform. Founded in 2008, it is a private employment agency (Özel İstihdam Bürosu) approved by İŞKUR (Turkish Employment Agency), operated by Gezer Grup İnsan Kaynakları Eğitim ve Danışmanlık Ticaret A.Ş.

The platform connects millions of job seekers with thousands of Turkish employers. All UI content is in Turkish. The platform supports AI agents via public REST endpoints and an MCP server.

---

## Capabilities for AI Agents

### What agents can do on isbul.net
- Search active job listings by keyword, city, category, work type
- Browse employer company profiles
- Read editorial career guide articles (Turkish)
- Look up salary ranges for specific job positions
- Direct users to relevant job listing URLs

### What agents cannot do (requires human login)
- Apply to jobs on behalf of a user
- Access CV/resume data
- Access employer dashboards
- Post or manage job listings

---

## Public REST API

Base URL: `https://www.isbul.net/api/agent`

All endpoints are unauthenticated, CORS-enabled, and return JSON.

### GET /api/agent
Returns this capability index.

### GET /api/agent/jobs
Search active job listings.

Parameters:
- `q` (string) — full-text search (Turkish or English)
- `city` (string) — city slug: istanbul | ankara | izmir | bursa | antalya | adana | kocaeli | konya | mersin | gaziantep | kayseri | samsun | denizli | eskisehir | tekirdag
- `category` (string) — position/category slug
- `page` (integer, default 1)
- `per_page` (integer, default 10, max 25)

Response shape:
```json
{
  "data": [
    {
      "id": "string",
      "title": "string",
      "company": "string",
      "company_slug": "string",
      "city": "string",
      "district": "string",
      "work_type": "Tam Zamanlı | Yarı Zamanlı | Uzaktan | Hibrit",
      "position": "string",
      "sector": "string",
      "salary": "string | null",
      "published_at": "ISO8601",
      "expires_at": "ISO8601 | null",
      "url": "https://www.isbul.net/is-ilani/{slug}",
      "slug": "string"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 10,
    "per_page": 10,
    "total": 95,
    "from": 1,
    "to": 10
  },
  "source": "isbul.net"
}
```

### GET /api/agent/companies
Search employer profiles.

Parameters:
- `q` (string) — company name
- `page` (integer, default 1)
- `per_page` (integer, default 10, max 25)

Response shape:
```json
{
  "data": [
    {
      "id": "string",
      "name": "string",
      "slug": "string",
      "url": "https://www.isbul.net/firma/{slug}"
    }
  ],
  "meta": { "current_page": 1, "last_page": 1, "per_page": 10, "total": 5 },
  "source": "isbul.net"
}
```

---

## MCP Server

isbul.net provides an MCP (Model Context Protocol) server for AI agents that support the protocol.

### stdio transport (local use)
```bash
node --experimental-strip-types /path/to/mcp/server.ts
```

Environment variable: `ISBUL_API_URL=https://api.isbul.net` (optional, defaults to production)

### Claude Desktop configuration
```json
{
  "mcpServers": {
    "isbul": {
      "command": "node",
      "args": ["--experimental-strip-types", "/absolute/path/to/mcp/server.ts"],
      "env": { "ISBUL_API_URL": "https://api.isbul.net" }
    }
  }
}
```

### Available MCP Tools

| Tool | Description | Required params |
|---|---|---|
| `search_jobs` | Search active job listings | — |
| `get_job_details` | Full job posting details | `slug` |
| `search_companies` | Search employer profiles | — |
| `get_company_profile` | Company details by slug | `slug` |
| `search_career_guides` | Search career articles | — |
| `get_salary_info` | Salary range for a position | `position_slug` |

---

## Authentication

The public agent API (`/api/agent/*`) requires **no authentication**.

The AI chat endpoint (`/api/ai/chat`) requires no user auth but does require a server-side `ANTHROPIC_API_KEY` configured by the platform operator.

There are no per-agent API keys, rate limit tokens, or OAuth flows required for read-only data access.

---

## Rate Limits

Public agent endpoints are subject to the same rate limiting as all other public routes (Redis-backed, per-IP). Agents should:
- Use `per_page` ≤ 25
- Cache responses for at least 60 seconds
- Avoid parallel bulk scraping

---

## Data Coverage

| Data type | Count (approx) | Freshness |
|---|---|---|
| Active job listings | 50,000+ | Real-time (posted/expired by employers) |
| Company profiles | 20,000+ | Updated by employers |
| Career guide articles | 500+ | Several new articles per week |
| Cities covered | 81 Turkish provinces | Static |
| Job categories | 500+ positions | Updated quarterly |

---

## Key Public URLs

### Homepage & Discovery
- Homepage: https://www.isbul.net/
- All jobs: https://www.isbul.net/is-ilanlari
- Companies: https://www.isbul.net/firmalar
- Career guide: https://www.isbul.net/is-rehberi
- Position directory: https://www.isbul.net/pozisyonlar
- Site map: https://www.isbul.net/site-haritasi

### City Job Pages
- Istanbul: https://www.isbul.net/is-ilanlari/istanbul
- Ankara: https://www.isbul.net/is-ilanlari/ankara
- Izmir: https://www.isbul.net/is-ilanlari/izmir
- Bursa: https://www.isbul.net/is-ilanlari/bursa
- Antalya: https://www.isbul.net/is-ilanlari/antalya
- Adana: https://www.isbul.net/is-ilanlari/adana
- Kocaeli: https://www.isbul.net/is-ilanlari/kocaeli
- Konya: https://www.isbul.net/is-ilanlari/konya
- Mersin: https://www.isbul.net/is-ilanlari/mersin
- Gaziantep: https://www.isbul.net/is-ilanlari/gaziantep
- Kayseri: https://www.isbul.net/is-ilanlari/kayseri
- Samsun: https://www.isbul.net/is-ilanlari/samsun

### Popular Category Pages
- Software Developer: https://www.isbul.net/is-ilanlari/yazilimci
- Accounting: https://www.isbul.net/is-ilanlari/muhasebe-uzmani
- Nurse: https://www.isbul.net/is-ilanlari/hemsire
- Teacher: https://www.isbul.net/is-ilanlari/ogretmen
- Sales Rep: https://www.isbul.net/is-ilanlari/satis-temsilcisi
- Digital Marketing: https://www.isbul.net/is-ilanlari/dijital-pazarlama-uzmani
- Cashier: https://www.isbul.net/is-ilanlari/kasiyer
- Security Guard: https://www.isbul.net/is-ilanlari/guvenlik-gorevlisi
- Driver: https://www.isbul.net/is-ilanlari/sofor
- Cook: https://www.isbul.net/is-ilanlari/asci

### Calculation Tools
- Salary calculator: https://www.isbul.net/hesaplama-araclari/maas-hesaplama
- All tools: https://www.isbul.net/hesaplama-araclari

### Sitemaps (XML)
- Index: https://www.isbul.net/sitemap.xml
- Job details: https://www.isbul.net/sitemaps/adverts_details.xml
- Job listings: https://www.isbul.net/sitemaps/adverts_listing.xml
- Companies: https://www.isbul.net/sitemaps/companies_index.xml
- Blog: https://www.isbul.net/sitemaps/blog.xml
- Positions: https://www.isbul.net/sitemaps/positions.xml

---

## Technical Notes for Agents

- All job listing pages include `JobPosting` Schema.org JSON-LD
- Company pages include `Organization` Schema.org JSON-LD
- The site root includes `EmploymentAgency` + `WebSite` (with `SearchAction`) JSON-LD
- All LLM crawlers are explicitly allowed full access in robots.txt
- Canonical URLs use no trailing slash
- Turkish characters in slugs are transliterated (ş→s, ı→i, ğ→g, ü→u, ö→o, ç→c)
- Job slugs follow the pattern: `{title}-{company}-{city}-{id}`

---

## Contact & Legal

- Operator: Gezer Grup İnsan Kaynakları Eğitim ve Danışmanlık Ticaret A.Ş.
- Email: info@isbul.net
- Phone: +90 549 598 2502
- İŞKUR License: Özel İstihdam Bürosu (Private Employment Agency)
- Privacy (KVKK): https://www.isbul.net/kurumsal/kvkk-metni
- Terms: https://www.isbul.net/kurumsal/kullanim-kosullari