perses-api-sdk

A Python SDK for the Perses API.

Requirements

• Python 3.12+
• A running Perses instance

Installation

pip install perses-api-sdk

Quick start

from perses_api import APIModel, Project, Dashboard
from perses_api.model import Metadata, ProjectSpec, DashboardSpec
from perses_api.model import Project as ProjectModel, Dashboard as DashboardModel

# Connect with a bearer token
client = APIModel(host="http://localhost:8080", token="<your-token>")

# Or connect with username/password (Basic auth)
client = APIModel(host="http://localhost:8080", username="admin", password="password")

# Create a project
projects = Project(client)
project = projects.create_project(
    ProjectModel(metadata=Metadata(name="my-project"), spec=ProjectSpec())
)

# Create a dashboard inside it
dashboards = Dashboard(client)
dashboard = dashboards.create_dashboard(
    "my-project",
    DashboardModel(
        metadata=Metadata(name="my-dashboard", project="my-project"),
        spec=DashboardSpec(),
    ),
)

Authentication

Pass a bearer token via token=, or supply username= and password= for HTTP Basic auth. When both are provided, the token takes precedence.

# Bearer token
client = APIModel(host="http://localhost:8080", token="eyJ...")

# Basic auth
client = APIModel(host="http://localhost:8080", username="admin", password="secret")

Available clients

Configuration options

client = APIModel(
    host="http://localhost:8080",
    token="<token>",
    timeout=30.0,           # request timeout in seconds (default: 10)
    http2_support=False,    # enable HTTP/2 (requires httpx[http2])
    num_pools=10,           # max concurrent connections
    retries=False,          # retry failed requests
    follow_redirects=True,  # follow HTTP redirects
)

Examples

Datasource

from perses_api import APIModel, ProjectDatasource
from perses_api.model import Metadata, DatasourceSpec, Datasource as DatasourceModel

client = APIModel(host="http://localhost:8080", token="<token>")
ds = ProjectDatasource(client, "my-project")

created = ds.create_datasource(
    DatasourceModel(
        metadata=Metadata(name="prometheus", project="my-project"),
        spec=DatasourceSpec(
            default=True,
            plugin={
                "kind": "PrometheusDatasource",
                "spec": {"directUrl": "http://prometheus:9090"},
            },
        ),
    )
)

Migrate a Grafana dashboard

from perses_api import APIModel, Migrate

client = APIModel(host="http://localhost:8080", token="<token>")
m = Migrate(client)

perses_dashboard = m.migrate(grafana_dashboard={"title": "My Dashboard", "panels": []})

Validate a dashboard

from perses_api import APIModel, Validate

client = APIModel(host="http://localhost:8080", token="<token>")
v = Validate(client)

v.validate(dashboard={"kind": "Dashboard", "metadata": {}, "spec": {}})

Development

Setup

# Install with test dependencies
uv sync --extra test

# Install with docs dependencies
uv sync --extra docs

Running integration tests

Requires Docker.

make integration

Or against an existing Perses instance:

PERSES_HOST=http://localhost:8080 \
PERSES_USERNAME=admin \
PERSES_PASSWORD=password \
uv run pytest tests/integration/ -v

License

Apache 2.0