Jobs Navi API for AI Agents

Why MCP?

「AIはサイトを直接見て答えられるのに、なぜMCPを噛ませる？」への答えです。1回限りの質問なら確かに不要、ただし複数サイト横断・定期実行・厳密フィルタ・大量取得で差が出ます。

観点	Webアクセス（MCPなし）	MCP経由
データ形式	HTMLをLLMが解釈	構造化JSONを即返却
レスポンス速度	数秒〜十数秒	100ms前後（DB直叩き）
2サイト横断	humanoid と physicalai を別々に巡回	1リクエストで両方（site_code省略）
フィルタ精度	UI表示できる範囲のみ	`salary_min` / `is_remote` / `prefecture` 等を厳密指定
大量取得	スクレイピングはブロック懸念	`offset/limit` で安全に全件
サイト改修耐性	レイアウト変更で壊れる	スキーマ固定で安定
定期実行（cron）	毎回ブラウザ起動 → 遅い・重い	curl 1発で済む

つまり「AIに今すぐ1件聞きたいだけ」なら不要。「自動化ワークフローに組み込みたい」「毎日集計したい」「2サイト同時に正確に検索したい」ならMCPが圧倒的に楽です。

Use Cases

AIエージェントが humanoid-jobs.com / physicalai-jobs.com の求人データを横断利用する代表的なシナリオです。

横断求人検索

シーン：「ヒューマノイドかフィジカルAIで、年収800万以上のリモート求人を探して」
動作：サイト指定なしで jobs_search を呼ぶだけで両サイトを同時検索。

jobs_search jobs_detail categories

企業リサーチ

シーン：「Boston Dynamicsっぽい企業を全部出して、技術スタックと求人数を一覧化」
動作：companies_search → companies_detail で技術スタック・募集職種まで取得。

companies_search companies_detail

業界ニュース解析

シーン：「ヒューマノイド業界の最新トレンドを記事から要約して」
動作：articles_search で記事を取得 → articles_detail で本文を解析。

articles_search articles_detail

マーケット定点観測

シーン：「ヒューマノイド求人数とフィジカルAI求人数の推移を毎週レポート」
動作：stats を週次cronで叩いてSlackに送るだけ。

stats sites_list health

Quick Start

Claude Code / Cursor などの MCP対応AIから3ステップで Jobs Navi に接続できます。

① （書き込みのみ）APIキーを発行
humanoid-jobs.com にログイン → /mypage/api-keys/ でキー生成。読み取りだけならスキップOK。
② MCPサーバーを設定ファイルに追加
Claude Code (.mcp.json) または Cursor (~/.cursor/mcp.json) に追加。env はキー発行した人だけ。
{ "mcpServers": { "jobs-navi": { "command": "npx", "args": ["-y", "jobs-navi-mcp"], "env": { "JOBS_NAVI_API_KEY": "jn_your_api_key_here" } } } }
③ AIクライアントを再起動
起動時に npx 経由で jobs-navi-mcp を自動取得。再起動後、24ツールが認識されます。
④ 自然言語で頼む
# 読み取り例 > 東京でロボティクスエンジニア、年収800万以上の求人ある？ > Boston Dynamicsが今出してる求人を全部教えて # 書き込み例（要APIキー） > 新しい求人を作って：シニアロボットエンジニア、年収900〜1500万、リモート可 > 自社プロフィールの説明文を「2026年度シリーズB完了」に更新して > 私の希望年収を900万に変えて、東京/神奈川希望にして

Connection Methods

Claude Code / Cursor / HTTP API の3通りで接続できます。HTTP APIならChatGPT Custom GPT Actionsからも呼べます。

.mcp.json または ~/.claude.json に下記を追加します。JOBS_NAVI_API_KEY は書き込みツール利用時に必須（読み取りのみなら省略可）。

{
  "jobs-navi": {
    "command": "npx",
    "args": ["-y", "jobs-navi-mcp"],
    "env": {
      "JOBS_NAVI_API_KEY": "jn_your_api_key_here"
    }
  }
}

~/.cursor/mcp.json に下記を追加。

{
  "mcpServers": {
    "jobs-navi": {
      "command": "npx",
      "args": ["-y", "jobs-navi-mcp"],
      "env": {
        "JOBS_NAVI_API_KEY": "jn_your_api_key_here"
      }
    }
  }
}

