APIリファレンス

接続した本人の下書きと写真を扱うAPIです。ベースURLはhttps://www.okibai.comです。公開・購入・有料掲載・チャットは、AI連携の権限に含まれません。

認証

OAuth 2.0の認可コードフローとS256 PKCEを使用します。scopeはlistings:draft、resourceはhttps://www.okibai.com/api/agent/mcpです。認可とトークン取得の両方に、このresourceを指定してください。

OAuthエンドポイント
パス	用途
GET /.well-known/oauth-authorization-server	認可サーバーのメタデータ。
GET /.well-known/oauth-protected-resource/api/agent/mcp	MCPの保護対象リソースのメタデータ。
POST /api/agent/oauth/register	公開クライアントの動的登録（DCR）。
GET /api/agent/oauth/authorize	オキバイのログイン・本人の同意画面へ移動。
POST /api/agent/oauth/token	認可コードの交換、リフレッシュトークンの更新。
POST /api/agent/oauth/revoke	接続の認証情報を無効化。

registerはapplication/json、tokenとrevokeはapplication/x-www-form-urlencodedで送信します。token_endpoint_auth_methodはnoneです。redirect_uriは登録したHTTPS URLまたはIP指定のHTTPループバックURLと完全に一致させます。CIMDには対応していません。

アクセストークンは最長15分、接続は最長30日です。リフレッシュトークンは更新ごとに変わります。同じリフレッシュトークンの再使用で接続が失効するため、更新は並列で行わないでください。実装例としてCLIも利用できます。

下書き・写真のエンドポイント

RESTエンドポイント
メソッドとパス	操作
GET /api/agent/catalog	有効なカテゴリID、地域コード、状態コードの取得。
POST /api/agent/drafts	非公開の下書き作成。
GET /api/agent/drafts/:id	本人の下書きの取得。
POST /api/agent/drafts/:id/images	画像の追加。画像バイト列を直接送信します。

Authorization: Bearerでアクセストークンを送信します。作成・写真追加には16〜128文字のIdempotency-Keyが必要です。英数字・ハイフン・アンダースコアを使用できます。再試行では同じキーと内容を使ってください。

Node.jsで下書きを作る例

const response = await fetch('https://www.okibai.com/api/agent/drafts', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.OKIBAI_ACCESS_TOKEN,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'chair-draft-20261014'
  },
  body: JSON.stringify({
    title: '木製の椅子',
    description: '座面に小さな傷があります。',
    price: 1500,
    category_id: 'ACTUAL_CATEGORY_ID',
    condition: 'fair',
    location: 'naha'
  })
});
const result = await response.json();
if (!response.ok) throw new Error(result.message);
console.log(result);

category_idはcatalogの結果から選択します。成功時は201と、id・status: draft・review_url・messageが返ります。写真追加はContent-Typeにimage/jpegなどを指定し、JSONや外部画像URLではなく画像のバイト列を送信します。

下書きの入力項目

下書きの主要入力項目
項目	指定方法
title（必須）	本人が確認した商品名。100文字以内。
description（必須）	傷、動作、付属品などの説明。5,000文字以内。
price（必須）	0〜100,000,000の整数。単位は日本円。
category_id（必須）	catalogに含まれる有効なカテゴリID。
condition（必須）	new / like_new / good / fair / poor / bad
location（必須）	catalogに含まれる沖縄県内の地域コード。例: naha
handover_method	hand_only / mail_only / negotiable
handover_location	受け渡しの補足。1,000文字以内。

conditionは新品、未使用に近い、目立った傷なし、やや傷あり、傷あり、全体的に状態が悪い、の順です。本人の確認なしに商品状態を推測しないでください。seller_id、status、有料掲載、審査結果などの管理項目は指定できません。

MCPクライアントの通信

POST /api/agent/mcpにJSON-RPCを送信します。Acceptにはapplication/jsonとtext/event-streamを指定します。Streamable HTTPのJSON応答を使用し、GETのSSEストリームは提供していません。GETは405を返します。

initializeとtools/listは認証なしで利用でき、tools/callにはOAuth認証が必要です。対応プロトコルは2025-11-25、2025-06-18、2025-03-26です。ツール一覧はMCPの案内をご確認ください。

利用上限

AI連携APIの主な利用上限
対象	上限
API経由の下書き作成	1アカウントにつきUTCの日付で20件、サービス全体で500件。
AI連携の操作	1アカウントにつき毎分60回、1クライアントにつき毎分300回。
画像	1枚2 MiB以下、1商品10枚まで。JPEG・PNG・WebP・GIF。
JSON本文	RESTは32 KiB、MCPは3 MiBまで。

画像の処理、接続の登録、IPからのアクセスにも制限があります。旧モバイルとの互換性を維持する直接作成経路は、上のAPI作成件数に含まれません。混雑や短時間の集中アクセスでは、上限未満でも制限される場合があります。

エラーと再試行

主なHTTPエラー
ステータス	対応
400	入力値、OAuthパラメータを確認します。
401 / 403	認証の期限、接続解除、アカウント状態、接続元を確認します。
404	本人の非公開下書きか、IDが正しいかを確認します。
409	同じ操作キーで別内容を送った場合、重複作成、処理中、公開済みなどの状態を確認します。
413 / 415 / 422	本文や画像のサイズ、送信形式、画像データを確認します。
429	時間をおいて再試行します。Retry-Afterは待機の目安です。日次上限では翌UTC日まで待つ必要があります。
503	利用できない状態です。下書きの状態を確認し、時間をおいて同じ操作キーで再試行します。

RESTエラーはerror（コード）とmessage（案内）を返します。アクセストークン、リフレッシュトークン、商品写真をログへ残さないでください。