> For the complete documentation index, see [llms.txt](https://docs.groundcover.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.groundcover.com/reference/remote-access-and-apis/sdks.md).

# API SDKs

Install the official Go, Python, and TypeScript SDKs to query data and manage groundcover resources.

The groundcover API SDKs provide typed clients for querying observability data and managing resources such as dashboards, monitors, destinations, and notification routes. These are API clients; use the [OpenTelemetry integration](/collect-data/opentelemetry.md) to instrument applications.

## Authentication

Create an [API key](/administer/api-keys.md) for a [service account](/administer/service-accounts.md) with the permissions needed for your operation. An ingestion key cannot be used to manage resources or query data.

For operations marked **Admin required**, the service account must have Admin permissions. Check the operation's [API example](/reference/remote-access-and-apis/api-examples.md#permissions) for its required role and any additional authentication requirements.

The SDKs read these environment variables:

```bash
export GC_API_KEY='<YOUR_API_KEY>'
export GC_BACKEND_ID='<YOUR_BACKEND_ID>'
export GC_BASE_URL='https://api.groundcover.com'
```

Find the Backend ID under **Settings → Access → API Keys**. For a self-hosted deployment, set `GC_BASE_URL` to your environment's API URL and use an API key issued by that environment. Keep API keys in server-side code or a secret store, not in browser applications.

## Go

Install the [Go SDK](https://github.com/groundcover-com/groundcover-sdk-go):

```bash
go get github.com/groundcover-com/groundcover-sdk-go
```

Initialize a client using the environment variables above:

```go
package main

import (
    "log"
    groundcover "github.com/groundcover-com/groundcover-sdk-go"
)

func main() {
    client, err := groundcover.NewClient()
    if err != nil {
        log.Fatal(err)
    }
    _ = client // Use client.Dashboards, client.Metrics, and other services.
}
```

See the [Go API reference](https://pkg.go.dev/github.com/groundcover-com/groundcover-sdk-go) and [runnable examples](https://github.com/groundcover-com/groundcover-sdk-go/tree/main/examples).

## Python

Install the [Python SDK](https://github.com/groundcover-com/groundcover-sdk-python) from GitHub into your project:

```bash
uv add "git+https://github.com/groundcover-com/groundcover-sdk-python.git"
```

Create a client and call a typed API function:

```python
from datetime import datetime, timedelta, timezone

import groundcover
from groundcover.api.metrics import metrics_query
from groundcover.models.query_request import QueryRequest
from groundcover.models.query_request_query_type import QueryRequestQueryType

now = datetime.now(timezone.utc)
with groundcover.Client() as client:
    result = metrics_query.sync_detailed(
        client=client,
        body=QueryRequest(
            promql="up",
            query_type=QueryRequestQueryType.INSTANT,
            start=now - timedelta(hours=1),
            end=now,
            step="1m",
        ),
    )
    print(result.parsed)
```

Typed operations expose synchronous and asynchronous methods. See the [Python README](https://github.com/groundcover-com/groundcover-sdk-python#readme) for configuration and examples.

## TypeScript / JavaScript

Install [`@groundcover/api-client`](https://www.npmjs.com/package/@groundcover/api-client):

```bash
npm install @groundcover/api-client
```

Run this example in a server-side JavaScript or TypeScript environment:

```typescript
import { initClient, metricsQuery } from '@groundcover/api-client';

const client = initClient();
const now = new Date();
const result = await metricsQuery({
  client,
  body: {
    Promql: 'up',
    QueryType: 'instant',
    Start: new Date(now.getTime() - 60 * 60 * 1000).toISOString(),
    End: now.toISOString(),
    Step: '1m',
  },
});
console.log(result.data);
```

See the [TypeScript SDK repository](https://github.com/groundcover-com/groundcover-sdk-typescript) for configuration and typed operations.

## REST and SDK coverage

The SDKs cover a selected set of API operations. An endpoint in [API Examples](/reference/remote-access-and-apis/api-examples.md) may not yet have a typed method in your installed SDK. Use the documented HTTP endpoint when needed, and check the SDK's generated operations before assuming a method exists.

Workflow methods have been removed from the Go SDK. For notification automation, use [Destinations](/reference/remote-access-and-apis/api-examples/destinations-api.md) and [Notification Routes](/reference/remote-access-and-apis/api-examples/notification-routes-api.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.groundcover.com/reference/remote-access-and-apis/sdks.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.