※ ChatGPT は Remote MCP 未対応です。 Custom GPT Actions から HTTP API を呼び出してください。

# Custom GPT Actions 設定
# Server URL
https://humanoid-jobs.com/api/mcp.php

# Method: POST / Body 例
{
  "action": "jobs.search",
  "params": { "keyword": "ロボティクス" }
}

読み取りは認証不要、書き込みは Authorization: Bearer jn_xxx が必要です。

# 読み取り（認証不要）
curl -X POST https://humanoid-jobs.com/api/mcp.php \
  -H "Content-Type: application/json" \
  -d '{"action": "jobs.search", "params": {"keyword": "ロボット", "limit": 5}}'

# 書き込み（APIキー必須）
curl -X POST https://humanoid-jobs.com/api/mcp.php \
  -H "Authorization: Bearer jn_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"action": "jobs.publish", "params": {"id": 15}}'

Authentication

読み取り12ツールは認証不要。書き込み12ツール（求人作成・更新・公開、自社/求職者プロフィール編集など）は jn_xxx 形式のAPIキーが必須です。

① APIキーを発行

humanoid-jobs.com にログイン後、/mypage/api-keys/ でキーを生成。jn_ + 48文字hex の51文字、最大5本まで保有可能。

② Bearer Token として送信

HTTP直叩きする場合は Authorization ヘッダに付与。Node.js MCPは JOBS_NAVI_API_KEY 環境変数で自動付与されます。

Authorization: Bearer jn_a1b2c3d4e5f6...

③ あなたのリソースだけ書き換え可

APIキーは発行ユーザーに紐付くため、自社の求人 / 自分のプロフィールのみ更新できます。他社の求人は読み取り可・書き込み不可です。

キー仕様 + セキュリティ

詳細仕様・多層防御・レート制限は Security / Rate Limits セクションを参照してください。

SHA-256ハッシュ保存（DBが漏洩しても平文キーは取り出せない）
本人リソースのみ操作可（他社/他人 = 404）
レート制限 Read 200/min、Write 30/min
即時失効可 /mypage/api-keys/ の「失効」ボタン

API Reference - 36 Tools

全36ツールの一覧。クリックでパラメータとレスポンス例を展開します。site_code 省略で横断検索。【要APIキー】のツールは書き込み・自分のリソース操作用です。

Utility

3 tools

READ health MCPサーバーのヘルスチェック。各サイトの求人数・企業数・記事数を返す

MCPサーバーのヘルスチェック。各サイトの求人数・企業数・記事数を返す

No parameters required.

Response Example

                        {
    "success": true,
    "data": {
        "status": "ok",
        "sites": [
            {
                "site_code": "humanoid",
                "name": "ヒューマノイドジョブ",
                "domain": "humanoid-jobs.com",
                "job_count": 1,
                "company_count": 1,
                "article_count": 0
            },
            {
                "site_code": "physicalai",
                "name": "フィジカルAIジョブ",
                "domain": "physicalai-jobs.com",
                "job_count": 0,
                "company_count": 0,
                "article_count": 0
            }
        ]
    }
}
                    

READ sites_list 横断対象のサイト一覧を返す（コード・名称・ドメイン・テーマカラー）

横断対象のサイト一覧を返す（コード・名称・ドメイン・テーマカラー）

No parameters required.

Response Example

                        {
    "success": true,
    "data": [
        {
            "site_code": "humanoid",
            "name": "ヒューマノイドジョブ",
            "domain": "humanoid-jobs.com",
            "specialty": "ロボット・ヒューマノイド人材特化",
            "theme_color": "#0EA5E9"
        },
        {
            "site_code": "physicalai",
            "name": "フィジカルAIジョブ",
            "domain": "physicalai-jobs.com",
            "specialty": "フィジカルAI人材特化",
            "theme_color": "#0d9488"
        }
    ]
}
                    

READ categories 求人カテゴリ一覧を求人件数付きで返す

求人カテゴリ一覧を求人件数付きで返す

Parameter	Type	Required	Description
`site_code`	`string`		humanoid / physicalai（省略で横断）

