API documentation

From API key to retained results.

This path uses only implemented v2 routes and environment variables. It covers a synchronous first lookup, then the polling flow used by retained 202 jobs.

Product reference Errors and governance Create or manage API key

Step 1

Keep the key server side.

Create a workspace-owned application key in the signed-in app. Grant scan:create for writes, scan:read for job and result reads, and finding:read only when findings are needed.

export TIGESS_API_BASE_URL="${TIGESS_API_BASE_URL:-https://api.tigess.com}"
: "${TIGESS_API_KEY:?Set TIGESS_API_KEY in your shell or secret manager}"

Never commit, paste into browser code, log or send TIGESS_API_KEY. The examples read it from the process environment.

Step 2

Run one completed MAC lookup.

The generated route is POST /v2/lookups/mac, requires scan:create and returns 200.

First lookup

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: quickstart-mac-1" \
  --data '{"value":"0c:11:22:33:44:55"}'

A successful free lookup returns a completed or partial product envelope immediately. Reuse the same Idempotency-Key only for the same normalized method, path and body.

Step 3

Poll an accepted retained job.

Domain, mail, web/TLS and scan creation return 202 with jobRef. Store that opaque value as TIGESS_JOB_REF; do not parse or manufacture it.

GET /v2/jobs/{job_ref}

curl -sS "${TIGESS_API_BASE_URL}/v2/jobs/${TIGESS_JOB_REF}" \
  -H "Authorization: Bearer ${TIGESS_API_KEY}"

Use bounded polling and stop at completed, partial, cancelled, failed or unavailable. Acceptance alone is not proof of results or required coverage.

Step 4

Retrieve retained results.

Result pages expose retained canonical projections and evidence references. Follow the returned cursor rather than inventing an offset.

GET /v2/jobs/{job_ref}/results

curl -sS "${TIGESS_API_BASE_URL}/v2/jobs/${TIGESS_JOB_REF}/results?limit=100" \
  -H "Authorization: Bearer ${TIGESS_API_KEY}"

Findings require the separate finding:read scope. Object detail stays inside the same tenant and job scope. Raw internal events, provider credentials and backend identifiers are never part of this surface.

Step 5

Handle errors as contract states.

Every error is a stable JSON envelope with a machine code. A 429 can carry Retry-After; wait for that interval rather than changing the idempotency key to evade a limit.

Selected quickstart error codes
Machine code	HTTP	Meaning
`authentication_required`	401	A valid application Bearer key is required.
`insufficient_scope`	403	The application key lacks the required operation scope.
`idempotency_key_conflict`	409	The key was already bound to a different normalized request.
`rate_limit_exceeded`	429	The application request rate limit was reached.
`capability_rate_limit_exceeded`	429	The product-specific minute or hour limit was reached.
`capability_unavailable`	503	A required public product lane is not currently available.

Rate limits apply per application and per product. Credit denials do not dispatch paid work. Partial or unavailable coverage must stay visible to downstream users.