Constellation Overwatch

Complete API documentation for Constellation Overwatch.

Overview

Constellation Overwatch provides a RESTful API with bearer token authentication for managing organizations, entities, and telemetry data.

Authentication

All API requests require authentication using a bearer token in the Authorization header:

curl -H "Authorization: Bearer <your-token>" \
  http://localhost:8080/api/v1/organizations

Base URL

http://localhost:8080/api/v1

Configuration Variables

These environment variables configure the API server:

Variable	Default	Description
`OVERWATCH_TOKEN`	`reindustrialize-dev-token`	Unified token for API and NATS authentication
`PORT`	`8080`	HTTP server port
`DB_PATH`	`./db/constellation.db`	libSQL database path
`NATS_PORT`	`4222`	NATS server port
`NATS_DATA_DIR`	`./data/overwatch`	NATS data directory
`WEB_UI_PASSWORD`	(empty)	Password for Web UI access (leave empty to disable)

Endpoints

Organizations

Method	Endpoint	Description
`GET`	`/organizations`	List all organizations
`POST`	`/organizations`	Create a new organization
`GET`	`/organizations?org_id=xxx`	Get organization by ID

Create Organization:

curl -s -X POST http://localhost:8080/api/v1/organizations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Fleet",
    "org_type": "civilian",
    "description": "Test drone fleet"
  }'

Allowed org_type values: military, civilian, commercial, ngo

Entities

Method	Endpoint	Description
`GET`	`/entities?org_id=xxx`	List all entities in organization
`POST`	`/entities?org_id=xxx`	Create a new entity
`GET`	`/entities?org_id=xxx&entity_id=yyy`	Get entity by ID
`PUT`	`/entities?org_id=xxx&entity_id=yyy`	Update an entity
`DELETE`	`/entities?org_id=xxx&entity_id=yyy`	Delete an entity

Create Entity:

curl -s -X POST "http://localhost:8080/api/v1/entities?org_id=$ORG_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Drone-001",
    "entity_type": "aircraft_multirotor",
    "description": "Primary vegetation inspection drone",
    "metadata": {
      "model": "DJI-M300",
      "serial": "ABC123456"
    }
  }'

Health Check

Method	Endpoint	Description
`GET`	`/health`	Service health status

NATS Subjects

Entity Events

constellation.entities.{org_id}.created
constellation.entities.{org_id}.updated
constellation.entities.{org_id}.deleted
constellation.entities.{org_id}.status

Telemetry

constellation.telemetry.{org_id}.{entity_id}

Commands

constellation.commands.{org_id}.{entity_id}
constellation.commands.{org_id}.broadcast

Response Format

All responses are returned in JSON format:

{
  "success": true,
  "data": {
    "entity_id": "5458eec0-b0e3-4290-8db5-17936dbbfc64",
    "org_id": "ae9c65d0-b5f3-4cec-8ffa-68ff1173e050",
    "entity_type": "aircraft_multirotor",
    "status": "unknown",
    "priority": "normal",
    "is_live": false
  }
}

Error Handling

Errors are returned with appropriate HTTP status codes:

Status Code	Description
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing token
`404`	Not Found - Resource not found
`500`	Internal Server Error

Full API documentation with interactive examples coming soon.

API Reference