API リファレンス
ベース URL：https://api.contaict.app
すべてのリクエスト・レスポンスは Content-Type: application/json です。
POST
/v1/token
アクセストークンを発行します。フロー A（ブラウザ JS）専用です。サイトキー（cs_）を使用してください。
リクエスト
| パラメータ | 場所 | 型 | 説明 |
|---|---|---|---|
| api_key | クエリ | string | サイトキー（cs_ で始まる） |
POST /v1/token?api_key=cs_xxxxxxxxxxxxレスポンス 200 OK
| フィールド | 型 | 説明 |
|---|---|---|
| token | string | アクセストークン。発行から 10 分間有効。同一トークンで初回判定＋5 回まで再判定が可能です（補足事項参照） |
| expires_at | string | トークンの有効期限（UTC ISO 8601 形式） |
{
"token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"expires_at": "2026-06-07T10:20:30Z"
}エラー
| ステータス | error | 説明 |
|---|---|---|
| 400 | invalid_request | api_key が空 |
| 401 | unauthorized | APIキーが無効、無効化済み、またはサイトキー以外 |
| 403 | forbidden | Origin がドメイン制限に一致しない |
| 429 | rate_limit_exceeded | 同一 IP からのトークン発行が短時間に集中（10 分間に 30 件） |
| 429 | quota_exceeded | 月次スキャン上限に達した |
POST
/v1/analyze
テキストのスパムスコアを返します。フロー A（トークン）とフロー B（Bearer）の 2 種類の認証方式に対応しています。
A トークンフロー
推奨構成：トークン取得はブラウザ JS、/v1/analyze の呼び出しはサーバーサイドから行います。ブラウザから直接 analyze を呼ぶ構成ではスコアをクライアント側で改ざんできるため、判定として機能しません。
| パラメータ | 場所 | 型 | 説明 |
|---|---|---|---|
| token | body | string | /v1/token で取得したトークン |
| text | body | string | 判定対象のテキスト（最大 3,000 文字） |
POST /v1/analyze
Content-Type: application/json
{
"token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"text": "お問い合わせ本文"
}B Bearer フロー（サーバー間）
| パラメータ | 場所 | 型 | 説明 |
|---|---|---|---|
| Authorization | header | string | Bearer sk_xxxx（サーバーキー） |
| text | body | string | 判定対象のテキスト（最大 3,000 文字） |
| client_ip | body | string | フォーム送信者の IP アドレス（必須）。不正アクセス検知に使用します。リバースプロキシ環境では REMOTE_ADDR がプロキシの IP になる場合があるため、適切なヘッダー（X-Forwarded-For 等）から取得してください。 |
POST /v1/analyze
Content-Type: application/json
Authorization: Bearer sk_xxxxxxxxxxxx
{
"text": "お問い合わせ本文",
"client_ip": "203.0.113.45"
}レスポンス 200 OK（A・B 共通）
| フィールド | 型 | 説明 |
|---|---|---|
| score | integer | 0〜100 の整数 |
| reason | string | 送信者に向けた判定理由（日本語 1〜2 文） |
{
"score": 85,
"reason": "お送りいただいた内容は、一方的なSEO対策サービスの売り込みであり、スパムと判断いたしました。"
}エラー
| ステータス | error | 説明 |
|---|---|---|
| 400 | invalid_request | token または text が空 |
| 401 | unauthorized | APIキーが無効、無効化済み、または種別違い（サーバーキー以外） |
| 403 | forbidden | IP 制限に一致しない |
| 400 | text_too_long | text が 3,000 文字を超えている |
| 404 | token_not_found | トークンが存在しない |
| 410 | token_expired | トークンの有効期限切れ（発行から 10 分超過） |
| 429 | rate_limit_exceeded | リクエストが短時間に集中、または異常なアクセスパターンを検出 |
| 429 | quota_exceeded | 月次スキャン上限に達した |
| 429 | rescan_limit_exceeded | 同一トークンでの再スキャンが上限（5 回）を超えた。新しいトークンを取得して再送信してください（フロー A のみ） |
エラーレスポンス例
{
"error": "unauthorized"
}スコアの見方
| スコア | 目安 |
|---|---|
| 0〜29 | 通常のお問い合わせ |
| 30〜69 | 判断が難しい（要確認） |
| 70〜100 | スパムの疑いが強い |
スコアの閾値判断はアプリケーション側で行ってください。contAIct はスコアのみを返します。
APIキーの種別
| 種別 | プレフィックス | 用途 | 使用できるエンドポイント |
|---|---|---|---|
| サイトキー | cs_ | ブラウザ JS に埋め込む公開キー。ドメイン制限必須。 | /v1/token |
| サーバーキー | sk_ | サーバーサイド専用。ブラウザに露出させないこと。 | /v1/analyze（Bearer） |
補足事項
月次スキャン件数のカウント定義
- フロー A：
/v1/analyzeの初回成功時に 1 件カウントします。同一トークンでの再スキャン（書き直し）は 5 回まで追加カウントされません。6 回目以降は429 rescan_limit_exceededが返るため、新しいトークンを取得してください（新規 1 件としてカウントされます）。 - フロー B：
/v1/analyzeの成功時に毎回 1 件カウントします。 - 月の起算日は、Free プランはアカウント登録日、有料プランは課金開始日（Checkout 完了日）です（暦月ではありません）。
テキストの文字数制限
最大 3,000 文字（Unicode 文字数）。漢字・かなも 1 文字としてカウントされます。上限を超えた場合は 400 text_too_long が返ります。
対応言語
判定対象テキストは日本語を前提としています。reason フィールドは常に日本語で返します。
ドメイン制限（フロー A）の仕様
- 登録ドメインと
Originヘッダーのホスト部分を照合します。 - サブドメインも許可されます（例：
example.comと設定するとsub.example.comも通ります）。 localhostや127.0.0.1も登録すれば開発環境で使用できます。- ワイルドカード（
*.example.com）は使用できません。
IP 制限（フロー B）の仕様
- 未設定の場合はすべての IP から呼び出し可能です。
- CIDR 表記（例：
203.0.113.0/24）での設定も可能です。 - 照合対象はリクエスト元サーバーの IP（
REMOTE_ADDR）です。
トークンと Origin のバインドについて
発行済みトークンは Origin に紐付きません。/v1/analyze はサーバーサイドから呼び出す設計のため、Origin ヘッダーの照合は行いません。