Skip to main content

​
Overview

The API allows you to manage and search cases. This article provides details about the available endpoints, request parameters, pagination, and example responses. Prerequisites: Obtaining API Key

​
Endpoint

[POST] api.wiv.ai/v2/cases/search
Search cases. Supports filtering and pagination.

​
Authentication

Requires valid API Key authentication credentials.

​
Request Body Parameters (JSON)

ParameterTypeDescription
date_rangeobjectStart & end dates
max_returned_itemsintegerDefault: 250
start_page_keyobjectPagination key

​
Request Examples

  1. Search all cases
POST /v2/cases/search
Content-Type: application/json

{}
  1. Specific max_returned_items
POST /v2/cases/search
Content-Type: application/json

{
    "max_returned_items": 50
}
  1. With filters and date range
{
    "date_range": {
        "start": "2024-01-01",
        "end": "2024-12-31"
    }
}

​
Pagination

Large case search results are returned in pages. The API uses a scroll-based pagination mechanism to deliver results consistently.

​
How it Works

  1. Initial Request
    • Send your search request with max_returned_items (default: 250).
    • The response will include data (cases) and a next_page_key object if more results exist.
  2. Fetching Next Page
    • Copy the scroll_id from the response next_page_key.
    • Provide it in your next request under start_page_key.scroll_id.
  3. End of Results
    • When there are no further results, "next_page_key": null is returned.

​
Request Example (Next Page)

POST /v2/cases/search
Content-Type: application/json

{
    "max_returned_items": 25,
    "start_page_key": {
        "scroll_id": "FGluY2x1ZGVfY29u==..."
    }
}

​
Response Example (With Next Page Key)

{
    "data": [
        {
            "case_id": "case_12345",
            ....
            "case_type": "EC2 Stopped Instances"
        }
    ],
    "next_page_key": {
        "scroll_id": "FGluY2x1Z==..."
    }
}

​
Key Notes

  • Opaque scroll ID: The scroll_id is an encoded system token. Always use it as returned, without modification.
  • Consistency: The scroll ensures results are returned in a stable order during the pagination session.
  • Session scope: New cases created during an active scroll session may not appear until you start a new search.
  • Performance:
    • Use page sizes of 25–100 items for UI-based pagination.
    • Use larger page sizes (up to 500) for backend batch processing.

​
Error Responses

StatusExample
400 Invalid Request{"error": "Request body must be a dictionary"}
401 Unauthorized{"error": "Authentication required"}
500 Internal Server Error{"error": "Internal server error"}

​
Best Practices

  • Apply specific date ranges in /cases/search for faster responses.
  • Always use pagination for large result sets.
  • Cache frequently accessed queries where possible.

​
Rate Limits

Standard API rate limits apply. Contact your administrator for details.