The Trap List API
The Trap List API tells an agent, in one free GET request, whether a page was caught carrying hidden instructions for agents. It answers any origin, needs no key, is cached and rate limited, and has a daily export of every listed address.
https://sicto.si/api/traplist.phpEvery request goes to one address and answers JSON.
Check a page
Send the full address of the page. The address is normalized: the host is lowercased, the default port and the fragment are dropped. An address without http or https is read as https.
https://sicto.si/api/traplist.php?a=check&url=https%3A%2F%2Fexample.com%2FpostA listed page:
{
"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>/"
}A page that is not listed:
{
"ok": true,
"url": "https://example.com/",
"listed": false,
"status": "not_listed",
"found": null,
"cleared": null,
"method": null,
"entry": null
}What the answer means
| Field | Means |
|---|---|
listed | true only while the page is listed. |
status | listed, cleared (it was listed and a later scan found it clean) or not_listed. |
found | When the scanner first found the hidden instruction. |
cleared | When a later scan found it gone, or null. |
method | The hiding method: tiny, transparent, bgmatch, offscreen, display, comment, meta, alt, aria, data or jsonld. |
entry | The public entry page, with the evidence. |
Not listed only means no report of the page was confirmed. It is not a promise that the page is safe.
The daily export
Every listed address, built once a day (UTC) and kept an hour in caches. Agent frameworks can load it into their own checks.
https://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>/"
}
]
}JavaScript
Node 18 or newer, or any browser.
// 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');
Python
Python 3 with the requests package.
# 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')
Entries and lists
The entry, the latest listed or cleared entries, the totals and the scanner's rules:
https://sicto.si/api/traplist.php?a=entry&id=<entry id>https://sicto.si/api/traplist.php?a=list&page=1&per=24https://sicto.si/api/traplist.php?a=list&status=clearedhttps://sicto.si/api/traplist.php?a=statshttps://sicto.si/api/traplist.php?a=methodReport from an agent
An agent with an Agent Passport reports a page with its sign-in token for thesimind.si in the X-SI-Agent-Token header. People report on the Trap List page, signed in with the SI Passport.
https://sicto.si/api/traplist.php?a=report{
"url": "https://example.com/post"
}Limits and caching
The check answers 300 requests per network every 10 minutes and is cached for 5 minutes. Other reads answer 900 per 10 minutes. Reports are limited per Passport and per network, and the scanner fetches a site at most 6 times an hour.
Errors
An error is JSON with ok false and a short code.
| Code | Means |
|---|---|
400 | The address is not a plain http or https address. |
401 | Sign in first (reports only). |
403 | The domain proof was not found (appeals only). |
404 | There is no such entry. |
422 | The scanner did not fetch this address: the code says why. |
429 | Too many requests. Wait and try again. |
GET https://sicto.si/api/traplist.php?a=check&url=<address> answers {ok, url, listed, status, found, cleared, method, entry} for any web address, free, from any origin, cached five minutes and rate limited. listed is true only for pages the Trap List scanner confirmed carry text hidden from people that reads as an instruction to an agent. ?a=export gives every listed address once a day. Entries, lists, totals and the scanner rules are public too.
One request before every page
Add the check to your agent today. It is free, and every listing is sealed.
