HarchOS API /0.1

API Reference

Complete reference for HarchOS REST, gRPC, and WebSocket APIs. Authenticate, create workloads, deploy models, and monitor your infrastructure.

View SDKs Quickstart Guide

Base URL: https://api.harchos.io

Authentication

Authenticate Your Requests

API Keys

Simple key-based authentication for server-to-server communication. Pass your API key via the X-API-Key header or Authorization Bearer token.

X-API-Key: hrch_live_sk_abc123def456

Use case: Backend services, CLI tools, automation scripts

OAuth 2.0

Industry-standard authorization framework for third-party integrations. Supports Authorization Code, Client Credentials, and Device Code flows.

Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

Use case: Third-party integrations, user-facing applications

JWT Tokens

JSON Web Tokens for stateless session management. Tokens are signed with RSA-4096 and include sovereignty claims for data residency enforcement.

Authorization: Bearer <jwt_token>

Use case: Session management, service mesh authentication

REST API

REST Endpoints

The HarchOS REST API provides comprehensive access to compute, data, model, and operations resources. All endpoints use JSON for request and response bodies, follow OpenAPI 3.1 specification, and support pagination, filtering, and field selection.

Compute

7 endpoints

POST/v1/compute/workloadsCreate a new compute workload

GET/v1/compute/workloadsList all workloads with filters

GET/v1/compute/workloads/:idGet workload details and status

PATCH/v1/compute/workloads/:idUpdate workload configuration

DELETE/v1/compute/workloads/:idTerminate and remove a workload

POST/v1/compute/workloads/:id/scaleScale workload GPU allocation

POST/v1/compute/workloads/:id/migrateMigrate workload to another hub

Carbon-Aware Scheduling

6 endpoints

GET/v1/carbon/intensityGet real-time carbon intensity by zone

GET/v1/carbon/optimal-hubFind the hub with lowest carbon intensity for a workload

POST/v1/carbon/optimizeOptimize workload placement for carbon efficiency

GET/v1/carbon/forecastGet carbon intensity forecast with green window detection

GET/v1/carbon/metricsGet aggregate carbon metrics across the platform

GET/v1/carbon/dashboardFull carbon-aware dashboard data

Data

5 endpoints

POST/v1/data/pipelinesCreate a data ingestion pipeline

GET/v1/data/pipelinesList all data pipelines

POST/v1/data/pipelines/:id/ingestTrigger data ingestion run

GET/v1/data/lakesList data lake storage volumes

POST/v1/data/lakes/:id/snapshotCreate a point-in-time snapshot

Models

6 endpoints

POST/v1/modelsRegister a new AI model

GET/v1/modelsList registered models

POST/v1/models/:id/deployDeploy model to inference endpoint

POST/v1/models/:id/trainStart model training job

GET/v1/models/:id/metricsGet model performance metrics

POST/v1/inferenceRun inference on a deployed model

Pricing

5 endpoints

GET/v1/pricing/plansList pricing plans with GPU type, tier, and region filters

GET/v1/pricing/plans/:idGet specific pricing plan details

GET/v1/pricing/estimateCalculate cost estimate for a workload configuration

GET/v1/pricing/billing/recordsList user billing records (auth required)

GET/v1/pricing/billing/records/:idGet specific billing record details

Regions

2 endpoints

GET/v1/regionsList all regions with hub count, GPUs, renewable %, and carbon intensity

GET/v1/regions/:codeGet specific region with compliance frameworks and latency data

Operations

5 endpoints

GET/v1/operations/hubsList all compute hubs and status

GET/v1/operations/hubs/:idGet hub details and capacity

POST/v1/operations/failoverInitiate hub failover procedure

GET/v1/operations/energyGet energy consumption and source data

POST/v1/operations/scheduleCreate carbon-aware schedule policy

Monitoring

6 endpoints

GET/v1/monitoring/metricsPlatform-wide metrics: GPUs, utilization, carbon, energy, CO2 saved

GET/v1/monitoring/health/detailedDetailed health check: DB status, API version, uptime, connections

GET/v1/monitoring/alertsList active alerts across the mesh

POST/v1/monitoring/alerts/rulesCreate alert rule

GET/v1/monitoring/tracesQuery distributed traces

GET/v1/monitoring/logsSearch structured logs

gRPC API

gRPC Service Definitions

High-performance gRPC services for latency-sensitive workloads and streaming operations. Uses Protocol Buffers v3 for schema definition and supports bi-directional streaming for real-time data flows.

ComputeService

Manage workloads, scaling, and GPU allocation across the mesh

CreateWorkload

GetWorkload

ListWorkloads

ScaleWorkload

MigrateWorkload

StreamWorkloadEvents

DataService

Data pipeline management, ingestion, and lake operations

CreatePipeline

IngestData

GetSnapshot

StreamData

ModelService

Model registration, training, and inference endpoints

RegisterModel

DeployModel

TrainModel

StreamInference

MeshService

Hub topology, health monitoring, and mesh orchestration

GetHubStatus

StreamMetrics

InitiateFailover

GetEnergyReport

IdentityService

Authentication, authorization, and audit logging

Authenticate

Authorize

StreamAuditEvents

RevokeToken

WebSocket API

Real-Time Streaming

WebSocket endpoints for real-time event streaming. Connect once, receive continuous updates for workload state changes, metrics, inference results, and audit events.

Streaming Endpoints

/v1/ws/workloads/:id/eventsReal-time workload state changes, logs, and metricsJSON over WebSocket

/v1/ws/metrics/streamLive platform metrics with configurable granularityJSON over WebSocket

/v1/ws/models/:id/inferenceStreaming inference for real-time model predictionsJSON over WebSocket

/v1/ws/audit/eventsReal-time audit event stream for compliance monitoringJSON over WebSocket

/v1/ws/hubs/:id/telemetryLive hub telemetry data including power, thermal, and networkProtobuf over WebSocket

Rate Limits

API Rate Limits

Rate limits protect the platform and ensure fair resource allocation. Headers include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset for real-time tracking.

Tier	Requests	Burst	Compute	Data
Free	100 req/min	50 req	10 GPU-hours/month free tier	5 GB/month
Developer	1,000 req/min	500 req	10 GPU-hours/day	50 GB/month
Professional	10,000 req/min	5,000 req	100 GPU-hours/day	500 GB/month
Enterprise	Custom	Custom	Unlimited	Unlimited
Sovereign	Custom	Custom	Dedicated	Dedicated

Error Handling

Error Codes

400

Bad Request

Invalid request body, missing required fields, or malformed parameters.

401

Unauthorized

Missing or invalid authentication credentials. Check API key or JWT token.

403

Forbidden

Insufficient permissions or sovereignty constraint violation. Data cannot leave the designated jurisdiction.

404

Not Found

The requested resource does not exist or has been decommissioned.

409

Conflict

Resource state conflict, such as attempting to deploy a model that is already deployed.

429

Rate Limited

Request rate exceeds your tier limit. Retry after the time specified in Retry-After header.

500

Internal Error

Unexpected server error. HarchOS operations team is automatically notified.

503

Service Unavailable

Hub is temporarily offline for maintenance. Traffic is rerouted to the nearest available hub.

Code Examples

Quick Code Samples

curl -X POST https://api.harchos.io/v1/compute/workloads \
  -H "Authorization: Bearer hrch_live_sk_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "llama-inference-prod",
    "gpu": "H100",
    "count": 8,
    "region": "morocco-dakhla",
    "sovereignty": "strict",
    "carbonAware": true,
    "schedule": "carbon-optimal"
  }'

View full SDK documentation Try the quickstart guide