API Reference

jpcite は RAG の置き換えではなく、AI agent が見つけて買う日本制度 packet bank です。長い PDF・複数の官公庁ページ・検索結果を LLM へ毎回渡す前に、出典 URL・取得時刻・known gaps・互換/排他ルール付きの Evidence Packet を返します。caller supplied baseline がある場合は、入力文脈量の削減見込みと break-even も返します。

REST API 公開仕様。programs / exclusions / meta / billing / dashboard / 各種データセット (laws / loans / court_decisions / bids / 行政処分 / 採択事例 / invoice / tax_rulesets) / agent・MCP 向け endpoint を含む。

Runnable レシピ集: 5-15 行で動く curl / Python / MCP サンプルは Recipes を参照。各レシピに「代替手段 vs jpcite cost」表と _disclaimer 取り扱いの実例を掲載。

ベース URL

https://api.jpcite.com

目次 (Endpoint catalogue)

公開 OpenAPI spec (docs/openapi/v1.json) と完全一致。★ = 本ページに詳細あり、それ以外は OpenAPI から自動展開した最小ドキュメント (本ページ後半に展開済み)。

• Programs (4)
• POST /v1/programs/batch ★
• POST /v1/programs/prescreen
• GET /v1/programs/search ★
• GET /v1/programs/{unified_id} ★
• Exclusions (2)
• POST /v1/exclusions/check ★
• GET /v1/exclusions/rules ★
• Meta (5)
• GET /healthz ★
• GET /readyz
• GET /v1/meta ★
• GET /v1/meta/freshness
• GET /v1/ping ★
• Billing (4)
• POST /v1/billing/checkout ★
• POST /v1/billing/keys/from-checkout ★
• POST /v1/billing/portal ★
• POST /v1/billing/refund_request
• Feedback (1)
• POST /v1/feedback ★
• Account & API Keys (/v1/me) (12)
• GET /v1/me
• POST /v1/me/billing-portal
• GET /v1/me/billing_history
• POST /v1/me/cap
• GET /v1/me/dashboard
• POST /v1/me/rotate-key
• GET /v1/me/tool_recommendation
• GET /v1/me/usage
• GET /v1/me/usage_by_tool
• POST /v1/session
• POST /v1/session/logout
• GET /v1/usage
• Alerts (/v1/me/alerts) (3)
• POST /v1/me/alerts/subscribe
• GET /v1/me/alerts/subscriptions
• DELETE /v1/me/alerts/subscriptions/{sub_id}
• Session & Device (3)
• POST /v1/device/authorize
• POST /v1/device/complete
• POST /v1/device/token
• Subscribers (Email) (4)
• GET /v1/email/unsubscribe
• POST /v1/email/unsubscribe
• POST /v1/subscribers
• GET /v1/subscribers/unsubscribe
• Compliance Newsletter (4)
• POST /v1/compliance/stripe-checkout
• POST /v1/compliance/subscribe
• POST /v1/compliance/unsubscribe/{unsubscribe_token}
• GET /v1/compliance/verify/{verification_token}
• Public Stats (Transparency) (5)
• GET /v1/stats/confidence
• GET /v1/stats/coverage
• GET /v1/stats/data_quality
• GET /v1/stats/freshness
• GET /v1/stats/usage
• Testimonials (3)
• POST /v1/me/testimonials
• DELETE /v1/me/testimonials/{testimonial_id}
• GET /v1/testimonials
• Advisors (6)
• GET /v1/advisors/match
• POST /v1/advisors/report-conversion
• POST /v1/advisors/signup
• POST /v1/advisors/track
• POST /v1/advisors/verify-houjin/{advisor_id}
• GET /v1/advisors/{advisor_id}/dashboard-data
• Widget (4)
• GET /v1/widget/enum_values
• GET /v1/widget/search
• POST /v1/widget/signup
• GET /v1/widget/{key_id}/usage
• APPI Privacy Requests (2)
• POST /v1/privacy/deletion_request
• POST /v1/privacy/disclosure_request
• Calendar (1)
• GET /v1/calendar/deadlines
• Case Studies (2)
• GET /v1/case-studies/search
• GET /v1/case-studies/{case_id}
• Loan Programs (2)
• GET /v1/loan-programs/search
• GET /v1/loan-programs/{loan_id}
• Enforcement Cases (2)
• GET /v1/enforcement-cases/search
• GET /v1/enforcement-cases/{case_id}
• Invoice Registrants (2)
• GET /v1/invoice_registrants/search
• GET /v1/invoice_registrants/{invoice_registration_number}
• Laws (3)
• GET /v1/laws/search
• GET /v1/laws/{unified_id}
• GET /v1/laws/{unified_id}/related-programs
• Court Decisions (3)
• POST /v1/court-decisions/by-statute
• GET /v1/court-decisions/search
• GET /v1/court-decisions/{unified_id}
• Tax Rulesets (3)
• POST /v1/tax_rulesets/evaluate
• GET /v1/tax_rulesets/search
• GET /v1/tax_rulesets/{unified_id}
• Bids (2)
• GET /v1/bids/search
• GET /v1/bids/{unified_id}
• jpcite: Programs (Active / Related / Stats / GX) (6)
• GET /v1/am/acceptance_stats
• GET /v1/am/active_at
• GET /v1/am/gx_programs
• GET /v1/am/open_programs
• GET /v1/am/programs/active_v2
• GET /v1/am/related/{program_id}
• jpcite: Intent / Reason / Enums (3)
• GET /v1/am/enums/{enum_name}
• GET /v1/am/intent
• GET /v1/am/reason
• jpcite: Tax Incentives & Certifications (3)
• GET /v1/am/certifications
• GET /v1/am/tax_incentives
• GET /v1/am/tax_rule
• jpcite: Loans & Mutual Insurance (2)
• GET /v1/am/loans
• GET /v1/am/mutual_plans
• jpcite: Laws & Enforcement (3)
• GET /v1/am/by_law
• GET /v1/am/enforcement
• GET /v1/am/law_article
• jpcite: Annotations / Validation / Provenance (4)
• GET /v1/am/annotations/{entity_id}
• GET /v1/am/provenance/fact/{fact_id}
• GET /v1/am/provenance/{entity_id}
• POST /v1/am/validate
• jpcite: Static Resources & Example Profiles (4)
• GET /v1/am/example_profiles
• GET /v1/am/example_profiles/{profile_id}
• GET /v1/am/static
• GET /v1/am/static/{resource_id}
• Evidence & Source Manifests (3)
• POST /v1/evidence/packets/query ★
• GET /v1/evidence/packets/{subject_kind}/{subject_id} ★
• GET /v1/source_manifest/{program_id} ★

バージョニングポリシー (Versioning policy)

エンドポイントは 2 種類に分かれる。契約の強さが異なるので、統合時に意識する。

