Short URL HTTP API
Note
Available in Grafana 12.4 and later.
This API complies with the new Grafana API structure. To learn more refer to documentation about the API structure in Grafana.
The legacy Short URL API is still available, and removal will be announced well in advance to avoid disruptions. Refer to Migrate from the legacy Short URL API to learn more about how both APIs match, and how to migrate.
This document may not contain the latest version of the API. For the most up-to-date list of available endpoints, refer to shorturl.grafana.app/v1beta1 in Swagger.
This API is in
beta, so it might change in future releases.
Use this API to create shortened URLs. A short URL represents a longer URL containing complex query parameters in a smaller and simpler format.
Requirements
Short URLs don’t use role-based access control. Any signed-in user, including users with the None role, can create, get, and resolve short URLs. Listing, updating, and deleting short URLs requires the Admin role. Listing is restricted to admins because it exposes every short URL in the organization. Updating and deleting are restricted because they can change or remove short URLs that other users created. For more information, refer to Organization roles.
Endpoints
The following table lists the main endpoints. The Swagger documentation also includes endpoints to search short URLs, delete a collection of short URLs, apply partial updates with PATCH, and read or update the status subresource.
Base path: /apis/shorturl.grafana.app/v1beta1/namespaces/{namespace}/
Replace {namespace} with your namespace. To learn which namespace to use, refer to the
API overview.
List short URLs
GET /apis/shorturl.grafana.app/v1beta1/namespaces/{namespace}/shorturls
Returns all short URLs in the organization. Use the limit query parameter to control the maximum number of short URLs returned. To retrieve more short URLs, use the continue token from the response to fetch the next page.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.
Query parameters:
limit(optional): Maximum number of short URLs to return.continue(optional): Continue token from a previous response to fetch the next page.
Required permissions: Admin role.
Example request
The following example shows a request to list short URLs:
GET /apis/shorturl.grafana.app/v1beta1/namespaces/default/shorturls HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The following example shows the response:
HTTP/1.1 200
Content-Type: application/json
{
"kind": "ShortURLList",
"apiVersion": "shorturl.grafana.app/v1beta1",
"metadata": {},
"items": [
{
"kind": "ShortURL",
"apiVersion": "shorturl.grafana.app/v1beta1",
"metadata": {
"name": "AT76wBvGk",
"namespace": "default",
"resourceVersion": "1762325460",
"creationTimestamp": "2026-11-05T06:51:00Z"
},
"spec": {
"path": "d/TxKARsmGz/new-dashboard?orgId=1&from=1599389322894&to=1599410922894"
},
"status": {
"lastSeenAt": 0
}
}
]
}Get a short URL
GET /apis/shorturl.grafana.app/v1beta1/namespaces/{namespace}/shorturls/{name}
Returns the short URL with the given name.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.{name}: The unique identifier of the short URL. This is themetadata.namefield in the short URL response.
Required permissions: Any authenticated user.
Example request
The following example shows a request to get a short URL:
GET /apis/shorturl.grafana.app/v1beta1/namespaces/default/shorturls/AT76wBvGk HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The following example shows the response:
HTTP/1.1 200
Content-Type: application/json
{
"kind": "ShortURL",
"apiVersion": "shorturl.grafana.app/v1beta1",
"metadata": {
"name": "AT76wBvGk",
"namespace": "default",
"resourceVersion": "1762325460",
"creationTimestamp": "2026-11-05T06:51:00Z"
},
"spec": {
"path": "d/TxKARsmGz/new-dashboard?orgId=1&from=1599389322894&to=1599410922894"
},
"status": {
"lastSeenAt": 1762325712000
}
}The response contains the following fields:
- metadata.name – The unique identifier of the short URL.
- spec.path – The path the short URL links to, relative to the Grafana
root_url. - status.lastSeenAt – The last time someone used the short URL, in milliseconds since the Unix epoch. The initial value is
0.
Resolve a short URL
GET /apis/shorturl.grafana.app/v1beta1/namespaces/{namespace}/shorturls/{name}/goto
Redirects to the full URL that the short URL links to. Grafana builds the full URL from its
root_url and the spec.path of the short URL, and updates status.lastSeenAt.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.{name}: The unique identifier of the short URL.
Query parameters:
redirect(optional): Set tofalseto return the full URL in a JSON body instead of redirecting.
Required permissions: Any authenticated user.
Example request
The following example shows a request to resolve a short URL:
GET /apis/shorturl.grafana.app/v1beta1/namespaces/default/shorturls/AT76wBvGk/goto HTTP/1.1
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The following example shows the response:
HTTP/1.1 302 Found
Location: https://grafana.example.com/d/TxKARsmGz/new-dashboard?orgId=1&from=1599389322894&to=1599410922894Example request with redirect=false
The following example shows a request with redirect=false, which returns the full URL in the response body instead of redirecting:
GET /apis/shorturl.grafana.app/v1beta1/namespaces/default/shorturls/AT76wBvGk/goto?redirect=false HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The following example shows the response:
HTTP/1.1 200
Content-Type: application/json
{
"url": "https://grafana.example.com/d/TxKARsmGz/new-dashboard?orgId=1&from=1599389322894&to=1599410922894"
}Create a short URL
POST /apis/shorturl.grafana.app/v1beta1/namespaces/{namespace}/shorturls
Creates a short URL.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.
Required permissions: Any authenticated user.
Example request
The following example shows a request to create a short URL:
POST /apis/shorturl.grafana.app/v1beta1/namespaces/default/shorturls HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>
{
"metadata": {
"generateName": "dash-"
},
"spec": {
"path": "d/TxKARsmGz/new-dashboard?orgId=1&from=1599389322894&to=1599410922894"
}
}JSON body schema:
- metadata.name – The unique identifier of the short URL. If you don’t want to provide one, set
metadata.generateNameto the prefix you want, and Grafana generates the rest of the name. - spec.path – The path to shorten, relative to the Grafana
root_url. For example,d/TxKARsmGz/new-dashboardorexplore?from=123&to=456.
The path must be relative. Grafana rejects the following paths:
- Absolute paths that start with
/ - Paths that contain
../or..\ - Paths that start with
//or\ - Paths that contain a URL scheme, such as
https://orjavascript:
Example response
The following example shows the response:
HTTP/1.1 201
Content-Type: application/json
{
"kind": "ShortURL",
"apiVersion": "shorturl.grafana.app/v1beta1",
"metadata": {
"name": "dash-7xkq2",
"namespace": "default",
"resourceVersion": "1762325460",
"creationTimestamp": "2026-11-05T06:51:00Z"
},
"spec": {
"path": "d/TxKARsmGz/new-dashboard?orgId=1&from=1599389322894&to=1599410922894"
},
"status": {
"lastSeenAt": 0
}
}To share the short URL, use <GRAFANA_URL>/goto/<NAME>?orgId=<ORG_ID>, where <NAME> is the metadata.name from the response.
Update a short URL
PUT /apis/shorturl.grafana.app/v1beta1/namespaces/{namespace}/shorturls/{name}
Replaces an existing short URL identified by name. Provide the full object, including metadata.resourceVersion from the latest version of the short URL.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.{name}: The unique identifier of the short URL.
Required permissions: Admin role.
Example request
The following example shows a request to update a short URL:
PUT /apis/shorturl.grafana.app/v1beta1/namespaces/default/shorturls/AT76wBvGk HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>
{
"kind": "ShortURL",
"apiVersion": "shorturl.grafana.app/v1beta1",
"metadata": {
"name": "AT76wBvGk",
"resourceVersion": "1762325460"
},
"spec": {
"path": "d/TxKARsmGz/new-dashboard?orgId=1&from=now-6h&to=now"
}
}Example response
The following example shows the response:
HTTP/1.1 200
Content-Type: application/json
{
"kind": "ShortURL",
"apiVersion": "shorturl.grafana.app/v1beta1",
"metadata": {
"name": "AT76wBvGk",
"namespace": "default",
"resourceVersion": "1762325999",
"creationTimestamp": "2026-11-05T06:51:00Z"
},
"spec": {
"path": "d/TxKARsmGz/new-dashboard?orgId=1&from=now-6h&to=now"
},
"status": {
"lastSeenAt": 1762325712000
}
}Delete a short URL
DELETE /apis/shorturl.grafana.app/v1beta1/namespaces/{namespace}/shorturls/{name}
Deletes an existing short URL identified by name. This operation can’t be reverted.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.{name}: The unique identifier of the short URL.
Required permissions: Admin role.
Example request
The following example shows a request to delete a short URL:
DELETE /apis/shorturl.grafana.app/v1beta1/namespaces/default/shorturls/AT76wBvGk HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The following example shows the response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "Status",
"apiVersion": "v1",
"metadata": {},
"status": "Success",
"code": 200
}Status codes
The endpoints on this page return the following status codes:
Migrate from the legacy Short URL API
The new API uses different request and response shapes than the legacy /api/short-urls endpoints, so changing the URL alone isn’t enough. The following table shows how the endpoints match:
When you migrate, consider the following differences:
- Request body: The legacy
pathanduidfields move tospec.pathandmetadata.name. - Response body: The legacy API returns
uidand a ready-to-shareurl. The new API returns the fullShortURLobject, so build the shareable URL frommetadata.nameas described in Create a short URL. - New operations: The new API also supports listing, updating, and deleting short URLs, which require the Admin role.


