Guides
Start typing to search…

The FSQL API

Introduction

The FSQL REST API provides a powerful interface for querying data using FSQL. It
allows users to search data, list available connectors, query schema information, etc., and receive buffered or streamed results as JSON.

This guide will walk you through the basics of using the API, from
authentication to executing queries and interpreting results.

Getting Started

What You'll Need

  • An HTTP client that can send JSON requests with custom headers (cURL, Postman, Insomnia, etc.)
  • A Query API key
  • Basic knowledge of the Query data model and/or OCSF (Open Cybersecurity Schema Framework)
  • Understanding of FSQL query syntax

API Basics

Authentication

All requests to the FSQL API require authentication using your API key, which should be passed in the x-token-authorization header.

If you don't have a Query API key, you can get one by following these steps:

  1. If you are not already a registered Query administrative user, register first from the Query login page (https://go.query.ai).

  2. Log in to Query as an administrative user. Generate a new API key as described below:

    1. Click on the Settings icon at the bottom of the left navigation bar and go to Settings.
    2. Click on the Organization section and click further to select the desired team.
    3. Click on Integrations and then click the 'Create' button to generate the API Key. Save it in a secure place for use in the following steps.

Request Format

Basic Request Structure

{
  "q": "YOUR FSQL QUERY HERE"
}

Response Formats

There are two response formats: traditional JSON over HTTP and Server-Sent Events (SSE).

JSON responses always have a command property with the name of the command that was invoked. They may have an error property with one or more error messages. Other properties vary by command.

SSE provides a stream of events and is especially useful when working with large QUERY result sets.

Server-Sent Events (SSE)

Events

Command

Command events describe the invoked FSQL command. There will always be one command event per request.

event: command
data: {"command": "EXPLAIN CONNECTORS"}

Error

Error events describe errors. There may be 0 or more error events per request.

event: error
data: {"error": "..."}

Metadata

Metadata events describe metadata about the response, like the search ID.

event: metadata
data: {"trace_id": "xyz123..."}

Data

Data events contain response data.

event: data
data: {...}

Tips for Using the API

  1. Start with EXPLAIN commands: Use the EXPLAIN commands to familiarize yourself with the available fields and how your queries translate to GraphQL.

  2. Handle SSE properly: When using the QUERY command, make sure your client can properly handle server-side events for streaming results.

  3. Mind your query complexity: Complex queries may take longer to process, especially when expanding FSQL paths to absolute schema references.

  4. Replace placeholders: Remember to replace YOUR_API_KEY in the examples with your actual API key.

Updated 1 day ago