Public API Connect v1
/api/connect/v1 is the documented tenant automation surface. Its resources, scopes, pagination, completeness metadata, and supported actions form the public contract.
API Connect / Release 4.4
Automate the evidence chain without bypassing it.
Use a tenant-scoped public API for pageable local collection access and supported review-preserving workflow actions—with scopes, completeness, correlation, and action boundaries made explicit.
One public tenant API
Know which interface is part of the contract.
Release 4.4 separates customer automation from browser implementation details and service-provider operations.
Browser application
HTML routes, form submissions, and browser-session endpoints support the interactive product. They are not a substitute public API and can evolve with the interface.
Private Control Center APIs
Control Center interfaces support authorized service operations. They are private service boundaries and are not exposed by a customer tenant API key.
MSSP boundary
Threat Foundry Control Center remains the authorized cross-tenant boundary for MSSP and managed-service operations. API Connect v1 stays inside the authenticated customer tenant; it does not provide portfolio-wide access, impersonation, or a path around customer authorization.
Purpose-bound access
Issue a key for the workflow, not for the whole platform.
Administrators create tenant-scoped API Connect keys using predefined purpose profiles. Every key requires a named owner and fixed expiry. New or blank scope state grants no authority. The raw secret is shown once; the platform retains a non-reversible verifier and bounded metadata.
Tenant scoped
Every key and every collection request is bound to one active tenant. Tenant context is activated before licensed data is read or changed.
Purpose profile
Purpose profiles issue allowlisted exact scopes. An isolated pentest uses a one-day read-only key rather than a broader testing profile.
Owned and revocable
Named ownership and expiry are mandatory. Administrators can revoke a key, which exposes only a short non-secret prefix for identification.
Discoverable capability
The capabilities resource reports the authenticated tenant, current key scopes, expiry, available endpoint families, and operating boundaries.
Bounded collection access
Pagination controls transport size—not analytical truth.
Authorized collections are delivered in bounded, signed-cursor pages. Follow next_cursor while continuation remains. Offset-based collection traversal is never snapshot-complete because records can change between pages.
False-negative safety
Offset collection traversal never claims snapshot completeness, even when the current pass has no continuation. It does not prove attacker behavior is absent. Absence-sensitive automation repeats the traversal and reconciles stable record identifiers. Responses identify continuation, known omissions, and evaluated scope so incomplete evidence cannot be mistaken for an exhaustive negative conclusion.
Connected local evidence
Enumerate the platform without losing source context.
Scope and license determine which resource families a key can use. Detail and child collections remain separately enumerable so automation can retrieve the stored context it needs.
Hunts and results
Saved hunts, run history, result rows, entities, notes, plans, and analytical context. Stored hunt-result JSON above 16 MiB returns 413 before loading or truncation, with guidance to retrieve complete bounded partitions.
Threat intelligence
Normalized tenant intelligence, provenance, source policy, reviewed context, integrations, and synchronization history.
Operations and cases
Triage items and history plus case metadata, evidence, tasks, and timeline events.
Detection evidence
Detection Studio, validation, assurance, ATT&CK, and D3FEND evidence. D3FEND scans each selected source record in full for mapped ATT&CK references; source and per-technique presentation caps remain disclosed and force completeness false when reached.
Exposure
Approved-scope EASM finding lifecycle, ownership, affected assets, service context, and stored evidence.
Risk
Governed risk records, ownership, treatment state, evidence health, scoring context, and review dates.
API audit
Minimized request status and correlation metadata without returning raw credentials, provider secrets, or hidden cross-tenant context.
Tenant context
Authenticated tenant identity and current API capability boundaries for reliable client initialization.
Review-preserving actions
Advance local work without silently making the decision.
Where the key scope, tenant license, record state, and workflow policy allow it, API Connect supports bounded local actions such as appending a saved-hunt note, progressing non-terminal triage, opening and maintaining cases and tasks, updating non-terminal exposure ownership and lifecycle metadata, and creating a draft risk.
hunting:writeauthorizes tenant-local hunt records and notes; it does not contact a model- Model-assisted generation requires the separate
hunting:generatescope and an eligible tenant-selected route - Terminal dispositions, risk acceptance, signoff, and administrative overrides remain governed decisions
- Provider-contacting reruns, connector synchronization, and report jobs are not presented as local v1 mutations
- No supported v1 action silently deploys to a provider, changes a provider configuration, or deletes customer records
Availability is explicit
A scope is necessary but not sufficient. Tenant licensing, feature settings, record ownership, current source policy, and workflow state are rechecked at the action boundary.
Correlation + operational safety
Make automation supportable without retaining secret payloads.
Request correlation
Mutating v1 actions require a unique Idempotency-Key. If X-Request-ID is also sent, both values must match. Responses return the request ID, and structured problems include a correlation ID plus safe recommendations.
Minimized audit trail
API audit records retain bounded status, timing, key fingerprint, path, and execution metadata. Raw API keys, reusable credentials, full queries, and result payloads are not audit content.
Isolated security testing
GPT-assisted API pentesting runs only against an isolated AWS environment with synthetic data. Production testing is limited to read-only smoke checks; mutation, load, injection, SSRF, and destructive testing stay out of production.
Customer-selected BYOAI
Model contact requires its own authority.
hunting:write remains local. A supported AI-assisted hunting workflow requires the separate hunting:generate scope and follows the tenant’s selected BYOAI provider and model route without hidden failover.
- The customer selects the provider account, model route, and authorized workflow evidence
- Using that route confirms the customer’s acceptance of the provider’s applicable terms, pricing, retention, privacy, and data-handling conditions
hunting:generatedoes not grant query execution, provider deployment, integration synchronization, or administrative override authority- Provider credentials and connector secrets are never API response or prompt content
- An unavailable or ineligible route does not produce a substitute provider verdict
No silent external action
Public API access does not grant provider deployment, destructive operations, cross-tenant service access, or a bypass around review. Any supported model contact must be visible, explicitly scoped, bounded, and attributable.
Start with the workflow
Map one automation workflow to the public API boundary.
Bring the collection, local action, tenant scope, expected volume, and review requirements. We will identify the least-privilege purpose profile and completeness checks.