エージェント開発者向け

Trap List API

Trap List API は、無料の GET リクエスト1回で、ページにエージェント向けの隠れた指示が見つかったかをエージェントに伝えます。どのオリジンからも使え、キーは不要、キャッシュとレート制限があり、掲載中のすべてのアドレスの日次エクスポートがあります。

ベースアドレス
APIhttps://sicto.si/api/traplist.php

すべてのリクエストは1つのアドレスに送られ、JSON で答えます。

01

ページを確認

ページの完全なアドレスを送ってください。アドレスは正規化されます。ホストは小文字になり、既定のポートとフラグメントは外されます。http も https もないアドレスは https として読みます。

GEThttps://sicto.si/api/traplist.php?a=check&url=https%3A%2F%2Fexample.com%2Fpost

掲載中のページ:

例
{
  "ok": true,
  "url": "https://example.com/post",
  "listed": true,
  "status": "listed",
  "found": "<the time, ISO 8601 UTC>",
  "cleared": null,
  "method": "tiny",
  "entry": "https://thesimind.si/trap-list/<entry id>/"
}

掲載されていないページ:

例
{
  "ok": true,
  "url": "https://example.com/",
  "listed": false,
  "status": "not_listed",
  "found": null,
  "cleared": null,
  "method": null,
  "entry": null
}
02

応答の意味

フィールド意味
listedページが掲載中の間だけ true です。
statuslisted、cleared(掲載後のスキャンでクリーン)、not_listed のいずれかです。
foundスキャナーが隠れた指示を最初に見つけた時刻です。
cleared後のスキャンでなくなったと確認した時刻、なければ null です。
method隠し方:tiny、transparent、bgmatch、offscreen、display、comment、meta、alt、aria、data、jsonld のいずれか。
entry証拠を載せた公開エントリーページです。

掲載されていないことは、このページの報告が確認されたことがないという意味で、安全だという約束ではありません。

03

日次エクスポート

掲載中のすべてのアドレスを1日1回(UTC)作成し、キャッシュに1時間保持します。エージェントフレームワークは自分のチェックに読み込めます。

GEThttps://sicto.si/api/traplist.php?a=export
例
{
  "ok": true,
  "name": "The Trap List",
  "date": "<YYYY-MM-DD>",
  "count": 1,
  "entries": [
    {
      "id": "<entry id>",
      "url": "https://example.com/post",
      "host": "example.com",
      "found": "<the time>",
      "method": "tiny",
      "sha256": "<64 hex characters>",
      "entry": "https://thesimind.si/trap-list/<entry id>/"
    }
  ]
}
04

JavaScript

Node 18 以降、またはどのブラウザでも。

check.mjs
// Check a page before your agent acts on it. Node 18 or newer, or any browser: the API answers every origin.
const TRAP_LIST = 'https://sicto.si/api/traplist.php';
export async function isTrapped(url) {
  const r = await fetch(TRAP_LIST + '?a=check&url=' + encodeURIComponent(url));
  if (!r.ok) return null;            // unknown: rate limited or a bad address; decide for yourself
  const j = await r.json();
  return j.listed ? j : false;       // the entry: status, found, method, entry page
}
const hit = await isTrapped(process.argv[2]);
console.log(hit ? 'Listed: ' + hit.method + ', since ' + hit.found + ', ' + hit.entry : hit === false ? 'Not listed' : 'Unknown');
05

Python

Python 3 と requests パッケージ。

check.py
# Check a page before your agent acts on it. Python 3 with requests.
import sys, requests
TRAP_LIST = 'https://sicto.si/api/traplist.php'

def is_trapped(url):
    r = requests.get(TRAP_LIST, params={'a': 'check', 'url': url}, timeout=10)
    if r.status_code != 200: return None   # unknown: rate limited or a bad address
    j = r.json()
    return j if j['listed'] else False

hit = is_trapped(sys.argv[1])
print('Listed: %s, since %s, %s' % (hit['method'], hit['found'], hit['entry']) if hit else 'Not listed' if hit is False else 'Unknown')
06

エントリーと一覧

エントリー、最新の掲載または解除のエントリー、合計、スキャナーのルール:

GEThttps://sicto.si/api/traplist.php?a=entry&id=<entry id>
GEThttps://sicto.si/api/traplist.php?a=list&page=1&per=24
GEThttps://sicto.si/api/traplist.php?a=list&status=cleared
GEThttps://sicto.si/api/traplist.php?a=stats
GEThttps://sicto.si/api/traplist.php?a=method
07

エージェントからの報告

Agent Passport を持つエージェントは、thesimind.si 向けのサインイントークンを X-SI-Agent-Token ヘッダーに入れてページを報告します。人は Trap List のページで SI Passport でサインインして報告します。

POSThttps://sicto.si/api/traplist.php?a=report
リクエスト
{
  "url": "https://example.com/post"
}
08

制限とキャッシュ

確認はネットワークごとに10分あたり300リクエストを受け付け、5分間キャッシュされます。ほかの読み取りは10分あたり900です。報告は Passport とネットワークごとに制限され、スキャナーが同じサイトを取得するのは1時間に最大6回です。

09

エラー

エラーは ok が false の JSON と短いコードで返ります。

コード意味
400アドレスが通常の http か https のアドレスではありません。
401先にサインインしてください(報告のみ)。
403ドメインの証明が見つかりません(異議申し立てのみ)。
404そのエントリーはありません。
422スキャナーはこのアドレスを取得しませんでした。コードが理由を示します。
429リクエストが多すぎます。待ってから再度お試しください。
ひとことで言う API

GET https://sicto.si/api/traplist.php?a=check&url=<アドレス> は、どのウェブアドレスについても {ok, url, listed, status, found, cleared, method, entry} で答えます。無料で、どのオリジンからも使え、5分間キャッシュされ、レート制限があります。listed が true になるのは、人には見えずエージェントへの指示として読める文字があると Trap List のスキャナーが確認したページだけです。?a=export は掲載中のすべてのアドレスを1日1回提供します。エントリー、一覧、合計、スキャナーのルールも公開です。

SI MIND が $SI のためにつくりました

どのページの前にも、リクエストを1回

今日からエージェントにこの確認を加えましょう。無料で、すべての掲載は封印されます。