Version metadata

Status: stable Category: infrastructure Added: 2026-04-20 Last reviewed: 2026-04-21

Summary

Returns Trinity's build and catalog identifiers for the deployed instance. Use this to detect contract drift during a rollout and to pin bug reports to an exact build. This is not a health probe — it does not exercise any downstream components. For health, see GET /api/health/check.

Endpoint

Field	Value
Method	GET
Path	/api/version/get
Full URL	https://engine.tripod-health.com/api/version/get
Authentication	API key (required)
Request body	none
Response body	application/json
Idempotent	Yes
Rate-limited	Yes

Purpose

Two problems this endpoint solves:

1. Contract drift detection. Every scoring response includes a catalog_version. When a caller sees an unfamiliar catalog_version in a response, hitting GET /api/version/get confirms whether the deployed catalog has moved. If yours matches the one in the scoring response, you are up to date; if not, your client was caching an older catalog snapshot.
2. Build pinning on incident reports. git_sha and deployed_at name the exact build. A support ticket quoting request_id alongside these two values narrows the investigation to a single deploy and a single call.

The values never change until the next deploy; latency is dominated by network, not by server work.

Authentication

Send a valid API key in the apikey header. See authentication.md. A missing or unknown key returns 401 Unauthenticated.

Request

Headers

Header	Required	Description
apikey	Yes	Consumer API key.

Path / query parameters

None.

Body

None. Any body on a GET request is ignored.

Response

Success — 200 OK

{
  "engine_version": "0.1.0",
  "catalog_version": "0.8.0",
  "git_sha": "9b84a23d4b5b9dc3f49856027c2458150f86c5cf",
  "deployed_at": "2026-04-21T03:16:25Z"
}

The body carries no request_id. To correlate a call, read the X-Request-ID response header: the gateway's trace ID for the request, which support can look up. See conventions.md.

Response fields

Field	Type	Always present	Description
engine_version	string (SemVer)	Yes	Version of the deployed code. Bumps on breaking or feature releases.
catalog_version	string (SemVer)	Yes	Version of the instrument / composite catalog embedded in this build. Matches the catalog_version field returned by /score and /cdri/compute responses.
git_sha	string (40-char hex)	Yes	Full Git commit SHA of the source that produced this build.
deployed_at	string (ISO 8601 UTC)	Yes	Timestamp the container image was built. Stable for the lifetime of the deploy.

Status codes

Code	Meaning	When
200	OK	Metadata returned.
401	Unauthenticated	Missing or invalid API key.
404	NotFound	Wrong path or method. GET /api/version/get is the only supported form.
429	RateLimited	Per-consumer rate limit exceeded. See Retry-After.
5xx	Varies	Unexpected failure. Quote the envelope's request_id (or, with no engine body, the X-Request-ID response header) when reporting.

Examples

The language-specific invocations below assume the call() helper from quickstart.md.

1. Canonical request and response

Send:

GET /api/version/get HTTP/1.1
Host: engine.tripod-health.com
apikey: $ENGINE_API_KEY

Receive (200 OK):

{
  "engine_version": "0.1.0",
  "catalog_version": "0.8.0",
  "git_sha": "9b84a23d4b5b9dc3f49856027c2458150f86c5cf",
  "deployed_at": "2026-04-21T03:16:25Z"
}

