Public API v2.0.0

Start with one bounded request.

Use stable server-to-server recipes for quick checks and governed research runs, then read source-linked results with workspace-scoped access.

Follow the complete quick start Choose a product Create or manage a key

Orientation

Key, request, response.

The quick start keeps credentials server-side and makes completed versus accepted work explicit.

1. Create a scoped key

Create a workspace-owned key in the signed-in app and keep it in a server-side secret manager.

2. Call one product

Begin with one bounded quick-check recipe and a stable idempotency key from your server.

3. Read the right response

A completed quick check returns 200. Accepted background work returns 202 and an opaque job reference to poll.

Quick start

Make one completed quick-check request.

This example uses a reserved MAC address, environment variables and a stable idempotency key. It does not contain a real credential.

MAC / OUI · POST /v2/lookups/mac

curl -sS -X POST "${TIGESS_API_BASE_URL}/v2/lookups/mac" \
  -H "Authorization: Bearer ${TIGESS_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: docs-mac-1" \
  --data '{"value":"0c:11:22:33:44:55"}'

Continue through polling and results OpenAPI 3.1 JSON

Safe interactive example

Inspect a free response or a no-request fixture.

Live mode calls only the four zero-credit recipes through the bounded website proxy. Paid products and research runs remain fixed, labelled fixtures for anonymous visitors.

The optional interactive example loads when it is near the viewport.

Exact reference

Need contract-level detail?

Most integrations can begin with the quick start. Open this disclosure for every implemented route, lifecycle semantic and generated contract identifier.

Open exact Public API v2 contract details

Four completed lookup examples

MAC / OUI · POST /v2/lookups/mac

curl -sS -X POST "${TIGESS_API_BASE_URL}/v2/lookups/mac" \
  -H "Authorization: Bearer ${TIGESS_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: docs-mac-1" \
  --data '{"value":"0c:11:22:33:44:55"}'

Phone · POST /v2/lookups/phone

curl -sS -X POST "${TIGESS_API_BASE_URL}/v2/lookups/phone" \
  -H "Authorization: Bearer ${TIGESS_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: docs-phone-1" \
  --data '{"defaultRegion":"GB","value":"020 7946 0018"}'

IP context · POST /v2/lookups/ip

curl -sS -X POST "${TIGESS_API_BASE_URL}/v2/lookups/ip" \
  -H "Authorization: Bearer ${TIGESS_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: docs-ip-1" \
  --data '{"includeContext":false,"value":"192.0.2.1"}'

DNS · POST /v2/lookups/dns

curl -sS -X POST "${TIGESS_API_BASE_URL}/v2/lookups/dns" \
  -H "Authorization: Bearer ${TIGESS_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: docs-dns-1" \
  --data '{"value":"example.org"}'

One accepted recursive scan

Quick, Balanced and Deep scans are passive by request. Advanced additionally requires options.active=true, workspace permission and approved target scope. maxCredits is mandatory and profile-bounded.

Quick scan · POST /v2/scans

curl -sS -X POST "${TIGESS_API_BASE_URL}/v2/scans" \
  -H "Authorization: Bearer ${TIGESS_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: docs-quick-scan-1" \
  --data '{"options":{"active":false,"maxCredits":100},"profile":"quick","target":{"type":"domain_name","value":"example.org"}}'

200 · completed or partial

MAC, phone, IP and DNS return a bounded product projection immediately.

202 · accepted

Domain, mail, web/TLS and scans return an opaque jobRef. Acceptance does not claim completion.

GET · retained state

Status, paginated results, findings and object detail remain tenant scoped. Cancellation is idempotent.

Public API v2 product routes
Method	Path	Product	Scope	Success	Idempotency
POST	`/v2/lookups/dns`	DNS lookup Partially configured	scan:create	200 · completed	Required
POST	`/v2/lookups/domain`	Domain core lookup Available	scan:create	202 · accepted	Required
POST	`/v2/lookups/ip`	IP context lookup Available	scan:create	200 · completed	Required
POST	`/v2/lookups/mac`	MAC / OUI lookup Available	scan:create	200 · completed	Required
POST	`/v2/lookups/mail`	Mail security lookup Available	scan:create	202 · accepted	Required
POST	`/v2/lookups/phone`	Phone format and region lookup Available	scan:create	200 · completed	Required
POST	`/v2/lookups/web`	Web and TLS posture lookup Available	scan:create	202 · accepted	Required
POST	`/v2/scans`	Recursive scan Available	scan:create	202 · accepted	Required

Public API v2 retained-job routes
Method	Path	Scope	Idempotency
GET	`/v2/jobs/{job_ref}`	scan:read	No
POST	`/v2/jobs/{job_ref}/cancel`	scan:create	Required
GET	`/v2/jobs/{job_ref}/findings`	scan:read	No
GET	`/v2/jobs/{job_ref}/objects/{object_id}`	scan:read	No
GET	`/v2/jobs/{job_ref}/results`	scan:read	No

Rate, credits and coverage remain explicit. Honor Retry-After. Partial or unavailable coverage never becomes an all-clear. Review error and governance semantics.

Server-side keys

Never embed TIGESS_API_KEY in browser code, examples or logs.

Exact authorization

Application scope, responsible-use acceptance, workspace grants and target scope are checked independently.

Generated identifiers

Product f910aadc268ef2fd…
OpenAPI ca850d0ae1bf90a3…