Integration & API

連携・API

既存の社内ポータルや業務システムに、
KotaMiのAI検索・ナレッジ活用機能を組み込めます。

KotaMi REST API 概要

KotaMiで提供している一部の機能をKotaMi REST APIで提供しています。

※ご利用には事前の申請が必要です。

共通仕様

API Endpoint

api.kotami.(固有番号).scm-ai.net

※固有番号は申請時にお伝えします。

プロトコル

HTTPS

レスポンスフォーマット

JSON

文字コード

UTF-8

ご利用方法

<ユーザー認証ありの設定の場合>

  1. 1. 認証トークン取得APIを実行し、有効期限付きトークンを取得します。
  2. 2. 取得したトークンをリクエストヘッダに指定して各APIを実行します。

<ユーザー認証なしの設定の場合>

  1. 1. 各APIを実行します。

※一部のAPIでは、トークンの指定が必要な場合があります。

リクエストの仕様

以下のリクエストヘッダを指定します。

ヘッダー名 必須 説明
X-Kotami-Authorization 必須 APIキー
※申請時に発行するAPIキー
X-Kotami-Token 条件付き必須 認証トークン取得APIで取得したトークン。
ユーザー認証ありの設定の場合は必須。
※認証トークン取得APIでは指定不要。
Content-Type 省略可 application/json
※リクエストボディにJSON文字列を指定する場合は必須。

パラメータの指定

パラメータの指定方法には以下3つの方法があります。詳細は各APIの仕様をご確認下さい。

指定方法 説明
パスパラメータ URIの一部(パス)として指定する方法。
例 : /v1/details/faq/25
クエリパラメータ URIのクエリストリングとして指定する方法。
例:/v1/search?nlq=%E3%83%AD%E3%82%B0%E3%82%A4%E3%83%B3%E6%96%B9%E6%B3%95%E3%81%AB%E3%81%A4%E3%81%84%E3%81%A4
リクエストボディ ボディに含める方法。
JSONを指定する場合はリクエストヘッダContent-Typeにapplication/jsonを指定して下さい。

HTTPステータスコード

KotaMi REST API は、下記のHTTPステータスコードを返します。

HTTPステータスコード 説明
200OK
リクエストが成功し、要求に応じたレスポンスが返されます。
400Bad Request
リクエストが不正です。パラメータに誤りがある場合に返されます。
401Unauthorized
認証できなかった場合に返されます。
403Forbidden
アクセスが禁止されている場合に返されます。
404Not Found
存在しないリソースへのリクエストがあった場合に返されます。
405Method Not Allowed
許可されていないメソッドを使用しようとした場合に返されます。
500Internal Server Error
サーバー内部にエラーが発生した場合に返されます。
503Service Unavailable
サービスが利用できない状態の場合に返されます。
- メンテナンス中
- アクセスが混み合っている

HTTPステータスコードが200以外のレスポンスの例

{
  "statusCode": 400,
  "message": "Bad Request"
}

この形でレスポンスがない場合もありますので、HTTPステータスコードで結果を判断して下さい。

KotaMi REST API 一覧

名称 HTTP メソッド URI 説明
認証トークン取得POST/v1/get_token認証トークンの取得をおこないます。
ユーザー情報取得GET/v1/get_user_infoユーザー情報の取得をおこないます。
各種設定情報取得GET/v1/get_settings/(type)各種設定情報を取得します。
検索GET/v1/search指定された条件で検索した結果を取得します。
閲覧数の多い情報取得GET/v1/topaccess閲覧数の多い情報を取得します。
詳細情報取得GET/v1/details/(kbn)/(key_no)指定された情報の詳細情報を取得します。
類似情報取得GET/v1/similarities/(kbn)/(document_id)指定された情報の類似情報を取得します。
フィードバックPUT/v1/feedback検索結果に対してフィードバックをおこないます。
文書アップロードPOST/v1/doc_upload文書アップロードをおこないます。

認証トークン取得

仕様

認証トークンの取得をおこないます。

HTTP メソッド

POST

URI

/v1/get_token

リクエスト

