11. REST API Reference

PUT /api/incidents/cancel-collection/{collectionId}

Cancel a collection

Cancels a collection (i.e. a host being added). All activities are stopped and status set to canceled. A pending collection will be removed from the scheduled pending list.

Parameters:

  • collectionId (integer) – The ID of the collection to cancel.

Status Codes:
POST /api/v2/livesessions

Schedule a Live-PsExec host collection

Schedule a collection from one or more hosts using the Live-PsExec method. Requires a username and password with administrator privileges on the target host(s).

The hostName field accepts a comma-separated list of hostnames or IP addresses.

Status Codes:

  • 200 OK – Collection successfully scheduled. Returns queue position and session ID.

  • 400 Bad Request – Scheduling failed. Returns error details and any conflicting session IDs.

POST /api/v2/items/{collectionId}/by-id

Get item details by ID

Returns all metadata associated with one or more items (artifacts) within a single collection (host). Pass a JSON array of artifact object IDs in the request body.

Parameters:

  • collectionId (integer) – The ID of the collection (host) containing the items.

Status Codes:

  • 200 OK – A list of item metadata objects.

POST /api/incidents/add-incident

Create a new incident

Creates a single new incident.

Note: The incident name must be unique. If called with an existing name, the existing incident is returned rather than creating a duplicate.

Query Parameters:

  • incident-name (string) – Name for the new incident. Must be unique. (Required)

  • description (string) – A description of the incident. (Required)

  • restricted (boolean) – If true, restricts access to the incident.

  • confidential (boolean) – If true, marks the incident as confidential.

Status Codes:

  • 200 OK – Incident created (or existing incident returned if the name already exists).

POST /api/auth/logon

Obtain an auth token

Authenticate and obtain a bearer token to use with all other API calls. The token is valid for 1 hour.

This endpoint must be called with the api-user account. Retrieve the password from the [administrative web application](https://docs.cybertriage.com/en/latest/chapters/team/index.html#api-user).

See the [IAM reference](https://docs.cybertriage.com/en/latest/chapters/team/index.html#create-and-manage-team-users) for creating and managing users.

Note: As of the 3.10 release, restApiKey is deprecated. Token-based auth is now required.

Query Parameters:

  • rememberMe (boolean)

  • transferCode (boolean)

Status Codes:

  • 200 OK – Authentication successful. Returns a bearer token valid for 1 hour.

  • 401 Unauthorized – Authentication failed. Verify the api-user credentials.

GET /api/sessionFiles/{id}

Download a collected file by MD5 hash

Downloads the content of a collected file identified by its MD5 hash. The response is compressed using zlib/deflate compression.

Deprecated: This endpoint is deprecated.

Parameters:

  • id (string) – The MD5 hash of the file to download.

Status Codes:

  • 200 OK – File contents as a compressed binary stream.

GET /api/incidents/list-incidents

List all incidents

Returns all incidents the authenticated user has access to.

Status Codes:

  • 200 OK – A list of incidents.

GET /api/correlation/checkcredentials

Validate API credentials

Validates the caller’s bearer token. Useful for confirming that authentication is working correctly before making other API calls.

Status Codes:
GET /api/collections/get-pending-collection-ids

List pending collection IDs

Returns the IDs of collections (hosts) that are scheduled and pending processing.

Status Codes:

  • 200 OK – A list of pending collection IDs.

GET /api/collections/get-active-collection-ids

List active collection IDs

Returns the IDs of collections (hosts) that are currently being processed.

Status Codes:

  • 200 OK – A list of active collection IDs.

POST /api/cloudingests

Trigger a cloud storage ingest

Triggers ingestion of a host collection file stored in cloud storage (e.g. S3). Available since CT Server 3.18.0.

The server locates the appropriate cloud storage profile using the S3 URI in filePath. You can also specify a cloudStorageProfileId explicitly to override profile matching.

If incidentName is omitted, an incident is auto-generated. If hostName is omitted, the display name is derived from the collection filename.

Status Codes:

  • 202 Accepted – Ingest successfully queued. Returns the new collection ID.

  • 400 Bad Request – Bad request. Invalid or missing input fields.

  • 403 Forbidden – Forbidden. The authenticated user does not have sufficient permissions.

  • 422 Unprocessable Entity – Unprocessable entity. No matching cloud storage profile was found for the provided S3 URI.