The Correlation API from Grafana — 3 operation(s) for correlation.
openapi: 3.0.3
info:
title: Grafana HTTP Access Correlation API
description: The Grafana HTTP API provides programmatic access to Grafana's core functionality including dashboards, data sources, alerts, users, organizations, folders, annotations, and teams. Authentication is handled via API keys, basic auth, or OAuth tokens passed in the Authorization header.
version: 11.0.0
contact:
name: Grafana Labs
url: https://grafana.com
license:
name: AGPL-3.0
url: https://www.gnu.org/licenses/agpl-3.0.html
servers:
- url: https://{instance}.grafana.net/api
description: Grafana Cloud
variables:
instance:
default: your-instance
- url: http://localhost:3000/api
description: Local Grafana instance
security:
- BearerAuth: []
- BasicAuth: []
- ApiKeyAuth: []
tags:
- name: Correlation
paths:
/datasources/uid/{sourceUID}/correlations:
parameters: []
post:
tags:
- Correlation
summary: Grafana Create Correlation
description: Creates a new correlation in Grafana between two data sources, allowing users to establish relationships and navigate between different data sources using the specified source data source UID. This operation enables the creation of links that help connect related data across different monitoring or logging systems, facilitating easier investigation and analysis workflows by defining how data in one source relates to data in another source through correlation configurations.
operationId: createCorrelation
parameters:
- name: sourceUID
in: path
description: ''
required: true
schema:
type: string
requestBody:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCorrelationCommand'
required: true
responses:
'200':
description: (empty)
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCorrelationResponseBody'
'400':
description: BadRequestError is returned when the request is invalid and it cannot be processed.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'403':
description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'404':
description: NotFoundError is returned when the requested resource was not found.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
/datasources/uid/{sourceUID}/correlations/{correlationUID}:
parameters: []
get:
tags:
- Correlation
summary: Grafana Get Correlation
description: The Get Correlation API operation in Grafana retrieves a specific correlation configuration between data sources using their unique identifiers. By making a GET request to the endpoint `/datasources/uid/{sourceUID}/correlations/{correlationUID}`, users can fetch detailed information about an existing correlation, including its configuration settings, transformations, and the relationship between a source data source and a target data source. This operation requires both the unique identifier of the source data source (sourceUID) and the unique identifier of the specific correlation (correlationUID) to return the correlation object with all its associated metadata and configuration parameters.
operationId: getCorrelation
parameters:
- name: sourceUID
in: path
description: ''
required: true
schema:
type: string
- name: correlationUID
in: path
description: ''
required: true
schema:
type: string
responses:
'200':
description: (empty)
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/Correlation'
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'404':
description: NotFoundError is returned when the requested resource was not found.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
patch:
tags:
- Correlation
summary: Grafana Update Correlation
description: Updates an existing correlation identified by its UID within a specific data source, also identified by UID. This PATCH operation allows you to modify the properties of a correlation, which defines relationships between queries or data across different data sources in Grafana. The correlation UID and source data source UID must be provided in the path parameters to target the specific correlation to update. The request typically includes fields such as the target data source, transformation expressions, or correlation description that need to be modified. This endpoint is useful for maintaining and refining data relationships as your monitoring infrastructure evolves, enabling more sophisticated cross-data-source queries and visualizations without recreating correlations from scratch.
operationId: updateCorrelation
parameters:
- name: sourceUID
in: path
description: ''
required: true
schema:
type: string
- name: correlationUID
in: path
description: ''
required: true
schema:
type: string
requestBody:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateCorrelationCommand'
required: false
responses:
'200':
description: (empty)
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateCorrelationResponseBody'
'400':
description: BadRequestError is returned when the request is invalid and it cannot be processed.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'403':
description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'404':
description: NotFoundError is returned when the requested resource was not found.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
/datasources/uid/{uid}/correlations/{correlationUID}:
parameters: []
delete:
tags:
- Correlation
summary: Grafana Delete Correlation
description: 'This API operation deletes a specific correlation in Grafana by targeting both the data source and correlation identifiers. The endpoint requires two parameters: the UID of the data source that owns the correlation and the correlationUID which uniquely identifies the correlation to be removed. When executed with a DELETE HTTP method, it permanently removes the specified correlation configuration that links queries or data between different data sources, helping administrators clean up unused or outdated correlation rules within their Grafana instance.'
operationId: deleteCorrelation
parameters:
- name: uid
in: path
description: ''
required: true
schema:
type: string
- name: correlationUID
in: path
description: ''
required: true
schema:
type: string
responses:
'200':
description: (empty)
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteCorrelationResponseBody'
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'403':
description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'404':
description: NotFoundError is returned when the requested resource was not found.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
components:
schemas:
Correlation:
title: Correlation
type: object
properties:
config:
$ref: '#/components/schemas/CorrelationConfig'
description:
type: string
description: Description of the correlation
examples:
- Logs to Traces
label:
type: string
description: Label identifying the correlation
examples:
- My Label
orgId:
type: integer
description: OrgID of the data source the correlation originates from
contentEncoding: int64
examples:
- 1
provisioned:
type: boolean
description: Provisioned True if the correlation was created during provisioning
sourceUID:
type: string
description: UID of the data source the correlation originates from
examples:
- d0oxYRg4z
targetUID:
type: string
description: UID of the data source the correlation points to
examples:
- PE1C5CBDA0504A6A3
type:
type: string
description: 'the type of correlation, either query for containing query information, or external for containing an external URL
+enum'
uid:
type: string
description: Unique identifier of the correlation
examples:
- 50xhMlg9k
description: Correlation is the model for correlations definitions
DeleteCorrelationResponseBody:
title: DeleteCorrelationResponseBody
type: object
properties:
message:
type: string
examples:
- Correlation deleted
Type1:
title: Type1
enum:
- regex
- logfmt
type: string
UpdateCorrelationResponseBody:
title: UpdateCorrelationResponseBody
type: object
properties:
message:
type: string
examples:
- Correlation updated
result:
allOf:
- $ref: '#/components/schemas/Correlation'
- description: Correlation is the model for correlations definitions
CreateCorrelationCommand:
title: CreateCorrelationCommand
type: object
properties:
config:
$ref: '#/components/schemas/CorrelationConfig'
description:
type: string
description: Optional description of the correlation
examples:
- Logs to Traces
label:
type: string
description: Optional label identifying the correlation
examples:
- My label
provisioned:
type: boolean
description: True if correlation was created with provisioning. This makes it read-only.
targetUID:
type: string
description: Target data source UID to which the correlation is created. required if type = query
examples:
- PE1C5CBDA0504A6A3
type:
type: string
description: 'the type of correlation, either query for containing query information, or external for containing an external URL
+enum'
description: CreateCorrelationCommand is the command for creating a correlation
UpdateCorrelationCommand:
title: UpdateCorrelationCommand
type: object
properties:
config:
$ref: '#/components/schemas/CorrelationConfigUpdateDTO'
description:
type: string
description: Optional description of the correlation
examples:
- Logs to Traces
label:
type: string
description: Optional label identifying the correlation
examples:
- My label
type:
type: string
description: 'the type of correlation, either query for containing query information, or external for containing an external URL
+enum'
description: UpdateCorrelationCommand is the command for updating a correlation
CorrelationConfig:
title: CorrelationConfig
required:
- field
- target
type: object
properties:
field:
type: string
description: Field used to attach the correlation link
examples:
- message
target:
type: object
additionalProperties: {}
description: Target data query
examples:
- prop1: value1
prop2: value
transformations:
type: array
items:
$ref: '#/components/schemas/Transformation'
description: ''
type:
type: string
description: 'the type of correlation, either query for containing query information, or external for containing an external URL
+enum'
CorrelationConfigUpdateDTO:
title: CorrelationConfigUpdateDTO
type: object
properties:
field:
type: string
description: Field used to attach the correlation link
examples:
- message
target:
type: object
additionalProperties: {}
description: Target data query
examples:
- prop1: value1
prop2: value
transformations:
type: array
items:
$ref: '#/components/schemas/Transformation'
description: Source data transformations
examples:
- - type: logfmt
- expression: (Superman|Batman)
type: regex
variable: name
Transformation:
title: Transformation
type: object
properties:
expression:
type: string
field:
type: string
mapValue:
type: string
type:
$ref: '#/components/schemas/Type1'
ErrorResponseBody:
title: ErrorResponseBody
required:
- message
type: object
properties:
error:
type: string
description: Error An optional detailed description of the actual error. Only included if running in developer mode.
message:
type: string
description: a human readable version of the error
status:
type: string
description: 'Status An optional status to denote the cause of the error.
For example, a 412 Precondition Failed error may include additional information of why that error happened.'
CreateCorrelationResponseBody:
title: CreateCorrelationResponseBody
type: object
properties:
message:
type: string
examples:
- Correlation created
result:
allOf:
- $ref: '#/components/schemas/Correlation'
- description: Correlation is the model for correlations definitions
description: CreateCorrelationResponse is the response struct for CreateCorrelationCommand
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: Service account token or API key
BasicAuth:
type: http
scheme: basic
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
description: 'Format: Bearer <api-key>'