Help us shape the future of Go! Take the 2026 Go Developer Survey

sentryapi

package
v1.4.15 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 19, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package sentryapi is the typed REST client for the ɳSentry cloud API.

Purpose: One client for both worlds — the hosted SaaS (api.sentry.nself.org) 

and a self-hosted / local sentry bundle (NSELF_SENTRY_API_URL).

Contract (v1, consumed by `nself sentry *` and the MCP sentry tools): 

Auth:   Authorization: Bearer nsk_<key>   (API keys issued per tenant, W1)
GET    /v1/me                              → {"tenant_id","email","tier","quotas":{dim:{"used","limit"}}}
GET    /v1/monitors                        → {"monitors":[Monitor]}
POST   /v1/monitors                        → 201 {"monitor":Monitor}
DELETE /v1/monitors/{id}                   → 204
POST   /v1/monitors/{id}/pause|resume      → {"monitor":Monitor}
GET    /v1/incidents?status=<s>            → {"incidents":[Incident]}
POST   /v1/incidents/{id}/ack|resolve      → {"incident":Incident}
GET    /v1/status-pages                    → {"status_pages":[StatusPage]}
POST   /v1/status-pages                    → 201 {"status_page":StatusPage}
GET    /v1/alerts/channels                 → {"channels":[AlertChannel]}
POST   /v1/alerts/channels/{id}/test       → {"delivered":bool,"detail":string}
Errors: non-2xx {"error":{"code","message"}}; 401 → ErrUnauthorized,
        402/429 → ErrQuotaExceeded (upgrade hint).

Constraints: no cobra imports here; pure HTTP + JSON so MCP and commands share it. SPORT: CLI-PKG-SENTRYAPI-001

Index

Constants

View Source 
const (
	EnvAPIURL = "NSELF_SENTRY_API_URL"
	EnvAPIKey = "NSELF_SENTRY_API_KEY"
)

EnvAPIURL / EnvAPIKey are the environment overrides for the client config.

View Source 
const DefaultAPIURL = "https://api.sentry.nself.org"

DefaultAPIURL is the hosted ɳSentry SaaS API endpoint.

View Source 
const KeyPrefix = "nsk_"

KeyPrefix is the required prefix for ɳSentry API keys.

Variables

View Source 
var ErrNotLoggedIn = errors.New("not logged in to ɳSentry — run 'nself sentry login'")

ErrNotLoggedIn is returned when no credentials file exists.

View Source 
var ErrQuotaExceeded = errors.New("quota exceeded for your tier — upgrade at https://sentry.nself.org/billing")

ErrQuotaExceeded is returned on HTTP 402/429 quota responses.

View Source 
var ErrUnauthorized = errors.New("unauthorized: invalid or missing API key — run 'nself sentry login'")

ErrUnauthorized is returned on HTTP 401 — the caller should suggest `nself sentry login`.

Functions

func DeleteCredentials 

func DeleteCredentials() error

DeleteCredentials removes the stored credentials (no-op when absent).

func Resolve 

func Resolve(flagURL, flagKey string) (apiURL, apiKey string)

Resolve computes the effective (apiURL, apiKey) using precedence: explicit args (flags) → env vars → credentials file → defaults. A missing key is not an error here — the API returns 401 and the client maps it to ErrUnauthorized with the login hint.

func ValidateKeyFormat 

func ValidateKeyFormat(key string) error

ValidateKeyFormat checks the nsk_ prefix without hitting the network.

func WriteCredentials 

func WriteCredentials(c *Credentials) error

WriteCredentials persists credentials at 0600 (dir 0700).

Types

type Account 

type Account struct {
	TenantID string                `json:"tenant_id"`
	Email    string                `json:"email"`
	Tier     string                `json:"tier"` // free | bundle | nself-plus
	Quotas   map[string]QuotaUsage `json:"quotas"`
}

Account is the response of GET /v1/me — identity, tier, and quota usage.

type AlertChannel 

type AlertChannel struct {
	ID      string `json:"id"`
	Kind    string `json:"kind"` // email | webhook | slack | telegram
	Target  string `json:"target"`
	Enabled bool   `json:"enabled"`
}

AlertChannel is a notification target (email/webhook/slack/telegram).

type Client 

type Client struct {
	BaseURL string
	APIKey  string
	HTTP    *http.Client
}

Client is a typed REST client for the ɳSentry API.

func New 

func New(baseURL, apiKey string) *Client

New returns a Client for baseURL/apiKey with a sane default timeout.

func (*Client) AckIncident 

func (c *Client) AckIncident(ctx context.Context, id string) (*Incident, error)

AckIncident acknowledges an open incident.

