Purpose
Supported Versions
Gravwell’s Direct Query API is designed for REST-based access to Gravwell search and requires a valid Gravwell account or token with search access.
Authentication
Gravwell uses API tokens for external integrations.Authentication Fields
Example:
https://gravwell.company.com or http://199.244.253.132
Users only need to provide the
Instance_url and Token in the AirMDR integration UI.Role-Based Access Recommendations
Best Practice: Create a dedicated low-privilege token specifically for AirMDR integration usage.
Pre-requisites
Users must have Administrator access to the Gravwell UI with sufficient privileges to create or manage users and verify firewall settings.Permission to create API tokens in Gravwell.
Gravwell admins can restrict token creation for non-admin users using CBAC controls.
Setup Steps
1
Generate the Instance URL
- Log in to the Gravwell web UI.
- Identify the Gravwell server IP address or hostname that is reachable from the AirMDR platform or configured remote agent.
- Use the Gravwell base URL in one of the following formats: Using IP Address:
http://199.244.253.132
or, if SSL/TLS is enabled:https://199.244.253.132
Using Hostname:https://gravwell.company.com - Remove any additional paths after the hostname or IP address.
Use this:http://199.244.253.132orhttps://gravwell.company.com
Avoid this:http://199.244.253.132/api/search/directhttps://gravwell.company.com/search/history - Save this value as
Instance_url.TheInstance_urlmust contain only the Gravwell base URL or reachable IP address. API paths such as/api/parseand/api/search/directare automatically appended by the integration during API requests.Ensure the Gravwell IP address or hostname is reachable from the AirMDR platform or the configured remote agent.
2
Generate the API Token in Gravwell UI
- Log in to the Gravwell web UI.
- From the left navigation menu, go to: Tools & Resources → API Tokens.
The Gravwell API Token interface is located under Tools & Resources.

- Click Create Token or New Token.
- Enter a clear token name. Example:
AirMDR Integration Token - Add a description.
Example:Token used by AirMDR to query Gravwell alerts and telemetry. - Select the required permissions. Recommended minimum permissions:
Gravwell supports selecting permissions as grouped permissions or fine-grained controls.
- Set an expiration date, if required.

- Click Generate.
- Copy the generated token immediately.

- Store the token securely.
3
Generate the API Token in Gravwell UI
- Log in to the Gravwell web UI.
- From the left navigation menu, go to: Tools & Resources → API Tokens.
The Gravwell API Token interface is located under Tools & Resources.

- Click Create Token or New Token.
- Enter a clear token name. Example:
AirMDR Integration Token - Add a description.
Example:Token used by AirMDR to query Gravwell alerts and telemetry. - Select the required permissions. Recommended minimum permissions:
Gravwell supports selecting permissions as grouped permissions or fine-grained controls.
- Set an expiration date, if required.

- Click Generate.
- Copy the generated token immediately.

- Store the token securely.
Integration Credential Requirements
Use the following values in the AirMDR integration configuration screen:Gravwell Credential Reference Table
Validate Connectivity
Use the following command to verify connectivity and token authentication:Sample Request & Response – /api/parse
Sample Request & Response – /api/parse
Request:Sample successful response:Sample Failure Response:
Sample Request & Response – /api/search/direct
Sample Request & Response – /api/search/direct
Request:Sample Successful Response:Sample Failure Response:
The
/api/parse endpoint validates query syntax, while /api/search/direct executes the actual Gravwell search query and returns results.The token used must have
Search permission enabled; otherwise the API returns authorization failures.Configure Gravwell in AirMDR Integrations Dashboard
- Navigate to AirMDR, provide the credentials and click Login
- Navigate to the AirMDR Integrations Dashboard in the left navigation pane and select Integrations.
- Use the search option, enter the keyword “Gravwell”, select the Connections tab, and click + Create button.
- Enter an unique name to the Instance (e.g.,
your org name-Gravwell) to easily identify the user connection by AirMDR. - Enter the application credentials like Instance URL and Token in the Authentication Details field params, and click Save.
Skills provided by this Integration
Additional Information
🧰 Error Handling
🧰 Error Handling
🔄 Monitoring & Logs
🔄 Monitoring & Logs
🛑 Security & Access Best Practices
🛑 Security & Access Best Practices
Do
- Use a dedicated Gravwell token for AirMDR.
- Grant only required permissions.
- Set token expiration where possible.
- Store the token in a secure vault.
- Use HTTPS with valid TLS certificates.
- Rotate tokens periodically.
- Disable or delete unused tokens.
- Use a remote agent when Gravwell is not publicly reachable.
Avoid
- Do not use personal admin tokens for integrations.
- Do not share tokens over email or chat.
- Do not disable SSL verification unless approved internally.
- Do not grant token write permissions unless absolutely required.
- Do not reuse the same token across multiple tools.
👉 Support & Maintenance
👉 Support & Maintenance
- 📧 Contact AirMDR Support through your designated support channel.
- 🔁 Rotate credentials regularly. Recommended cadence: Every 90 days or as per internal security policy
- 🔄 Reconnect in AirMDR when secrets are changed.

