API Overview

Novacore REST API overview — base URLs, authentication, error handling, and conventions.

The Novacore REST API provides programmatic access to the Sourceful energy coordination platform. Manage organizations, sites, devices, and access real-time telemetry data.

Base URLs

Environment	Base URL
Testnet	`https://novacore-testnet.sourceful.dev`
Mainnet	`https://novacore-mainnet.sourceful.dev`

See Environments for details on when to use each.

Authentication

All authenticated endpoints require a JWT token in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Obtain a token via the challenge/verify flow. Tokens expire after 24 hours.

Request Format

Content-Type: application/json
All request bodies are JSON
All timestamps are ISO-8601 or Unix epoch milliseconds

Response Format

Successful responses return JSON:

{
  "id": "org-abc123",
  "name": "My Energy Lab",
  "created_at": "2026-03-06T10:00:00Z"
}

Error Responses

Errors return an appropriate HTTP status code with a JSON body:

{
  "error": "not_found",
  "message": "Organization not found"
}

Status Code	Description
`400`	Bad Request — invalid parameters
`401`	Unauthorized — missing or expired token
`403`	Forbidden — insufficient permissions
`404`	Not Found — resource doesn't exist
`409`	Conflict — resource already exists
`422`	Unprocessable Entity — validation failed
`429`	Too Many Requests — rate limited
`500`	Internal Server Error

Knowledge gap for Johan: Verify the exact error response format. Is there an error code field? What about validation error details (field-level errors)?

Pagination

Knowledge gap for Johan: How does pagination work? Cursor-based or offset-based? What are the query parameters and response envelope fields?

Rate Limiting

Knowledge gap for Johan: What are the rate limits per environment? Are they per-identity, per-org, or per-IP? What headers indicate rate limit status?

API Endpoints Overview

Section	Description
Auth & Identities	Authentication, challenge/verify, identity management
Organizations	Org CRUD, membership, roles
Sites	Site management within orgs
Devices & Gateways	Device provisioning, gateway claiming
Telemetry	SSE streams, historical data queries
Zap Local API	Local REST API on the gateway device
Price API	Electricity prices and grid tariffs
Public Data	Grid cells, DER types, device types (no auth required)

Streaming

For real-time data, Novacore provides:

SSE (Server-Sent Events) — for web apps and simple integrations
WebSocket — for bidirectional real-time communication
NATS — for backend services and integrations (requires approved access)

See Telemetry and Real-time Data guide for details.