Introduction to monopole.tech

Overview

The monopole platform provides a unified API for ingesting field data, running detection pipelines, and managing experiment metadata. Whether you are building a small-scale physics simulation or a distributed observatory network, the same primitives apply.

This documentation is organized into four main sections: Getting Started walks you through your first request, API Reference documents every endpoint, Guides covers production patterns, and Examples contains runnable client code.

Installation

The official client libraries are distributed through standard package managers. Install the SDK that matches your runtime:

# Node.js
npm install @monopole/sdk

# Python
pip install monopole

# Go
go get github.com/monopole-tech/go-sdk

Each client targets the same REST API and shares a consistent resource model. Behavior is identical across runtimes — only the syntax differs.

Quickstart

Make your first request by initializing the client with an API key and creating a monopole record. The example below detects a hypothetical monopole event and records its measured flux.

import { Monopole } from '@monopole/sdk';

const client = new Monopole({
  apiKey: process.env.MONOPOLE_API_KEY,
  apiVersion: '2026-01-15',
});

const event = await client.monopoles.create({
  detector: 'det_north_42',
  flux: 1.4e-15,         // particles per cm^2 per second
  charge: 'magnetic',
  metadata: { run: 'rn_88a' },
});

console.log(event.id);

If everything is configured correctly, the API returns a monopole resource with a generated identifier and an ISO-8601 timestamp.

{
  "id": "mp_01HMR8X9C2",
  "object": "monopole",
  "detector": "det_north_42",
  "flux": 1.4e-15,
  "charge": "magnetic",
  "created_at": "2026-04-04T22:13:58Z"
}

Configuration

Client behavior is controlled through a single configuration object. The most common parameters are listed below.

API Reference Overview

The monopole API is organized around RESTful resources and uses predictable URLs, accepts application/json request bodies, returns application/json responses, and uses standard HTTP response codes.

Base URL

https://api.monopole.tech/v3

Authentication

All API requests must be authenticated using an API key sent via the Authorization header. Keys are scoped to a single environment.

Authorization: Bearer sk_live_a1b2c3d4e5f6

The Monopole object

A Monopole represents a recorded detection event. Each event carries field measurements, detector context, and audit metadata.

Create a monopole

Records a new detection event. The flux and detector fields are required.

POST /v3/monopoles

Retrieve a monopole

Returns the monopole resource matching the supplied identifier.

GET /v3/monopoles/{id}

List all monopoles

Returns a paginated list of monopole resources. Pagination is cursor-based, controlled with starting_after and limit.

GET /v3/monopoles?limit=20

Errors

The API uses conventional HTTP response codes. Codes in the 2xx range indicate success, 4xx indicate caller errors, and 5xx indicate platform errors.