Skip to main content

API Integration

Spider is designed API first.

  • The frontend is headless
  • All APIs used by the UIs are accessible and documented in the OpenAPI doc
  • You can build new tools, integrate with or extend Spider using its API

Service Accounts management​

To interact with Spider APIs, it is recommended to create Service Accounts, and to share with them access to data as you would for users.

Using the API​

Authenticate the Service Account​

Spider Service Accounts API connection offers OAuth2 client-credentials way for connection.
You may use either:

Basic Auth + application/x-www-form-urlencoded request body​

POST /customer/v1/sessions/for/service-account
Authorization: Basic ...
Content-Type: application/x-www-form-urlencoded
Accept: application.json

grant_type=client_credentials

application/x-www-form-urlencoded request body only​

POST /customer/v1/sessions/for/service-account
Content-Type: application/x-www-form-urlencoded
Accept: application.json

grant_type = client_credentials
&client_id = ...
&client_secret=...

application/json request body​

POST /customer/v1/sessions/for/service-account
Content-Type: application/json
Accept: application/json

{
  "grant_type": "client_credentials",
  "client_id": "...",
  "client_secret": "..."
}

Response​

The response is in JSON, and contains:

  • the JWT to reuse when calling the API,
  • its TTL
{
  "access_token": "{sa_access_token}",
  "token_type": "Bearer",
  "expires_in": 5400
}

When using wrong credentials, an error is returned.
The account is locked after a few consecutive unsuccessful attempts.

Select a team​

Often, the service account will access Whisperer through a team, in the same way as users.
For this, you need to exchange the service account token for a team token.

GET /teams/v1/teams/{id}/user-token/
Authorization: Bearer {sa_access_token}
Accept: application/json
  • Replace {id} your team's id
  • Replace {access_token} with the JWT fetched before

The response is in JSON, and contains:

  • the team scoped JWT,
{
  "token": "{team_access_token}"
}

Search for HTTP communications (for instance)​

You may now, for instance, search for erroneous HTTP communications.

POST /web-read/v1/http-com/_search
Authorization: Bearer {team_access_token}
Content-Type: application/json
Accept: application/json

{
  "size":20,
  "whisperers":["qCC4TpvyThic6FVAYf2VTw"],
  "startDate":"2025-05-31T10:00:00.000Z",
  "stopDate":"2025-05-31T10:20:00.000Z",
  "query":"stats.statusCode:500",
  "sort": [{"key":"req.start","order":"desc"}]
}

The result will be a collection of items:

  • How many items were found: 607
  • The array of the first items
  • The query to send as is to get the next page
tip

aggs is null as no aggregation query was made

  • To use aggregation, send a aggs field in the request, using Elasticsearch DSL
  • Look at queries sent by the UI to get samples
{
    "total": 607,
    "aggs": null,
    "items": [{
       "@id": "qCC4TpvyThic6FVAYf2VTw.hosts-6997d99564-xq9gp.485758.10.42.0.122-36604-10.42.0.138-3000.3885872403.HTTP.2"
    }],
    "nextPage": {
        "@type": "SearchAction",
        "query": {
            "size": 20,
            "whisperers": ["qCC4TpvyThic6FVAYf2VTw"],
            "startDate": "2025-05-31T10:00:00.000Z",
            "stopDate": "2025-05-31T10:20:00.000Z",
            "query": "stats.statusCode:500",
            "sort": [{ "key": "req.start", "order": "desc" }],
            "next": [
                1748729513.6748428,
                "qCC4TpvyThic6FVAYf2VTw.hosts-6997d99564-xq9gp.485758.10.42.0.1-41628-10.42.0.138-3000.210121981.HTTP.0"
            ]
        }
    }
}

Getting the payload​

You may then want to retrieve the inner payload of communications.
You can ask for response body like this (res):

POST GET /web-read/v1/http-com/{id}/res/body/
Authorization: Bearer {team_access_token}

Use req to get the request.
By default, the body will be sent with the same headers as captured for Content-Type and Content-Encoding. Only Transfer-Encoding is not reproduced.

Check the OpenAPI to know what other options you have.

note

There are tens and more of APIs exposed by Spider to access data and manage its configuration.
Check the OpenAPI to know more, or ask for help / training.

Spider resources model​

Here is a simplified view of Spider resources and their links.
To help you with your exploration.