func (*Client) CreateMonitor 

func (c *Client) CreateMonitor(ctx context.Context, req CreateMonitorRequest) (*Monitor, error)

CreateMonitor creates a monitor and returns the created record.

func (*Client) CreateStatusPage 

func (c *Client) CreateStatusPage(ctx context.Context, req CreateStatusPageRequest) (*StatusPage, error)

CreateStatusPage creates a status page.

func (*Client) DeleteMonitor 

func (c *Client) DeleteMonitor(ctx context.Context, id string) error

DeleteMonitor removes a monitor by id.

func (*Client) ListAlertChannels 

func (c *Client) ListAlertChannels(ctx context.Context) ([]AlertChannel, error)

ListAlertChannels returns the tenant's alert channels.

func (*Client) ListIncidents 

func (c *Client) ListIncidents(ctx context.Context, status string) ([]Incident, error)

ListIncidents returns incidents, optionally filtered by status (open | acknowledged | resolved; empty = all).

func (*Client) ListMonitors 

func (c *Client) ListMonitors(ctx context.Context) ([]Monitor, error)

ListMonitors returns all monitors for the tenant.

func (*Client) ListStatusPages 

func (c *Client) ListStatusPages(ctx context.Context) ([]StatusPage, error)

ListStatusPages returns the tenant's status pages.

func (*Client) PauseMonitor 

func (c *Client) PauseMonitor(ctx context.Context, id string, pause bool) (*Monitor, error)

PauseMonitor pauses (paused=true) or resumes (paused=false) a monitor.

func (*Client) ResolveIncident 

func (c *Client) ResolveIncident(ctx context.Context, id string) (*Incident, error)

ResolveIncident resolves an incident.

func (*Client) TestAlertChannel 

func (c *Client) TestAlertChannel(ctx context.Context, id string) (*TestChannelResult, error)

TestAlertChannel sends a test notification through a channel.

func (*Client) WhoAmI 

func (c *Client) WhoAmI(ctx context.Context) (*Account, error)

WhoAmI returns the authenticated account (tier + quota usage).

type CreateMonitorRequest 

type CreateMonitorRequest struct {
	Name            string `json:"name"`
	URL             string `json:"url"`
	Kind            string `json:"kind"`
	IntervalSeconds int    `json:"interval_seconds"`
}

CreateMonitorRequest is the body of POST /v1/monitors.

type CreateStatusPageRequest 

type CreateStatusPageRequest struct {
	Name string `json:"name"`
	Slug string `json:"slug"`
}

CreateStatusPageRequest is the body of POST /v1/status-pages.

type Credentials 

type Credentials struct {
	APIURL string `json:"api_url"`
	APIKey string `json:"api_key"`
}

Credentials is the on-disk shape of ~/.nself/sentry.json.

func ReadCredentials 

func ReadCredentials() (*Credentials, error)

ReadCredentials loads the stored credentials, or ErrNotLoggedIn.

type Incident 

type Incident struct {
	ID             string `json:"id"`
	MonitorID      string `json:"monitor_id"`
	Title          string `json:"title"`
	Status         string `json:"status"` // open | acknowledged | resolved
	Severity       string `json:"severity"`
	StartedAt      string `json:"started_at"`
	AcknowledgedAt string `json:"acknowledged_at,omitempty"`
	ResolvedAt     string `json:"resolved_at,omitempty"`
}

Incident is a monitoring incident (open → acknowledged → resolved).

type Monitor 

type Monitor struct {
	ID              string `json:"id"`
	Name            string `json:"name"`
	URL             string `json:"url"`
	Kind            string `json:"kind"` // http | tcp | ping
	IntervalSeconds int    `json:"interval_seconds"`
	Status          string `json:"status"` // up | down | paused | pending
	Paused          bool   `json:"paused"`
	CreatedAt       string `json:"created_at"`
}

Monitor is an uptime monitor owned by the authenticated tenant.

type QuotaUsage 

type QuotaUsage struct {
	Used  int64 `json:"used"`
	Limit int64 `json:"limit"`
}

QuotaUsage is used/limit for a single quota dimension.

type StatusPage 

type StatusPage struct {
	ID        string `json:"id"`
	Name      string `json:"name"`
	Slug      string `json:"slug"`
	URL       string `json:"url"`
	Public    bool   `json:"public"`
	CreatedAt string `json:"created_at"`
}

StatusPage is a public status page owned by the tenant.

type TestChannelResult 

type TestChannelResult struct {
	Delivered bool   `json:"delivered"`
	Detail    string `json:"detail"`
}

TestChannelResult is the response of POST /v1/alerts/channels/{id}/test.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.