On This Page

Home / Cribl as Code/Cribl API

Cribl API

The Cribl API is a RESTful API that provides a centrally managed control plane for programmatically configuring and managing Cribl resources. Developers can use the API to:

  • Retrieve and manage data.
  • Automate repetitive manual processes.
  • Integrate with third-party applications.
  • Consistently replicate environments and resources for testing, development, and deployment.

The Cribl API generally follows a resource-based structure in which each endpoint corresponds with a specific Cribl resource or collection of resources. In request URLs, resource-specific paths branch off from the base URL.

Read the Authentication page to learn how to authenticate to the Cribl API.

About PATCH Requests

In the Cribl API for the control plane, PATCH requests require a complete representation of the resource that you want to update. Endpoints that use the PATCH method do not support partial updates. Cribl removes any omitted fields when updating the resource. If you use a GET request to retrieve an existing configuration to use in the body of a PATCH request, confirm that the configuration is correct. If the existing configuration is incorrect, the updated resource may not function as expected. The Update Configurations workflow provides an example for updating a Destination using the PATCH method.

The Cribl API for the management plane does support partial updates for endpoints that use the PATCH method.

Try It Out

The API Reference is also available in Cribl at Settings > Global > API Reference. We recommend using the in-product API Reference because it features a Try it out button for each endpoint that you can use to construct and execute a curl command and examine the response. The in-product API Reference aligns with your environment and provides a seamless testing experience.

At the top of the in-product API Reference, a Servers drop-down menu lists the base URLs associated with your Stream Leader and Worker Groups, Edge Fleets, and Search instance. Try it out commands use the base URL that you select from the Servers drop-down menu. The default selection in the Servers drop-down is the base URL for your Leader.

Base URLs

The base URL is the root address for making requests to the Cribl API. The standardized base URL format provides a consistent, predictable pattern.

Follow the format examples in this section to construct the base URL for your Cribl deployment.

To compose the complete URL for a request to a specific endpoint, append the endpoint path that is listed in the API Reference to your base URL (for example, https://myapp.goatfarm.com:3000/api/v1/m/devgroup/routes).

Base URLs on Cribl.Cloud

On Cribl.Cloud, the base URL format for Cribl Stream, Edge, and Lake endpoints is:

https://${workspaceName}-${organizationId}.cribl.cloud/api/v1

For requests that are specific to a certain Worker Group or Fleet, the base URL includes /m and the name of the Worker Group or Fleet:

https://${workspaceName}-${organizationId}.cribl.cloud/api/v1/m/${groupName}

For licenses that are limited to a single Worker Group, the groupName is always default.

For Cribl Search endpoints, the base URL includes /m and default_search:

https://${workspaceName}-${organizationId}.cribl.cloud/api/v1/m/default_search

Base URLs in Customer-Managed Deployments

Customers who manage their own single-instance deployments use the following base URL format:

https://${hostname}:${port}/api/v1

In Distributed deployments that are customer-managed, the base URL includes /m and the name of the Worker Group or Fleet:

https://${hostname}:${port}/api/v1/m/${groupName}

For licenses that are limited to a single Worker Group, the groupName is always default.

Path Parameters

Many Cribl API endpoints require to you provide path parameters. Most path parameters are used to specify individual resources. For example, in the endpoint GET /pack/{id}, the {id} identifies the specific Cribl Pack to retrieve.

For some endpoints, path parameters limit the scope of the request in some way. For example, in the endpoint GET /products/{product}/groups, the {product} path parameter indicates the Cribl product whose Worker Groups or Edge Fleets should be listed in the response. In another example, GET /p/{pack}/pipelines, the {pack} path parameter limits the response to Pipelines within the specified Pack.

The API Reference identifies and describes the path parameters for each endpoint.

Query Parameters

Some Cribl API endpoints support optional query parameters for filtering or modifying the response. For example, endpoints that return a list of objects can have lengthy responses, so they might support limit and offset query parameters to use for paginating the response. Other endpoints might support query parameters that allow you to specify additional properties to include in the response or a JavaScript expression to apply as a filter.

The API Reference identifies and describes the supported query parameters for each endpoint.

Request Size Limit

The size limit for requests to the Cribl API is 5 MB.

Media Types

For endpoints that require a request body (typically POST, PUT, and PATCH), the server expects a valid Content-Type request header that specifies the media type of the request body. In this example request, the Content-Type value is application/json:

curl --request POST \
--url 'https://${workspaceName}-${organizationId}.cribl.cloud/api/v1/m/default_search/search/jobs' \
--header 'Authorization: Bearer ${token}' \
--header 'Content-Type: application/json' \
--data '{
  "query": "cribl dataset=\"goatherd_sample_dataset\" | limit 1000",
  "earliest": "-1h",
  "latest": "now",
  "sampleRate": 1
}'

If the request omits the Content-Type header or the value does not match the supported media type for the endpoint, the server might return an error.

For most POST, PUT, and PATCH endpoints in the Cribl API, the media type for the request body is application/json. Some endpoints support other media types, such as application/x-ndjson or application/x-www-form-urlencoded. The API Reference specifies the supported media type for each endpoint in the Request body drop-down list.

Location of the request body media type for an endpoint in the API Reference.
Endpoint's request body media type in API Reference

The API Reference also specifies the media type for each endpoint’s responses, which is helpful for ensuring proper data processing.

Location of the response media type for an endpoint in the API Reference.
Endpoint's response media type in API Reference

HTTP Status Codes

The Cribl API can return the following HTTP status codes in response headers:

HTTP Status CodeMeaning
200 OKThe request was successful.
204 No ContentThe request was successful, but there is no content to send in the response. Often used for DELETE requests.
400 Bad RequestThe server could not understand the request due to malformed syntax or missing parameters.
401 UnauthorizedAuthentication failed because credentials are missing or invalid.
403 ForbiddenThe server understood the request but did not authorize it because permissions are insufficient to access the requested resource.
404 Not FoundThe requested resource was not found. The endpoint may not exist or the resource may be unavailable.
405 Method Not AllowedThe request method is not supported for the resource (for example, a POST request for a resource that only supports GET).
415 Unsupported Media TypeThe server did not accept the request because the payload is in an unsupported data format. Often indicates that the Content-Type header is incorrect.
420 Shutting DownThe server is in the process of shutting down or is in standby.
429 Too Many RequestsThe number of requests exceeds the loginRateLimit or ssoRateLimit setting.
500 Internal Server ErrorThe server encountered an unexpected condition that prevented it from fulfilling the request.
502 Bad GatewayWhile acting as a gateway or proxy, the server received an invalid response from the upstream server.
503 Service UnavailableThe server could not handle the request due to temporary overload or maintenance.

See the MDN Web Docs for more information about HTTP status codes.