List projects

Answers every project the caller may see, with how its apps stand.

GET /v1/platform/projects

Platform → · All API references → · Get started →

Address	`https://api.hanzo.ai/v1/platform/projects`
Method	`GET`
Operation	`get_platform_projects`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Answers every project the caller may see, with how its apps stand.

A project is the partOf its apps' values files name, so this is the declaration inventory grouped by that key, joined per app with CD's reconciliation, the pods the cluster runs and the newest release the registry publishes, and folded into counts: apps, namespaces, sync, health and drift. Declarations that name no project are listed separately, because each one is drift in git.

A SuperAdmin sees every owner's projects, the platform's own among them; an org admin sees only its own org's. org narrows a SuperAdmin to one owner. A plane that cannot be read leaves its counts at unknown and says why in cdUnavailable or clusterUnavailable; it never empties the board. A values file that does not parse is listed in unreadable and costs only its own row.

Request

1 field.

Field	In	Type	Required	Description
`org`	query	string	—	Org names whose projects to read.

Response

Status	Body	Meaning
`200`	platform.projectBoard	ok
`default`	problem-details	refused

200 body — 29 fields.

Field	In	Type	Always	Description
`cdUnavailable`	body	platform.unreadable	—
`cdUnavailable.reason`	body	string	—	Reason is why: the cause for a SuperAdmin, and which plane for anyone else.
`clusterUnavailable`	body	platform.unreadable	—
`clusterUnavailable.reason`	body	string	—	Reason is why: the cause for a SuperAdmin, and which plane for anyone else.
`projects`	body	platform.Project[]	—	Projects are sorted by owner, then name.
`projects[].apps`	body	integer (int64)	—	Apps is how many declarations name the project.
`projects[].drift`	body	platform.driftTally	—
`projects[].drift.ok`	body	integer (int64)	—	OK is how many rows run what they declare.
`projects[].drift.red`	body	integer (int64)	—	Red is how many have drifted badly.
`projects[].drift.yellow`	body	integer (int64)	—	Yellow is how many have drifted within tolerance.
`projects[].health`	body	platform.healthTally	—
`projects[].health.degraded`	body	integer (int64)	—	Degraded is how many CD reports Degraded.
`projects[].health.healthy`	body	integer (int64)	—	Healthy is how many CD reports Healthy.
`projects[].health.missing`	body	integer (int64)	—	Missing is how many have no live objects at all.
`projects[].health.progressing`	body	integer (int64)	—	Progressing is how many are still rolling out.
`projects[].health.unknown`	body	integer (int64)	—	Unknown is every other verdict, and apps CD could not be asked about.
`projects[].name`	body	string	—	Name is the project, as the values files spell it in `partOf`.
`projects[].namespaces`	body	string[]	—	Namespaces are the namespaces its apps deploy into, sorted.
`projects[].org`	body	string	—	Org is the organization that owns the project.
`projects[].sync`	body	platform.syncTally	—
`projects[].sync.outOfSync`	body	integer (int64)	—	OutOfSync is how many differ from git until someone syncs them.
`projects[].sync.synced`	body	integer (int64)	—	Synced is how many run what git declares.
`projects[].sync.unknown`	body	integer (int64)	—	Unknown is how many CD holds no verdict for, or could not be read.
`unassigned`	body	platform.declRef[]	—	Unassigned are declarations that name no project.
`unassigned[].name`	body	string	—	Name is the declaration's name, the file's basename.
`unassigned[].org`	body	string	—	Org is the values directory the declaration lives in.
`unreadable`	body	platform.unreadableFile[]	—	Unreadable are the values files in the caller's scope that do not parse, so their projects are unknown.
`unreadable[].path`	body	string	—	Path is the values file, relative to the repository root.
`unreadable[].reason`	body	string	—	Reason is why it could not be read.

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo platform projects list

.ts

.py

.go

.rs

.java

import { Configuration, PlatformApi } from 'hanzoai';

const api = new PlatformApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getPlatformProjects();

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import PlatformApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = PlatformApi(client).get_platform_projects()

cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.PlatformAPI.GetPlatformProjects(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_client::apis::{configuration::Configuration, platform_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = platform_api::get_platform_projects(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.PlatformApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new PlatformApi(client).getPlatformProjects();

curl https://api.hanzo.ai/v1/platform/projects \
  -H "Authorization: Bearer $HANZO_API_KEY"

MCP reaches platform through the platform tool, which names its 38 operations with its own verbs — this one among them, under a name only MCP declares. describe explains any of them:

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "get_build"
         }
       }
     }'

Platform API · All Hanzo APIs · Interactive reference

Was this page useful?

PreviousGet projects NextList releases