Overview

For endpoints that support them, meta functions allow decorating responses from the Synqly API with additional meta information. Meta functions are organized into groups, representing a specific type of metadata.

Calling Meta Functions

When making a request without a body (typically an HTTP GET request), add any number of meta= query parameters, each containing a single meta function.

GET
https://api.synqly.com/v1/siem/event?meta=stats/count([raw_data.time])&meta=api/response(primary)

For requests that do take a JSON body, include the meta functions in a root-level meta key as an array of function calls.

POST
https://api.synqly.com/v1/example
{
    "meta": [ "api/response(all)" ]
}

SDKs

Each SDK will have a means of taking meta functions for calls to endpoints that support it.

Note: To avoid type issues make sure your SDK version is 0.2.55 or later.

For the Go SDK the example GET call above could be made like this:

queryResponse, err := apiClient.Siem.QueryEvents(ctx, &engine.QuerySiemEventsRequest{
    Meta: []*string{engine.String("stats/count([raw_data.time])"), engine.String("api/response(primary)")},
})

Using our Python SDK, that same call looks like this:

query_response = api_client.siem.query_events(
    meta=[
        "stats/count([raw_data.time])",
        "api/response(primary)",
    ],
)

Review the documentation for each specific SDK to best determine how the call arguments provided for that language.

Responses

When a Synqly endpoint supports meta functions, the returned data will include a top level "meta" item. This will then provide results organized first by group, then by function.

https://api.synqly.com/v1/siem/event?meta=stats/count()&meta=api/response(primary)

{
    "response": {},
    "cursor": "...",
    "meta": {
        "api": {
            "response": {
                "primary": {
                    "url": "https://example.com/api/getThing",
                    "response": "...raw response string..."
                }
            }
        },
        "stats": {
            "count": {
                "*": 308
            }
        }
    }
}

Available Functions

Look at individual endpoints to determine support for a specific meta function.

api/response

This function is used to include the raw response from API calls made from Synqly to the provider API.

api/response(responses, <[filters...]>

• responses: An enum, it must be 'primary', 'list', or 'all'.
  • primary: Include the raw response for the 'primary' call in the meta response. This is generally the final call that populates the data in the Synqly response.
  • list: Include all raw responses for made to the backing provider API, organized by URL, filtered by any filters....
  • all: Include both the singled out 'primary' response as well as the list of all responses, filtered by filters....
• [filters...]: Optional. An array of strings. This represents an allow list of URLs to include the the responses list. These filters can contain leading or trailing * s to indicate wildcards.

Examples

• api/response(primary)
• api/response(list)
• api/response(list,[http://example.com/api/call, http://sub.example.com/api/call?filter=example&limit=5] api/response(all)
• api/response(all, [http://example.com*, */api/call, *filter=example*]

Meta Return

The API return will include meta data shaped similarly to the following:

api/response(all)

{
    "meta": {
        "api": {
            "response": {
                "primary": {
                    "url": "https://example.com/api/v1/getThing",
                    "response": "...raw response string..."
                },
                "list": {
                    "https://example.com/api/v1/getThing": [
                        "...raw response string..."
                    ],
                    "https://example.com/api/v1/polledSupportingCall": [
                        "...first call raw response string...",
                        "...second call raw response string...",
                        "...third call raw response string..."
                    ]
                }
            }
        }
    }
}

stats/count

This function is used to calculate count statistics on a returned set of data. Without argument it returns the total count of items available. With arguments, it breaks up the count into facet by any passed facets fields.

stats/count(<[facets...]>

• [facets]: Optional. If excluded, the total count is returned. If included, each provided value will further break up the data, returning an individual count for each bucket.

Note: For many providers, running a statistics query is performed as an alternative to a data query. As a result, running a stats query may populate the response meta, but result in an empty data set.

Examples

• stats/count()
• stats/count([time])
• stats/count([raw_data.message, raw_data.activity_id])

Meta Return

The API return will include meta data shaped similarly to the following:

stats/count()

{
    "meta": {
        "stats": {
            "count": {
                "*": 345
            }
        }
    }
}

stats/count([raw_data.message, raw_data.activity_id])

{
    "meta": {
        "stats": {
            "count": {
                "message:example1,activity_id:1": 21,
                "message:example2,activity_id:1": 55,
                "message:example1,activity_id:2": 146,
                "message:example2,activity_id:2": 123,
            }
        }
    }
}