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:
-
If you are not already a registered Query administrative user, register first from the Query login page (https://go.query.ai).
-
Log in to Query as an administrative user. Generate a new API key as described below:
- Click on the Settings icon at the bottom of the left navigation bar and go to Settings.
- Click on the Organization section and click further to select the desired team.
- 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
- HTTP Method: POST
- Content-Type: application/json
- Request Body: JSON object with a
q
property containing your FSQL query - Endpoint: https://api.query.ai/search/translation/fsql
- [Optional] Accept: text/event-stream
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
-
Start with EXPLAIN commands: Use the EXPLAIN commands to familiarize yourself with the available fields and how your queries translate to GraphQL.
-
Handle SSE properly: When using the QUERY command, make sure your client can properly handle server-side events for streaming results.
-
Mind your query complexity: Complex queries may take longer to process, especially when expanding FSQL paths to absolute schema references.
-
Replace placeholders: Remember to replace
YOUR_API_KEY
in the examples with your actual API key.
Updated 1 day ago