パラメータ名 型 必須 説明
リクエストボディ (JSON)
authorization string 必須 "ユーザーID:パスワード" を Base64エンコードした文字列。

リクエストヘッダContent-Typeにapplication/jsonを指定して下さい。

リクエストの例

curl -X POST -H "X-Kotami-Authorization: APIキー" -H "Content-Type: application/json" /
-d "{/"authorization/": /"dGVzdC11c2VyQHNjbS1haS5uZXQ6cGFzc3dvcmQ=/"}" /
https://api.kotami.(固有番号).scm-ai.net/v1/get_token

レスポンス

名前 説明
user_id ユーザーID。
token トークン。

レスポンスの例

{
  "user_id": "test-user@scm-ai.net",
  "token": "xxxxxxxxx"
}

ユーザー認証

仕様

ユーザー情報の取得をおこないます。
※ユーザー認証ありの設定の場合のみ呼び出し可能です。

HTTP メソッド

GET

URI

/v1/get_user_info

リクエスト

パラメータ名 型 必須 説明
なし

リクエストの例

curl -H "X-Kotami-Authorization: APIキー" -H "X-Kotami-Token: xxxxxxxxx" /
https://api.kotami.(固有番号).scm-ai.net/v1/get_user_info

レスポンス

名前 説明
user_id ユーザーID。
user_name 氏名。
user_name_kana 氏名カナ。
teams チームCDとチーム名のリスト。
user_auth_cd ユーザー権限CD。
user_auth_name ユーザー権限名。
mailaddress メールアドレス。
メールアドレス単独利用の設定でない場合は空。

レスポンスの例

{
  "user_id": "test-user@scm-ai.net",
  "user_name": "てすと ゆーざー ",
  "usre_name_kana": "テスト ユーザー",
  "teams": [
    {
      "team_cd": 1,
      "team_name": "チーム1"
    },
    {
      "team_cd": 2,
      "team_name": "チーム2"
    }
  ],
  "user_auth_cd": 1,
  "user_auth_name": "一般",
  "mailaddress": ""
}

各種設定情報取得

仕様

各種設定情報を取得します。

HTTP メソッド

GET

URI

/v1/get_settings/(type)

リクエスト

パラメータ名 型 必須 説明
パスパラメータ
type string 必須 取得する各種設定のタイプを指定。
- category : カテゴリ
- team : チーム
- auth : 権限

リクエストの例

curl -H "X-Kotami-Authorization: APIキー" -H "X-Kotami-Token: xxxxxxxxx" /
https://api.kotami.(固有番号).scm-ai.net/v1/get_settings/category

レスポンス

名前 説明
type 各種設定のタイプ。
- category : カテゴリ
- team : チーム
- auth : 権限
results 結果のリスト。

List[result]
名前 説明
id ID。
name 名前。

レスポンスの例

{
  "type": "category",
  "results": [
    {
      "id": 44,
      "name": "トラブル"
    },
    {
      "id": 45,
      "name": "サポート・保証"
    },
    {
      "id": 46,
      "name": "カスタマイズ"
    }
  ]
}

詳細情報取得

仕様

指定された情報の詳細情報を取得します。

HTTP メソッド

GET

URI

/v1/details/(kbn)/(key_no)

リクエスト

パラメータ名 型 必須 説明
パスパラメータ
kbn string 必須 詳細情報の区分。
- faq : FAQ
- doc : 文書
key_no int 必須 キーNo。
- kbnがfaq : FAQ No
- kbnがdoc : 文書 No
クエリパラメータ
answer_html string 任意 trueの場合、FAQの回答内容をHTML形式で返します。
kbnがdocの場合に指定されていた場合は無視されます。
- true : 回答内容をHTML形式で返す
- false : 回答内容をテキスト形式で返す
デフォルト値 : false

リクエストの例

curl -H "X-Kotami-Authorization: APIキー" -H "X-Kotami-Token: xxxxxxxxx" /
https://api.kotami.(固有番号).scm-ai.net/v1/details/doc/203

レスポンス