Response Example

                        {
    "success": true,
    "data": [
        {
            "site_code": "humanoid",
            "slug": "robot-engineer",
            "name": "ロボットエンジニア",
            "parent_slug": null,
            "description": null,
            "job_count": 1
        }
    ]
}
                    

Jobs

3 tools

READ jobs_search 求人をキーワード・カテゴリ・都道府県・雇用形態・リモート・給与でフィルタ検索

求人をキーワード・カテゴリ・都道府県・雇用形態・リモート・給与でフィルタ検索

Parameter	Type	Description
`site_code`	`string`	humanoid / physicalai（省略で横断）
`keyword`	`string`	職種名・スキル・企業名
`category_slug`	`string`	カテゴリスラッグ
`prefecture`	`string`	都道府県名 (例: 東京都)
`employment_type`	`string`	full_time / part_time / contract / freelance / internship
`is_remote`	`boolean`	リモート可のみ true
`salary_min`	`number`	最低給与（万円）
`limit`	`number`	返却件数（default 20, max 100）
`offset`	`number`	オフセット（ページネーション）

Response Example

                        {
    "success": true,
    "data": {
        "total": 11,
        "limit": 20,
        "offset": 0,
        "results": [
            {
                "id": 1,
                "site_code": "humanoid",
                "slug": "sample",
                "title": "ヒューマノイドロボットエンジニア",
                "employment_type": "full_time",
                "prefecture": "東京都",
                "is_remote": 0,
                "salary_min": 6000000,
                "salary_max": 12000000,
                "company_name": "Sample Robotics"
            }
        ]
    }
}
                    

READ jobs_detail 求人の詳細情報を取得（スキル要件・福利厚生・企業情報）

求人の詳細情報を取得（スキル要件・福利厚生・企業情報）

Parameter	Type	Description
`id`	`number`	求人ID（id または slug 必須）
`slug`	`string`	求人スラッグ
`site_code`	`string`	slug指定時の対象サイト

Response Example

                        {
    "success": true,
    "data": {
        "id": 1,
        "title": "ヒューマノイドロボットエンジニア",
        "description": "...",
        "skills_required": [
            "ROS2",
            "C++",
            "Python"
        ],
        "company_name": "Sample Robotics",
        "industry": "ロボティクス"
    }
}
                    

READ jobs_list 新着または注目求人の一覧（トップページ・ウィジェット用）

新着または注目求人の一覧（トップページ・ウィジェット用）

Parameter	Type	Description
`site_code`	`string`	humanoid / physicalai
`featured_only`	`boolean`	注目求人のみ true
`limit`	`number`	返却件数

Response Example

                        {
    "success": true,
    "data": [
        {
            "id": 1,
            "title": "求人例",
            "is_featured": 1,
            "company_name": "Sample Robotics"
        }
    ]
}
                    

Companies

2 tools

READ companies_search 企業をキーワード・業種でフィルタ検索（アクティブ求人数付き）

企業をキーワード・業種でフィルタ検索（アクティブ求人数付き）

Parameter	Type	Description
`site_code`	`string`	humanoid / physicalai
`keyword`	`string`	企業名・説明のキーワード
`industry`	`string`	業種（例: ロボティクス）
`limit`	`number`	返却件数（default 20, max 50）

Response Example

                        {
    "success": true,
    "data": [
        {
            "id": 1,
            "company_name": "Sample Robotics",
            "industry": "ロボティクス",
            "active_job_count": 3
        }
    ]
}
                    

READ companies_detail 企業の詳細情報（技術スタック・オフィス画像・アクティブ求人一覧）

企業の詳細情報（技術スタック・オフィス画像・アクティブ求人一覧）

Parameter	Type	Description
`id`	`number`	企業ID（id または slug 必須）
`slug`	`string`	企業公開スラッグ
`site_code`	`string`	slug指定時の対象サイト

Response Example

                        {
    "success": true,
    "data": {
        "id": 1,
        "company_name": "Sample Robotics",
        "tech_stack": [
            "ROS2",
            "Python"
        ],
        "active_jobs": [
            {
                "id": 1,
                "title": "エンジニア"
            }
        ]
    }
}
                    

Articles

2 tools

READ articles_search 求人関連記事をキーワード・カテゴリで検索

求人関連記事をキーワード・カテゴリで検索