/v1/* — 安定契約 (stable contract): - /v1/programs/*, /v1/exclusions, /v1/billing/* など、/v1/ 配下の全エンドポイント - response contract の破壊的変更はしない - マイナー改訂は 追加のみ (additive): 新しい任意フィールド、新しい optional query parameter、新しいエンドポイントの追加 - 破壊的変更が必要になった場合は /v2/* を新設し、/v1/* は最低 6 ヶ月並走させてから deprecate - deprecation は response の Sunset / Deprecation header と docs 更新で 90 日以上前に告知

/healthz, /meta, /v1 prefix を持たない utility 系 — ライフサイクル扱い (lifecycle, unversioned): - /healthz は liveness probe のみで、返却内容は空 object に変わる可能性あり - /meta は aggregate stats (total_programs, last_updated 等) を返すが、field 追加・削除・意味変更が発生しうる - 本 reference には、利用者が呼び出す公開 API のみを掲載します - これらの shape 変更は 30 日前に docs/api-reference.md と changelog で告知 するが、/v2 昇格は行わない

統合する client 側の注意: /v1/* 以外のレスポンスを business logic の入力に使わない。監視・運用系 (dashboard, health check) に限定する。

OpenAPI spec

機械可読な契約は下記で配布する:

• GET /v1/openapi.agent.json — ChatGPT Custom GPT Actions や AI tool import 向けの evidence/search subset。課金・Webhook・アカウント管理系 endpoint は含めません
• GET /v1/openapi.json — live server が返す full 公開仕様。SDK 生成・Postman・完全な開発者リファレンス向け
• GET /openapi.json — /v1/openapi.json へ 308 Permanent Redirect。旧 path からの移行期間のみの互換 alias
• docs/openapi/v1.json — 公開 snapshot

admin 系 (/v1/admin/*) は公開仕様から除外。preview 系 (/v1/legal/*, /v1/accounting/*) は default export には入らず、calendar 系は v1 public export に含みます。本 reference には利用者が呼び出す公開 API のみを掲載します。

Evidence Packet / Source Manifest

AI クライアントで回答文を作る前に、根拠だけを先に集めるための endpoint。jpcite は回答文を生成せず、出典 URL、取得時刻、content hash、provenance、互換性ルール判定、既知の欠落を構造化して返す。

Endpoint	用途
POST /v1/evidence/packets/query	複数レコードを検索条件からまとめ、AI に渡しやすい evidence packet を作る
POST /v1/evidence/packets/batch	最大 100 件の {kind, id} を 1 往復で Evidence Packet 化する。paid key、X-Cost-Cap-JPY、Idempotency-Key 必須
GET /v1/evidence/packets/{subject_kind}/{subject_id}	program / houjin など単一対象の evidence packet を取得する
GET /v1/source_manifest/{program_id}	制度単位の source chain、license、取得日時、検証状態を確認する

レスポンスは packet_id、corpus_snapshot_id、generated_at、records[]、quality.known_gaps[] を含みます。AI / Agent SDK から読みやすい別名として、トップレベルに jpcite_cost_jpy、estimated_tokens_saved、source_count、known_gaps も返します。source_url、source_fetched_at、source_checksum、license は根拠が接続済みの場合に返ります。quality.known_gaps[] または known_gaps[] が空でない場合は、AI の回答側でも「どの根拠が未接続か」を明示すること。

トークン量・外部 LLM API 料金・追加検索回数への影響は workload-dependent。jpcite の課金対象は billable API/MCP call であり、外部 LLM 側の token / search / cache / tool cost は利用者のモデル設定に依存する。

最小リクエスト例:

curl -X POST "https://api.jpcite.com/v1/evidence/packets/query" \
  -H "Content-Type: application/json" \
  -d '{
    "query_text": "東京都 製造業 設備投資 補助金",
    "limit": 5,
    "include_compression": true,
    "source_tokens_basis": "token_count",
    "source_token_count": 8000,
    "input_token_price_jpy_per_1m": 250
  }'

include_compression=true は入力文脈の比較用メタデータを返すための指定です。source_token_count と input_token_price_jpy_per_1m は、呼び出し側が置いた baseline として扱われます。

Claude Agent SDK / claude -p / GitHub Actions のような反復実行では、毎回 PDF と検索結果をそのまま prompt に入れる前に、この Evidence Packet を作り、jpcite_cost_jpy、estimated_tokens_saved、source_count、known_gaps を見て、AI に渡す入力を小さくできます。外部 provider の請求削減は保証ではなく、caller baseline 条件下の入力文脈比較です。

認証

API key は X-API-Key header で送る:

X-API-Key: YOUR_API_KEY

API key 不在は匿名扱い、無効 key は 401 Unauthorized。旧互換 header は公開 docs の推奨経路ではありません。

AI agent / 士業システム / 社内ワークフローが継続利用する場合は、次の任意 header も併用する:

Header	用途
X-Client-Tag	paid key 利用時に、顧客・会社フォルダ・案件単位で使用量を分けて追うための 32 文字以内タグ
Idempotency-Key	同じ POST を再試行する時の二重実行・二重課金防止。batch / fanout 系では必須になる場合がある
X-Cost-Cap-JPY	billable POST の予算上限。/v1/cost/preview の predicted_total_yen 以上を指定すると、想定外の広がりを止められる

Payment-control outputs

Wallet / x402 / cost preview は無料クレジットではなく、AI agent が実行前に「この呼び出しは払えるか」「上限を超えないか」「再送で二重課金されないか」を判断するための payment-control output です。

Output	使いどころ
/v1/cost/preview	実行予定の endpoint / MCP call から billable units と予測金額を先に返す
X-Cost-Cap-JPY	実行時に予算上限を指定し、予測外の fanout / batch を止める
Idempotency-Key	同じ POST の再送・retry を同一実行として扱い、二重課金を避ける
x402 payment proof	agent-to-agent / wallet 経由の支払い証跡を payload と request に紐付ける

Rate limit

区分	上限
匿名 (key 無し)	3 req/日 per IP (IPv4 /32 / IPv6 /64)、JST 翌日 00:00 リセット
認証済み (Paid)	¥3/billable unit metered (税込 ¥3.30)。通常の検索・詳細取得は 1 unit、batch/export は各 endpoint の式に従います。予算上限や保護レート制限が適用される場合があります

¥3/billable unit の対価: 1 回の API 呼び出しで、日本の公的制度データを横断して照合済みの根拠 JSON を返します。実際の対価は次の 3 点:

• Cross-source data integration: 1 request can combine relevant public-program, case-study, loan, enforcement, law, tax, bid, and invoice-registrant datasets with source URLs and freshness metadata. Caller 側で同等を組み立てる場合の取得・正規化・整合性検証を肩代わりする
• Primary source citation: 主要公開レコードの多くに 一次資料 (官公庁 / 政策金融公庫 等) の source_url を付与。aggregator 経由のデータは source_url に登録しない
• Freshness metadata: median 7 日以内の source_fetched_at。/v1/meta/freshness で per-source の鮮度分布を公開

匿名 IP 制限は discoverability 系 (/meta, /v1/ping, /v1/programs/*, /v1/exclusions/*, /v1/feedback) にのみ適用。/healthz, /v1/subscribers/unsubscribe, dashboard 系 (/v1/me/*, /v1/session) はカウントしない。/v1/cost/preview は無料見積もり用の独立した短期 rate limit を持ち、匿名 3 req/日の枠を消費しない。

/v1/cost/preview は予定している API / MCP call の billable units と予測課金額を確認する無料 estimator です。token baseline との比較はここでは行いません。入力文脈量の比較は /v1/intelligence/precomputed/query または Evidence Packet の include_compression=true で行います。

curl -X POST "https://api.jpcite.com/v1/cost/preview" \
  -H "Content-Type: application/json" \
  -d '{
    "stack_or_calls": [
      {"tool": "/v1/intelligence/precomputed/query"},
      {"tool": "/v1/evidence/packets/query"}
    ],
    "iterations": 1
  }'

レスポンスの predicted_total_yen は jpcite 側の予測課金額です。外部 LLM の input / output / reasoning / cache / search / provider tool billing は含みません。

Artifact Endpoints

検索結果ではなく、稟議・DD・申請前確認に貼りやすい完成物 envelope を返す endpoint。いずれも request-time LLM call は行わない。

Endpoint	用途	billing
POST /v1/artifacts/compatibility_table	制度併用可否の組み合わせ確認。/v1/funding_stack/check と同じ公開ルールを貼り付けやすい artifact として返す	pair 数
POST /v1/artifacts/application_strategy_pack	事業者 profile から申請候補、金額フィット、併用可否、確認質問、次アクションをまとめる申請前確認 pack	1 unit
POST /v1/artifacts/houjin_dd_pack	法人番号から公開情報DD packを作る。法人基本情報、インボイス、行政処分、採択履歴、所在地整合、監視状態、DD質問をまとめる	1 unit
POST /v1/artifacts/company_public_baseline	日本企業調査の first-hop。法人番号から公的ベースライン、benefit/risk angles、質問、known gaps、source receipts を返す	1 unit
POST /v1/artifacts/company_folder_brief	company_public_baseline を会社フォルダ/CRM/顧問先メモへ貼りやすい形に整形する Brief preview。18-unit の Company Folder Pack は複数 section を束ねる workflow 例	1 unit
POST /v1/artifacts/company_public_audit_pack	監査/DD/稟議前確認向けに、公的証跡、mismatch flags、確認範囲、DD質問をまとめる	1 unit

Company public artifacts

認証: 任意。匿名は 3 req/日 per IP、paid key は通常の metered unit。paid key の場合、監査用途で audit_seal が付く場合がある。

Request body:

{
  "houjin_bangou": "1234567890123",
  "include_sections": ["meta", "invoice_status", "enforcement"],
  "max_per_section": 10
}

houjin_bangou はインボイス登録番号形式も受け付け、13桁へ正規化する。会社名だけで単一法人と断定する endpoint ではない。

Response: artifact_id, artifact_type, artifact_version, generated_at, summary, sections[], sources[], known_gaps[], source_receipts[], copy_paste_parts, recommended_followup_by_channel, agent_routing, human_review_required, corpus_snapshot_id, corpus_checksum を含む。

company_public_baseline は、AIや実務者が一般Web検索へ行く前の最初の公的確認として使う。回答側では source_url, source_fetched_at, identity_confidence, known_gaps を保持し、known_gaps に出た収録外・非公的文脈・直近ニュースだけを追加調査する。

company_folder_brief は、会社フォルダREADME、CRMメモ、顧問先への質問、source receipts、known gaps、次の作業キューへ貼るための表示寄りartifact。出力例: folder_readme, crm_note, owner_questions, source_receipts, known_gaps, recommended_followup_by_channel, copy_paste_parts。

company_public_audit_pack は、監査/DD/稟議前確認で使う公開情報の証跡表。行政処分、インボイス、採択履歴などの空欄を「問題なし」「安全」「処分なし」と解釈してはいけない。確認済み範囲と未接続範囲を known_gaps[] で示す。

POST /v1/artifacts/application_strategy_pack

認証: 任意。匿名は 3 req/日 per IP、paid key は通常の metered unit。

Request body:

{
  "profile": {
    "prefecture": "Tokyo",
    "is_sole_proprietor": true,
    "planned_investment_man_yen": 800,
    "declared_certifications": ["経営革新計画承認"]
  },
  "max_candidates": 5,
  "compatibility_top_n": 5
}

Response: artifact_id, artifact_type=application_strategy_pack, summary, sections[], sources[], known_gaps[], next_actions[], human_review_required[], corpus_snapshot_id, corpus_checksum を含む。sections[] には ranked_candidates, application_questions, compatibility_screen が入り、検索候補ではなく申請前に確認すべき判断材料として返す。

compatibility_top_n=0 で併用可否 section を省略できる。候補の source / deadline が不足する場合は known_gaps[] に明示する。

POST /v1/artifacts/houjin_dd_pack

認証: 任意。匿名は 3 req/日 per IP、paid key は通常の metered unit。

Request body:

{
  "houjin_bangou": "1234567890123",
  "include_sections": ["meta", "enforcement", "invoice_status"],
  "max_per_section": 10
}

include_sections 未指定時は meta, adoption_history, enforcement, invoice_status, peer_summary, jurisdiction, watch_status を返す。インボイス登録番号形式も受け付け、13桁へ正規化する。

Response: artifact_id, artifact_type=houjin_dd_pack, summary, sections[], sources[], known_gaps[], next_actions[], human_review_required[], corpus_snapshot_id, corpus_checksum を含む。paid key の場合は audit_seal も付く。

known_gaps[] は「該当なし」ではなく「現時点の返却情報では確認できない」ことを表す。行政処分やインボイスの空欄を安全性の証明として扱わないこと。

匿名超過時:

HTTP/1.1 429 Too Many Requests
Retry-After: <翌日 JST 00:00 までの秒>

{"detail": "anon rate limit exceeded", "limit": 3, "resets_at": "2026-05-02T00:00:00+09:00"}

IP は raw 保存せずハッシュ化します。詳細は pricing.md。

---

3 回の無料検証フロー (匿名 3 req/日 で価値を確認する順序)

匿名 3 req/日 (IP 単位、JST 翌日 00:00 リセット) を、 課金前の評価に最大限使うための推奨順序です。 各 endpoint の field 詳細は本ページ下部の Programs / Context Compression 章を参照してください。

回	確認内容	例
1 回目	制度候補と一次資料が返ること、 source_url がまとめサイト経由でないこと、 source_fetched_at が付いていること	GET /v1/programs/search?q=IT導入&limit=3
2 回目	precomputed Evidence Packet が live web search 無し / LLM call 無しで返ること (bundle_kind=precomputed_intelligence · usage.web_search_required=false)	GET /v1/intelligence/precomputed/query?q=省力化&limit=5
3 回目	caller baseline を渡すと compression.input_context_reduction_rate と compression.cost_savings_estimate.break_even_met が返ること、 agent_recommendation.recommend_for_cost_savings が条件付きで true / false に分かれること	GET /v1/intelligence/precomputed/query?q=省力化&limit=5&source_tokens_basis=pdf_pages&source_pdf_pages=30&input_token_price_jpy_per_1m=300

確認すべき response field の意味:

• source_url / source_fetched_at — 1 回目で確認。 一次資料 URL と取得時刻
• quality.known_gaps[] — Evidence / intelligence response で確認。 「未接続な根拠」 を AI 側で明示するため
• compression.packet_tokens_estimate / source_tokens_estimate / input_context_reduction_rate — 3 回目で確認。 caller baseline がある時のみ意味を持つ
• compression.cost_savings_estimate.break_even_met — 入力文脈量の参考比較 (provider_billing_not_guaranteed=true 同梱)
• agent_recommendation.cost_savings_decision — supported_by_caller_baseline / not_supported_by_caller_baseline / needs_caller_baseline / needs_input_token_price

3 回到達して全項目が想定通りなら、税込概算 ¥3.30/billable unit で「データ統合 + 一次出典 + 鮮度 + 入力文脈削減見込み」が得られるかを判断できます。ブラウザで順に検証する場合は https://jpcite.com/playground?flow=evidence3。個別 field の詳細仕様は Context Compression 章 と pricing.md break_even_met の正しい読み方 を参照。

継続利用に移る場合は、同じ endpoint を X-API-Key 付きで呼び、案件単位の X-Client-Tag を固定する。POST の再試行では Idempotency-Key、広い batch / fanout では X-Cost-Cap-JPY を付ける。

---

Programs

GET /v1/programs/search

自由記述 + 構造化フィルタで制度を検索。

認証: 任意 (未認証は匿名扱い)

Query parameters:

name	type	required	description
q	string	no	自由記述検索。日本語の表記ゆれを正規化し、短い語句は補助的な一致方式で検索
tier	string (repeat)	no	S / A / B / C。複数指定で OR。公開検索では非公開行は返りません
prefecture	string	no	都道府県名 (完全一致, 例: 青森県)
authority_level	string	no	標準値: national / prefecture / municipality / financial。日本語別名 (国 / 都道府県 / 市区町村 / 公庫) も API 側で正規化して受け付ける
funding_purpose	string (repeat)	no	資金用途 (例: 設備投資)
target_type	string (repeat)	no	対象者種別 (例: 認定新規就農者)
amount_min	number	no	助成上限の下限 (万円)
amount_max	number	no	助成上限の上限 (万円)
limit	int	no	1〜100 (default 20)
offset	int	no	ページング (default 0)
fields	enum	no	minimal / default / full。レスポンスサイズ切替 (default default)

fields 選択肢:

値	results[] の中身	目安サイズ (1 record)	用途
minimal	unified_id / primary_name / tier / prefecture / authority_name / amount_max_man_yen / official_url の 7 キーのみ	~150-300 B	リスト表示、クイックフィルタ、MCP tool の中間結果
default (省略時)	Program 全フィールド (今までと完全互換)	~500-800 B	通常の統合
full	Program + enriched (A-J 全次元) + source_mentions + lineage (source_url / source_fetched_at / source_checksum)。enriched / source_mentions は null でもキーが必ず存在	~3-50 KB (enriched 次第)	単一制度の深い読み込み、エージェントのリサーチ

minimal / full は追加扱い。default のスキーマは破壊的変更せずに維持する。

Response (SearchResponse):

{
  "total": 153,
  "limit": 20,
  "offset": 0,
  "results": [
    {
      "unified_id": "string",
      "primary_name": "string",
      "aliases": ["string"],
      "authority_level": "national",
      "authority_name": "経済産業省",
      "prefecture": null,
      "municipality": null,
      "program_kind": "補助金",
      "official_url": "https://...",
      "amount_max_man_yen": 450,
      "amount_min_man_yen": 30,
      "subsidy_rate": 0.5,
      "trust_level": "high",
      "tier": "A",
      "coverage_score": 0.82,
      "gap_to_tier_s": ["J_statistics"],
      "a_to_j_coverage": {"A_basics": true, "B_target": true},
      "excluded": false,
      "exclusion_reason": null,
      "crop_categories": [],
      "equipment_category": null,
      "target_types": ["中小企業"],
      "funding_purpose": ["設備投資"],
      "amount_band": "100-500",
      "application_window": {"start": "2026-04-01", "end": "2026-06-30"}
    }
  ]
}

Response example at fields=minimal:

{
  "total": 153,
  "limit": 20,
  "offset": 0,
  "results": [
    {
      "unified_id": "UNI-71f6029070",
      "primary_name": "経営開始資金",
      "tier": "S",
      "prefecture": null,
      "authority_name": "農林水産省",
      "amount_max_man_yen": 1500,
      "official_url": "https://www.maff.go.jp/j/new_farmer/..."
    }
  ]
}

Response example at fields=full: default と同じ results[i] に加え、各 record に enriched (A-J 次元) / source_mentions (list of {url, fetched_at}) / source_url / source_fetched_at / source_checksum が必ず入る (値が null でもキーは存在)。

Example:

# default shape
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.jpcite.com/v1/programs/search?q=IT導入&tier=S&tier=A&limit=5"

# minimal — list rendering / quick filter
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.jpcite.com/v1/programs/search?q=IT導入&limit=20&fields=minimal"

ソート: 自由記述検索では関連度順、それ以外は出典確認状況と制度名で安定ソート。

---

GET /v1/programs/{unified_id}

単一制度の詳細取得。enriched (A-J 次元の詳細) と source_mentions を含む。

認証: 任意

Path parameters:

name	type	required	description
unified_id	string	yes	制度 ID

Query parameters:

name	type	required	description
fields	enum	no	minimal / default / full。レスポンスサイズ切替 (default default)

fields 選択肢 (/v1/programs/{unified_id}):

値	中身	備考
minimal	7-key whitelist (unified_id / primary_name / tier / prefecture / authority_name / amount_max_man_yen / official_url)	詳細画面では通常使わないが、埋め込み UI の軽量表示に
default (省略時)	ProgramDetail (Program + enriched + source_mentions + lineage) — 従来と完全互換	通常の統合
full	同上。ただし enriched / source_mentions / lineage 3 キーは null でも必ず key が存在する契約に揃う	「null = 調査済で空」「key なし = 旧サーバー」を区別する必要がある AI agent 向け

Response (ProgramDetail): SearchResponse.results[] と同じ構造 + 以下:

{
  "...Program fields...": "...",
  "enriched": {
    "A_basics": {"...": "..."},
    "B_target": {"...": "..."},
    "J_statistics": null
  },
  "source_mentions": [
    {"url": "https://...", "fetched_at": "2026-04-15T10:00:00Z", "confidence": 0.9}
  ]
}

Example:

# default (current behavior, unchanged)
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.jpcite.com/v1/programs/UNI-71f6029070"

# minimal — just the headline fields
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.jpcite.com/v1/programs/UNI-71f6029070?fields=minimal"

# full — enriched / source_mentions / lineage keys included in the documented response shape
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.jpcite.com/v1/programs/UNI-71f6029070?fields=full"

エラー: 存在しない ID は 404 Not Found。

---

POST /v1/programs/batch

最大 50 件の unified_id をまとめて解決する。GET /v1/programs/{unified_id} を N 回叩く代わりに 1 リクエストで済ませる用途 (agent が search_programs の 20 件候補を全件 enrich したい等)。

認証: 任意 (未認証は匿名扱い)。API key 付きの paid batch は二重課金防止のため Idempotency-Key header が必須。さらに実行前の予算確認として、X-Cost-Cap-JPY header または body の max_cost_jpy のどちらかを必ず渡します。両方ある場合は低い方を上限として扱います。

Request body (BatchGetProgramsRequest):

{
  "unified_ids": ["UNI-71f6029070", "UNI-185c08e0c1", "UNI-test-a-1"],
  "max_cost_jpy": 9
}

field	type	required	description
unified_ids	string[]	yes	1〜50 件の制度 ID。重複は自動 dedupe (最初の出現順を保持)
max_cost_jpy	integer	paid only	body で渡すリクエスト予算。header X-Cost-Cap-JPY と両方ある場合は低い方を採用

バリデーション:

• unified_ids が空配列 → 422 Unprocessable Entity
• 50 件超 → 422 Unprocessable Entity
• unified_ids の cap は 50 件 (paging は提供しない。50 超の caller は client 側で chunk する)

Response (BatchGetProgramsResponse):

{
  "results": [
    {
      "unified_id": "UNI-71f6029070",
      "primary_name": "経営開始資金",
      "tier": "S",
      "enriched": {"A_basics": {"...": "..."}},
      "source_mentions": [{"url": "https://...", "fetched_at": "2026-04-15T..."}],
      "source_url": "https://...",
      "source_fetched_at": "2026-04-22T...",
      "source_checksum": "638865704e10041c",
      "...": "..."
    }
  ],
  "not_found": ["UNI-typo-1"],
  "billing": {
    "billable_units": 2,
    "yen_excl_tax": 6,
    "unit_price_yen": 3,
    "not_found_billed": false
  }
}

field	type	description
results	ProgramDetail[]	各要素は GET /v1/programs/{id}?fields=full と同じ shape。enriched / source_mentions / lineage 3 キーは null でも必ず存在。dedupe 後の入力 unified_ids 順を保存
not_found	string[]	DB に該当行がなかった ID。部分成功扱いなので 404 ではなく 200 で not_found[] に入る
billing	object	実際に請求対象になった件数。not_found は請求しないため、billable_units == results.length

重要な契約:

• 順序保証: results[] は見つかった ID だけを dedupe 後の入力順で返す。not_found がある場合、results[i] は元入力の同じ index とは限らない。
• 部分成功: 50 件のうち 3 件が存在しなくても 200 が返り、3 件は not_found[] に入る。全件無しでも {"results": [], "not_found": [...]} で 200。
• 例外は 500: not_found は「DB に存在しない」ケースだけ。JSON decode 失敗等の例外は batch 全体が 500 で落ちる (部分成功を暗黙に隠さない方針)。
• paging なし: 50-cap がそのまま paging。50 超の ID リストは client 側で chunk(ids, 50) してループする。

Billing / cap: cap 判定は dedupe 後の ID 件数で保守的に見積もります。実際の請求は見つかった results.length 件だけです (not_found は請求しません)。1 件 = ¥3 なので、3 件依頼して 2 件だけ見つかった場合は ¥6。API key 付きの paid batch は Idempotency-Key がない場合 428、X-Cost-Cap-JPY / max_cost_jpy がない場合 400、予測額が上限を超える場合 402 で止める。実行前に月次 cap も projected units で検査し、cap 超過が見込まれる場合は処理前に 503 で止める。

Example:

curl -X POST https://api.jpcite.com/v1/programs/batch \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: 01HX..." \
  -H "X-Cost-Cap-JPY: 6" \
  -H "Content-Type: application/json" \
  -d '{"unified_ids":["UNI-71f6029070","UNI-185c08e0c1"]}'

# SDK パターン: search -> batch で 20 件 enrich
import httpx

with httpx.Client(
    base_url="https://api.jpcite.com",
    headers={"X-API-Key": "YOUR_API_KEY"},
) as client:
    search = client.get(
        "/v1/programs/search",
        params={"q": "IT導入", "fields": "minimal", "limit": 20},
    ).json()
    ids = [item["unified_id"] for item in search["results"]]
    detail = client.post(
        "/v1/programs/batch",
        headers={
            "Idempotency-Key": "batch-it-2026-05-03-001",
            "X-Cost-Cap-JPY": str(len(set(ids)) * 3),
        },
        json={"unified_ids": ids},
    ).json()
    for item in detail["results"]:
        print(item["unified_id"], item["primary_name"], item.get("enriched"))
    if detail["not_found"]:
        print("missing:", detail["not_found"])

---

Exclusions

制度の併用チェック関連。概念は exclusions.md。

GET /v1/exclusions/rules

登録済みの併用チェックルールを返す。

注意: 登録済みルールに一致しない場合でも、「併用して安全」を保証するものではありません。実申請前に source_urls の一次資料、担当窓口、専門家を確認してください。

認証: 任意

Response (list[ExclusionRule]):

[
  {
    "rule_id": "RULE-EXAMPLE-001",
    "kind": "same_asset_exclusive",
    "severity": "warning",
    "program_a": "UNI-1111111111",
    "program_b": "UNI-2222222222",
    "program_b_group": [],
    "description": "同じ設備費を二つの制度で重ねて申請できない可能性があります。",
    "source_notes": "公募要領の併給制限",
    "source_urls": ["<公式公募要領URL>"],
    "extra": {}
  }
]

フィールド:

field	type	description
rule_id	string	ルール一意 ID
kind	string	論点の種類。例: 同時利用不可、前提条件、同一経費の重複、金額調整
severity	string | null	確認の強さ。例: 重大、警告、要確認
program_a	string | null	片側の制度 ID
program_b	string | null	もう片側の制度 ID (または group を使用)
program_b_group	string[]	複数制度が相手の場合のグループ
description	string | null	ユーザー向けの要約
source_notes	string | null	出典の簡易メモ
source_urls	string[]	一次資料 URL
extra	object	追加メタ

---

POST /v1/exclusions/check

候補制度セットに対して、併用時に確認すべき論点があるかを調べる。

認証: 任意

Request body (ExclusionCheckRequest):

{
  "program_ids": ["UNI-1111111111", "UNI-2222222222"]
}

field	type	required	description
program_ids	string[]	yes (1 件以上)	search_programs や get_program で得た制度 ID 配列。重複は自動 dedup

Response (ExclusionCheckResponse):

{
  "program_ids": ["UNI-1111111111", "UNI-2222222222"],
  "hits": [
    {
      "rule_id": "RULE-EXAMPLE-001",
      "kind": "same_asset_exclusive",
      "severity": "warning",
      "programs_involved": ["UNI-1111111111", "UNI-2222222222"],
      "description": "同じ設備費を二つの制度で重ねて申請できない可能性があります。",
      "source_urls": ["<公式公募要領URL>"]
    }
  ],
  "checked_rules": 181
}

判定ロジック:

• 併用不可や同一経費の重複は、関係する制度が候補セットに含まれると hits に出ます。
• 前提条件は、候補制度に必要な認定・資格・関連制度があり得る場合に hits に出ます。

限界 (重要): hits: [] は「登録済みルールでは衝突未検出」という意味です。「併用して安全」を意味しません。

エラー: program_ids が空なら 400 Bad Request。

Example:

curl -X POST -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"program_ids":["UNI-1111111111","UNI-2222222222"]}' \
  https://api.jpcite.com/v1/exclusions/check

---

Meta

GET /v1/meta

公開検索対象データの統計。ダッシュボード表示や health check 用途。

認証: 任意

Response (Meta):

{
  "total_programs": 11601,
  "tier_counts": {"S": 114, "A": 1340, "B": 4186, "C": 5961},
  "prefecture_counts": {"青森県": 42, "_none": 4311, "...": "..."},
  "exclusion_rules_count": 181,
  "last_ingested_at": "2026-04-25T17:25:00Z",
  "data_as_of": "2026-04-25",
  "data_lineage": {
    "last_fetched_at": "2026-04-25T17:25:00Z",
    "unique_checksums": 12873
  }
}

• total_programs は公開検索対象件数 (tier S/A/B/C 11,601)。検索対象外・審査保留行は含めません
• tier_counts は公開検索対象の tier 別件数。検索対象外の制度は search / batch / MCP では常に除外
• prefecture_counts の _none は prefecture=null (全国制度または未ラベル) のバケット
• exclusion_rules_count は登録済みの併用チェックルール数
• last_ingested_at は DB の最終 ingest 時刻, data_as_of は元データの基準日
• data_lineage.last_fetched_at は programs.source_fetched_at の最大値、unique_checksums は source_checksum のユニーク数 (列が存在する時のみ)
• 採択事例 / 融資 / 行政処分 / 法令 等の周辺データセット件数は本エンドポイントの返却対象外 (それぞれ専用エンドポイント側で取得)

Example:

curl https://api.jpcite.com/v1/meta

Legacy alias (deprecated): GET /meta は /v1/meta へ 308 Permanent Redirect する。既存の client は stop する前に /v1/ prefix へ書き換えること。legacy path は lifecycle 系 (unversioned) 扱いで、将来のメジャーバージョンで削除の可能性あり。

---

GET /healthz

Liveness probe。DB 接続のみ確認。

認証: 不要

Response:

{"status": "ok"}

---

GET /v1/ping

認証付き probe。/healthz は liveness (DB ping のみ) で key 検証をしないため、 「今この key で API に届くか + tier は何か」を 1 本で確認したい時に使う。

認証: 任意 (未認証は free 扱い)

Response:

{
  "ok": true,
  "authenticated": true,
  "tier": "paid",
  "server_time_utc": "2026-04-23T14:00:00Z",
  "server_version": "0.1.0",
  "rate_limit_remaining": null
}

field	type	description
ok	bool	常に true (到達できた時点で)
authenticated	bool	有効な key が提示されたか
tier	string	free / paid
server_time_utc	string	サーバー時刻 (UTC, YYYY-MM-DDTHH:MM:SSZ)
server_version	string	jpcite version
rate_limit_remaining	int | null	本日の残り呼び出し数。paid (metered) は null

使用量への影響: /v1/ping は認証付き呼び出しのみ使用量に反映されます。 頻繁に heartbeat したい用途では /healthz を推奨します。

匿名時の rate_limit_remaining: 未認証時は匿名クォータの目安値を返します。

Example:

curl -H "X-API-Key: YOUR_API_KEY" https://api.jpcite.com/v1/ping

---

Billing

Stripe 経由のサブスクリプション管理。詳細フローは getting-started.md。

POST /v1/billing/checkout

Stripe Checkout セッションを作成して URL を返す。

認証: 不要

Request body:

field	type	required	description
success_url	string	yes	決済後のリダイレクト先 (session_id を受け取るページ)
cancel_url	string	yes	キャンセル時のリダイレクト先
customer_email	string	no	Stripe に事前に渡すメールアドレス

tier フィールドは存在しません。課金は ¥3/billable unit の従量課金です。通常の検索・詳細取得は 1 unit、batch / export 系は各 endpoint の式で実行前に units を見積もります。

Response:

{"url": "https://checkout.stripe.com/...", "session_id": "cs_live_..."}

エラー: 請求設定が未完了の場合は 400、一時的に請求サービスが利用できない場合は 503。

---

POST /v1/billing/portal

Stripe Customer Portal URL を返す (サブスク変更・キャンセル・カード変更用)。

認証: 必須 (Bearer / X-API-Key)

Request body:

{"return_url": "https://your-app.example.com/account"}

Response:

{"url": "https://billing.stripe.com/..."}

---

POST /v1/billing/keys/from-checkout

Checkout 成功後に API key を発行する。1 session につき 1 回のみ。

認証: Checkout 開始時に発行した jpcite_checkout_state cookie が必要。 Stripe session_id だけでは API key を取得できない。通常は https://jpcite.com/success.html / https://jpcite.com/en/success.html のブラウザ画面から呼び出す。

Request body:

{"session_id": "cs_live_..."}

Response:

{"api_key": "YOUR_API_KEY", "tier": "metered", "...": "..."}

tier は課金プランではなく、発行されたキーの種類を表す補助フィールドです。料金は有効な API key での利用が一律 ¥3/billable unit (税込 ¥3.30) です。

エラー:

• 402 Payment Required — session が paid になっていない
• 403 Forbidden — checkout state cookie がない、または一致しない
• 409 Conflict — 同 subscription で既に key 発行済み (rotation は /v1/billing/portal 経由)

---

Feedback

POST /v1/feedback

開発者向けの feedback 受け口。変なレスポンスを見つけた時・命名案がある時に、 GitHub issue を開く前に 1 POST で送れる軽量窓口。

認証: 任意 (未認証でも OK)。API key を付けると、後から問い合わせ内容を確認しやすくなります。

Request body (FeedbackRequest):

{
  "message": "search で 認定新規就農者 が Hit しない件",
  "rating": 3,
  "endpoint": "/v1/programs/search",
  "request_id": "abcd1234"
}

field	type	required	description
message	string	yes	1〜4000 文字。自由記述
rating	int	no	1〜5 (満足度)
endpoint	string	no	関連エンドポイント (例: /v1/programs/search)
request_id	string	no	x-request-id header の値など

Response (FeedbackResponse):

{"received": true, "feedback_id": 42}

Rate limit: 1 日あたり 10 件 per API key (認証時) または per IP hash (未認証時)。 超過時は 429 Too Many Requests。

保存される情報:

• message, rating, endpoint, request_id (上記入力)
• 認証時: API key に紐づく識別子
• ip_hash (raw IP は保存しない)
• created_at (UTC ISO)

Example:

curl -X POST https://api.jpcite.com/v1/feedback \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"検索対象外判定の理由が見えづらい","rating":4}'

---

Context Compression (workload-dependent estimate)

GET /v1/intelligence/precomputed/query

LLM context prefetch 用に、事前計算済みの evidence bundle をコンパクトに返す。リクエスト時に LLM call は行わず、live web search も要求しない。これは evidence packaging のための endpoint であり、context-size や cost への影響は workload-dependent な参考比較として扱う。

圧縮効果について: この endpoint は、LLM に渡す前の資料整理を目的にしています。トークン数や回答コストへの影響は、モデル、質問、プロンプト、検索設定、キャッシュ状態によって変わるため、同じ質問群・同じモデル・同じ実行日で比較します。

公開できる数値は、同じ質問群、同じモデル、同じ実行日で比較したベンチマーク結果に限定します。AI は「caller baseline 条件下の入力文脈削減見込み」として説明してください。

認証: 任意 (未認証は匿名扱い)

Query parameters:

name	type	required	description
q	string	yes	事前計算済み summary に照合する自由記述 query
prefecture	string	no	都道府県フィルタ
tier	string	no	tier フィルタ
limit	int	no	records[] の最大件数。1〜500 (default 10)
include_facts	bool	no	true で raw facts も含める。default false
include_compression	bool	no	context-size estimate を含める。default true
input_token_price_jpy_per_1m	number	no	caller 側の input token 単価。参考比較が可能な場合のみ使用
source_tokens_basis	string	no	unknown / pdf_pages / token_count。caller が比較対象を渡した場合だけ source estimate を出す
source_pdf_pages	int	no	LLM にそのまま読ませる予定だった PDF ページ数。source_tokens_basis=pdf_pages のときだけ使用
source_token_count	int	no	caller が自分のモデル UI / tokenizer で測った入力 token 数。source_tokens_basis=token_count のときだけ使用
output_format	string	no	現在は json のみ対応

Example:

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.jpcite.com/v1/intelligence/precomputed/query?q=省力化&limit=5"

PDF をそのまま LLM に読ませる代わりに packet 化する場合の参考比較:

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.jpcite.com/v1/intelligence/precomputed/query?q=省力化&limit=5&source_tokens_basis=pdf_pages&source_pdf_pages=30&input_token_price_jpy_per_1m=300"

source_pdf_pages は caller が知っている比較対象を明示する値です。jpcite は URL から勝手にページ数やトークン数を推定しません。

すでに自分の LLM 画面や tokenizer で比較対象の token 数が分かっている場合:

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.jpcite.com/v1/intelligence/precomputed/query?q=省力化&limit=5&source_tokens_basis=token_count&source_token_count=18500&input_token_price_jpy_per_1m=300"

Key response fields:

field	type	description
bundle_kind	string	precomputed_intelligence。事前計算済み bundle であることを示す
precomputed.record_count	int	事前計算済み summary を含む record 件数
usage.web_search_required	bool	常に false。この endpoint 自体が live web search をしないことを示す
compression	object	context-size estimate。caller baseline に基づく入力文脈量の参考比較
compression.input_context_reduction_rate	float|null	max(0, source - packet) / source。caller baseline が無いときは null。入力文脈量だけの参考値
compression.provider_billing_not_guaranteed	bool	常に true。output / reasoning / cache / tool-use / search 料金を含まないことを明示する
compression.source_tokens_input_source	string	caller_supplied の場合のみ、caller が渡した baseline に基づく比較であることを示す
compression.savings_claim	string	常に estimate_not_guarantee。参考推定であることを示す
compression.cost_savings_estimate.break_even_source_tokens_estimate	int	jpcite 1 回分 (¥3) を入力文脈削減だけで回収するために必要な source token 数の目安 (= packet_tokens_estimate + break_even_avoided_tokens)
evidence_value.records_returned	int	records[] の件数
evidence_value.source_linked_records	int	source_url または source 付き fact を持つ record 数
evidence_value.precomputed_records	int	precomputed summary を持つ record 数
evidence_value.pdf_fact_refs	int	PDF fact 参照の合計
evidence_value.known_gap_count	int	quality.known_gaps の件数
evidence_value.fact_provenance_coverage_pct_avg	float|null	record 単位 fact 出典率の平均
evidence_value.web_search_performed_by_jpcite	bool	常に false。jpcite はライブ検索しない
evidence_value.request_time_llm_call_performed	bool	常に false。jpcite は応答時に LLM を呼ばない
agent_recommendation.recommendation	string	AI agent 向けの次アクション。use_jpcite_prefetch / use_evidence_packet / broaden_query_or_skip
agent_recommendation.recommend_for_evidence	bool	source-linked record が 1 件以上あり、出典付き根拠 layer として推薦できるか。caller baseline 不要の axis-1
agent_recommendation.evidence_decision	string	supported_by_source_linked_records / no_records_returned / records_returned_without_source_links
agent_recommendation.recommend_for_cost_savings	bool	true のときだけ、caller が渡した baseline と token 単価で break-even を満たしたことを示す
agent_recommendation.cost_savings_decision	string	supported_by_caller_baseline のときだけ、AI は「この条件ならコスト削減の可能性がある」と説明できる
agent_recommendation.missing_for_cost_claim	array	コスト削減として説明するために不足している caller 入力
agent_recommendation.value_reasons	array	AI が jpcite を推薦するときに引用できる肯定 signal リスト
agent_recommendation.context_savings	object	compression がある場合に返る。evaluated=false は caller baseline 不足、break_even_met は baseline と input 単価がそろう場合だけ意味を持つ

---

エラー形式 (Error format)

標準 error response:

{"detail": "エラー理由"}

code	意味
400	リクエスト不正 (params / body)
401	認証失敗 / revoked key
402	Stripe 決済未完了
404	リソース無し
409	重複操作 (key 発行済み等)
429	rate limit 超過
503	Stripe 未設定など運用外状態

---

カテゴリ別エンドポイント

下記は OpenAPI と対応する endpoint 一覧です。主要 endpoint は本ページ前半で詳しく説明し、それ以外は request / response の形と curl 例を中心に載せています。詳細は OpenAPI spec、もしくは mcp-tools.md の同名 MCP tool を参照してください。

凡例: - 認証 列の "任意 (未認証は匿名扱い)" は 3 req/日 per IP の anonymous quota を消費する。必須 は 401/403 を返す (Bearer / X-API-Key 必須)。 - Response の "..." は array/object の省略表記。完全 contract は OpenAPI spec を参照。 - 一部の専門テンプレートや審査中の機能は、公開対象になった時点で OpenAPI と MCP ツール一覧に追加されます。

---

Programs (additional)

POST /v1/programs/prescreen

Rank programs by fit to a caller business profile.

This is the "judgment" complement to /v1/programs/search's "discovery".

認証: 任意 (未認証は匿名扱い)

Request body (PrescreenRequest):

{
  "company_url": "string",
  "declared_certifications": [
    "..."
  ],
  "employee_count": 0,
  "founded_year": 0,
  "houjin_bangou": "string",
  "industry_jsic": "string",
  "is_sole_proprietor": true,
  "limit": 10,
  "...": "..."
}

Response 200 (PrescreenResponse):

{
  "limit": 0,
  "profile_echo": {},
  "results": [
    "..."
  ],
  "total_considered": 0
}

Example:

curl -X POST "https://api.jpcite.com/v1/programs/prescreen" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"company_url": "string", "declared_certifications": ["..."], "employee_count": 0, "founded_year": 0, "houjin_bangou": "string", "industry_jsic": "string", "is_sole_proprietor": true, "limit": 10, "...": "..."}'

---

Meta (additional)

GET /readyz

Readyz

認証: 不要

Example:

curl -X GET "https://api.jpcite.com/readyz"

---

GET /v1/meta/freshness

Meta Freshness

認証: 任意 (未認証は匿名扱い)

Query parameters:

name	type	required	description
limit	integer	no	—
sort_by	string	no	—
tier	string	no	—

Response 200 (MetaFreshnessResponse):

{
  "generated_at": "string",
  "median_fetched_at": "string",
  "pct_over_180d": 0.0,
  "pct_within_30d": 0.0,
  "top_rows": [
    "..."
  ],
  "total": 0
}

Example:

curl -X GET "https://api.jpcite.com/v1/meta/freshness?limit=50" \
  -H "X-API-Key: YOUR_API_KEY"

---

Billing (additional)

POST /v1/billing/refund_request

Stripe で課金された ¥3/billable unit メータリング分の返金を顧客が請求するためのエンドポイント。運営側で 14 日以内に手動審査を行います。 このエンドポイントは受付番号の発行と通知のみで、自動的な返金や API キー失効は行いません。既に課金済みの分も審査完了までそのまま残ります。

認証: 任意

Request body (RefundRequest):

{
  "amount_yen": 0,
  "customer_id": "string (わかる場合のみ)",
  "reason": "string",
  "requester_email": "[email protected]"
}

Response 201 (RefundResponse):

{
  "contact": "support",
  "expected_response_within_days": 14,
  "note": "返金は手動審査となります。既に課金済みの ¥3/billable unit メータリング分は自動取消しされません — 審査完了後、運営から個別にご連絡します。",
  "received_at": "string",
  "request_id": "string"
}

Example:

curl -X POST "https://api.jpcite.com/v1/billing/refund_request" \
  -H "Content-Type: application/json" \
  -d '{"amount_yen": 0, "reason": "string", "requester_email": "[email protected]"}'

---

Account & API Keys (/v1/me)

GET /v1/me

Get Me

認証: 必須 (Bearer / X-API-Key)

Response 200 (MeResponse):

{
  "created_at": "string",
  "customer_id": "string",
  "subscription_cancel_at_period_end": true,
  "subscription_current_period_end": "string",
  "subscription_status": "string",
  "tier": "string"
}

Example:

curl -X GET "https://api.jpcite.com/v1/me" \
  -H "X-API-Key: YOUR_API_KEY"

---

POST /v1/me/billing-portal

Billing Portal

認証: 必須 (Bearer / X-API-Key)

Response 200 (BillingPortalResponse):

{
  "url": "string"
}

Example:

curl -X POST "https://api.jpcite.com/v1/me/billing-portal" \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/me/billing_history

API key に紐づく直近の請求履歴を返す。請求書がまだない場合は空配列を返す。

認証: 必須 (Bearer / X-API-Key)

Response 200 (BillingHistoryResponse):

{
  "cached_at": "string",
  "customer_id": "string",
  "invoices": [
    "..."
  ]
}

Example:

curl -X GET "https://api.jpcite.com/v1/me/billing_history" \
  -H "X-API-Key: YOUR_API_KEY"

---

POST /v1/me/cap

Set the customer's self-serve monthly spend cap.

Authenticated with X-API-Key. Anonymous callers (no key) cannot set a cap because the anonymous tier is already gated by the 3 req/日 free quota — there is nothing to cap.

The unit price stays ¥3 per billable unit. monthly_cap_yen is a client budget control: at cap-reached the API returns 503 with cap_reached: true and Stripe usage is not recorded for the rejected request, so the cap is enforced.

認証: 必須 (Bearer / X-API-Key)

Request body (CapRequest):

{
  "monthly_cap_yen": 0
}

Response 200 (CapResponse):

{
  "monthly_cap_yen": 0,
  "ok": true
}

Example:

curl -X POST "https://api.jpcite.com/v1/me/cap" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"monthly_cap_yen": 0}'

---

GET /v1/me/dashboard

30-day usage summary for the calling key.

Bearer-authenticated. The series is filled with zeros for days with no usage so the UI can render a contiguous bar chart without client-side gap-filling.

認証: 必須 (Bearer / X-API-Key)

Query parameters:

name	type	required	description
days	integer	no	—

Response 200 (DashboardSummary):

{
  "cap_remaining_yen": 0,
  "current_period_end": "string",
  "days": 0,
  "last_30_amount_yen": 0,
  "last_30_calls": 0,
  "last_7_calls": 0,
  "month_to_date_amount_yen": 0,
  "...": "..."
}

Example:

curl -X GET "https://api.jpcite.com/v1/me/dashboard?days=30" \
  -H "X-API-Key: YOUR_API_KEY"

---

POST /v1/me/rotate-key

現在の API key を失効し、新しい API key を発行します。月次上限や通知設定は引き継がれます。

認証: 必須 (Bearer / X-API-Key)

Response 200 (RotateKeyResponse):

{
  "api_key": "string",
  "tier": "string"
}

Example:

curl -X POST "https://api.jpcite.com/v1/me/rotate-key" \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/me/tool_recommendation

Map a free-text intent to recommended tool candidates.

Pure keyword scoring — no LLM API call. The caller is expected to be an LLM agent; we return signal, the caller composes the next request.

認証: 必須 (Bearer / X-API-Key)

Query parameters:

name	type	required	description
intent	string	yes	—
limit	integer	no	—

Response 200 (ToolRecommendationResponse):

{
  "fallback_used": true,
  "intent": "string",
  "tools": [
    "..."
  ]
}

Example:

curl -X GET "https://api.jpcite.com/v1/me/tool_recommendation" \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/me/usage

Get Me Usage

認証: 必須 (Bearer / X-API-Key)

Query parameters:

name	type	required	description
days	integer	no	—

Response 200:

[
  {
    "calls": 0,
    "date": "string"
  }
]

Example:

curl -X GET "https://api.jpcite.com/v1/me/usage?days=30" \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/me/usage_by_tool

Top N endpoints by call count over the requested window.

認証: 必須 (Bearer / X-API-Key)

Query parameters:

name	type	required	description
days	integer	no	—
limit	integer	no	—

Response 200 (ToolUsageResponse):

{
  "days": 0,
  "top": [
    "..."
  ],
  "total_amount_yen": 0,
  "total_calls": 0
}

Example:

curl -X GET "https://api.jpcite.com/v1/me/usage_by_tool?days=30" \
  -H "X-API-Key: YOUR_API_KEY"

---

POST /v1/session

Create Session

認証: 任意 (未認証は匿名扱い)

Request body (SessionRequest):

{
  "api_key": "string"
}

Response 200 (SessionResponse):

{
  "tier": "string"
}

Example:

curl -X POST "https://api.jpcite.com/v1/session" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api_key": "string"}'

---

POST /v1/session/logout

Logout

認証: 任意 (未認証は匿名扱い)

Example:

curl -X POST "https://api.jpcite.com/v1/session/logout" \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/usage

Probe the caller's current quota state without consuming a slot.

The handler is not attached to AnonIpLimitDep so anonymous callers can call it freely — the whole point of the tool is to avoid burning the bucket while checking it.

認証: 任意 (未認証は匿名扱い)

Response 200 (UsageStatus):

{
  "limit": 0,
  "note": "string",
  "remaining": 0,
  "reset_at": "string",
  "reset_timezone": "string",
  "tier": "string",
  "upgrade_url": "string",
  "used": 0
}

Example:

curl -X GET "https://api.jpcite.com/v1/usage" \
  -H "X-API-Key: YOUR_API_KEY"

---

Alerts (/v1/me/alerts)

POST /v1/me/alerts/subscribe

認証済み API key にアラート通知を登録します。webhook_url または email のどちらか一方は必須です。

filter_value は filter_type='all' 以外で必須です。

認証: 必須 (Bearer / X-API-Key)

Request body (AlertSubscribeRequest):

{
  "email": "[email protected]",
  "filter_type": "tool",
  "filter_value": "string",
  "min_severity": "critical",
  "webhook_url": "string"
}

Response 201 (SubscriptionResponse):

{
  "active": true,
  "created_at": "string",
  "email": "string",
  "filter_type": "string",
  "filter_value": "string",
  "id": 0,
  "last_triggered": "string",
  "min_severity": "string",
  "...": "..."
}

Example:

curl -X POST "https://api.jpcite.com/v1/me/alerts/subscribe" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "filter_type": "tool", "filter_value": "string", "min_severity": "critical", "webhook_url": "string"}'

---

GET /v1/me/alerts/subscriptions

認証済み API key の有効なアラート通知を一覧します。停止済み通知は通常レスポンスに含まれません。

認証: 必須 (Bearer / X-API-Key)

Response 200:

[
  {
    "active": true,
    "created_at": "string",
    "email": "...",
    "filter_type": "string",
    "filter_value": "...",
    "id": 0,
    "last_triggered": "...",
    "min_severity": "string",
    "...": "..."
  }
]

Example:

curl -X GET "https://api.jpcite.com/v1/me/alerts/subscriptions" \
  -H "X-API-Key: YOUR_API_KEY"

---

DELETE /v1/me/alerts/subscriptions/{sub_id}

Deactivate (soft-delete) the subscription.

The record stays retained with active=0 so audit trails remain intact. A re-subscribe creates a fresh record rather than reviving the old one — this keeps created_at semantically honest.

404 when the id does not belong to this key OR when it is already inactive (so callers cannot probe the id-space of other keys).

認証: 必須 (Bearer / X-API-Key)

Path parameters:

name	type	required	description
sub_id	integer	yes	—

Response 200 (DeactivateResponse):

{
  "id": 0,
  "ok": true
}

Example:

curl -X DELETE "https://api.jpcite.com/v1/me/alerts/subscriptions/<sub_id>" \
  -H "X-API-Key: YOUR_API_KEY"

---

Session & Device

POST /v1/device/authorize

Mint a fresh (device_code, user_code) pair (RFC 8628 §3.1).

認証: 任意 (未認証は匿名扱い)

Request body (AuthorizeRequest):

{
  "client_id": "jpcite-mcp",
  "scope": "string"
}

Response 200 (AuthorizeResponse):

{
  "device_code": "string",
  "expires_in": 0,
  "interval": 0,
  "user_code": "string",
  "verification_uri": "string",
  "verification_uri_complete": "string"
}

Example:

curl -X POST "https://api.jpcite.com/v1/device/authorize" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"client_id": "jpcite-mcp", "scope": "string"}'

---

POST /v1/device/complete

Completes device activation after checkout and enables token polling for the MCP client.

認証: 任意 (未認証は匿名扱い)

Request body (CompleteRequest):

{
  "stripe_checkout_session_id": "string",
  "user_code": "string"
}

Response 200 (CompleteResponse):

{
  "ok": true
}

Example:

curl -X POST "https://api.jpcite.com/v1/device/complete" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"stripe_checkout_session_id": "string", "user_code": "string"}'

---

POST /v1/device/token

Device-flow poll endpoint (RFC 8628 §3.4).

Success → {access_token, token_type, scope} + 200. Pending → authorization_pending (400). Polling too fast → slow_down (400). Expired → expired_token (400). Denied → access_denied (400). Invalid grant_type / device_code → invalid_grant (400).

認証: 任意 (未認証は匿名扱い)

Request body (TokenRequest):

{
  "client_id": "jpcite-mcp",
  "device_code": "string",
  "grant_type": "string"
}

Response 200 (TokenSuccess):

{
  "access_token": "string",
  "scope": "string",
  "token_type": "Bearer"
}

Example:

curl -X POST "https://api.jpcite.com/v1/device/token" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"client_id": "jpcite-mcp", "device_code": "string", "grant_type": "string"}'

---

Subscribers (Email)

GET /v1/email/unsubscribe

メール下部のリンクから表示される unsubscribe ページ。

リンクに含まれる token を検証し、ユーザーが明示的に操作した場合に配信停止を行う。

認証: 任意 (未認証は匿名扱い)

Query parameters:

name	type	required	description
email	string	yes	—
token	string	yes	—

Example:

curl -X GET "https://api.jpcite.com/v1/email/unsubscribe" \
  -H "X-API-Key: YOUR_API_KEY"

---

POST /v1/email/unsubscribe

配信停止を受け付ける endpoint。同じ token で複数回呼ばれても結果は同じ。

無効な token でも、メールアドレスの存在確認に使われないよう同じ形のレスポンスを返す。

認証: 任意 (未認証は匿名扱い)

Query parameters:

name	type	required	description
email	string	yes	—
token	string	yes	—
reason	string	null	no

Response 200 (UnsubscribeResponse):

{
  "at": "string",
  "unsubscribed": true
}

Example:

curl -X POST "https://api.jpcite.com/v1/email/unsubscribe" \
  -H "X-API-Key: YOUR_API_KEY"

---

POST /v1/subscribers

Subscribe

認証: 任意 (未認証は匿名扱い)

Request body (SubscriberSubscribeRequest):

{
  "email": "[email protected]",
  "source": "string"
}

Response 201 (SubscriberSubscribeResponse):

{
  "subscribed": true
}

Example:

curl -X POST "https://api.jpcite.com/v1/subscribers" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "source": "string"}'

---

GET /v1/subscribers/unsubscribe

Unsubscribe

認証: 任意 (未認証は匿名扱い)

Query parameters:

name	type	required	description
token	string	yes	—
email	string	yes	—

Example:

curl -X GET "https://api.jpcite.com/v1/subscribers/unsubscribe" \
  -H "X-API-Key: YOUR_API_KEY"

---

Compliance Newsletter

POST /v1/compliance/stripe-checkout

Creates a checkout session for a verified paid subscriber.

認証: 任意 (未認証は匿名扱い)

Request body (CheckoutRequest):

{
  "cancel_url": "https://jpcite.com/alerts?status=canceled",
  "subscriber_id": 0,
  "success_url": "https://jpcite.com/alerts?status=ok"
}

Response 200 (CheckoutResponse):

{
  "session_id": "string",
  "url": "string"
}

Example:

curl -X POST "https://api.jpcite.com/v1/compliance/stripe-checkout" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cancel_url": "https://jpcite.com/alerts?status=canceled", "subscriber_id": 0, "success_url": "https://jpcite.com/alerts?status=ok"}'

---

POST /v1/compliance/subscribe

Create a new subscription request and send a verification email.

Duplicate email behaviour: the response shape is privacy-preserving and does not reveal whether an email is already registered. Repeated requests may resend the verification email subject to rate limits.

認証: 任意 (未認証は匿名扱い)

Request body (ComplianceSubscribeRequest):

{
  "areas_of_interest": [
    "string"
  ],
  "email": "[email protected]",
  "houjin_bangou": "string",
  "industry_codes": [
    "string"
  ],
  "plan": "free",
  "prefecture": "string",
  "source_lang": "ja"
}

Response 201 (ComplianceSubscribeResponse):

{
  "checkout_url": "string",
  "next_step": "verify",
  "subscriber_id": 0
}

Example:

curl -X POST "https://api.jpcite.com/v1/compliance/subscribe" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"areas_of_interest": ["string"], "email": "[email protected]", "houjin_bangou": "string", "industry_codes": ["string"], "plan": "free", "prefecture": "string", "source_lang": "ja"}'

---

POST /v1/compliance/unsubscribe/{unsubscribe_token}

Cancels the subscription and stops future compliance newsletter emails. Returns HTML for the unsubscribe confirmation flow.

認証: 任意 (未認証は匿名扱い)

Path parameters:

name	type	required	description
unsubscribe_token	string	yes	—

Example:

curl -X POST "https://api.jpcite.com/v1/compliance/unsubscribe/<unsubscribe_token>" \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/compliance/verify/{verification_token}

Verify a subscriber email and render a minimal HTML page. The link is idempotent; repeated clicks show the same success page. Paid subscribers are directed to Stripe Checkout after verification.

認証: 任意 (未認証は匿名扱い)

Path parameters:

name	type	required	description
verification_token	string	yes	—

Example:

curl -X GET "https://api.jpcite.com/v1/compliance/verify/<verification_token>" \
  -H "X-API-Key: YOUR_API_KEY"

---

Public Stats (Transparency)

GET /v1/stats/confidence

Live Bayesian Discovery + Use posteriors per tool, last 30 days.

認証: 任意 (未認証は匿名扱い)

Response 200 (ConfidenceResponse):

{
  "generated_at": "string",
  "overall": {},
  "per_tool": [
    "..."
  ],
  "since": "string",
  "until": "string",
  "window_days": 0
}

Example:

curl -X GET "https://api.jpcite.com/v1/stats/confidence" \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/stats/coverage

Stats Coverage

認証: 任意 (未認証は匿名扱い)

Response 200 (CoverageResponse):

{
  "bids": 0,
  "case_studies": 0,
  "court_decisions": 0,
  "enforcement_cases": 0,
  "exclusion_rules": 0,
  "generated_at": "string",
  "invoice_registrants": 0,
  "laws": 0,
  "...": "..."
}

Example:

curl -X GET "https://api.jpcite.com/v1/stats/coverage" \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/stats/data_quality

Stats Data Quality

認証: 任意 (未認証は匿名扱い)

Response 200 (DataQualityResponse):

{
  "cross_source_agreement": {},
  "fact_count_total": 0,
  "field_kind_breakdown": {},
  "freshness_buckets": {},
  "generated_at": "string",
  "label_histogram": {},
  "license_breakdown": {},
  "mean_score": 0.0,
  "...": "..."
}

Example:

curl -X GET "https://api.jpcite.com/v1/stats/data_quality" \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/stats/freshness

Stats Freshness

認証: 任意 (未認証は匿名扱い)

Response 200 (FreshnessResponse):

{
  "generated_at": "string",
  "sources": {}
}

Example:

curl -X GET "https://api.jpcite.com/v1/stats/freshness" \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/stats/usage

Stats Usage

認証: 任意 (未認証は匿名扱い)

Response 200 (UsageResponse):

{
  "daily": [
    "..."
  ],
  "generated_at": "string",
  "since": "string",
  "total": 0,
  "until": "string",
  "window_days": 30
}

Example:

curl -X GET "https://api.jpcite.com/v1/stats/usage" \
  -H "X-API-Key: YOUR_API_KEY"

---

Testimonials

POST /v1/me/testimonials

Submit Testimonial

認証: 必須 (Bearer / X-API-Key)

Request body (TestimonialSubmit):

{
  "audience": "税理士",
  "linkedin_url": "string",
  "name": "string",
  "organization": "string",
  "text": "string"
}

Response 201 (TestimonialSubmitResponse):

{
  "pending_review": true,
  "received": true,
  "testimonial_id": 0
}

Example:

curl -X POST "https://api.jpcite.com/v1/me/testimonials" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"audience": "税理士", "linkedin_url": "string", "name": "string", "organization": "string", "text": "string"}'

---

DELETE /v1/me/testimonials/{testimonial_id}

Delete My Testimonial

認証: 必須 (Bearer / X-API-Key)

Path parameters:

name	type	required	description
testimonial_id	integer	yes	—

Response 204: No Content

Example:

curl -X DELETE "https://api.jpcite.com/v1/me/testimonials/<testimonial_id>" \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/testimonials

List Testimonials

認証: 任意 (未認証は匿名扱い)

Response 200 (TestimonialListResponse):

{
  "rows": [
    "..."
  ],
  "total": 0
}

Example:

curl -X GET "https://api.jpcite.com/v1/testimonials" \
  -H "X-API-Key: YOUR_API_KEY"

---

Advisors

GET /v1/advisors/match

Return advisors matching the supplied filters, ordered by relevance.

認証: 任意 (未認証は匿名扱い)

Query parameters:

name	type	required	description
prefecture	string	null	no
specialty	string	null	no
industry	string	null	no
limit	integer	no	—

Response 200 (MatchResponse):

{
  "ranking": {},
  "results": [
    "..."
  ],
  "total": 0
}

Example:

curl -X GET "https://api.jpcite.com/v1/advisors/match" \
  -H "X-API-Key: YOUR_API_KEY"

---

POST /v1/advisors/report-conversion

Record a referral conversion and queue the corresponding referral summary.

認証: 任意 (未認証は匿名扱い)

Request body (ReportConversionRequest):

{
  "conversion_value_yen": 0,
  "evidence_url": "https://...",
  "referral_token": "string"
}

Example:

curl -X POST "https://api.jpcite.com/v1/advisors/report-conversion" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"conversion_value_yen": 0, "evidence_url": "https://...", "referral_token": "string"}'

---

POST /v1/advisors/signup

Create an advisor profile and return the onboarding URL. Public listing starts after official registry verification and payout readiness are complete.

認証: 任意 (未認証は匿名扱い)

Request body (SignupRequest):

{
  "address": "string",
  "agreed_to_terms": true,
  "city": "string",
  "commission_model": "flat",
  "commission_rate_pct": 5,
  "commission_yen_per_intro": 3000,
  "contact_email": "[email protected]",
  "contact_phone": "string",
  "...": "..."
}

Response 200 (SignupResponse):

{
  "advisor_id": 0,
  "next_step": "stripe_connect",
  "stripe_connect_onboarding_url": "string"
}

Example:

curl -X POST "https://api.jpcite.com/v1/advisors/signup" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"address": "string", "agreed_to_terms": true, "city": "string", "commission_model": "flat", "commission_rate_pct": 5, "commission_yen_per_intro": 3000, "contact_email": "[email protected]", "contact_phone": "string", "...": "..."}'

---

POST /v1/advisors/track

Record a referral click and return a referral redirect URL after explicit user consent. Any referral fee is resolved at conversion time.

認証: 任意 (未認証は匿名扱い)

Request body (TrackRequest):

{
  "advisor_id": 0,
  "source_program_id": "string",
  "source_query_hash": "string",
  "consent_granted": true
}

Response 200 (TrackResponse):

{
  "redirect_url": "string",
  "token": "string"
}

Example:

curl -X POST "https://api.jpcite.com/v1/advisors/track" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"advisor_id": 0, "source_program_id": "string", "source_query_hash": "string", "consent_granted": true}'

---

POST /v1/advisors/verify-houjin/{advisor_id}

Verify the advisor's organization number against the official registry. Repeated successful verification is safe.

認証: 任意 (未認証は匿名扱い)

Path parameters:

name	type	required	description
advisor_id	integer	yes	—

Example:

curl -X POST "https://api.jpcite.com/v1/advisors/verify-houjin/<advisor_id>" \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/advisors/{advisor_id}/dashboard-data

Return referral and earnings summary for the advisor dashboard.

認証: 必須 (Bearer / X-API-Key)

Path parameters:

name	type	required	description
advisor_id	integer	yes	—

Response 200 (AdvisorDashboardResponse):

{
  "advisor": {},
  "referrals": [
    "..."
  ],
  "summary": {
    "clicks": "...",
    "conversions": "...",
    "paid_yen": "...",
    "unpaid_yen": "..."
  }
}

Example:

curl -X GET "https://api.jpcite.com/v1/advisors/<advisor_id>/dashboard-data" \
  -H "X-API-Key: YOUR_API_KEY"

---

Widget

GET /v1/widget/enum_values

Return filter enum vocab for widget dropdowns — prefectures, industries, authority_levels, and a short target_types list drawn from programs.

認証: 任意 (未認証は匿名扱い)

Query parameters:

name	type	required	description
key	string	null	no

Example:

curl -X GET "https://api.jpcite.com/v1/widget/enum_values" \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/widget/search

Search programs restricted to the widget surface.

Widget 向けに /v1/programs/search と同等の制度検索を返す軽量 endpoint。

認証: 任意 (未認証は匿名扱い)

Query parameters:

name	type	required	description
key	string	null	no
q	string	null	no
prefecture	string	null	no
authority_level	string	null	no
industry	string	null	no
target	string[]	null	no
funding_purpose	string[]	null	no
limit	integer	no	—

Example:

curl -X GET "https://api.jpcite.com/v1/widget/search" \
  -H "X-API-Key: YOUR_API_KEY"

---

POST /v1/widget/signup

Create a Stripe Checkout session for the widget plan.

The widget key is provisioned after Stripe confirms checkout completion.

認証: 任意 (未認証は匿名扱い)

Request body (WidgetSignupRequest):

{
  "cancel_url": "string",
  "email": "[email protected]",
  "label": "string",
  "origins": [
    "string"
  ],
  "plan": "business",
  "success_url": "string"
}

Response 200 (WidgetSignupResponse):

{
  "checkout_url": "string",
  "session_id": "string"
}

Example:

curl -X POST "https://api.jpcite.com/v1/widget/signup" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cancel_url": "string", "email": "[email protected]", "label": "string", "origins": ["string"], "plan": "business", "success_url": "string"}'

---

GET /v1/widget/{key_id}/usage

Return the owner-visible widget usage summary.

認証: 任意 (未認証は匿名扱い)

Path parameters:

name	type	required	description
key_id	string	yes	—

Example:

curl -X GET "https://api.jpcite.com/v1/widget/<key_id>/usage" \
  -H "X-API-Key: YOUR_API_KEY"

---

APPI Privacy Requests

POST /v1/privacy/deletion_request

個人情報の保護に関する法律 第33条 に基づく削除請求を受付けます。 このエンドポイントは受付番号の発行と運営宛通知のみを行い、 実際の削除は 30 日以内に運営側で本人確認の上で別途対応します (§33-3 法定上限)。 個人情報そのものはこのレスポンスでは返却・ 操作しません。

認証: 任意 (未認証は匿名扱い)

Request body (DeletionRequest):

{
  "deletion_reason": "string",
  "identity_verification_method": "drivers_license",
  "requester_email": "[email protected]",
  "requester_legal_name": "string",
  "target_data_categories": [
    "representative"
  ],
  "target_houjin_bangou": "string"
}

Response 201 (DeletionResponse):

{
  "contact": "support",
  "expected_response_within_days": 30,
  "received_at": "string",
  "request_id": "string"
}

Example:

curl -X POST "https://api.jpcite.com/v1/privacy/deletion_request" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"deletion_reason": "string", "identity_verification_method": "drivers_license", "requester_email": "[email protected]", "requester_legal_name": "string", "target_data_categories": ["representative"], "target_houjin_bangou": "string"}'

---

POST /v1/privacy/disclosure_request

個人情報の保護に関する法律 第31条 に基づく開示請求を受付けます。 このエンドポイントは受付番号の発行と運営宛通知のみを行い、 実際の開示は 14 日以内に運営側で本人確認の上で別途対応します。 個人情報そのものはこのレスポンスでは返却しません。

認証: 任意 (未認証は匿名扱い)

Request body (DisclosureRequest):

{
  "identity_verification_method": "drivers_license",
  "requester_email": "[email protected]",
  "requester_legal_name": "string",
  "target_houjin_bangou": "string"
}

Response 201 (DisclosureResponse):

{
  "contact": "support",
  "expected_response_within_days": 14,
  "received_at": "string",
  "request_id": "string"
}

Example:

curl -X POST "https://api.jpcite.com/v1/privacy/disclosure_request" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"identity_verification_method": "drivers_license", "requester_email": "[email protected]", "requester_legal_name": "string", "target_houjin_bangou": "string"}'

---

Calendar

GET /v1/calendar/deadlines

List upcoming submission deadlines.

Answers "what's due in the next 30 days for 東京 SMBs?" in one call so callers don't stitch together N search_programs requests. Programs without a structured end_date are silently excluded — they are not "no deadline", they are "we couldn't extract one" and need case-by-case lookup via get_program.

認証: 任意 (未認証は匿名扱い)

Query parameters:

name	type	required	description
within_days	integer	no	Only return programs whose end_date falls between today and today + within_days (inclusive). Default 30.
prefecture	string	null	no
authority_level	string	null	no
tier	string[]	null	no
limit	integer	no	—

Response 200 (DeadlinesResponse):

{
  "as_of": "string",
  "results": [
    "..."
  ],
  "total": 0,
  "within_days": 0
}

Example:

curl -X GET "https://api.jpcite.com/v1/calendar/deadlines?within_days=30" \
  -H "X-API-Key: YOUR_API_KEY"

---

Case Studies

GET /v1/case-studies/search

Search 採択事例 case studies.

認証: 任意 (未認証は匿名扱い)

Query parameters:

name	type	required	description
q	string	null	no
prefecture	string	null	no
industry_jsic	string	null	no
houjin_bangou	string	null	no
program_used	string	null	no
min_subsidy_yen	integer	null	no
max_subsidy_yen	integer	null	no
min_employees	integer	null	no
max_employees	integer	null	no
limit	integer	no	—
offset	integer	no	—

Response 200 (CaseStudySearchResponse):

{
  "limit": 0,
  "offset": 0,
  "results": [
    "..."
  ],
  "total": 0
}

Example:

curl -X GET "https://api.jpcite.com/v1/case-studies/search" \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/case-studies/{case_id}

Single case study lookup by case_id.

認証: 任意 (未認証は匿名扱い)

Path parameters:

name	type	required	description
case_id	string	yes	—

Response 200 (CaseStudy):

{
  "capital_yen": 0,
  "case_id": "string",
  "case_summary": "string",
  "case_title": "string",
  "company_name": "string",
  "confidence": 0.0,
  "employees": 0,
  "fetched_at": "string",
  "...": "..."
}

Example:

curl -X GET "https://api.jpcite.com/v1/case-studies/<case_id>" \
  -H "X-API-Key: YOUR_API_KEY"

---

Loan Programs

GET /v1/loan-programs/search

Search loan programs with three-axis risk filters.

認証: 任意 (未認証は匿名扱い)

Query parameters:

name	type	required	description
q	string	null	no
provider	string	null	no
loan_type	string	null	no
collateral_required	string	null	no
personal_guarantor_required	string	null	no
third_party_guarantor_required	string	null	no
min_amount_yen	integer	null	no
max_amount_yen	integer	null	no
max_interest_rate	number	null	no
min_loan_period_years	integer	null	no
limit	integer	no	—
offset	integer	no	—

Response 200 (LoanProgramSearchResponse):

{
  "limit": 0,
  "offset": 0,
  "results": [
    "..."
  ],
  "total": 0
}

Example:

curl -X GET "https://api.jpcite.com/v1/loan-programs/search" \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/loan-programs/{loan_id}

Get Loan Program

認証: 任意 (未認証は匿名扱い)

Path parameters:

name	type	required	description
loan_id	integer	yes	—

Response 200 (LoanProgram):

{
  "amount_max_yen": 0,
  "collateral_required": "required",
  "confidence": 0.0,
  "fetched_at": "string",
  "grace_period_years_max": 0,
  "id": 0,
  "interest_rate_base_annual": 0.0,
  "interest_rate_special_annual": 0.0,
  "...": "..."
}

Example:

curl -X GET "https://api.jpcite.com/v1/loan-programs/<loan_id>" \
  -H "X-API-Key: YOUR_API_KEY"

---

Enforcement Cases

GET /v1/enforcement-cases/search

Search enforcement cases for compliance / DD lookup.

認証: 任意 (未認証は匿名扱い)

Query parameters:

name	type	required	description
q	string	null	no
event_type	string	null	no
ministry	string	null	no
prefecture	string	null	no
legal_basis	string	null	no
program_name_hint	string	null	no
recipient_houjin_bangou	string	null	no
min_improper_grant_yen	integer	null	no
max_improper_grant_yen	integer	null	no
disclosed_from	string	null	no
disclosed_until	string	null	no
limit	integer	no	—
offset	integer	no	—

Response 200 (EnforcementCaseSearchResponse):

{
  "limit": 0,
  "offset": 0,
  "results": [
    "..."
  ],
  "total": 0
}

Example:

curl -X GET "https://api.jpcite.com/v1/enforcement-cases/search" \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/enforcement-cases/{case_id}

Get Enforcement Case

認証: 任意 (未認証は匿名扱い)

Path parameters:

name	type	required	description
case_id	string	yes	—

Response 200 (EnforcementCase):

{
  "amount_grant_paid_yen": 0,
  "amount_improper_grant_yen": 0,
  "amount_improper_project_cost_yen": 0,
  "amount_project_cost_yen": 0,
  "amount_yen": 0,
  "bureau": "string",
  "case_id": "string",
  "confidence": 0.0,
  "...": "..."
}

Example:

curl -X GET "https://api.jpcite.com/v1/enforcement-cases/<case_id>" \
  -H "X-API-Key: YOUR_API_KEY"

---

Invoice Registrants

GET /v1/invoice_registrants/search

Search 適格請求書発行事業者 by name / 法人番号 / location / status.

This endpoint is lookup-only. Bulk-style queries (empty q + empty filters paging through the complete dataset) work but return exactly one page at a time; the PDL v1.0 attribution is repeated on every page to keep 出典明記 + 編集・加工注記 visible across paginated reads.

認証: 任意 (未認証は匿名扱い)

Query parameters:

name	type	required	description
q	string	null	no
houjin_bangou	string	null	no
kind	string	null	no
prefecture	string	null	no
registered_after	string	null	no
registered_before	string	null	no
active_only	boolean	no	When true (default), excludes revoked (revoked_date IS NOT NULL) and expired (expired_date IS NOT NULL) rows. Flip to false for historical/audit research.
limit	integer	no	Page size. Default 50, maximum 100. No wildcard bulk export — point consumers at NTA's own download URL for full snapshots.
offset	integer	no	—

Response 200 (InvoiceRegistrantSearchResponse):

{
  "attribution": {
    "edited": "...",
    "license": "...",
    "notice": "...",
    "source": "...",
    "source_url": "..."
  },
  "limit": 0,
  "offset": 0,
  "results": [
    "..."
  ],
  "total": 0
}

Example:

curl -X GET "https://api.jpcite.com/v1/invoice_registrants/search" \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/invoice_registrants/{invoice_registration_number}

Exact lookup by 適格請求書発行事業者登録番号 ('T' + 13 digits).

未登録または未収録の場合は、単純な 404 だけで終わらせず、確認に使える追加情報を返す。重要な確認では、レスポンス内の案内に従って国税庁の公式検索も確認してください。

認証: 任意 (未認証は匿名扱い)

Path parameters:

name	type	required	description
invoice_registration_number	string	yes	—

Response 200 (GetResponse):

{
  "attribution": {
    "edited": "...",
    "license": "...",
    "notice": "...",
    "source": "...",
    "source_url": "..."
  },
  "result": {
    "address_normalized": "...",
    "confidence": "...",
    "expired_date": "...",
    "fetched_at": "...",
    "houjin_bangou": "...",
    "invoice_registration_number": "...",
    "last_updated_nta": "...",
    "normalized_name": "...",
    "...": "..."
  }
}

Example:

curl -X GET "https://api.jpcite.com/v1/invoice_registrants/<invoice_registration_number>" \
  -H "X-API-Key: YOUR_API_KEY"

---

Laws

GET /v1/laws/search

Search laws (statutes, ordinances, ministerial rules).

認証: 任意 (未認証は匿名扱い)

Query parameters:

name	type	required	description
q	string	null	no
law_type	string	null	no
ministry	string	null	no
currently_effective_only	boolean	no	When true (default), only revision_status='current' rows are returned. Flip to false to include 'superseded' rows.
include_repealed	boolean	no	When false (default), revision_status='repealed' rows are excluded. Flip to true for historical research.
promulgated_from	string	null	no
promulgated_to	string	null	no
enforced_from	string	null	no
enforced_to	string	null	no
limit	integer	no	—
offset	integer	no	—

Response 200 (LawSearchResponse):

{
  "limit": 0,
  "offset": 0,
  "results": [
    "..."
  ],
  "total": 0
}

Example:

curl -X GET "https://api.jpcite.com/v1/laws/search" \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/laws/{unified_id}

Return a single law including summary, article_count, and lineage.

認証: 任意 (未認証は匿名扱い)

Path parameters:

name	type	required	description
unified_id	string	yes	—

Response 200 (Law):

{
  "article_count": 0,
  "confidence": 0.95,
  "enforced_date": "string",
  "fetched_at": "string",
  "full_text_url": "string",
  "last_amended_date": "string",
  "law_number": "string",
  "law_short_title": "string",
  "...": "..."
}

Example:

curl -X GET "https://api.jpcite.com/v1/laws/<unified_id>" \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/laws/{unified_id}/related-programs

Reverse lookup: which programs cite this law via program_law_refs.

認証: 任意 (未認証は匿名扱い)

Path parameters:

name	type	required	description
unified_id	string	yes	—

Query parameters:

name	type	required	description
ref_kind	string	null	no
limit	integer	no	—
offset	integer	no	—

Response 200 (RelatedProgramsResponse):

{
  "law_unified_id": "string",
  "limit": 0,
  "offset": 0,
  "results": [
    "..."
  ],
  "total": 0
}

Example:

curl -X GET "https://api.jpcite.com/v1/laws/<unified_id>/related-programs" \
  -H "X-API-Key: YOUR_API_KEY"

---

Court Decisions

POST /v1/court-decisions/by-statute

Return court decisions citing a given LAW-<10 hex> statute.

TRACE endpoint: resolves the statute→ruling edge via related_law_ids_json. When article_citation is supplied, we additionally require the article string to appear in key_ruling or source_excerpt — the ingest does not yet write a structured (law_id, article) map, so this is a honest contains-check, not a false-precision exact join. Callers should treat article_citation narrowing as best-effort.

認証: 任意 (未認証は匿名扱い)

Request body (CourtDecisionByStatuteRequest):

{
  "article_citation": "string",
  "law_id": "string",
  "limit": 20,
  "offset": 0
}

Response 200 (CourtDecisionSearchResponse):

{
  "limit": 0,
  "offset": 0,
  "results": [
    "..."
  ],
  "total": 0
}

Example:

curl -X POST "https://api.jpcite.com/v1/court-decisions/by-statute" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"article_citation": "string", "law_id": "string", "limit": 20, "offset": 0}'

---

GET /v1/court-decisions/search

Search court decisions (判決 / 決定 / 命令).

認証: 任意 (未認証は匿名扱い)

Query parameters:

name	type	required	description
q	string	null	no
court	string	null	no
court_level	string	null	no
decision_type	string	null	no
subject_area	string	null	no
references_law_id	string	null	no
decided_from	string	null	no
decided_to	string	null	no
limit	integer	no	—
offset	integer	no	—

Response 200 (CourtDecisionSearchResponse):

{
  "limit": 0,
  "offset": 0,
  "results": [
    "..."
  ],
  "total": 0
}

Example:

curl -X GET "https://api.jpcite.com/v1/court-decisions/search" \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/court-decisions/{unified_id}

Return a single court decision with full source lineage.

認証: 任意 (未認証は匿名扱い)

Path parameters:

name	type	required	description
unified_id	string	yes	—

Response 200 (CourtDecision):

{
  "case_name": "string",
  "case_number": "string",
  "confidence": 0.9,
  "court": "string",
  "court_level": "supreme",
  "decision_date": "string",
  "decision_type": "判決",
  "fetched_at": "string",
  "...": "..."
}

Example:

curl -X GET "https://api.jpcite.com/v1/court-decisions/<unified_id>" \
  -H "X-API-Key: YOUR_API_KEY"

---

Tax Rulesets

POST /v1/tax_rulesets/evaluate

Evaluate one or more rulesets against a caller business_profile.

Walks eligibility_conditions_json for each selected record and returns per-ruleset applicable + matched / unmatched predicate lists. Never interprets tax law — pure JSON predicate matching.

target_ruleset_ids omitted -> evaluates all CURRENT rulesets (effective_until IS NULL OR effective_until >= today). Use /search with effective_on + explicit ids list to evaluate historical snapshots.

認証: 任意 (未認証は匿名扱い)

Request body (EvaluateRequest):

{
  "business_profile": {},
  "target_ruleset_ids": [
    "..."
  ]
}

Response 200 (EvaluateResponse):

{
  "results": [
    "..."
  ]
}

Example:

curl -X POST "https://api.jpcite.com/v1/tax_rulesets/evaluate" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"business_profile": {}, "target_ruleset_ids": ["..."]}'

---

GET /v1/tax_rulesets/search

Search 税務判定ルールセット (tax_rulesets).

認証: 任意 (未認証は匿名扱い)

Query parameters:

name	type	required	description
q	string	null	no
tax_category	string	null	no
ruleset_kind	string	null	no
effective_on	string	null	no
limit	integer	no	—
offset	integer	no	—

Response 200 (TaxRulesetSearchResponse):

{
  "limit": 0,
  "offset": 0,
  "results": [
    "..."
  ],
  "total": 0
}

Example:

curl -X GET "https://api.jpcite.com/v1/tax_rulesets/search" \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/tax_rulesets/{unified_id}

Return a single 税務判定ルールセット by TAX-<10hex> id.

認証: 任意 (未認証は匿名扱い)

Path parameters:

name	type	required	description
unified_id	string	yes	—

Response 200 (TaxRulesetOut):

{
  "authority": "string",
  "authority_url": "string",
  "calculation_formula": "string",
  "confidence": 0.0,
  "effective_from": "string",
  "effective_until": "string",
  "eligibility_conditions": "string",
  "eligibility_conditions_json": null,
  "...": "..."
}

Example:

curl -X GET "https://api.jpcite.com/v1/tax_rulesets/<unified_id>" \
  -H "X-API-Key: YOUR_API_KEY"

---

Bids

GET /v1/bids/search

Search bids (入札案件). Text search when q is given, else most recently published first.

認証: 任意 (未認証は匿名扱い)

Query parameters:

name	type	required	description
q	string	null	no
bid_kind	string	null	no
procuring_houjin_bangou	string	null	no
winner_houjin_bangou	string	null	no
program_id_hint	string	null	no
min_amount	integer	null	no
max_amount	integer	null	no
deadline_after	string	null	no
limit	integer	no	—
offset	integer	no	—

Response 200 (BidsSearchResponse):

{
  "limit": 0,
  "offset": 0,
  "results": [
    "..."
  ],
  "total": 0
}

Example:

curl -X GET "https://api.jpcite.com/v1/bids/search" \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/bids/{unified_id}

Return a single 入札案件 by BID-<10 hex> unified_id.

認証: 任意 (未認証は匿名扱い)

Path parameters:

name	type	required	description
unified_id	string	yes	—

Response 200 (BidOut):

{
  "announcement_date": "string",
  "awarded_amount_yen": 0,
  "bid_deadline": "string",
  "bid_description": "string",
  "bid_kind": "open",
  "bid_title": "string",
  "budget_ceiling_yen": 0,
  "classification_code": "string",
  "...": "..."
}

Example:

curl -X GET "https://api.jpcite.com/v1/bids/<unified_id>" \
  -H "X-API-Key: YOUR_API_KEY"

---

jpcite: Programs (Active / Related / Stats / GX)

GET /v1/am/acceptance_stats

採択率 / 採択事例 statistics from the acceptance statistics corpus.

認証: 任意 (未認証は匿名扱い)

Query parameters:

name	type	required	description
program_name	string	null	no
year	integer	null	no
region	string	null	no
industry	string	null	no
limit	integer	no	—
offset	integer	no	—

Response 200 (SearchResponse):

{
  "error": {},
  "limit": 0,
  "meta": {},
  "offset": 0,
  "results": [
    {}
  ],
  "retrieval_note": "string",
  "total": 0
}

Example:

curl -X GET "https://api.jpcite.com/v1/am/acceptance_stats" \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/am/active_at

Point-in-time snapshot: programs whose effective window covered a given date.

認証: 任意 (未認証は匿名扱い)

Query parameters:

name	type	required	description
date	string	yes	ISO YYYY-MM-DD
region	string	null	no
industry	string	null	no
size	string	null	no
limit	integer	no	—

Response 200 (ActiveAtResponse):

{
  "error": {},
  "limit": 0,
  "meta": {},
  "offset": 0,
  "pivot_date": "string",
  "results": [
    {}
  ],
  "retrieval_note": "string",
  "total": 0
}

Example:

curl -X GET "https://api.jpcite.com/v1/am/active_at" \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/am/gx_programs

GX / 脱炭素 / 再エネ / EV / ZEB-ZEH curated 補助金 programs.

認証: 任意 (未認証は匿名扱い)

Query parameters:

name	type	required	description
theme	string	no	—
company_size	string	null	no
region	string	null	no
limit	integer	no	—

Response 200 (SimpleSearchResponse):

{
  "error": {},
  "results": [
    {}
  ],
  "total": 0
}

Example:

curl -X GET "https://api.jpcite.com/v1/am/gx_programs?theme=ghg_reduction" \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/am/open_programs

Currently-open (公募中) program rounds on a target date.

認証: 任意 (未認証は匿名扱い)

Query parameters:

name	type	required	description
on_date	string	null	no
region	string	null	no
industry	string	null	no
size	string	null	no
natural_query	string	null	no
limit	integer	no	—

Response 200 (OpenProgramsResponse):

{
  "error": {},
  "limit": 0,
  "meta": {},
  "offset": 0,
  "pivot_date": "string",
  "results": [
    {}
  ],
  "retrieval_note": "string",
  "total": 0
}

Example:

curl -X GET "https://api.jpcite.com/v1/am/open_programs" \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/am/programs/active_v2

Three-axis active-at: effective window + application_open + application_close in one query.

Returns programs that: - are effective on as_of (effective_from <= as_of < effective_until, with effective_from_source provenance hint), AND - have an application round whose open_date <= application_open_by (when provided), AND - have an application round whose close_date >= application_close_by (when provided), AND - match prefecture (when provided).

Caveat: 改正履歴の時系列データは一部のみ充足しています。effective_from / effective_until が入っている record だけを日付別追跡に使い、その他は現時点の スナップショットとして扱ってください。response には _lifecycle_caveat が含まれる 場合があります。

認証: 任意 (未認証は匿名扱い)

Query parameters:

name	type	required	description
as_of	string	null	no
application_open_by	string	null	no
application_close_by	string	null	no
prefecture	string	null	no
limit	integer	no	—

Example:

curl -X GET "https://api.jpcite.com/v1/am/programs/active_v2" \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/am/related/{program_id}

Graph walk over public program relationships (prerequisite / compatible / incompatible / replaces / amends / related / references_law etc.).

認証: 任意 (未認証は匿名扱い)

Path parameters:

name	type	required	description
program_id	string	yes	—

Query parameters:

name	type	required	description
relation_types	string[]	null	no
depth	integer	no	—
max_edges	integer	no	—

Response 200 (RelatedProgramsResponse):

{
  "depth": 1,
  "error": {},
  "hint": "string",
  "nodes": [
    {}
  ],
  "relations": [
    {}
  ],
  "retry_with": {},
  "seed_id": "string",
  "seed_kind": "string",
  "...": "..."
}

Example:

curl -X GET "https://api.jpcite.com/v1/am/related/<program_id>?relation_types=['string']" \
  -H "X-API-Key: YOUR_API_KEY"

---

jpcite: Intent / Reason / Enums

GET /v1/am/enums/{enum_name}

List canonical enum values + frequency for a given enum_name.

認証: 任意 (未認証は匿名扱い)

Path parameters:

name	type	required	description
enum_name	string	yes	—

Response 200 (EnumValuesResponse):

{
  "description": "string",
  "enum_name": "string",
  "error": {},
  "frequency_map": {},
  "last_updated": "string",
  "values": [
    "string"
  ]
}

Example:

curl -X GET "https://api.jpcite.com/v1/am/enums/<enum_name>" \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/am/intent

Route a natural-language query to the best-fit tool + extracted slots (query_rewrite layer).

認証: 任意 (未認証は匿名扱い)

Query parameters:

name	type	required	description
query	string	yes	—

Response 200 (IntentResponse):

{
  "all_scores": [
    {}
  ],
  "confidence": 0.0,
  "error": {},
  "intent_id": "string",
  "intent_name_ja": "string",
  "sample_queries": [
    "string"
  ]
}

Example:

curl -X GET "https://api.jpcite.com/v1/am/intent" \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/am/reason

Return a citation-backed narrative skeleton (source_url + snippet per claim). This endpoint is a structured reasoning aid for downstream agents, not a final answer generator; callers should preserve citations and apply their own user-facing wording.

認証: 任意 (未認証は匿名扱い)

Query parameters:

name	type	required	description
query	string	yes	—
persona	string	null	no

Response 200 (ReasonResponse):

{
  "answer_skeleton": "string",
  "confidence": 0.0,
  "db_bind_notes": [
    "..."
  ],
  "db_bind_ok": true,
  "error": {},
  "filters_extracted": {},
  "intent": "string",
  "intent_name_ja": "string",
  "...": "..."
}

Example:

curl -X GET "https://api.jpcite.com/v1/am/reason" \
  -H "X-API-Key: YOUR_API_KEY"

---

jpcite: Tax Incentives & Certifications

GET /v1/am/certifications

認定・認証制度 (健康経営 / えるぼし / くるみん / SDGs / 経営革新 等) search.

認証: 任意 (未認証は匿名扱い)

Query parameters:

name	type	required	description
query	string	null	no
authority	string	null	no
size	string	null	no
industry	string	null	no
limit	integer	no	—
offset	integer	no	—

Response 200 (SearchResponse):

{
  "error": {},
  "limit": 0,
  "meta": {},
  "offset": 0,
  "results": [
    {}
  ],
  "retrieval_note": "string",
  "total": 0
}

Example:

curl -X GET "https://api.jpcite.com/v1/am/certifications" \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/am/tax_incentives

税制特例 (特別償却 / 税額控除 / 繰越欠損金 / 非課税措置) search across ~285 rows.

認証: 任意 (未認証は匿名扱い)

Query parameters:

name	type	required	description
query	string	null	no
authority	string	null	no
industry	string	null	no
target_year	integer	null	no
target_entity	string	null	no
natural_query	string	null	no
limit	integer	no	—
offset	integer	no	—

Response 200 (SearchResponse):

{
  "error": {},
  "limit": 0,
  "meta": {},
  "offset": 0,
  "results": [
    {}
  ],
  "retrieval_note": "string",
  "total": 0
}

Example:

curl -X GET "https://api.jpcite.com/v1/am/tax_incentives" \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/am/tax_rule

Single tax measure lookup with root law, rate, and applicability window.

認証: 任意 (未認証は匿名扱い)

Query parameters:

name	type	required	description
measure_name_or_id	string	yes	—
rule_type	string	null	no
as_of	string	null	no

Response 200 (TaxRuleResponse):

{
  "error": {},
  "results": [
    {}
  ],
  "total": 0
}

Example:

curl -X GET "https://api.jpcite.com/v1/am/tax_rule" \
  -H "X-API-Key: YOUR_API_KEY"

---

jpcite: Loans & Mutual Insurance

GET /v1/am/loans

Loan product query — 公庫 / 商工中金 / 自治体制度融資 with 3-axis guarantor filter.

認証: 任意 (未認証は匿名扱い)

Query parameters:

name	type	required	description
loan_kind	string	null	no
no_collateral	boolean	no	—
no_personal_guarantor	boolean	no	—
no_third_party_guarantor	boolean	no	—
max_amount_yen	integer	null	no
min_amount_yen	integer	null	no
lender_entity_id	string	null	no
name_query	string	null	no
limit	integer	no	—

Response 200 (LoanSearchResponse):

{
  "error": {},
  "limit": 10,
  "offset": 0,
  "result_count": 0,
  "results": [
    {}
  ],
  "total": 0
}

Example:

curl -X GET "https://api.jpcite.com/v1/am/loans?loan_kind=ippan" \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/am/mutual_plans

共済 / 年金 / 労災 cross-search (小規模企業共済 / iDeCo+ / DB / DC / 労災特別加入).

認証: 任意 (未認証は匿名扱い)

Query parameters:

name	type	required	description
plan_kind	string	null	no
premium_monthly_yen	integer	null	no
tax_deduction_type	string	null	no
provider_entity_id	string	null	no
name_query	string	null	no
limit	integer	no	—

Response 200 (LoanSearchResponse):

{
  "error": {},
  "limit": 10,
  "offset": 0,
  "result_count": 0,
  "results": [
    {}
  ],
  "total": 0
}

Example:

curl -X GET "https://api.jpcite.com/v1/am/mutual_plans?plan_kind=retirement_mutual" \
  -H "X-API-Key: YOUR_API_KEY"

---

jpcite: Laws & Enforcement

GET /v1/am/by_law

Programs / tax rules / certifications linked to a specific law (fuzzy name match).

認証: 任意 (未認証は匿名扱い)

Query parameters:

name	type	required	description
law_name	string	yes	—
article	string	null	no
amendment_date	string	null	no
limit	integer	no	—
offset	integer	no	—

Response 200 (LawProgramResponse):

{
  "error": {},
  "law_aliases_tried": [
    "string"
  ],
  "limit": 0,
  "meta": {},
  "offset": 0,
  "results": [
    {}
  ],
  "retrieval_note": "string",
  "total": 0
}

Example:

curl -X GET "https://api.jpcite.com/v1/am/by_law" \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/am/enforcement

Is this entity currently barred from 補助金 / 助成金 (行政処分 排除期間 check)?

認証: 任意 (未認証は匿名扱い)

Query parameters:

name	type	required	description
houjin_bangou	string	null	no
target_name	string	null	no
as_of_date	string	no	—

Response 200 (EnforcementCheckResponse):

{
  "active_exclusions": [
    {}
  ],
  "all_count": 0,
  "currently_excluded": false,
  "error": {},
  "found": false,
  "queried": {},
  "recent_history": [
    {}
  ]
}

Example:

curl -X GET "https://api.jpcite.com/v1/am/enforcement" \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/am/law_article

Exact 条文 lookup: '租税特別措置法' + '41の19' → full article text + amendment history.

認証: 任意 (未認証は匿名扱い)

Query parameters:

name	type	required	description
law_name_or_canonical_id	string	yes	—
article_number	string	yes	—

Response 200 (LawArticleResponse):

{
  "article_id": "string",
  "article_number": "string",
  "article_number_sort": 0,
  "effective_from": "string",
  "effective_until": "string",
  "error": {},
  "found": false,
  "last_amended": "string",
  "...": "..."
}

Example:

curl -X GET "https://api.jpcite.com/v1/am/law_article" \
  -H "X-API-Key: YOUR_API_KEY"

---

jpcite: Annotations / Validation / Provenance

GET /v1/am/annotations/{entity_id}

制度・法人・法令などの補足メモ、品質ラベル、検証結果を entity_id から取得する。

認証: 任意 (未認証は匿名扱い)

Path parameters:

name	type	required	description
entity_id	string	yes	jpcite の entity_id

Query parameters:

name	type	required	description
kinds	string[]	null	no
include_superseded	boolean	no	Include superseded / expired annotations (default False = currently-live only).
limit	integer	no	—

Response 200 (AnnotationsResponse):

{
  "entity_id": "string",
  "error": {},
  "filters": {},
  "limit": 0,
  "meta": {},
  "offset": 0,
  "results": [
    {}
  ],
  "retrieval_note": "string",
  "...": "..."
}

Example:

curl -X GET "https://api.jpcite.com/v1/am/annotations/<entity_id>?kinds=['string']" \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/am/provenance/fact/{fact_id}

Return source details for one fact, with entity-level sources when fact-level provenance is unavailable.

認証: 任意 (未認証は匿名扱い)

Path parameters:

name	type	required	description
fact_id	integer	yes	Fact identifier

Response 200 (ProvenanceResponse):

{
  "error": {},
  "limit": 0,
  "meta": {},
  "offset": 0,
  "results": [
    {}
  ],
  "retrieval_note": "string",
  "total": 0
}

Example:

curl -X GET "https://api.jpcite.com/v1/am/provenance/fact/<fact_id>" \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/am/provenance/{entity_id}

Return source URLs, license, role, fetched timestamp, and license summary for one entity.

認証: 任意 (未認証は匿名扱い)

Path parameters:

name	type	required	description
entity_id	string	yes	Stable entity identifier

Query parameters:

name	type	required	description
include_facts	boolean	no	If True, also return per-fact provenance when available. Default False = entity-level sources only.
fact_limit	integer	no	Max facts when include_facts=True (default 200).

Response 200 (ProvenanceResponse):

{
  "error": {},
  "limit": 0,
  "meta": {},
  "offset": 0,
  "results": [
    {}
  ],
  "retrieval_note": "string",
  "total": 0
}

Example:

curl -X GET "https://api.jpcite.com/v1/am/provenance/<entity_id>?include_facts=false" \
  -H "X-API-Key: YOUR_API_KEY"

---

POST /v1/am/validate

汎用 intake 検証。入力された applicant_data を登録済みの検証ルールに照らして評価し、 rule 単位の passed/failed/deferred を返します。

認証: 任意 (未認証は匿名扱い)

Request body (ValidationRequest):

{
  "applicant_data": {},
  "entity_id": "string",
  "scope": "intake"
}

Response 200 (ValidationResponse):

{
  "applicant_hash": "string",
  "entity_id": "string",
  "error": {},
  "results": [
    {}
  ],
  "scope": "intake",
  "summary": {},
  "total": 0
}

Example:

curl -X POST "https://api.jpcite.com/v1/am/validate" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"applicant_data": {}, "entity_id": "string", "scope": "intake"}'

---

jpcite: Static Resources & Example Profiles

GET /v1/am/example_profiles

List 5 canonical client-intake example payloads (PII-clean).

認証: 任意 (未認証は匿名扱い)

Response 200 (ExampleProfileList):

{
  "results": [
    "..."
  ],
  "total": 0
}

Example:

curl -X GET "https://api.jpcite.com/v1/am/example_profiles" \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/am/example_profiles/{profile_id}

Return one canonical client profile JSON as a complete-payload example.

認証: 任意 (未認証は匿名扱い)

Path parameters:

name	type	required	description
profile_id	string	yes	Profile id; see /v1/am/example_profiles.

Response 200 (ExampleProfileDetail):

{
  "id": "string",
  "profile": {}
}

Example:

curl -X GET "https://api.jpcite.com/v1/am/example_profiles/<profile_id>" \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/am/static

List curated jpcite taxonomies, including glossary, money types, obligations, sector terms, and exclusion-rule categories.

認証: 任意 (未認証は匿名扱い)

Response 200 (StaticResourceList):

{
  "results": [
    "..."
  ],
  "total": 0
}

Example:

curl -X GET "https://api.jpcite.com/v1/am/static" \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/am/static/{resource_id}

Load one taxonomy/lookup file. Returns full JSON content + license.

認証: 任意 (未認証は匿名扱い)

Path parameters:

name	type	required	description
resource_id	string	yes	Resource id; see /v1/am/static for the catalog.

Response 200 (StaticResourceDetail):

{
  "content": {},
  "id": "string",
  "license": "string"
}

Example:

curl -X GET "https://api.jpcite.com/v1/am/static/<resource_id>" \
  -H "X-API-Key: YOUR_API_KEY"

---

関連

• mcp-tools.md — 同じ機能を MCP tool として叩く
• exclusions.md — 排他ルールの概念
• pricing.md — 料金
• サンプル集 — 8 本の runnable サンプル (Python 4 + TypeScript 4, 各ファイル 50-150 行)