Evidence API

Evidence API

Collect artifacts, inspect integrity metadata, export bounded sets, and apply retention holds.

Evidence operations require the corresponding special grant in addition to API scope. Incident visibility alone cannot authorize raw-artifact access.

Use the shared API contract for authentication, pagination, request headers, idempotency, and error responses.

Request collection

POST/organizations/{organization_id}/evidence
Scope
evidence:write
Auth
Bearer API key

Requests central evidence collection from an authorized source with the required collection capability. Quarantine restoration uses a separate response action.

Request body
incident_idstringrequired

Restricted investigation owning the collection.

asset_idstringrequired

Source asset.

artifact_referencestringrequired

Existing observed artifact reference, not an arbitrary remote shell command.

retention_daysintegerrequired

Explicit raw-evidence lifetime, subject to organization policy.

rule1–3650 days
reasonstringrequired

Audited justification. Empty values are invalid.

rule1–2000 characters
202Accepted

Returns evidence ID and collection operation. A failed collection preserves the error and does not claim stored bytes.

Read evidence metadata

GET/organizations/{organization_id}/evidence/{evidence_id}
Scope
evidence:read
Auth
Bearer API key

Returns source, collection time, byte length, SHA-256, availability, transformations, expiry, and active holds. It does not return artifact bytes.

200Result

Returns data and request_id.

Export evidence

POST/organizations/{organization_id}/evidence-exports
Scope
evidence:read
Auth
Bearer API key

Creates an audited evidence export. Requires download authorization for every selected item and incident visibility.

Request body
evidence_idsstring[]required

Existing available items visible to the caller.

rule1–200 unique IDs
reasonstringrequired

Audited justification. Empty values are invalid.

rule1–2000 characters
202Accepted

Returns export ID and operation. A completed export contains a manifest and artifact digests.

Read an evidence export

GET/organizations/{organization_id}/evidence-exports/{export_id}
Scope
evidence:read
Auth
Bearer API key

Returns state, manifest metadata, and an expiring download URL only after success. Unavailable or deleted source items produce an explicit export failure.

200Result

Returns data and request_id.

Create a hold

POST/organizations/{organization_id}/evidence-holds
Scope
evidence:hold
Auth
Bearer API key

Creates a hold that blocks ordinary deletion for the selected items. Requires hold-management authority.

Request body
evidence_idsstring[]required

Items to preserve.

rule1–200 unique IDs
owner_idstringrequired

Responsible hold reviewer.

review_attimestamprequired

Future review date; review is not automatic release.

reasonstringrequired

Audited justification. Empty values are invalid.

rule1–2000 characters
201Created

Returns hold ID and protected item IDs. Existing retention deadlines remain recorded but cannot authorize deletion while held.

Release a hold

POST/organizations/{organization_id}/evidence-holds/{hold_id}/release
Scope
evidence:hold
Auth
Bearer API key

Releases an evidence hold. Requires If-Match and hold-release authorization. Releasing does not immediately delete evidence still within retention.

Request body
reasonstringrequired

Audited justification. Empty values are invalid.

rule1–2000 characters
200Result

Returns the released hold and audit reference.

Delete eligible evidence

DELETE/organizations/{organization_id}/evidence/{evidence_id}
Scope
evidence:write
Auth
Bearer API key

Deletes eligible evidence. Requires If-Match; active holds or retained dependencies return 409 evidence_held. Backup copies follow their independent expiry.

202Accepted

Returns deletion operation. Verify completion and availability state; do not treat acceptance as physical reclamation.