Parameter	Type	Description
`site_code`	`string`	humanoid / physicalai
`keyword`	`string`	タイトル・本文のキーワード
`category`	`string`	記事カテゴリ
`limit`	`number`	返却件数

Response Example

                        {
    "success": true,
    "data": [
        {
            "id": 1,
            "title": "業界の最新トレンド",
            "category": "trend",
            "view_count": 1234
        }
    ]
}
                    

READ articles_detail 記事本文を含む詳細情報を取得

記事本文を含む詳細情報を取得

Parameter	Type	Required	Description
`slug`	`string`	YES	記事スラッグ
`site_code`	`string`		対象サイト

Response Example

                        {
    "success": true,
    "data": {
        "slug": "example",
        "title": "記事タイトル",
        "body": "記事本文..."
    }
}
                    

Stats & Plans

2 tools

READ stats サイトごとの統計情報（アクティブ求人数・企業数・求職者数・応募数・記事数）

サイトごとの統計情報（アクティブ求人数・企業数・求職者数・応募数・記事数）

Parameter	Type	Required	Description
`site_code`	`string`		humanoid / physicalai

Response Example

                        {
    "success": true,
    "data": [
        {
            "site_code": "humanoid",
            "active_jobs": 1,
            "companies": 1,
            "seekers": 0,
            "applications": 0,
            "articles": 0
        }
    ]
}
                    

READ plans 企業向け掲載プラン一覧（プラン名・月額・求人枠・スカウト枠・機能）

企業向け掲載プラン一覧（プラン名・月額・求人枠・スカウト枠・機能）

Parameter	Type	Required	Description
`site_code`	`string`		humanoid / physicalai

Response Example

                        {
    "success": true,
    "data": [
        {
            "slug": "basic",
            "name": "ベーシック",
            "price_monthly": 30000,
            "job_limit": 3
        }
    ]
}
                    

Auth

1 tools

READ auth_me 【要APIキー】APIキーに紐づくユーザー情報を返す。接続確認に使う

【要APIキー】APIキーに紐づくユーザー情報を返す。接続確認に使う

No parameters required.

Response Example

                        {
    "success": true,
    "data": {
        "user_id": 2,
        "email": "company@example.com",
        "name": "テスト株式会社",
        "role": "company"
    }
}
                    

Jobs Write

5 tools

WRITE jobs_my_list 【要APIキー / 企業】自分の会社が掲載中の求人一覧（draft含む）を返す

【要APIキー / 企業】自分の会社が掲載中の求人一覧（draft含む）を返す

Parameter	Type	Required	Description
`status`	`string`		draft / active / closed / paused
`limit`	`number`		返却件数（default 30, max 100）

Response Example

                        {
    "success": true,
    "data": [
        {
            "id": 1,
            "title": "求人",
            "status": "active",
            "view_count": 2
        }
    ]
}
                    

WRITE jobs_create 【要APIキー / 企業】求人を新規作成する（下書き状態で保存）。jobs_publishで公開

【要APIキー / 企業】求人を新規作成する（下書き状態で保存）。jobs_publishで公開

Parameter	Type	Required	Description
`title`	`string`	YES	求人タイトル
`category_slug`	`string`	YES	カテゴリスラッグ
`description`	`string`	YES	求人説明本文
`employment_type`	`string`		full_time / part_time / contract / internship / remote
`location`	`string`		勤務地
`is_remote`	`boolean`		リモート可
`salary_min`	`number`		最低年俸（円）
`salary_max`	`number`		最高年俸（円）
`requirements`	`string`		必須要件
`preferred`	`string`		歓迎要件
`benefits`	`string`		福利厚生

Response Example

                        {
    "success": true,
    "message": "求人を下書きとして作成しました",
    "data": {
        "id": 15,
        "slug": "job-abc123",
        "status": "draft"
    }
}
                    

WRITE jobs_update 【要APIキー / 企業】自社の求人を更新する（指定フィールドのみ上書き）

【要APIキー / 企業】自社の求人を更新する（指定フィールドのみ上書き）

Parameter	Type	Required	Description
`id`	`number`	YES	更新する求人ID
`title`	`string`		タイトル
`salary_min`	`number`		最低年俸
`salary_max`	`number`		最高年俸
`description`	`string`		本文

