Upload a CSV file to add entities to a watchlist Technical Preview

POST /api/entity_analytics/watchlists/{watchlist_id}/csv_upload
Api key auth Basic auth

Spaces method and path for this operation:

post /s/{space_id}/api/entity_analytics/watchlists/{watchlist_id}/csv_upload

Refer to Spaces for more information.

Uploads a CSV file to add entities to a watchlist. The CSV must contain a header row with a "type" column (user, host, service, or generic) and one or more ECS identity fields (e.g. "user.name", "host.hostname") used to match entities in the entity store.

Matched entities are added to the watchlist and their entity.attributes.watchlists field is updated in the entity store.

Each row will match up to 10,000 entities.

Path parameters

  • watchlist_id string Required

    The ID of the watchlist to add entities to

multipart/form-data

Body Required

  • file string(binary) Required

    The CSV file to upload.

Responses

  • 200 application/json

    Upload successful

    Hide response attributes Show response attributes object
    • failed integer Required

      Number of rows that failed to process

    • items array[object] Required
      Hide items attributes Show items attributes object
      • error string

        Error message if the row failed to process

      • matchedEntities integer Required

        Number of entities matched for this row

      • status string Required

        Values are success, failure, or unmatched.

    • successful integer Required

      Number of rows that matched at least one entity

    • total integer Required

      Total number of rows processed

    • unmatched integer Required

      Number of rows that matched no entities
  • 413

    File too large

POST /api/entity_analytics/watchlists/{watchlist_id}/csv_upload 
curl \
 --request POST 'https://localhost:5601/api/entity_analytics/watchlists/high-risk-vendors/csv_upload' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: multipart/form-data" \
 --form "file=type,user.name
user,john.doe
user,jane.smith
"
Request example 
{"file" => "type,user.name\nuser,john.doe\nuser,jane.smith\n"}
Response examples (200) 
{
  "failed": 1,
  "items": [
    {
      "matchedEntities": 1,
      "status": "success"
    },
    {
      "error": "Invalid entity type",
      "matchedEntities": 0,
      "status": "failure"
    },
    {
      "matchedEntities": 0,
      "status": "unmatched"
    }
  ],
  "successful": 1,
  "total": 3,
  "unmatched": 1
}