---
title: "Short URL HTTP API | Grafana documentation"
description: "Grafana Short URL HTTP API"
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# 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](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/apis/).
> 
> The legacy [Short URL API](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/api-legacy/short_url/) is still available, and removal will be announced well in advance to avoid disruptions. Refer to [Migrate from the legacy Short URL API](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/short_url/#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](https://play.grafana.org/swagger?api=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](https://grafana.com/docs/grafana/latest/administration/roles-and-permissions/#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](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/apis/).

Expand table

| Method | Summary                                                                                                                                  | Path                    |
|--------|------------------------------------------------------------------------------------------------------------------------------------------|-------------------------|
| GET    | [List short URLs](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/short_url/#list-short-urls)         | `shorturls`             |
| GET    | [Get a short URL](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/short_url/#get-a-short-url)         | `shorturls/{name}`      |
| GET    | [Resolve a short URL](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/short_url/#resolve-a-short-url) | `shorturls/{name}/goto` |
| POST   | [Create a short URL](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/short_url/#create-a-short-url)   | `shorturls`             |
| PUT    | [Update a short URL](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/short_url/#update-a-short-url)   | `shorturls/{name}`      |
| DELETE | [Delete a short URL](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/short_url/#delete-a-short-url)   | `shorturls/{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](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/apis/).

**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 ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```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 ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```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](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/apis/).
- `{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 ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```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 ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```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`](https://grafana.com/docs/grafana/latest/setup-grafana/configure-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`](https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/#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](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/apis/).
- `{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 ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```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 ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```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 ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```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 ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```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](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/apis/).

**Required permissions**: Any authenticated user.

### Example request

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

http ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```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`](https://grafana.com/docs/grafana/latest/setup-grafana/configure-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 ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```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](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/apis/).
- `{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 ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```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 ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```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](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/apis/).
- `{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 ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```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 ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

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

Expand table

| Code  | Meaning                                                                                                  | Returned by                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
|-------|----------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `200` | OK.                                                                                                      | [List](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/short_url/#list-short-urls), [Get](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/short_url/#get-a-short-url), [Update](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/short_url/#update-a-short-url), [Delete](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/short_url/#delete-a-short-url) |
| `200` | OK, when `redirect=false`.                                                                               | [Resolve](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/short_url/#resolve-a-short-url)                                                                                                                                                                                                                                                                                                                                                                        |
| `201` | Created.                                                                                                 | [Create](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/short_url/#create-a-short-url)                                                                                                                                                                                                                                                                                                                                                                          |
| `201` | Created, if the short URL doesn’t exist and the request body doesn’t include `metadata.resourceVersion`. | [Update](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/short_url/#update-a-short-url)                                                                                                                                                                                                                                                                                                                                                                          |
| `302` | Found, redirects to the full URL.                                                                        | [Resolve](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/short_url/#resolve-a-short-url)                                                                                                                                                                                                                                                                                                                                                                        |
| `400` | Bad request (invalid JSON or invalid `metadata.name`).                                                   | [Create](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/short_url/#create-a-short-url), [Update](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/short_url/#update-a-short-url)                                                                                                                                                                                                                                              |
| `401` | Unauthorized.                                                                                            | All endpoints                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `403` | Access denied (only organization administrators can list short URLs).                                    | [List](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/short_url/#list-short-urls)                                                                                                                                                                                                                                                                                                                                                                               |
| `403` | Access denied.                                                                                           | [Get](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/short_url/#get-a-short-url), [Resolve](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/short_url/#resolve-a-short-url)                                                                                                                                                                                                                                                  |
| `403` | Access denied, or the path is invalid.                                                                   | [Create](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/short_url/#create-a-short-url)                                                                                                                                                                                                                                                                                                                                                                          |
| `403` | Access denied (only organization administrators can update short URLs), or the path is invalid.          | [Update](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/short_url/#update-a-short-url)                                                                                                                                                                                                                                                                                                                                                                          |
| `403` | Access denied (only organization administrators can delete short URLs).                                  | [Delete](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/short_url/#delete-a-short-url)                                                                                                                                                                                                                                                                                                                                                                          |
| `404` | Short URL not found.                                                                                     | [Get](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/short_url/#get-a-short-url), [Resolve](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/short_url/#resolve-a-short-url), [Delete](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/short_url/#delete-a-short-url)                                                                                                                      |
| `409` | Conflict (a short URL with the same name already exists).                                                | [Create](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/short_url/#create-a-short-url)                                                                                                                                                                                                                                                                                                                                                                          |
| `409` | Conflict (the short URL changed or was deleted since you read it).                                       | [Update](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/short_url/#update-a-short-url)                                                                                                                                                                                                                                                                                                                                                                          |

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

Expand table

| Legacy endpoint            | New endpoint                                                                          |
|----------------------------|---------------------------------------------------------------------------------------|
| `POST /api/short-urls`     | `POST /apis/shorturl.grafana.app/v1beta1/namespaces/{namespace}/shorturls`            |
| `GET /api/short-urls/:uid` | `GET /apis/shorturl.grafana.app/v1beta1/namespaces/{namespace}/shorturls/{name}`      |
| `GET /goto/:uid`           | `GET /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](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/short_url/#create-a-short-url).
- **New operations:** The new API also supports listing, updating, and deleting short URLs, which require the Admin role.