Response Example

                        {
    "success": true,
    "message": "求人を更新しました",
    "data": {
        "id": 15
    }
}
                    

WRITE jobs_publish 【要APIキー / 企業】求人を公開する（draft → active）

【要APIキー / 企業】求人を公開する（draft → active）

Parameter	Type	Required	Description
`id`	`number`	YES	公開する求人ID

Response Example

                        {
    "success": true,
    "message": "求人を公開しました",
    "data": {
        "id": 15,
        "status": "active"
    }
}
                    

WRITE jobs_close 【要APIキー / 企業】求人を終了する（active → closed）

【要APIキー / 企業】求人を終了する（active → closed）

Parameter	Type	Required	Description
`id`	`number`	YES	終了する求人ID

Response Example

                        {
    "success": true,
    "message": "求人を終了しました",
    "data": {
        "id": 15,
        "status": "closed"
    }
}
                    

Company Profile

2 tools

READ company_profile_get 【要APIキー / 企業】自社の企業プロフィールを取得

【要APIキー / 企業】自社の企業プロフィールを取得

No parameters required.

Response Example

                        {
    "success": true,
    "data": {
        "id": 1,
        "company_name": "テスト株式会社",
        "industry": "ロボティクス",
        "employee_count": "50-100",
        "website_url": "https://example.com"
    }
}
                    

WRITE company_profile_update 【要APIキー / 企業】自社の企業プロフィールを更新（未作成時は新規作成）

【要APIキー / 企業】自社の企業プロフィールを更新（未作成時は新規作成）

Parameter	Type	Description
`company_name`	`string`	会社名（新規作成時は必須）
`company_name_kana`	`string`	フリガナ
`industry`	`string`	業種
`employee_count`	`string`	従業員数（例: 50-100）
`founded_year`	`number`	設立年
`website_url`	`string`	公式サイトURL
`logo_url`	`string`	ロゴURL
`description`	`string`	会社説明
`address`	`string`	住所
`phone`	`string`	電話番号
`contact_person`	`string`	担当者名

Response Example

                        {
    "success": true,
    "message": "企業プロフィールを更新しました",
    "data": {
        "id": 1
    }
}
                    

Seeker Profile

2 tools

READ seeker_profile_get 【要APIキー / 求職者】自分の求職者プロフィールを取得

【要APIキー / 求職者】自分の求職者プロフィールを取得

No parameters required.

Response Example

                        {
    "success": true,
    "data": {
        "id": 1,
        "full_name": "テスト 太郎",
        "prefecture": "東京都",
        "experience_years": 5,
        "desired_job_category": "robot-engineer",
        "is_public": 1
    }
}
                    

WRITE seeker_profile_update 【要APIキー / 求職者】自分のプロフィールを更新（未作成時は新規作成）

【要APIキー / 求職者】自分のプロフィールを更新（未作成時は新規作成）

Parameter	Type	Description
`full_name`	`string`	氏名（新規作成時は必須）
`full_name_kana`	`string`	フリガナ
`birth_year`	`number`	生年（西暦）
`gender`	`string`	male / female / other / prefer_not
`prefecture`	`string`	居住都道府県
`experience_years`	`number`	経験年数
`current_status`	`string`	employed / unemployed / student / other
`desired_job_category`	`string`	希望職種カテゴリ
`desired_salary_min`	`number`	希望最低給与（万円）
`resume_url`	`string`	履歴書URL
`pr_text`	`string`	自己PR
`is_public`	`boolean`	企業に公開するか

Response Example

                        {
    "success": true,
    "message": "求職者プロフィールを更新しました",
    "data": {
        "id": 1
    }
}
                    

Applications

2 tools

READ applications_list 【要APIキー】応募一覧。企業ロールなら自社求人への応募、求職者ロールなら自分が出した応募

【要APIキー】応募一覧。企業ロールなら自社求人への応募、求職者ロールなら自分が出した応募

Parameter	Type	Required	Description
`limit`	`number`		返却件数（default 30, max 100）

Response Example

                        {
    "success": true,
    "data": [
        {
            "id": 1,
            "job_id": 1,
            "job_title": "エンジニア",
            "applicant_name": "テスト太郎",
            "status": "pending",
            "created_at": "2026-05-01 10:00:00"
        }
    ]
}
                    

