Enterprise Open source Grafana Cloud

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.

MethodSummaryPath
GETList short URLsshorturls
GETGet a short URLshorturls/{name}
GETResolve a short URLshorturls/{name}/goto
POSTCreate a short URLshorturls
PUTUpdate a short URLshorturls/{name}
DELETEDelete a short URLshorturls/{name}

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:

http
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
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 the metadata.name field in the short URL response.

Required permissions: Any authenticated user.

Example request

The following example shows a request to get a short URL:

http
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
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 to false to 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:

http
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
HTTP/1.1 302 Found
Location: https://grafana.example.com/d/TxKARsmGz/new-dashboard?orgId=1&from=1599389322894&to=1599410922894

Example 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:

http
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
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:

http
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.generateName to 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-dashboard or explore?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:// or javascript:

Example response

The following example shows the response:

http
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:

http
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
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:

http
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
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:

CodeMeaningReturned by
200OK.List, Get, Update, Delete
200OK, when redirect=false.Resolve
201Created.Create
201Created, if the short URL doesn’t exist and the request body doesn’t include metadata.resourceVersion.Update
302Found, redirects to the full URL.Resolve
400Bad request (invalid JSON or invalid metadata.name).Create, Update
401Unauthorized.All endpoints
403Access denied (only organization administrators can list short URLs).List
403Access denied.Get, Resolve
403Access denied, or the path is invalid.Create
403Access denied (only organization administrators can update short URLs), or the path is invalid.Update
403Access denied (only organization administrators can delete short URLs).Delete
404Short URL not found.Get, Resolve, Delete
409Conflict (a short URL with the same name already exists).Create
409Conflict (the short URL changed or was deleted since you read it).Update

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:

Legacy endpointNew endpoint
POST /api/short-urlsPOST /apis/shorturl.grafana.app/v1beta1/namespaces/{namespace}/shorturls
GET /api/short-urls/:uidGET /apis/shorturl.grafana.app/v1beta1/namespaces/{namespace}/shorturls/{name}
GET /goto/:uidGET /apis/shorturl.grafana.app/v1beta1/namespaces/{namespace}/shorturls/{name}/goto

When you migrate, consider the following differences:

  • Request body: The legacy path and uid fields move to spec.path and metadata.name.
  • Response body: The legacy API returns uid and a ready-to-share url. The new API returns the full ShortURL object, so build the shareable URL from metadata.name as described in Create a short URL.
  • New operations: The new API also supports listing, updating, and deleting short URLs, which require the Admin role.