API reference

Base URL: https://api.greenjoules.cloud/v1. All endpoints are JSON over HTTPS. Where a third-party API shape is well-known (OpenAI, S3), we mirror it. A small set of X-Energy-* response headers are added on every response.

Authentication

Mint tokens in the portal. Pass them as a bearer header.

Authorization: Bearer jc_LIVE_…

Tokens are scoped at creation (read / deploy / billing-admin). Rotation is one click in the portal; old tokens revoke at the next request.

Inference (OpenAI-compatible)

Endpoint	Maps to
`POST /v1/chat/completions`	Chat completions, OpenAI shape
`POST /v1/completions`	Legacy text completions
`POST /v1/embeddings`	Embeddings
`GET /v1/models`	List available models + their cost-tier classifications

Set model: "auto" to let the router pick the cheapest capable silicon for each request. Or pin a model by name.

POST /v1/chat/completions
{
  "model": "auto",
  "messages": [{"role":"user","content":"summarize this contract"}],
  "max_tokens": 512
}

200 OK
X-Energy-Joules: 0.31
X-Routed-To: nebius/eu-helsinki/h100-sxm5
X-Tier: L2

{
  "id": "chatcmpl_…",
  "model": "llama-3.3-70b-instruct",
  "choices": [...]
}

Object Store (S3-compatible)

Drop-in for the S3 API. Change the endpoint, keep your code. Zero egress within the mesh.

Operation	Path
PUT object	`PUT /{bucket}/{key}`
GET object	`GET /{bucket}/{key}`
LIST	`GET /{bucket}?list-type=2`
DELETE	`DELETE /{bucket}/{key}`

Configure the AWS SDK with endpoint_url="https://api.greenjoules.cloud" and your jc_… token as the access-key/secret pair.

Workloads

For containers, functions, and HCL-described stacks, install the CLI and use invisible deploy against an invisible.hcl file. The CLI talks to the same API as the console.

invisible login
invisible deploy
invisible logs workload.site
invisible energy workload.site --since 1h

Response headers

Header	Meaning
`X-Energy-Joules`	Total energy this request consumed, in joules
`X-Carbon-mg`	Carbon equivalent, in milligrams CO₂eq
`X-Routed-To`	Provider / region / silicon class that served the request
`X-Tier`	Routing class — L0 lookup, L1 extraction, L2 aggregation, L3 reasoning
`X-Receipt-Id`	Identifier of the signed receipt for this request

Status, errors, rate limits

Standard HTTP semantics. 429 when you exceed your free-tier budget. 402 when your balance is empty — top up at portal.greenjoules.cloud. Per-account error rates are public at status.greenjoules.cloud.

Versioning

All endpoints are versioned under /v1. Breaking changes ship under /v2. We will keep /v1 serving for at least 12 months after a /v2 is announced.

This page is a preview of the API surface for the v1 launch. Routes go GA progressively as nodes come online — see status for current availability.