WRITE applications_update 【要APIキー / 企業】自社求人への応募ステータスを更新

【要APIキー / 企業】自社求人への応募ステータスを更新

Parameter	Type	Required	Description
`id`	`number`	YES	応募ID
`status`	`string`	YES	pending / reviewing / accepted / rejected / withdrawn

Response Example

                        {
    "success": true,
    "message": "応募ステータスを更新しました",
    "data": {
        "id": 1,
        "status": "accepted"
    }
}
                    

Webhooks

3 tools

WRITE webhooks_register 【要APIキー】イベント発生時にPOSTで通知するWebhookを登録（最大5本）

【要APIキー】イベント発生時にPOSTで通知するWebhookを登録（最大5本）

Parameter	Type	Required	Description
`url`	`string`	YES	POST通知先URL（https://必須）
`events`	`array`	YES	new_application / application_status_changed / new_scout / job_published / job_closed
`label`	`string`		識別用ラベル

Response Example

                        {
    "success": true,
    "message": "Webhookを登録しました",
    "data": {
        "id": 1,
        "url": "https://example.com/webhook",
        "events": [
            "new_application"
        ],
        "secret": "abc123..."
    }
}
                    

READ webhooks_list 【要APIキー】登録済みWebhook一覧（呼び出し回数・失敗回数付き）

【要APIキー】登録済みWebhook一覧（呼び出し回数・失敗回数付き）

No parameters required.

Response Example

                        {
    "success": true,
    "data": [
        {
            "id": 1,
            "url": "https://example.com/webhook",
            "events": [
                "new_application"
            ],
            "total_calls": 12,
            "total_failures": 0
        }
    ]
}
                    

WRITE webhooks_delete 【要APIキー】Webhookを削除

【要APIキー】Webhookを削除

Parameter	Type	Required	Description
`id`	`number`	YES	Webhook ID

Response Example

                        {
    "success": true,
    "message": "Webhookを削除しました",
    "data": {
        "id": 1
    }
}
                    

Notifications

2 tools

READ notifications_list 【要APIキー】自分の通知一覧と未読件数を返す

【要APIキー】自分の通知一覧と未読件数を返す

Parameter	Type	Required	Description
`unread_only`	`boolean`		未読のみ true
`limit`	`number`		返却件数（default 30）

Response Example

                        {
    "success": true,
    "data": {
        "unread_count": 3,
        "items": [
            {
                "id": 1,
                "type": "new_application",
                "title": "新着応募がありました",
                "is_read": 0
            }
        ]
    }
}
                    

WRITE notifications_read 【要APIキー】通知を既読にする（ID配列または "all"）

【要APIキー】通知を既読にする（ID配列または "all"）

Parameter	Type	Required	Description
`ids`	`mixed`	YES	ID配列 [1,2,3] または "all"

Response Example

                        {
    "success": true,
    "message": "全ての通知を既読にしました",
    "data": {
        "marked": "all"
    }
}
                    

Bulk & Analytics

4 tools

WRITE jobs_bulk_create 【要APIキー / 企業】求人を一括作成（最大50件、各draft状態）

【要APIキー / 企業】求人を一括作成（最大50件、各draft状態）

Parameter	Type	Required	Description
`jobs`	`array`	YES	求人オブジェクト配列。各要素は jobs_create と同じフィールド

Response Example

                        {
    "success": true,
    "message": "全ての求人を作成しました",
    "data": {
        "created_count": 50,
        "error_count": 0,
        "created": [
            {
                "index": 0,
                "id": 15,
                "slug": "...",
                "title": "..."
            }
        ],
        "errors": []
    }
}
                    

WRITE jobs_clone 【要APIキー / 企業】既存求人を複製（draft状態）

【要APIキー / 企業】既存求人を複製（draft状態）

Parameter	Type	Required	Description
`id`	`number`	YES	複製元の求人ID
`title`	`string`		新求人のタイトル

Response Example

                        {
    "success": true,
    "message": "求人を複製しました",
    "data": {
        "id": 20,
        "slug": "...",
        "cloned_from": 15,
        "status": "draft"
    }
}
                    

READ jobs_analytics 【要APIキー / 企業】求人別の表示数・応募数・お気に入り数・CVR