名前 説明
document_id 詳細情報固有のdocument_id。
key_no キーNo。
- kbnがfaq : FAQ No
- kbnがdoc : 文書 No
title タイトル。
- kbnがfaq : FAQの質問内容
- kbnがdoc : 文書のファイル名
contents_body コンテンツ。
- kbnがfaq :
  - answer_htmlがture : 回答内容(HTML)
  - answer_htmlがfalse : 回答内容
- kbnがdoc : 文書内のテキスト
contents_table コンテンツ(表情報)。
kbnがdocの時のみ。
表がないdocx、docx以外の文書は空。

表情報が以下のルールで文字列連結されて記述されます。
表の区切り文字 : @@@
行の区切り文字 : $$$
セルの区切り文字 : ###
※詳しくはレスポンスの例を参照して下さい。
local_link ファイルのURLまたはローカルパス。
kbnがdocの時のみ。
categories カテゴリのリスト。

List[category]
名前 説明
category_id カテゴリID。
category_name カテゴリ名。
solved_cnt 「役に立った」が押された回数。
access_cnt アクセス数。
regist_date 詳細情報の登録日。
YYYY年MM月DD日
update_date 詳細情報の更新日。
YYYY年MM月DD日

レスポンスの例

{
  "document_id": "3149bb79-503f-42d8-b630-4970c5d04065",
  "key_no": 203,
  "title": "指定害獣の駆除について.docx",
  "contents_body": "指定害獣の駆除について/n/n町で害獣に指定されている動物を見かけた場合は、担当までご連絡ください。/n指定害獣については、以下の表をご参照下さい。/n/nまた、むやみに刺激すると襲い掛かってくる可能性がございますので、発見した場合は刺激せずご連絡ください。/n/nまた、指定害獣以外にイノシシ・クマを目撃した方は速やかにご連絡をお願い致します。/n連絡先は下記の表をご参照ください。/n/n指定害獣やイノシシ・クマは食べ物を探して街に出てきます。/n野良猫などに与えている餌や残飯等のごみを目的にしているという調査結果があります。/n野生動物への餌付けはしないように、また残飯の処理は徹底してお願い致します。",
  "contents_table": "名前###体長###特徴$$$アライグマ###0.4 - 1.2 m###夜行性で雑食性$$$ハクビシン###0.6 - 1.0 m###鼻から頭に向けて白い毛$$$イタチ###0.3 - 0.5 m ###肉食中心でネズミ類を捕食$$$テン###0.3 - 0.5 m###川の近くで生息する$$$ネズミ###0.1 - 0.2 m###繁殖力が非常に強い$$$コウモリ###0.1 - 0.2 m###民家に住みつくことが多い@@@目撃動物###連絡先$$$指定害獣発見時###xxx-xxxx-xxxx$$$イノシシ・クマ発見時###yyy-yyyy-yyyy",
  "local_link": "////filexvr//docs//指定害獣の駆除について.docx",
  "categories": [
    {
      "category_id": 7,
      "category_name": "トラブル"
    }
  ],
  "solved_cnt": 5,
  "access_cnt": 23,
  "regist_date": "2021年06月10日",
  "update_date": "2021年06月17日"
}

類似情報取得

仕様

指定された情報の類似情報を取得します。
FAQの場合はFAQの類似情報、文書の場合は文書の類似情報の取得になります。

HTTP メソッド

GET

URI

/v1/similarities/(kbn)/(key_no)

リクエスト

パラメータ名 型 必須 説明
パスパラメータ
kbn string 必須 詳細情報の区分。
- faq : FAQ
- doc : 文書
key_no string 必須 キーNo。
- kbnがfaq : FAQ No
- kbnがdoc : 文書 No
クエリパラメータ
count int 任意 返す類似情報の最大件数。類似情報が指定件数なければ返す数は少なくなります。最大値は10000。
デフォルト値 : 10
return_fields string 任意 返して欲しい項目をカンマ区切りで指定。
※指定項目以外に必ず返す項目があります。詳しくはレスポンスの例をご確認下さい。
未指定の場合は下記の全ての項目を返します。
key_no,title,contents,keywords,categories,solved_cnt,access_cnt

リクエストの例

