EchoScan API and Integration Guide
Browser Verifier collects and submits signals in the browser. A successful Submit returns an EchoScan server-issued imprint, which your backend uses to retrieve the official Report.
Building an automated evaluator? The Agent API discovery guide covers the product catalog, OpenAPI contract, and Agent Trial flow. Human Workspace users can connect the production MCP Server through OAuth 2.1 without sharing a Secret API Key.
For command-line setup, see CLI Integration.
Recommended Flow
Follow this checklist from top to bottom. For the first integration, enter one website URL in Console. EchoScan creates the Web App and default server API key together. As you select or scroll through a step, the right panel adds the execution boundary, practical checks, and the expected result for that stage.
1. Add Your Website
Open first website setup in Console. Enter the website where Browser Verifier will run, such as https://shop.example.com. Console extracts the scheme, host, and port, removes the path, query, and fragment, and saves the exact Origin, then creates the Web App and default server API key in one transaction. Copy the publishable env_... Environment ID after creation.
You can start with localhost:3000, 127.0.0.1:8000 or [::1]:3000 before your website is running. Console defaults these loopback addresses to HTTP and other domains to HTTPS; an explicit HTTP(S) scheme is preserved. The preview shows the exact Origin to save. After local integration works, open the website details in Website integrations, choose Add address, and append your deployment address on a new line while keeping the local address. Save the same configuration: its Environment ID and existing server Key stay unchanged. Adding an address does not prove integration; each website must complete a real Submit and your backend must read the Report for that same Imprint.
The existing free plan supports local integration. Actual browser Submit and server requests are metered separately under the current plan rules, with the same rules for local and deployed websites. Local and deployed data remain in the same Workspace.
2. Save The Server API Key
After first website setup succeeds, Console shows the default API key secret once. Save it immediately in your backend secret manager or environment variables. Keep it out of browser code, logs, and source control. You can later create, rotate, or revoke keys independently in API Key management without changing the Web App.
3. Install Browser Verifier
Install the Browser SDK and pass the Environment ID from step 1 to createEchoScan({ environmentId }). Console owns Allowed Origins, so browser code only needs the public Environment ID.
4. Get And Send The Imprint
Call run() when a protected action such as sign-in, registration, or payment occurs. Send the returned imprint to your own server with the business request.
5. Query The Report On Your Backend
Use the secret API key from step 2 to query the canonical Report endpoint by imprint. The official device identity and risk result come from the server Report.
6. Apply Your Business Decision
Read risk.status, risk.reasons, and risk.findings. Combine the result with account, transaction, and business context to allow, challenge, review, or deny the action. Return only the minimum business result to the browser.
Browser code and server routes may share a repository. The security boundary is where code runs: environmentId is publishable, while the API key is server-only.
Integration succeeds when the browser completes a real Submit and your backend retrieves a valid Report for that same imprint. SUSPICIOUS or DECEPTIVE can be successfully retrieved reports. Handle collection or query failure separately from the risk status.
Get And Send The Imprint
Direct mode requires environmentId in the fixed env_<32 lowercase hex> format. Browser Verifier sends it with fingerprint submission and the correlated public-key request. It does not accept a Workspace ID and does not place an API key or authorization secret in the browser.
npm install @echoscan/browser-verifier@3.0.5
import { createEchoScan } from '@echoscan/browser-verifier'
const sdk = createEchoScan({
environmentId: 'env_0123456789abcdef0123456789abcdef'
})
const { imprint } = await sdk.run()
Choose npm or CDN integration. For CDN integration, choose exactly one of the independent ESM and UMD blocks below. Your backend implements the example lookup path.
CDN: ESM (choose one)
<script type="module">
import { createEchoScan } from 'https://cdn.echoscan.org/v1/echoscan.esm.js'
const sdk = createEchoScan({
environmentId: 'env_0123456789abcdef0123456789abcdef'
})
try {
const { imprint } = await sdk.run()
const response = await fetch('/api/echoscan/report', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ imprint })
})
if (!response.ok) throw new Error('Report lookup failed')
// Continue with the minimal business result from your backend.
} catch {
// Collection or lookup failed: stop this action; offer a controlled retry.
} finally {
sdk.dispose()
}
</script>
CDN: UMD (choose one)
<script src="https://cdn.echoscan.org/v1/echoscan.umd.js"></script>
<script>
(async () => {
const sdk = window.EchoScan.createEchoScan({
environmentId: 'env_0123456789abcdef0123456789abcdef'
})
try {
const { imprint } = await sdk.run()
const response = await fetch('/api/echoscan/report', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ imprint })
})
if (!response.ok) throw new Error('Report lookup failed')
// Continue with the minimal business result from your backend.
} catch {
// Collection or lookup failed: stop this action; offer a controlled retry.
} finally {
sdk.dispose()
}
})()
</script>
run() returns imprint and an optional minimal diagnostic receipt. New imprints use imp_<32 lowercase hex>.
Allowed Origins are exact browser deployment protection, not secret authentication. Register complete http or https origins such as https://staging.example.com:8443 or http://localhost:3000. Matching preserves scheme and port and lowercases the host. Paths, query strings, fragments, user info, wildcards (including *.example.com), bare domains, null, file://, and extension origins are rejected. An empty allowlist or a missing Origin header rejects every public Submit.
Browser Verifier Initialization Input
| Parameter | Meaning |
|---|---|
environmentId |
Publishable Browser Environment ID. The server resolves it to the trusted Workspace and validates Allowed Origins |
Run output. imprint is the server-issued report identifier returned by a successful run(); send it with the protected business action.
Diagnose One Browser Verifier Run
These examples target Browser Verifier 3.0.5. Use the same version in the browser and its installed assets.
getLastRunTrace() and detailed error-class exports from published 2.x are removed in this major. Keep SDK_VERSION, EchoScanError.category and the minimal diagnostic receipt for support. For the direct profile, not_sent means no correlated API request began; unconfirmed means an ID was sent without a matching receipt; received means a durable server receipt was observed for its named API operation. Unconfirmed requests may have no server record. An ID is never authorization to read diagnostics.
import { createEchoScan, SDK_VERSION, EchoScanError } from '@echoscan/browser-verifier'
const sdk = createEchoScan({ environmentId: 'env_0123456789abcdef0123456789abcdef' })
try {
const { imprint } = await sdk.run()
// Send imprint to your server; only the server queries the business Report.
await fetch('/api/echoscan/report', {
method: 'POST', headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ imprint, sdkVersion: SDK_VERSION })
})
} catch (error) {
const category = error instanceof EchoScanError ? error.category : 'integration_failed'
const support = { sdkVersion: SDK_VERSION, category,
diagnostic: error instanceof EchoScanError ? error.diagnostic : null }
// Provide only this safe summary to support. No automatic diagnostic upload.
void support
} finally {
sdk.dispose()
}
Support staff can use the minimal diagnostic receipt to correlate recorded requests and formal Reports within their authorized scope. The receipt does not contain a complete browser session, and an unconfirmed request may have no server record.
Keep Imprint in the controlled business flow and the full Report on your server. Do not copy raw errors, fingerprints, IPs, keys, cookies or parameterized URLs. A technical failure is not a risk verdict, and missing information alone does not establish risk.
A failed Submit or failed Report query is a technical failure, not a risk verdict. Keep that action pending or denied under your business rules. Only recoverable technical failures may use bounded retries; do not keep scanning until PASS. A successfully retrieved SUSPICIOUS or DECEPTIVE Report is evaluated data. Choose allow, challenge, review or deny using your own business context. Your application implements any challenge; your backend still owns eligibility, idempotency and duplicate issuance prevention.
Send Imprint To The Server
Send the imprint with the protected business action using the shape that fits your API.
await fetch('/api/your-action', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
...yourActionPayload,
echoscanImprint: imprint
})
})
await fetch('/api/your-action', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-EchoScan-Imprint': imprint
},
body: JSON.stringify(yourActionPayload)
})
await fetch('/api/echoscan/report', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ imprint })
})
/api/echoscan/report above is an example path owned by the integrator, not an EchoScan endpoint.
Minimal Complete Default Integration
Use Node.js 22.22 or a supported 22.x runtime, pnpm, and the npm-published Browser Verifier. The following is a standalone demo project. For an existing project, preserve its configuration and merge only the required code. First add http://localhost:3000 in Console. Set the actual Environment ID in .env.local and the Secret in .env.server; keep both files out of source control.
package.json
{
"private": true,
"type": "module",
"scripts": {
"dev": "vite --host 127.0.0.1 --port 3000 --strictPort",
"server": "node --env-file=.env.server server.mjs"
},
"dependencies": {
"@echoscan/browser-verifier": "3.0.5",
"ajv": "8.20.0",
"ajv-formats": "3.0.1"
},
"devDependencies": {
"vite": "7.3.6"
}
}
index.html
<button id="verify" type="button">Verify visit</button>
<p id="result" role="status"></p>
<script type="module" src="/main.js"></script>
main.js
import { createEchoScan } from '@echoscan/browser-verifier'
const sdk = createEchoScan({ environmentId: import.meta.env.VITE_ECHOSCAN_ENVIRONMENT_ID })
const button = document.querySelector('#verify')
const result = document.querySelector('#result')
button.addEventListener('click', async () => {
button.disabled = true
result.textContent = 'Checking…'
try {
const { imprint } = await sdk.run()
const response = await fetch('/api/echoscan/report', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ imprint })
})
if (!response.ok) throw new Error('Report lookup failed')
const { decision } = await response.json()
if (!['allow', 'challenge'].includes(decision)) throw new Error('Invalid decision')
result.textContent = decision === 'allow' ? 'Report retrieved: allow' : 'Report retrieved: additional verification'
} catch {
result.textContent = 'Verification unavailable. Retry when ready.'
} finally {
button.disabled = false
}
})
window.addEventListener('pagehide', () => sdk.dispose(), { once: true })
vite.config.js
export default {
server: { proxy: { '/api/echoscan/report': 'http://127.0.0.1:3001' } }
}
server.mjs
import { createServer } from 'node:http'
import { readFile } from 'node:fs/promises'
import Ajv2020 from 'ajv/dist/2020.js'
import addFormats from 'ajv-formats'
const apiKey = process.env.ECHOSCAN_API_KEY
if (!apiKey) throw new Error('ECHOSCAN_API_KEY is required')
const contract = JSON.parse(await readFile(new URL('./openapi.json', import.meta.url), 'utf8'))
const ajv = new Ajv2020()
addFormats(ajv)
const validateReport = ajv.compile(contract.components.schemas['public.report.schema.json'])
createServer(async (request, response) => {
const send = (status, body) => {
response.writeHead(status, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' })
response.end(JSON.stringify(body))
}
if (request.method !== 'POST' || request.url !== '/api/echoscan/report') {
send(404, { error: 'not_found' })
return
}
let imprint
try {
let body = ''
for await (const chunk of request) {
body += chunk
if (Buffer.byteLength(body) > 2048) throw new Error('Request too large')
}
imprint = JSON.parse(body).imprint
if (typeof imprint !== 'string' || !/^imp_[0-9a-f]{32}$/.test(imprint)) throw new Error('Invalid imprint')
} catch {
send(400, { error: 'invalid_request' })
return
}
try {
const upstream = await fetch(`https://api.echoscan.org/api/v1/fingerprint/report/${imprint}`, {
headers: { 'X-API-Key': apiKey, Accept: 'application/json' },
signal: AbortSignal.timeout(5000)
})
if (!upstream.ok) {
// HTTP failures never enter the risk decision branch.
send(503, { error: 'verification_unavailable' })
return
}
const report = await upstream.json()
if (!validateReport(report) || report.imprint !== imprint) {
send(503, { error: 'verification_unavailable' })
return
}
if (report.risk.status === 'UNAVAILABLE') {
send(503, { error: 'verification_unavailable' })
return
}
const decision = report.risk.status === 'PASS' ? 'allow' : 'challenge'
send(200, { decision })
} catch {
send(503, { error: 'verification_unavailable' })
}
}).listen(3001, '127.0.0.1')
.gitignore
.env.local
.env.server
node_modules/
dist/
.env.local
VITE_ECHOSCAN_ENVIRONMENT_ID=env_0123456789abcdef0123456789abcdef
.env.server
ECHOSCAN_API_KEY=<your_server_secret_key>
pnpm install
curl --fail --output openapi.json https://echoscan.org/openapi.json
pnpm server
# In a second terminal:
pnpm dev
Open http://localhost:3000 after starting both processes and click Verify visit. After a real browser Submit, the backend queries the same Imprint and validates the result against the downloaded official OpenAPI Report Schema. Success returns only allow or challenge; failure displays unavailable. This example policy does not perform sign-in, payment, or resource delivery. Preserve your own authentication, authorization, and additional verification policy when integrating it. Download openapi.json in the explicit setup step; normal execution does not fetch remote schemas.
Report Integration (Lite and Pro)
Lite and Pro use the same base Report structure. The common query below also applies after an upgrade; read the Secret API Key only in server-executed code.
Query Report
GET https://api.echoscan.org/api/v1/fingerprint/report/{imprint}
X-API-Key: <your_lite_key>
Accept: application/json
Node.js, Go, Python, and Rust SDKs wrap the same server HTTP API.
SDK Version Scope
The server SDK installation and call examples on this page pin 0.2.4, which uses the current Report, History, and Account Map routes. In 0.2.3, the Pro method-set clients also use these public routes and can be used with an authorized Lite or Pro key. Its Lite clients still call the retired /api/v1/fingerprint/report-lite/{imprint} route and do not work with the current base Report API. If retaining 0.2.3, use the Pro method-set client for these operations, or upgrade to 0.2.4; client names do not determine your plan.
Public package installation, import/build, and synthetic HTTP examples have been checked. This does not establish production integration for every language SDK.
npm install @echoscan/echoscan@0.2.4
import { createLiteClient } from '@echoscan/echoscan'
const echoscan = createLiteClient({
apiKey: process.env.ECHOSCAN_API_KEY
})
const report = await echoscan.getReport(imprint)
console.log(report.risk.status)
go get github.com/echoscan/echoscan-go@v0.2.4
package main
import (
"context"
"log"
"os"
echoscan "github.com/echoscan/echoscan-go"
)
func main() {
imprint := "imp_0123456789abcdef0123456789abcdef"
echoscanClient, err := echoscan.NewLiteClient(os.Getenv("ECHOSCAN_API_KEY"))
if err != nil {
log.Fatal(err)
}
report, err := echoscanClient.GetReport(context.Background(), imprint)
if err != nil {
log.Fatal(err)
}
log.Printf("risk_status=%v", report["risk"].(map[string]any)["status"])
}
pip install echoscan==0.2.4
import os
from echoscan import EchoScanLiteClient
imprint = "imp_0123456789abcdef0123456789abcdef"
echoscan_client = EchoScanLiteClient(os.environ["ECHOSCAN_API_KEY"])
report = echoscan_client.get_report(imprint)
print(report["risk"]["status"])
[dependencies]
echoscan = "=0.2.4"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
use std::env;
use echoscan::LiteClient;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let imprint = "imp_0123456789abcdef0123456789abcdef";
let api_key = env::var("ECHOSCAN_API_KEY")?;
let echoscan = LiteClient::new(&api_key)?;
let report = echoscan.get_report(imprint).await?;
println!("{}", report["risk"]["status"]);
Ok(())
}
Request metering. Browser Submit is recorded for its Browser Environment. Applicable metered API Key and MCP requests share the Workspace server allowance. Metered server routes include Report GET, Account Map POST, History GET, and other applicable protected API calls. A call reaching usage tracking counts once, including an application error or a repeated query of the same Imprint. Requests rejected before tracking by authentication, rate limits, or quota checks do not enter that server count. Browser retries recognized as duplicates by the same submission ID do not consume another Submit unit.
Lite uses a UTC calendar month. Pro Beta and paid Pro use their active entitlement or subscription period. Creating another key does not add quota. Browser Submit and server calls are separate counts, not unique visitor counts. Check Console for the current limits and period.
Canonical Report
Lite and Pro use the same base Report structure; Enterprise keys also use this canonical contract. Optional fields can be omitted when signals or applicable data are unavailable.
| Report content | What you can learn |
|---|---|
| Identifier and time | Which detection this Report belongs to, and when it was generated. |
| Device continuity | Workspace-scoped Device ID, seen-before state, total visits, and available first and previous seen times. |
| Current-visit risk | Overall risk status, product reasons, and the severity of each finding. |
| Browser and operating system | Identified names, available versions, and their risk statuses. |
| Network | Available egress IP, country or region, proxy results, network consistency, and other context. |
| Recent activity | When available, event, distinct IP, and distinct country counts for 5 minutes, 1 hour, and 24 hours. |
A first device record has null for the previous seen time. Preserve the meanings of 0, false, empty collections, and null; handle missing fields according to the public contract. The base continuity summary and recent activity are separate from a History API query for a specified time range.
Normal example:
{
"schema_version": "1.0",
"imprint": "imp_0123456789abcdef0123456789abcdef",
"created_at": "2026-07-28T01:30:00Z",
"device": {
"id": "did_A12B34C56D78",
"seen_before": false,
"access_count": 1,
"previous_seen_at": null
},
"risk": {
"status": "PASS",
"reasons": [],
"findings": []
},
"browser": {
"status": "PASS",
"name": "Google Chrome",
"version": "145"
},
"operating_system": {
"status": "PASS",
"name": "Windows",
"version": "11"
},
"network": {
"status": "PASS",
"observed_ip": "203.0.113.10",
"country_code": "JP",
"ip_consistency": "MATCH",
"proxy_detected": false
},
"activity": {
"5m": {
"events": 1,
"distinct_ips": 1,
"distinct_countries": 1
},
"1h": {
"events": 1,
"distinct_ips": 1,
"distinct_countries": 1
},
"24h": {
"events": 1,
"distinct_ips": 1,
"distinct_countries": 1
}
}
}
Suspicious example:
{
"schema_version": "1.0",
"imprint": "imp_11111111111111111111111111111111",
"created_at": "2026-07-28T01:35:00Z",
"device": {
"id": "did_C98D76E54F32",
"seen_before": false,
"access_count": 1,
"previous_seen_at": null
},
"risk": {
"status": "SUSPICIOUS",
"reasons": [
"SIGNAL_DATA_INCOMPLETE"
],
"findings": [
{
"reason": "SIGNAL_DATA_INCOMPLETE",
"status": "SUSPICIOUS"
}
]
},
"browser": {
"status": "SUSPICIOUS",
"name": "Google Chrome",
"version": "145"
},
"operating_system": {
"status": "PASS",
"name": "Windows",
"version": "11"
},
"network": {
"status": "PASS",
"observed_ip": "198.51.100.20",
"country_code": "US",
"ip_consistency": "MATCH",
"proxy_detected": false
},
"activity": {
"5m": {
"events": 1,
"distinct_ips": 1,
"distinct_countries": 1
},
"1h": {
"events": 1,
"distinct_ips": 1,
"distinct_countries": 1
},
"24h": {
"events": 1,
"distinct_ips": 1,
"distinct_countries": 1
}
}
}
Returning-device example:
{
"schema_version": "1.0",
"imprint": "imp_22222222222222222222222222222222",
"created_at": "2026-07-28T02:00:00Z",
"device": {
"id": "did_A12B34C56D78",
"seen_before": true,
"access_count": 8,
"first_seen_at": "2026-06-10T03:20:00Z",
"previous_seen_at": "2026-07-27T08:40:00Z"
},
"risk": {
"status": "PASS",
"reasons": [],
"findings": []
},
"browser": {
"status": "PASS",
"name": "Google Chrome",
"version": "145"
},
"operating_system": {
"status": "PASS",
"name": "Windows",
"version": "11"
},
"network": {
"status": "PASS",
"observed_ip": "203.0.113.10",
"country_code": "JP",
"ip_consistency": "MATCH",
"proxy_detected": false
},
"activity": {
"5m": {
"events": 1,
"distinct_ips": 1,
"distinct_countries": 1
},
"1h": {
"events": 2,
"distinct_ips": 1,
"distinct_countries": 1
},
"24h": {
"events": 8,
"distinct_ips": 2,
"distinct_countries": 1
}
}
}
Field Reference
| Field | Availability | Meaning |
|---|---|---|
schema_version |
Always returned. | Public data-structure version used by this report. |
imprint |
Always returned. | Unique identifier for this detection report. |
created_at |
Always returned in UTC. | Time this report was generated. |
device |
Always returned. | Identification result and visit history for this device in the current Workspace. |
device.id |
Always returned. | Device ID within the current Workspace. |
device.seen_before |
Always returned. | Whether this device was seen before the current visit. |
device.access_count |
Always returned and includes the current visit. | Total visits for this device in the current Workspace, including this visit. |
risk |
Always returned. | Overall risk result for this visit. |
risk.status |
Always returned. | Overall risk level for this visit. |
browser |
Always returned. | Browser information identified by EchoScan and its risk status. |
browser.status |
Always returned. | Risk level for the browser identity dimension of this visit. |
browser.name |
Returned when available. | Browser name identified by EchoScan. |
browser.version |
Returned when available. | Browser version identified by EchoScan. |
operating_system |
Always returned. | Operating-system information identified by EchoScan and its risk status. |
operating_system.status |
Always returned. | Risk level for the operating-system environment dimension of this visit. |
operating_system.name |
Returned when available. | Operating-system name identified by EchoScan. |
operating_system.version |
Returned when available. | Operating-system version identified by EchoScan. |
network |
Always returned. | Network information and risk status for this visit. |
network.status |
Always returned. | Risk level for the network dimension of this visit. |
network.observed_ip |
Returned when available. | Public egress IP used when this request reached EchoScan. |
network.country_code |
Returned when available. | Country or region code associated with the request egress IP. |
Finite Values
| Field | Value | Title | Meaning | Example customer action |
|---|---|---|---|---|
device.seen_before |
true |
Previously seen | EchoScan had seen this device before the current visit. | |
device.seen_before |
false |
First record | This visit is the first record for the device. | |
risk.status |
PASS |
No risk currently needs attention | Continue processing this visit under the normal business rules. | Continue the existing business flow. |
risk.status |
SUSPICIOUS |
Risk needs attention | Evaluate the result together with the account and business context. | Add verification, rate limits, or manual review. |
risk.status |
DECEPTIVE |
Clear high-risk indicators are present | The visit shows clear signs of disguise, automation, or a high-risk network. | Apply stricter verification, restrictions, or manual review. |
risk.status |
UNAVAILABLE |
Assessment unavailable | Critical data is insufficient to complete the assessment. | Show verification unavailable; keep the action pending or deny it according to your business policy. |
browser.status |
PASS |
Browser information looks normal | No browser-information issue currently needs attention. | |
browser.status |
SUSPICIOUS |
Browser information needs attention | The browser information contains an issue that needs attention. | |
browser.status |
DECEPTIVE |
Browser information is high risk | The browser information shows clear signs of disguise. | |
operating_system.status |
PASS |
Operating-system information looks normal | No operating-system information issue currently needs attention. | |
operating_system.status |
SUSPICIOUS |
Operating-system information needs attention | The operating-system information contains an issue that needs attention. | |
operating_system.status |
DECEPTIVE |
Operating-system information is high risk | The operating-system information shows clear signs of disguise. | |
network.status |
PASS |
Network information looks normal | No network-information issue currently needs attention. | |
network.status |
SUSPICIOUS |
Network information needs attention | The network information contains a risk that needs attention. | |
network.status |
DECEPTIVE |
Network information is high risk | The network information shows clear high-risk indicators. |
History and Account Map (Lite / Pro)
Lite and Pro both support History and optional Account Map, including new links and existing snapshot reads. Both use the same server-issued Imprint, server-only Secret boundary, endpoint, and base Report. Pro provides higher request allowances, rate limits, and Browser Environment capacity.
Query Report
The base Report query is shown once in Report Integration. The SDK examples below also demonstrate the separate History operation.
History queries are available in Lite and Pro. The SDK Lite/Pro names describe method sets, not separate Report structures or plan requirements. Use a client exposing the required methods with your active Workspace key:
GET https://api.echoscan.org/api/v1/fingerprint/imprint/{imprint}/history?days=7&recent=20
X-API-Key: <your_server_key>
Accept: application/json
GET https://api.echoscan.org/api/v1/fingerprint/imprint/{imprint}/history?from=2026-03-01&to=2026-03-18&recent=20
X-API-Key: <your_server_key>
Accept: application/json
npm install @echoscan/echoscan@0.2.4
import { createProClient } from '@echoscan/echoscan'
const echoscan = createProClient({
apiKey: process.env.ECHOSCAN_API_KEY
})
const report = await echoscan.getReport(imprint)
console.log(report.risk.status, report.risk.reasons)
const history = await echoscan.getHistory(imprint, { days: 7 })
go get github.com/echoscan/echoscan-go@v0.2.4
package main
import (
"context"
"log"
"os"
echoscan "github.com/echoscan/echoscan-go"
)
func main() {
imprint := "imp_0123456789abcdef0123456789abcdef"
days := 7
echoscanClient, err := echoscan.NewProClient(os.Getenv("ECHOSCAN_API_KEY"))
if err != nil {
log.Fatal(err)
}
report, err := echoscanClient.GetReport(context.Background(), imprint)
if err != nil {
log.Fatal(err)
}
history, err := echoscanClient.GetHistory(context.Background(), imprint, echoscan.HistoryQuery{Days: &days})
if err != nil {
log.Fatal(err)
}
log.Printf("risk_status=%v", report["risk"].(map[string]any)["status"])
_ = history
}
pip install echoscan==0.2.4
import os
from echoscan import EchoScanProClient
imprint = "imp_0123456789abcdef0123456789abcdef"
echoscan_client = EchoScanProClient(os.environ["ECHOSCAN_API_KEY"])
report = echoscan_client.get_report(imprint)
history = echoscan_client.get_history(imprint, days=7)
print(report["risk"]["status"])
[dependencies]
echoscan = "=0.2.4"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
use std::env;
use echoscan::{HistoryQuery, ProClient};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let imprint = "imp_0123456789abcdef0123456789abcdef";
let api_key = env::var("ECHOSCAN_API_KEY")?;
let echoscan = ProClient::new(&api_key)?;
let report = echoscan.get_report(imprint).await?;
let _history = echoscan.get_history(imprint, HistoryQuery::Days { days: 7, recent: None }).await?;
println!("{}", report["risk"]["status"]);
Ok(())
}
Optional: Enable Account Map (Lite / Pro)
Use Account Map when you need to answer questions such as:
- How many accounts are associated with this device?
- How many devices has this account used?
- Have this account and device appeared together before?
- Is one device receiving many new account relationships in a short period?
- Could the pattern indicate account sharing or account takeover?
Lite and Pro both support creating Account Map links. Pass the stable internal user ID with the server-side Report query.
Node.js
const report = await pro.getReport(imprint, {
accountRef: currentUser.id
})
Go
report, err := pro.GetReportWithOptions(
context.Background(),
imprint,
echoscan.ReportOptions{AccountRef: currentUser.ID},
)
if err != nil {
return err
}
Python
report = pro.get_report(
imprint,
account_ref=current_user.id,
)
Rust
use echoscan::ReportOptions;
let report = pro
.get_report_with_options(
imprint,
ReportOptions { account_ref: Some(current_user.id.clone()) },
)
.await?;
Account Map is completely optional. Use a stable, non-sensitive, immutable internal user primary key as accountRef. Do not send an email address, phone number, real name, nickname, or mutable username. Account relationships are isolated by Workspace.
A Report GET can return an existing snapshot for that Imprint without a new accountRef. Creating an Account Map link and reading an existing snapshot are separate operations. Returning to Lite does not by itself make an existing snapshot disappear. Account Map v1 does not automatically change risk.status; interpret relationship signals with your own business rules.
Consistency for concurrent or delayed linking
Account Map statistics include only relationships that have completed and are visible when the response is generated.
Concurrent POST responses cannot anticipate other relationships that have not completed yet.
After all concurrent or delayed links complete, later GET responses recompute historical statistics in server event order (recorded_at, then event_id).
An earlier event keeps its historical boundary, while a later event includes visible relationships at or before its boundary.
Account Map response example:
{
"account_map": {
"account_seen_before": true,
"relationship_seen_before": false,
"accounts_on_device": 7,
"devices_on_account": 2,
"accounts_first_seen_on_device_1h": 4
}
}
| Field | Meaning |
|---|---|
account_seen_before |
Whether this account appeared on any device in the current Workspace before this visit. |
relationship_seen_before |
Whether this exact account and current device appeared together before this visit. |
accounts_on_device |
Number of distinct accounts associated with the current device, including the current relationship. |
devices_on_account |
Number of distinct devices associated with the current account, including the current relationship. |
accounts_first_seen_on_device_1h |
Number of accounts whose first relationship with the current device occurred during the previous hour. When accountRef is sent after registration, this can approximate new registrations. When sent only at sign-in, it counts accounts first observed by EchoScan and does not prove that the account was just created. |
Report Fields And Reasons
The canonical Report always uses this field model. Optional values follow the public contract and available signals or applicable data. account_map can contain an existing snapshot; it is not guaranteed on every request.
{
"schema_version": "1.0",
"imprint": "imp_0123456789abcdef0123456789abcdef",
"created_at": "2026-07-28T01:30:00Z",
"device": {
"id": "did_A12B34C56D78",
"seen_before": true,
"access_count": 42,
"first_seen_at": "2026-06-10T03:20:00Z",
"previous_seen_at": "2026-07-27T08:40:00Z"
},
"risk": {
"status": "DECEPTIVE",
"reasons": [
"BROWSER_VERSION_MISMATCH",
"PROXY_DETECTED",
"NETWORK_INCONSISTENT"
],
"findings": [
{
"reason": "BROWSER_VERSION_MISMATCH",
"status": "DECEPTIVE"
},
{
"reason": "PROXY_DETECTED",
"status": "DECEPTIVE"
},
{
"reason": "NETWORK_INCONSISTENT",
"status": "DECEPTIVE"
}
]
},
"browser": {
"status": "DECEPTIVE",
"name": "Google Chrome",
"version": "145"
},
"operating_system": {
"status": "PASS",
"name": "Windows",
"version": "11"
},
"network": {
"status": "DECEPTIVE",
"observed_ip": "198.23.233.104",
"country_code": "US",
"alternate_ip": "126.234.173.23",
"ip_consistency": "MISMATCH",
"proxy_detected": true,
"location": {
"country_name": "United States",
"region": "Illinois",
"city": "Elk Grove Village",
"timezone": "America/Chicago"
},
"provider": "Example Hosting Provider",
"connection_type": "proxy",
"asn": 36352
},
"activity": {
"5m": {
"events": 2,
"distinct_ips": 1,
"distinct_countries": 1
},
"1h": {
"events": 8,
"distinct_ips": 2,
"distinct_countries": 2
},
"24h": {
"events": 21,
"distinct_ips": 4,
"distinct_countries": 3
}
}
}
A passing report still serializes explicit empty reasons and findings arrays:
{
"risk": {
"status": "PASS",
"reasons": [],
"findings": []
}
}
The tables below provide the return rule for every field and the product meaning of each finite machine value.
Product Reasons
| Reason | Meaning |
|---|---|
BROWSER_VERSION_MISMATCH |
Browser version information is inconsistent |
OS_ENVIRONMENT_MISMATCH |
Operating-system environment information is inconsistent |
AUTOMATION_DETECTED |
Automated access was detected |
ENVIRONMENT_INCONSISTENT |
Current device environment information is inconsistent |
PROXY_DETECTED |
Proxy or VPN risk was detected |
HOSTING_NETWORK_DETECTED |
Access originated from a hosting service or datacenter network |
NETWORK_INCONSISTENT |
Network identity information is inconsistent |
LOCATION_INCONSISTENT |
Location-related information is inconsistent |
SIGNAL_DATA_INCOMPLETE |
Critical data for this detection is incomplete |
A reason names the risk category. Overall severity is expressed by risk.status; each risk.findings entry also carries the severity contributed by that reason.
Canonical Additional Fields
| Field | Availability | Meaning |
|---|---|---|
device.first_seen_at |
Returned when available, in UTC. | Time this Workspace first saw the device. |
device.previous_seen_at |
Always returned; null on the first visit. |
Most recent time this device was seen before the current visit. |
risk.reasons |
Always returned. Returns an empty array [] for PASS. |
Product-level reason categories associated with this risk result. |
risk.findings |
Always returned. Returns an empty array [] for PASS. |
Reason and severity pairs used to produce the report verdict. |
network.alternate_ip |
Returned when available. | Client public IP detected by EchoScan. |
network.ip_consistency |
Always returned. | Consistency result between the client public IP and request egress IP. |
network.proxy_detected |
Returned when available. | Whether proxy or VPN risk was detected. |
network.location |
Returned when available. | Network location information associated with the request egress IP. |
network.location.country_name |
Returned when available with network.location. |
Country or region name associated with the request egress IP. |
network.location.region |
Returned when available with network.location. |
Region or first-level administrative area associated with the request egress IP. |
network.location.city |
Returned when available with network.location. |
City associated with the request egress IP. |
network.location.timezone |
Returned when available with network.location. |
Time zone associated with the network location of the request egress IP. |
network.provider |
Returned when available. | Network organization or service provider associated with the request egress IP. |
network.connection_type |
Returned when available. | Network type associated with the request egress IP. |
network.asn |
Returned when available. | Autonomous system number associated with the request egress IP. |
activity |
Returned when available. | Summary of recent visit activity for the current device. |
activity.5m |
Always returned with activity and includes this visit. |
Visit activity for the current device during the last 5 minutes. |
activity.5m.events |
Always returned with its time window. | Number of visits in this time window. |
activity.5m.distinct_ips |
Always returned with its time window. | Number of distinct IP addresses in this time window. |
activity.5m.distinct_countries |
Always returned with its time window. | Number of distinct countries or regions in this time window. |
activity.1h |
Always returned with activity and includes this visit. |
Visit activity for the current device during the last hour. |
activity.1h.events |
Always returned with its time window. | Number of visits in this time window. |
activity.1h.distinct_ips |
Always returned with its time window. | Number of distinct IP addresses in this time window. |
activity.1h.distinct_countries |
Always returned with its time window. | Number of distinct countries or regions in this time window. |
activity.24h |
Always returned with activity and includes this visit. |
Visit activity for the current device during the last 24 hours. |
activity.24h.events |
Always returned with its time window. | Number of visits in this time window. |
activity.24h.distinct_ips |
Always returned with its time window. | Number of distinct IP addresses in this time window. |
activity.24h.distinct_countries |
Always returned with its time window. | Number of distinct countries or regions in this time window. |
account_map |
Optional; returned when an existing snapshot is available or a link operation returns one. | Workspace-isolated account-relationship snapshot for this Imprint. |
Network Finite Values
| Field | Value | Title | Meaning | Example customer action |
|---|---|---|---|---|
network.ip_consistency |
MATCH |
IP information matches | Network IP information is consistent. | |
network.ip_consistency |
MISMATCH |
IP information differs | Network IP information is inconsistent. | |
network.ip_consistency |
UNKNOWN |
No clear result | No clear IP consistency result is available. | |
network.proxy_detected |
true |
Risk detected | Proxy or VPN risk was detected. | |
network.proxy_detected |
false |
No risk detected | No proxy or VPN risk was detected. | |
network.connection_type |
residential |
Residential | Residential broadband network. | |
network.connection_type |
mobile |
Mobile | Mobile carrier network. | |
network.connection_type |
corporate |
Corporate | Business or institutional network. | |
network.connection_type |
hosting |
Hosting | Cloud, server-hosting, or datacenter network. | |
network.connection_type |
proxy |
Proxy | Proxy, VPN, or similar relay network. | |
network.connection_type |
unknown |
Unclassified | The network has not been assigned a specific type. |
History
History queries a specified time range and is available in both Lite and Pro, separate from the base Report continuity summary.
{
"imprint": "imp_33333333333333333333333333333333",
"range": {
"from": "2026-03-01",
"to": "2026-03-18",
"days": 18
},
"summary": {
"events": 12,
"truncated": false,
"firstSeenAt": "2026-03-01T08:10:00+09:00",
"lastSeenAt": "2026-03-18T21:34:00+09:00"
},
"timeline": [
{
"date": "2026-03-01",
"count": 2
},
{
"date": "2026-03-18",
"count": 3
}
],
"recent": [
{
"at": "2026-03-18T21:34:00+09:00",
"surface": "login"
}
]
}
days is mutually exclusive with from/to; from and to must be provided together in YYYY-MM-DD format.
History Field Reference
| Field | Meaning |
|---|---|
imprint |
Detection report identifier used for this History query |
range |
Time range applied to this History query |
range.from |
First date in the query range |
range.to |
Last date in the query range |
range.days |
Number of calendar days covered by the range |
summary |
Aggregate summary for the selected range |
summary.events |
Total visit events in the selected range |
summary.truncated |
Whether the response reached its return limit |
summary.firstSeenAt |
Earliest event time inside the selected range |
summary.lastSeenAt |
Most recent event time inside the selected range |
timeline |
Daily visit-count series |
timeline.date |
Calendar date for a timeline entry |
timeline.count |
Visit events recorded on that date |
recent |
Most recent visit-event list |
recent.at |
Time of a recent event |
recent.surface |
Customer-provided business surface identifier |
Live Data Deletion
Delete current live detection data by Workspace, Browser Environment, device, or account. Processing is asynchronous; query the request receipt for its status.
Call from server-side code with an active Workspace Server API Key in X-API-Key. Every ordinary server key for that Workspace has deletion capability. Browser Environment IDs, Console cookies, Agent Trial credentials, and MCP authorization do not apply. The key determines the Workspace; the body does not accept workspace_id. This operation is available through HTTP only; server SDKs and Console do not yet expose a deletion operation.
Choose A Deletion Scope
scope |
Selectors | Deletion scope |
|---|---|---|
workspace |
No additional selectors | All detection history and associated data in the current Workspace, including anonymous visits, Account Map links, and visits with no recorded environment. |
environment |
Required environment_id |
All detection history and associated data for the specified Browser Environment, including anonymous visits, regardless of the date range displayed in Console. |
device |
Required device_id; optional environment_id |
The device’s visits and associated data within the selected scope, including visits made under any account on that device. |
account |
Required account_ref; optional environment_id |
Visits explicitly bound to the Account Map reference and their associated data. A matching device or IP does not expand selection to unbound visits. |
Use the env_... from Console website integration as environment_id; disabled environments can also be cleaned. Use the Report’s device.id as device_id. For account_ref, use the same stable internal user ID supplied when binding the Report. Omitting environment_id from device or account requests selects matching history across the Workspace.
Deletion includes detection records and Account Map links directly associated with the selected visits, plus device data whose ownership can be confirmed. Other Workspaces remain unchanged. Shared device data or uncertain ownership puts the entire request into review_required; no partial deletion occurs.
Submit A Deletion Request
POST /api/v1/data-deletions returns HTTP 202 and a request receipt. HTTP 202 confirms acceptance; completion is determined by the receipt’s status.
Browser Environment scope:
POST https://api.echoscan.org/api/v1/data-deletions
X-API-Key: <your_server_key>
Content-Type: application/json
Accept: application/json
{
"request_id": "0123456789abcdef0123456789abcdef",
"scope": "environment",
"environment_id": "env_0123456789abcdef0123456789abcdef",
"confirmation": "DELETE_LIVE_DATA"
}
| Field | Rule |
|---|---|
request_id |
Required. Generate a random 32-character lowercase hexadecimal ID for each new operation and persist it before sending. Reuse it on retries. Example IDs are not for actual requests. |
scope |
Required. workspace, environment, device, or account. |
confirmation |
Required. Must be DELETE_LIVE_DATA. |
environment_id |
Required for environment, optional for device and account, and omitted for workspace. |
device_id |
Only for device. Never combine it with account_ref. |
account_ref |
Only for account. At most 256 bytes, without control characters or surrounding whitespace. |
The body is limited to 4096 bytes. Omit inapplicable fields; null, duplicate fields, and undeclared fields are rejected.
Workspace scope:
POST https://api.echoscan.org/api/v1/data-deletions
X-API-Key: <your_server_key>
Content-Type: application/json
Accept: application/json
{
"request_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"scope": "workspace",
"confirmation": "DELETE_LIVE_DATA"
}
Device scope, limited to a Browser Environment:
POST https://api.echoscan.org/api/v1/data-deletions
X-API-Key: <your_server_key>
Content-Type: application/json
Accept: application/json
{
"request_id": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"scope": "device",
"device_id": "did_example_device_1",
"environment_id": "env_0123456789abcdef0123456789abcdef",
"confirmation": "DELETE_LIVE_DATA"
}
Account scope, limited to a Browser Environment:
POST https://api.echoscan.org/api/v1/data-deletions
X-API-Key: <your_server_key>
Content-Type: application/json
Accept: application/json
{
"request_id": "cccccccccccccccccccccccccccccccc",
"scope": "account",
"account_ref": "EXAMPLE-customer-42",
"environment_id": "env_0123456789abcdef0123456789abcdef",
"confirmation": "DELETE_LIVE_DATA"
}
Acceptance receipt:
{
"request_id": "0123456789abcdef0123456789abcdef",
"scope": "environment",
"environment_id": "env_0123456789abcdef0123456789abcdef",
"status": "queued",
"received_at": "2026-11-05T00:00:00Z",
"copies_status": "not_verified"
}
Query The Result
GET /api/v1/data-deletions/{requestId} returns HTTP 200 and the current receipt. Use a currently active Server API Key for the same Workspace. The path’s requestId is the request_id saved before submission.
GET https://api.echoscan.org/api/v1/data-deletions/0123456789abcdef0123456789abcdef
X-API-Key: <your_server_key>
Accept: application/json
HTTP 200 confirms receipt retrieval; status determines the deletion outcome. Poll every few seconds with a timeout, retaining the original request ID for subsequent queries or support review.
Completion receipt:
{
"request_id": "0123456789abcdef0123456789abcdef",
"scope": "environment",
"environment_id": "env_0123456789abcdef0123456789abcdef",
"status": "live_data_deleted",
"received_at": "2026-11-05T00:00:00Z",
"finished_at": "2026-11-05T00:00:01Z",
"copies_status": "not_verified",
"deleted": {
"visit_events": 12,
"devices": 3
}
}
Deletion Receipt Fields
| Field | Meaning |
|---|---|
request_id |
Deletion request ID. |
scope |
Requested deletion scope. |
environment_id |
Returned when the request specifies a Browser Environment. |
status |
Current processing status. |
received_at |
Request receipt time. |
finished_at |
Processing end time; optional. |
copies_status |
Always not_verified; copy erasure is not verified by this API. |
reason |
Review or execution failure reason code. |
deleted |
Successful deletion counts by data category. An absent target can produce zero counts; category counts are not visitor counts. |
Status And Review
status |
Meaning and action |
|---|---|
queued |
Accepted or executing; keep querying. |
live_data_deleted |
Current live detection data in the selected scope has been deleted. |
review_required |
No deletion occurred. Contact support with the request ID and reason. |
failed |
Deletion did not commit and processing has ended. Reconcile the cause before deciding whether to create a new request. |
Review reasons are shared_device_data (shared device data), account_key_version_review (Account Map relationships need review), and ownership_review (data ownership needs review). Execution failures use execution_failed. Both review_required and failed are terminal and do not automatically retry.
Retries And Errors
Repeating POST with the same request_id and target returns the original receipt without executing deletion again. Changing the scope or selectors returns a conflict. GET retrieves the original receipt without resubmitting the target.
HTTP / error.code |
Action |
|---|---|
400 / invalid_deletion_request |
Check the scope, fields, and confirmation. |
401 / invalid_api_key |
Check that the server key is valid. |
403 / data_deletion_forbidden |
Use an ordinary server key for the Workspace. |
404 / data_deletion_environment_not_found |
Check that the environment belongs to the key’s Workspace. |
404 / data_deletion_not_found |
No receipt was found in the current Workspace; this does not confirm deletion. |
409 / data_deletion_conflict |
Check the original ID and target, then GET the original result. |
429 / data_deletion_busy |
Honor Retry-After: 10. Each Workspace allows one queued request, with at least 10 seconds between new requests. |
429 / key_rate_limited |
Reduce request and polling frequency. |
500 / data_deletion_failed |
The result is uncertain; retry the original ID and selectors. |
503 / data_deletion_unavailable |
Temporarily unavailable; retain the original request ID. |
Reuse the original ID after a lost response. If POST repeatedly returns 503 while GET returns 404, stop automatic retries and contact support with that ID. Do not use a new ID to bypass an uncertain result. Submission and polling do not consume detection/Report quota; ordinary request rate limits still apply.
Retention Boundaries
The Workspace, login accounts, members, Browser Environment configuration, API keys, installations, OAuth grants, billing, and actual usage remain unchanged. Account closure and a complete integration Reset are separate operations.
live_data_deleted confirms current live detection data only. Backups, exports, logs, and research copies are outside this confirmation, and copies_status remains not_verified. Deletion requests involving copies require separate handling through support; this status does not authorize continued use of those copies.
Deletion does not prevent future collection. Pause collection before clearing a test batch, wait for live_data_deleted, then start the next batch with fresh SDK submission IDs. Disable the corresponding Browser Environment or stop integration calls when future collection must also stop.
Server Decision
Use risk.status, risk.reasons, and risk.findings as report inputs and combine them with account, transaction, and business context. Network details and activity are part of the canonical Report; History is a separate time-range operation available in both plans.
if (report.risk.status === 'UNAVAILABLE') {
return Response.json({ error: 'verification_unavailable' }, { status: 503 })
}
const decision =
report.risk.status === 'PASS'
? 'allow'
: 'challenge'
return Response.json({ decision })
This allow-or-challenge branch is an example customer policy. EchoScan Report API v1 does not return recommended_action.
Keep the full report server-side and return only the business result needed by the browser.
Error Shape
{
"error": {
"code": "invalid_api_key",
"message": "API key is invalid"
}
}
Branch on error.code; treat error.message as display text.
Error Field Reference
| Field | Meaning |
|---|---|
error |
Public error object |
error.code |
Stable machine code for server-side branching |
error.message |
Error description suitable for logs or interface text |
Failure Stages And Recovery
SDK 3.0 uses EchoScanError.category, with SDK version and a minimal correlation receipt. Do not parse messages or import the old detailed Error/Transport classes.
| Category | Meaning and recovery |
|---|---|
configuration, run_in_progress, disposed |
Fix the options/lifecycle; this rejected call has no new API receipt. |
detection_failed |
Collection did not produce a submittable result. Keep the business action pending or denied. |
cancelled, timeout |
The server may have received a request. Check the receipt state; failure is not PASS. |
submission_failed |
Delivery, API response or validation failed. Give support the safe receipt and category; do not fabricate a Report. |
Public-key GET can retry transient failures; Browser Verifier does not automatically retry Submit POST. A new run() is a new collection/submission, not a guaranteed replay with the previous submission ID. Recognized same-ID duplicate submissions do not consume Submit quota twice, but a fresh run may consume new usage.
For direct HTTP, check the status before reading the success contract. Branch on error.code from the envelope; do not assume every proxy/network failure has JSON. invalid_api_key, origin_not_allowed, quota_exceeded, and key_rate_limited require the corresponding credential, Origin, quota, or backoff correction. A successful HTTP response still needs Report validation and the same Imprint.
HTTP 503 quota_state_unavailable. The service cannot reliably read or settle the current quota usage state and stops before executing the protected operation. This is a temporary availability failure, distinct from HTTP 429 quota_exceeded; it does not establish that your allowance is exhausted. Display verification unavailable, never PASS. Retry GET only within your configured limits after service recovery; avoid continuous polling. Changing keys or upgrading a plan does not repair unavailable quota state. If the failure persists, retain the HTTP status, public error code, and request identifier for support without logging keys or the full Report. For a write with an uncertain response, check the existing snapshot before deciding whether to repeat it.
Server SDK errors are normalized separately in 0.2.3 and 0.2.4: Node EchoScanApiError.code / serverCode; Go APIError.Code / ServerCode; Python ApiError.code / server_code; Rust ApiError.code / server_code. For this 503, the normalized code is upstream_unavailable and the server-code field retains quota_state_unavailable. The HTTP status, request identifier, and retry fields use each language’s public types. Check the matching public SDK types for your installed version.
Server SDK GET wrappers can retry transient failures according to their configured limits. Each tracked retry or repeated Report GET can consume server usage, even after a business error. Authentication/rate/quota refusals before tracking do not consume that count. Account Map POST is a write: do not blindly retry it or change the account reference after an uncertain response. These failures must never fall through to the PASS branch.
Connect AI With EchoScan MCP
Use standard MCP to connect Codex, Claude Code, VS Code, or another compatible client directly to EchoScan. The client opens browser authorization the first time it needs access to a Workspace.
Connect EchoScan to your AI
Add this remote endpoint once. Your client opens EchoScan authorization when access is required—no API key is pasted into the AI client.
https://api.echoscan.org/mcp
View setup methods
Run this once in a terminal, then approve the EchoScan workspace and permissions in your browser.
codex mcp add echoscan --url https://api.echoscan.org/mcp
Run this once in a terminal. Claude Code will start browser authorization when it first connects.
claude mcp add --transport http echoscan https://api.echoscan.org/mcp
Add this server entry to your MCP configuration. VS Code will request authorization when the server is first used.
{
"servers": {
"echoscan": {
"type": "http",
"url": "https://api.echoscan.org/mcp"
}
}
}
Create a remote Streamable HTTP server with these values. If the client supports MCP OAuth, it will discover the authorization flow automatically.
Name: EchoScan
Transport: Streamable HTTP
URL: https://api.echoscan.org/mcp
Authentication: OAuth 2.1 + PKCE
Primary tools (summary) are echoscan_get_report, echoscan_get_history, and echoscan_get_usage. See the MCP guide for the complete tool and OAuth scope list, enablement conditions, and call permissions. This summary is not the full tool list.
If the AI will also change EchoScan integration code, give it these canonical sources first:
https://echoscan.org/llms.txthttps://echoscan.org/docs/ai-context.md
They are maintained against the same public API contract and validated for consistency. MCP authorization never requires you to paste an EchoScan API key into the AI client.
CLI Integration
Create EchoScan integration configuration and check connection status. Requires Node.js 22.22 or a later 22.x release. Run in your project directory:
npx @echoscan/cli init --origin https://example.com
Authorize EchoScan CLI in your browser and select a Workspace. After creating configuration, follow the recommended flow to connect Browser Verifier and your backend, then check the connection:
npx @echoscan/cli status
npx @echoscan/cli verify
status shows the current connection state. verify succeeds when both the browser and server are connected. The CLI creates configuration; it does not install SDKs or modify application code.