【要APIキー / 企業】求人別の表示数・応募数・お気に入り数・CVR

Parameter	Type	Required	Description
`id`	`number`		求人ID（省略で全求人集計）

Response Example

                        {
    "success": true,
    "data": {
        "total_jobs": 5,
        "total_views": 1234,
        "total_applications": 42,
        "overall_conversion": 3.41,
        "jobs": [
            {
                "id": 1,
                "title": "...",
                "view_count": 500,
                "application_count": 15,
                "favorite_count": 23
            }
        ]
    }
}
                    

READ applicants_export 【要APIキー / 企業】応募者情報をフラット構造で返す（CSV変換用）

【要APIキー / 企業】応募者情報をフラット構造で返す（CSV変換用）

Parameter	Type	Required	Description
`job_id`	`number`		特定求人で絞り込み
`status`	`string`		pending / reviewing / accepted / rejected / withdrawn

Response Example

                        {
    "success": true,
    "data": {
        "count": 1,
        "applicants": [
            {
                "id": 1,
                "job_title": "ROS2エンジニア",
                "applicant_email": "...",
                "full_name": "テスト 太郎",
                "prefecture": "東京都",
                "status": "pending"
            }
        ]
    }
}
                    

AI Helpers

3 tools

READ salary_benchmark 【要APIキー】サイト内active求人から給与統計（中央値・四分位）を計算

【要APIキー】サイト内active求人から給与統計（中央値・四分位）を計算

Parameter	Type	Description
`category_slug`	`string`	カテゴリスラッグ
`prefecture`	`string`	都道府県
`is_remote`	`boolean`	リモート可のみ

Response Example

                        {
    "success": true,
    "data": {
        "sample_size": 42,
        "min": 3000000,
        "max": 15000000,
        "median": 7500000,
        "p25": 5500000,
        "p75": 10000000,
        "avg": 7800000,
        "unit": "円 / 年"
    }
}
                    

READ jobs_similar 【要APIキー】指定求人と類似する求人を返す（スコアリング）

【要APIキー】指定求人と類似する求人を返す（スコアリング）

Parameter	Type	Required	Description
`id`	`number`	YES	基準求人ID
`limit`	`number`		返却件数（default 10, max 30）

Response Example

                        {
    "success": true,
    "data": {
        "source_id": 15,
        "results": [
            {
                "id": 18,
                "title": "類似求人",
                "similarity_score": 85,
                "company_name": "Sample"
            }
        ]
    }
}
                    

READ jobs_quality_check 【要APIキー / 企業】自社求人を10項目で採点。グレードA-Dと改善ヒントを返す

【要APIキー / 企業】自社求人を10項目で採点。グレードA-Dと改善ヒントを返す

Parameter	Type	Required	Description
`id`	`number`	YES	採点する求人ID

Response Example

                        {
    "success": true,
    "data": {
        "job_id": 15,
        "score": 72,
        "grade": "B",
        "checks": [
            {
                "name": "タイトル20文字以上",
                "pass": true,
                "weight": 10
            }
        ],
        "summary": "良好。改善するともっと応募が増えます"
    }
}
                    

Rate Limits

DoS・乱用防止のため、Nginx層（L4）+ PHP層（L7）の2段でレート制限を実装しています。超過すると HTTP 429 + Retry-After ヘッダで返却。

Layer 1: Nginx（IP単位、burst対応）

エンドポイント	制限	Burst	理由
`/api/auth.php`	1 req/sec	5	ブルートフォース対策
`/api/mcp.php`	5 req/sec	20	DoS対策（IP単位）

Layer 2: PHP（APIキー / IP単位、1分バケット）

区分	制限	識別子
認証なしRead	60 req/min	IPアドレス
認証ありRead	200 req/min	APIキーID
Write	30 req/min	APIキーID

レスポンス例（超過時）

                    # HTTP/2 429
# Retry-After: 32

{
  "success": false,
  "message": "レート制限超過: write は1分あたり 30 回までです",
  "retry_after_sec": 32
}
                

クライアントは Retry-After ヘッダ秒数を待ってからリトライしてください。

Security

本番運用に必要なセキュリティ対策を多層防御で実装しています。

🛡️ 多層防御アーキテクチャ