curl -H "X-Kotami-Authorization: APIキー" -H "X-Kotami-Token: xxxxxxxxx" /
https://api.kotami.(固有番号).scm-ai.net/v1/similarities/faq/279 /
-d count=3 -d return_fields=key_no,title,contents,keywords,categories,solved_cnt,access_cnt -G

レスポンス

名前 説明
similarities 類似情報のリスト。

List[similarity]
名前 説明
kbn 詳細情報の区分。
- faq : FAQ
- doc : 文書
document_id 詳細情報固有のdocument_id。
key_no キーNo。
- kbnがfaq : FAQ No
- kbnがdoc : 文書 No
title タイトル。
- kbnがfaq : FAQの質問内容
- kbnがdoc : 文書のファイル名
contents コンテンツ。
- kbnがfaq : 回答内容
- kbnがdoc : 文書内のテキスト
※先頭から200文字程度を返します。
keywords キーワードのリスト。
kbnがdocの場合は空。
categories カテゴリのリスト。

List[category]
名前 説明
category_id カテゴリID。
category_name カテゴリ名。
solved_cnt 「役に立った」が押された回数。
access_cnt アクセス数。

レスポンスの例

{
  "similarities": [
    {
      "kbn": "faq",
      "document_id": "4956zs79-235f-12d8-b879-4356c5d04065",
      "key_no": 91,
      "title": "ユーザID/パスワードを忘れました",
      "contents": "ユーザID、パスワードを再設定できます。/nHttps://***.***.***.*** から再設定してください。",
      "keywords": [
        "ログイン"
      ],
      "categories": [
        {
          "category_id": 39,
          "category_name": "手続き"
        },
        {
          "category_id": 45,
          "category_name": "サポート・保証"
        }
      ],
      "solved_cnt": 0,
      "access_cnt": 10
    },
    {
      "kbn": "faq",
      "document_id": "1023rg79-503f-42d8-s630-42314x5w04657",
      "key_no": 94,
      "title": "接続パスワードを忘れました",
      "contents": "接続パスワードが不明の場合は、以下のページからパスワードの再設定を行ってください。/nパスワードの再設定",
      "keywords": [
        "初期化"
      ],
      "categories": [
        {
          "category_id": 39,
          "category_name": "手続き"
        }
      ],
      "solved_cnt": 2,
      "access_cnt": 5
    }
  ]
}

フィードバック

仕様

検索結果に対してフィードバックをおこないます。

HTTP メソッド

PUT

URI

/v1/feedback/(kbn)/(key_no)

リクエスト

パラメータ名 型 必須 説明
パスパラメータ
kbn string 必須 詳細情報の区分。
- faq : FAQ
- doc : 文書
key_no string 必須 キーNo。
- kbnがfaq : FAQ No
- kbnがdoc : 文書 No
リクエストボディ (JSON)
feedback_status int 必須 フィードバックステータス。
- 1 : 役に立った
- 2 : 役に立たなかった
nlq string 任意 自然文検索文字列。
検索APIで検索に使用した自然文検索文字列を指定します。
※URLエンコード(パーセントエンコード)して下さい。
自然文検索に無関係なフィードバックの場合は指定不要。

リクエストヘッダContent-Typeにapplication/jsonを指定して下さい。

リクエストの例

curl -X PUT -H "X-Kotami-Authorization: APIキー" -H "X-Kotami-Token: xxxxxxxxx" -H "Content-Type: application/json" /
-d "{/"feedback_status/": 1, /"nlq/": /"%E3%83%AD%E3%82%B0%E3%82%A4%E3%83%B3%E6%96%B9%E6%B3%95%E3%81%AB%E3%81%A4%E3%81%84%E3%81%A6%E7%9F%A5%E3%82%8A%E3%81%9F%E3%81%84/"}" /
https://api.kotami.(固有番号).scm-ai.net/v1/feedback/faq/279

レスポンス

名前 説明
kbn 詳細情報の区分。
- faq : FAQ
- doc : 文書
key_no キーNo。
- kbnがfaq : FAQ No
- kbnがdoc : 文書 No
nlq 自然文検索文字列。
未指定の場合は空。
solved_cnt 「役に立った」が押された回数。
unsolved_cnt 「役に立たなかった」が押された回数。

