Skip to content
Hyphae Cloud

What the engine reports about itself, live or offline.

GET
/v0/projects/{id}/head
curl --request GET \
  --url https://infra-hyphae.run/v0/projects/example/head \
  --header 'Authorization: Bearer <token>'

Native exposes no JSON status over HTTP (every /v2 body is the binary HYPRSP01 product envelope), so this is a Cloud envelope around what the engine actually reports. Running tenant (source: live_probe): hyphae version --json fields, the X-Hyphae-Protocol-Minor and X-Hyphae-Request-Id headers of a GET /v2/capabilities probe, and that body verbatim (base64). Sleeping tenant (source: offline_status): the snapshot object of hyphae status --data-dir (visible_csn, root_digest, directory_lineage, catalog_version, logical_time_micros) plus the newest Cloud snapshot id. A tenant that has never started has no directory and answers 409. The Cloud never wakes a tenant to answer.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters”
id
required
string
/^prj_[0-9a-f]{16}$/

Responses

Section titled “ Responses ”

200

Section titled “200”

Probe result.

Media typeapplication/json

endpoint, protocol_minor, request_id, capabilities present when source is live_probe; lineage (and latest_snapshot if any) when offline_status.

object
project
required
string
/^prj_[0-9a-f]{16}$/
state
required
string
Allowed values: stopped running sleeping
source
required
string
Allowed values: live_probe offline_status
lineage

The snapshot object printed by hyphae status --data-dir. Field names are Native’s.

object
catalog_version
required
integer
directory_lineage
required
string
logical_time_micros
required
integer
root_digest
required
string
visible_csn
required
integer
latest_snapshot
string
/^snap_[0-9a-f]{16}$/
engine
required

Fields of hyphae version --json, named as Native names them.

object
engine_version
required
string
Allowed value: 3.0.0
native_directory_format
required
integer
product_api_version
required
integer
endpoint
object
data_plane
required
string
Allowed value: /v2
upstream
required

Loopback listener the Cloud forwards to, e.g. http://127.0.0.1:20000. Reachable by same-host processes without the Cloud.

string
protocol_minor

Native’s X-Hyphae-Protocol-Minor response header on the probe.

string
request_id

Native’s X-Hyphae-Request-Id response header on the probe.

string
capabilities
object
content_type
required
string
Allowed value: application/vnd.hyphae.product-v1
bytes
required
integer
body_base64
required

The GET /v2/capabilities body verbatim (Native HYPRSP01 envelope), base64.

string
observed_at
required

RFC 3339, UTC.

string format: date-time
Example
{
  "state": "stopped",
  "source": "live_probe",
  "engine": {
    "engine_version": "3.0.0"
  },
  "endpoint": {
    "data_plane": "/v2"
  },
  "capabilities": {
    "content_type": "application/vnd.hyphae.product-v1"
  }
}

401

Section titled “401”

Missing, malformed, duplicate, or unknown credential (authentication_required).

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: invalid_request authentication_required authorization_denied not_found conflict payload_too_large not_implemented tenant_not_running tenant_running function_runtime_missing function_timeout function_bad_output function_busy orchestrator_unavailable upstream_unavailable internal
message
required
string
Example
{
  "error": {
    "code": "invalid_request"
  }
}

Headers

Section titled “Headers”
WWW-Authenticate
string
Allowed value: Bearer realm="hyphae-cloud"

404

Section titled “404”

Unknown route, or a project the caller does not own (not_found).

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: invalid_request authentication_required authorization_denied not_found conflict payload_too_large not_implemented tenant_not_running tenant_running function_runtime_missing function_timeout function_bad_output function_busy orchestrator_unavailable upstream_unavailable internal
message
required
string
Example
{
  "error": {
    "code": "invalid_request"
  }
}

409

Section titled “409”

The operation needs a running engine and the project is stopped or sleeping (tenant_not_running).

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: invalid_request authentication_required authorization_denied not_found conflict payload_too_large not_implemented tenant_not_running tenant_running function_runtime_missing function_timeout function_bad_output function_busy orchestrator_unavailable upstream_unavailable internal
message
required
string
Example
{
  "error": {
    "code": "invalid_request"
  }
}

502

Section titled “502”

The engine failed to start or did not answer (upstream_unavailable).

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: invalid_request authentication_required authorization_denied not_found conflict payload_too_large not_implemented tenant_not_running tenant_running function_runtime_missing function_timeout function_bad_output function_busy orchestrator_unavailable upstream_unavailable internal
message
required
string
Example
{
  "error": {
    "code": "invalid_request"
  }
}

503

Section titled “503”

The host cannot run tenants right now — engine binary missing, wrong pin, or ports exhausted (orchestrator_unavailable).

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: invalid_request authentication_required authorization_denied not_found conflict payload_too_large not_implemented tenant_not_running tenant_running function_runtime_missing function_timeout function_bad_output function_busy orchestrator_unavailable upstream_unavailable internal
message
required
string
Example
{
  "error": {
    "code": "invalid_request"
  }
}