レイヤー	対策	内容
L4 (Nginx)	IPベースレート制限	PHP到達前に過剰リクエストを破棄
HTTP Headers	セキュリティヘッダ	HSTS / X-Content-Type-Options / Referrer-Policy / Permissions-Policy / CSP frame-ancestors
CORS	Origin ホワイトリスト	humanoid-jobs.com / physicalai-jobs.com / kyuujin.prompters.jp / asi.co.jp のみ許可
L7 認証	APIキー検証	Bearer + 正規表現マッチ + SHA-256ハッシュ照合（タイミング攻撃耐性）
L7 レート制限	APIキー / IP 単位	Read/Write 別の上限、超過で 429 + Retry-After
ロール検証	company / seeker 境界	ロール違反は 403、他人のリソースアクセスは 404
SQL Injection	PDO Prepared Statement	全クエリプレースホルダ使用、LIMIT等動的部分は intval キャスト
SSRF対策	Webhook URL検証	localhost / 10.x / 192.168.x / 172.16-31.x / 169.254.x / link-local 拒否
ブルートフォース	ログイン試行追跡	email 5回 / IP 20回失敗で15分ロック
セッション	Cookie強化	HttpOnly / Secure / SameSite=Lax
エラー情報	非露出	例外詳細は error_log のみ、クライアントには汎用メッセージ

🔑 APIキー仕様

項目	値
形式	`jn_` + hex 48文字 = 51文字
エントロピー	192ビット（24バイト乱数）
保存形式	SHA-256ハッシュ（平文非保存）
スコープ	発行ユーザー本人のリソースのみ
最大保有数	5本 / ユーザー
失効	即時可能 (/mypage/api-keys/)

⚠️ キーが漏洩した可能性があれば即座に失効してください。 失効後は次のリクエストから 401 となります。

📊 監視ダッシュボード

管理者は /admin/security/ でリアルタイムに監視可能:

過去24時間のログイン失敗 / 成功サマリー
IP別失敗回数（5回以上=注視、20回以上=ロック中）
アカウント別失敗回数 + 異なるIP数（パスワードスプレー検知）
直近50件の失敗タイムライン（User-Agent含む）
発行済みAPIキー一覧（呼出回数・最終利用日時）

ログは30日保持（日次cronで自動クリーンアップ）。

🚨 脆弱性報告

セキュリティ脆弱性を発見された場合は security@humanoid-jobs.com までご連絡ください。公開前にパッチを提供いたします。

Error Handling

エラー時は success: false と HTTPステータスコードで返却します。例外詳細はクライアントに露出しません（汎用メッセージのみ）。

                    {
  "success": false,
  "message": "slug or id is required"
}
                

HTTP	意味	原因例
`400`	Bad Request	必須パラメータ不足・不正な値・不正JSON・SSRF対象URL
`401`	Unauthorized	APIキー無効・期限切れ・形式不正
`403`	Forbidden	ロール違反（company専用ツールをseekerが呼ぶ等）
`404`	Not Found	指定リソース不存在 or 編集権限なし
`405`	Method Not Allowed	GETでアクセス（POSTのみ受付）
`429`	Too Many Requests	レート制限超過・ブルートフォースロック中（`Retry-After` 参照）
`500`	Server Error	内部エラー（詳細は error_log のみ）

Why MCP?

Use Cases

横断求人検索

企業リサーチ

業界ニュース解析

マーケット定点観測

Quick Start

Connection Methods

Authentication

① APIキーを発行

② Bearer Token として送信

③ あなたのリソースだけ書き換え可

キー仕様 + セキュリティ

API Reference - 36 Tools

Utility

Jobs

Companies

Articles

Stats & Plans

Auth

Jobs Write

Company Profile

Seeker Profile

Applications

Webhooks

Notifications

Bulk & Analytics

AI Helpers

Rate Limits

Layer 1: Nginx（IP単位、burst対応）

Layer 2: PHP（APIキー / IP単位、1分バケット）

レスポンス例（超過時）

Security

🛡️ 多層防御アーキテクチャ

🔑 APIキー仕様

📊 監視ダッシュボード

🚨 脆弱性報告

Error Handling

ヒューマノイドロボット業界でキャリアを築こう

ログイン

新規登録

新規登録

パスワードリセット

ヒューマノイドロボット業界で
キャリアを築こう