レスポンスの例

{
  "kbn": "faq",
  "key_no": 279,
  "nlq": "ログイン方法について知りたい",
  "solved_cnt": 3,
  "unsolved_cnt": 1
}

文書アップロード

仕様

文書アップロードの依頼をおこないます。
アップロードの実行結果は管理者サイト「文書一覧」にてご確認下さい。
※システム管理者権限を有するユーザーIDで取得したトークンを指定する必要があります。

HTTP メソッド

POST

URI

/v1/doc_upload

リクエスト

パラメータ名 型 必須 説明
リクエストボディ (form-data)
upload_file file 必須 アップロードファイル。
アップロード可能なファイル拡張子は以下。
docx, xls, xlsx, pptx, pdf, html, txt
※ファイル名にはマルチバイト文字を含めないで下さい。
filename string 必須 拡張子込みのファイル名。
※URLエンコード(パーセントエンコード)して下さい。
categories string 必須 カテゴリID。カテゴリIDをカンマ区切りで指定。
auth_cds string 必須 権限CD (文書の参照範囲)。権限CDをカンマ区切りで指定。
public_flg int 必須 公開フラグ。
- 1 : 公開
- 2 : 非公開
local_link string 任意 ファイルのURLまたはローカルパス。
※URLエンコード(パーセントエンコード)して下さい。

URLの場合(例.https://xxx.yyy.zzz/xxxxx)
検索結果の詳細画面でファイルを開くことが出来るようになります。
ローカルパスの場合(¥¥xxxx¥yyy¥zzz¥xxxxx)
検索結果の詳細画面にローカルパスを表示することが出来るようになります。

リクエストの例

curl -X POST -H "X-Kotami-Authorization: APIキー" -H "X-Kotami-Token: xxxxxxxxx" /
-F "upload_file=@./doc_test.docx" -F "filename=%E3%83%86%E3%82%B9%E3%83%88%E3%83%89%E3%82%AD%E3%83%A5%E3%83%A1%E3%83%B3%E3%83%88.docx" /
-F "categories=39,45" -F "auth_cds=1,2" -F "public_flg=1" /
-F "local_link=https://xxx.yyy.zzz/%E3%83%86%E3%82%B9%E3%83%88%E3%83%89%E3%82%AD%E3%83%A5%E3%83%A1%E3%83%B3%E3%83%88.docx" /
https://api.kotami.(固有番号).scm-ai.net/v1/doc_upload

レスポンス

名前 説明
doc_no 文書 No。
filename ファイル名。
process 処理内容。
- add : 登録
- update : 更新(同じ名前のファイルがアップロード済の場合)

レスポンスの例

{
  "doc_no": 5,
  "filename": "テストドキュメント.docx",
  "process": "add"
}

変更履歴

2024.11.25 API「検索」のレスポンスおよびレスポンスの例「highlight」の記載を修正。
2024.04.15 API「フィードバック」のパラメータをdocument_idからkbn、key_noに変更。
API「認証トークン取得」のパラメータであるuser_idとpasswordをbase64エンコードして送信するように変更。
API「検索」のパラメータ「passages」にWatson Discoveryを利用しない環境での但し書きを追加。
2023.06.27 FAQ/文書に対するカテゴリ複数設定対応に伴う修正
リクエストパラメータ「category_id」を「categories」に変更。
API「文書アップロード」
リクエストパラメータ「return_fields」の指定値を「category」から「categories」に変更。
API「検索」
API「閲覧数の多い情報取得」
API「類似情報取得」
レスポンスの「category_id」、「category_name」を削除し、「categories」を追加。
API「検索」
API「閲覧数の多い情報取得」
API「詳細情報取得」
API「類似情報取得」
API「類似情報取得」のパラメータをdocument_idからkbn、key_noに変更。
2022.02.24 API「文書アップロード」のアップロード可能なファイル拡張子に「txt」を追加
2021.10.18 API「文書アップロード」を追加
2021.08.16 新規作成

KotaMiの機能を、ぜひ体験してください

まずは資料ダウンロード、または無料トライアルから。