Remember: the body carries no request_id. Capture the X-Request-ID response header (the gateway's trace ID) if you need to quote the call in a ticket.

2. Calling the endpoint in your language

curl

curl -sS "https://engine.tripod-health.com/api/version/get" \
  -H "apikey: $ENGINE_API_KEY"

To capture the X-Request-ID response header:

curl -sS -D - "https://engine.tripod-health.com/api/version/get" \
  -H "apikey: $ENGINE_API_KEY" \
  -o /dev/null \
  | grep -i "^x-request-id"

Python (requests)

# Uses the call() helper from quickstart.md.
meta = call("GET", "/api/version/get")
print(f"engine {meta['engine_version']} catalog {meta['catalog_version']} "
      f"sha={meta['git_sha'][:12]} deployed={meta['deployed_at']}")

Node.js (native fetch)

// Uses the call() helper from quickstart.md.
const meta = await call("GET", "/api/version/get");
console.log(
  `engine ${meta.engine_version} catalog ${meta.catalog_version} ` +
  `sha=${meta.git_sha.slice(0, 12)} deployed=${meta.deployed_at}`,
);

TypeScript

// Uses the typed call<T>() helper from quickstart.md.
interface VersionResponse {
  engine_version: string;
  catalog_version: string;
  git_sha: string;
  deployed_at: string;
}

const meta = await call<VersionResponse>("GET", "/api/version/get");
if (meta.catalog_version !== EXPECTED_CATALOG_VERSION) {
  throw new Error(`catalog drift: expected ${EXPECTED_CATALOG_VERSION}, got ${meta.catalog_version}`);
}

Go

// Uses the call() helper from quickstart.md.
meta, err := call("GET", "/api/version/get", nil, 3)
if err != nil {
    panic(err)
}
fmt.Printf("engine %v catalog %v sha=%.12s deployed=%v\n",
    meta["engine_version"], meta["catalog_version"],
    meta["git_sha"], meta["deployed_at"])

Java

// Uses the call() helper from quickstart.md.
String meta = call("GET", "/api/version/get", null, 3);
String catalogVersion = extract(meta, "catalog_version");
String gitSha = extract(meta, "git_sha");
System.out.println("catalog=" + catalogVersion + " sha=" + gitSha.substring(0, 12));

C# (.NET HttpClient)

// Uses the Call() helper from quickstart.md.
var meta = await Call(HttpMethod.Get, "/api/version/get");
Console.WriteLine(
    $"engine {meta.GetProperty("engine_version").GetString()} " +
    $"catalog {meta.GetProperty("catalog_version").GetString()} " +
    $"sha={meta.GetProperty("git_sha").GetString()![..12]}"
);

PowerShell

# Uses the Invoke-Engine helper from quickstart.md.
$meta = Invoke-Engine -Method Get -Path "/api/version/get"
"engine $($meta.engine_version) catalog $($meta.catalog_version) sha=$($meta.git_sha.Substring(0,12))"

3. Error scenarios

This endpoint has no endpoint-specific errors. It cannot fail for reasons other than auth (401), rate limits (429), or unexpected infrastructure failures (5xx). For 401 envelope examples see infrastructure-api-health-check.md.

Intended use

• Contract-drift checks during a rollout. When a deploy is in flight, call this endpoint and compare catalog_version against the version your client was generated for. A mismatch means you need to regenerate or refresh.
• Incident-report bundling. When filing a support ticket for an unexpected response, include engine_version, catalog_version, git_sha, and the request_id of the offending call. That lets the team jump straight to the exact build and call.
• CI smoke tests that want to assert a specific deploy is live. Compare the response's git_sha against the SHA your pipeline just deployed; only proceed once they match.

Mistaken use

• Do not use this as a health check. It returns 200 even when downstream components are unhealthy. Use GET /api/health/check for health.
• Do not poll this at high frequency. The values only change on deploy. Caching the response for minutes or hours is fine; polling every second adds no information.
• Do not parse engine_version for feature detection. The catalog is the contract — features come and go at the catalog level. Inspect GET /api/catalog/get to find out what is available.
• Do not compare git_sha as a substring. It is a full 40-char hex SHA. A short-SHA comparison is fine, but compare exact equal lengths — substring comparisons against the first seven characters are a source of silent false negatives.

Debugging

1. Capture the X-Request-ID response header. The success body carries no request_id, so this gateway trace ID is how support finds the call. On an error, quote the envelope's request_id.
2. 401 Unauthenticated — confirm the apikey header is being sent and the key has not been rotated. See authentication.md.
3. 404 NotFound — double-check the path (/api/version/get, not /api/version or /version/get) and the method (GET).
4. catalog_version does not match what scoring responses carry. That should not happen — both are baked in at build time. If you see a mismatch, quote the request_id from a recent scoring response plus the X-Request-ID from a version call in a support ticket.
5. git_sha or deployed_at is "unknown". This indicates a local or otherwise non-CI build. You should never see "unknown" against the production URL; if you do, report it with the request ID.

Rate limits

See rate-limits.md.

Related endpoints

• GET /health — unauthenticated container liveness probe. Internal use only.
• GET /api/health/check — authenticated end-to-end health check.
• GET /api/catalog/get — catalog tree, including the authoritative catalog_version.

Change history

Date	Change
2026-04-20	Initial publication.
2026-10-14	The engine assigns every request ID; an X-Request-ID request header is not used. The X-Request-ID response header is the gateway's trace ID for the request and does not match request_id; quote request_id to support.