Skip to main content

​
Overview

The Garnet API Go SDK is the official client library for interacting with the Garnet platform. It provides a comprehensive set of tools for managing runtime security agents, monitoring events, and implementing network policies across your infrastructure.

Quickstart

Get up and running with the SDK in minutes

API Reference

Explore all available methods and types

Core Concepts

Learn about agents, events, and policies

GitHub

View source code and contribute

​
Key Features

Create, update, and monitor security agents across your infrastructure. Support for multiple agent types including GitHub Actions, Kubernetes, and vanilla deployments.
  • Register agents with custom metadata and labels
  • Track agent health with heartbeat monitoring
  • Filter and query agents by environment, version, or custom attributes
  • Manage agent lifecycle across different platforms
Ingest and query security events from your agents in real-time.
  • Stream events using the ashkaal format
  • Filter events by agent, time range, or metadata
  • Block malicious events with network policies
  • Paginated event queries with flexible sorting
Implement granular network policies to control and block suspicious traffic.
  • Define policies at project, cluster, or agent scope
  • Create rules based on event patterns
  • Automatic policy enforcement across agents
Built-in support for organizations and projects with role-based access control.
  • Project-level resource isolation
  • Multiple authentication methods (user, agent, project tokens)
  • Organization-wide settings and policies

​
Architecture

The SDK is built around a central Client type that handles all HTTP communication with the Garnet API. It supports:
  • Multiple Authentication Types: User tokens, agent tokens, and project tokens
  • Flexible Base URL: Connect to different Garnet environments or self-hosted instances
  • Cursor & Offset Pagination: Efficient data retrieval for large datasets
  • Type-safe API: Comprehensive type definitions for all request and response models
The SDK uses github.com/garnet-org/jibril-ashkaal for event formatting and requires Go 1.25.0 or later.

​
Authentication Methods

Garnet supports three token types for different use cases:
Token TypeUse CaseHeader
User TokenAPI access for authenticated usersAuthorization: Bearer <token>
Agent TokenAgent-to-API communicationX-Agent-Token: <token>
Project TokenProject-scoped automationX-Project-Token: <token>
Agent tokens are automatically issued when you create a new agent via CreateAgent(). Store these securely for your agent deployments.

​
Agent Types

Garnet supports multiple agent deployment models: 
agent := types.CreateAgent{
    Kind:     types.AgentKindGithub,
    OS:       "linux",
    Arch:     "amd64",
    Hostname: "runner-1",
    Version:  "1.0.0",
    IP:       "10.0.1.5",
    MachineID: "gh-runner-abc123",
    GithubContext: &types.AgentGithubContext{
        Repository: "myorg/myrepo",
        RunID:      "123456789",
    },
}

​
Pagination Strategies

The SDK supports two pagination methods:

​
Cursor-based Pagination

Recommended for real-time data and large datasets. Used by Agents() and similar methods. 
pageArgs := types.CursorPageArgs{
    First: ptr(50), // Fetch first 50 items
}

result, err := client.Agents(ctx, types.ListAgents{
    ProjectID: projectID,
    PageArgs:  pageArgs,
})

// Next page
if result.PageInfo.HasNextPage {
    nextArgs := types.CursorPageArgs{
        First: ptr(50),
        After: result.PageInfo.EndCursor,
    }
}

​
Offset-based Pagination

Traditional page-based pagination. Used by legacy endpoints. 
page := 1
perPage := 20

result, err := client.LegacyAgents(ctx, types.LegacyListAgents{
    PageArgs: types.PageArgs{
        Page:    &page,
        PerPage: &perPage,
    },
})

​
Error Handling

The SDK uses typed errors from the types/errs package: 
switch {
case errors.Is(err, types.ErrAgentNotFound):
    // Handle agent not found
case errors.Is(err, types.ErrUnauthorizedAgent):
    // Handle permission denied
default:
    // Handle other errors
}
Always check for errors returned by SDK methods. The API will return HTTP 400+ status codes for invalid requests, which are surfaced as Go errors.

​
Support

Documentation

Comprehensive guides and tutorials

GitHub Issues

Report bugs or request features

​
Next Steps

1

Install the SDK

Add the Garnet API SDK to your Go project
go get github.com/garnet-org/api
2

Follow the Quickstart

Learn how to initialize the client and make your first API call View Quickstart →
3

Explore Core Concepts

Learn about agents, events, issues, and network policies View Core Concepts →

Build docs developers (and LLMs) love

Get started for freeTalk to us