Project
Where your sites live: create one, deploy a build, roll back to any release.
Also for this capability: API · CLI · MCP · SDKs
Where your sites live: create one, deploy a build, roll back to any release.
| Base URL | https://api.hanzo.ai |
| Operations | 57 |
| Auth | Authorization: Bearer $HANZO_API_KEY |
Specification
Specification pending — no HIP in hanzoai/hips declares capability: project yet. What this capability serves is below, from the API document; what it is — the store it owns, how it meters, what it publishes — is written as a HIP under HIP-0139.
Four surfaces
| Surface | Reaches this capability as | Coverage |
|---|---|---|
| REST | project at its own prefix | 57 operations |
| CLI | hanzo project … | 57 of 57 |
| SDK | ProjectApi in every published client | 28 of 57 — the clients are generated at their own release |
| MCP | tool projects on https://api.hanzo.ai/v1/mcp | 48 operations, 1 under the document's own id — ask describe for the rest |
Quickstart
export HANZO_API_KEY=sk-... # console.hanzo.ai → API keysThen the first call — a read that needs nothing but the key. GET /v1/project, operation get_project:
hanzo project listimport { Configuration, ProjectApi } from 'hanzoai';
const api = new ProjectApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getProject();from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import ProjectApi
client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = ProjectApi(client).get_project()cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)
resp, _, err := client.ProjectAPI.GetProject(context.Background()).Execute()
if err != nil {
return err
}use hanzo_client::apis::{configuration::Configuration, project_api};
let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();
let result = project_api::get_project(&cfg, Default::default()).await?;import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.ProjectApi;
ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));
var result = new ProjectApi(client).getProject();The method above is the one at the current release of the document. [email protected] (npm) was generated from an earlier release, where this operation carried a different id, so it spells the method differently — regenerating the clients is what makes the two agree. SDKs →
curl https://api.hanzo.ai/v1/project \
-H "Authorization: Bearer $HANZO_API_KEY"Tool projects, op get_project — POST the JSON-RPC envelope to https://api.hanzo.ai/v1/mcp.
curl -X POST https://api.hanzo.ai/v1/mcp \
-H "Authorization: Bearer $HANZO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "projects",
"arguments": {
"op": "get_project",
"input": {}
}
}
}'Answers 200 with project.projectsProject[] — ok.
Endpoints
| Endpoint | What it does |
|---|---|
POST /v1/project/{slug}/deploy | Upload a built site as one archive and serve it |
POST /v1/project/{slug}/deployments/{id}/complete | CompleteDeployment is the CI completion hook that flips a queued git deployment to live (or error) once CI has synced the built site to S3. |
GET /v1/project/{slug}/deployments/{id} | Returns one deployment of a project by id. |
GET /v1/project/{slug}/deployments | Returns a project's deploy history, newest version first. |
POST /v1/project/{slug}/deployments | Opens a deployment and hands back a short-lived, prefix-scoped grant to write its bytes straight to object storage. |
POST /v1/project/{slug}/domains/{host}/verify | Checks the DNS challenge for a pending custom hostname and, when it passes, promotes the host so it begins routing at the edge. |
DELETE /v1/project/{slug}/domains/{host} | Gives a custom hostname back, so the name is free to reuse. |
GET /v1/project/{slug}/domains | Returns every custom hostname this site holds: the live ones, plus any pending claim with the DNS records it still owes. |
POST /v1/project/{slug}/domains | Attaches one or more CUSTOM public hostnames to this org's site. |
POST /v1/project/{slug}/publish | Promotes a build output into a new release AND goes live with it — create+activate in one call, which is the 99% path. |
POST /v1/project/{slug}/purge | Flushes the site's edge cache without redeploying anything. |
POST /v1/project/{slug}/releases/{release}/activate | Points the site at an existing release — the go-live, and equally the ROLLBACK. |
GET /v1/project/{slug}/releases | Returns a site's releases newest-first, marking the active one — the rollback menu. |
POST /v1/project/{slug}/releases | Promotes a build output into a new immutable release WITHOUT serving it — the staged half of publishing, for when you want to check a release before… |
GET /v1/project/{slug}/shot | Get a PNG of the project's live site |
PUT /v1/project/{slug}/star | Bookmarks a project for the person calling, and answers whether it is starred afterwards. |
DELETE /v1/project/{slug}/star | Removes the caller's own bookmark from a project, and answers whether it is starred afterwards. |
GET /v1/project/{slug} | Returns one project of yours by slug — its settings, its live URL and the deployment currently serving it. |
PATCH /v1/project/{slug} | Changes a project's settings, and only the settings you send. |
DELETE /v1/project/{slug} | Deletes a project and takes its site off the internet. |
GET /v1/project/edge | health reports whether a publish reaches readers, rather than whether it was accepted. |
POST /v1/project/fork | Creates a project seeded from a PUBLISHED EXAMPLE — either a starter-kit template from the ONE embedded gallery catalog, or any live project on the… |
GET /v1/project/sites/{slug} | Returns one site — the same row ListSites carries, for one slug. |
POST /v1/project/sites/deploy | Deploys a caller-supplied file manifest — the deploy_site capability an agent calls — and answers with where it went live. |
GET /v1/project/sites | Returns the org's deployed sites at the pretty URLs they serve at. |
POST /v1/project/sites | Generates a self-contained, mobile-responsive static site from a natural-language brief and deploys it live in one call. |
GET /v1/project/tags | The site's browser tag set for the hosted tag — which pixels to inject, by publishable key |
GET /v1/project | Returns every project your org owns. |
POST /v1/project | Creates a project — the handle a site is deployed and served under — and answers 201 with it in draft. |
POST /v1/projects/{slug}/deploy | Upload a built site as one archive and serve it |
POST /v1/projects/{slug}/deployments/{id}/complete | CompleteDeployment is the CI completion hook that flips a queued git deployment to live (or error) once CI has synced the built site to S3. |
GET /v1/projects/{slug}/deployments/{id} | Returns one deployment of a project by id. |
GET /v1/projects/{slug}/deployments | Returns a project's deploy history, newest version first. |
POST /v1/projects/{slug}/deployments | Opens a deployment and hands back a short-lived, prefix-scoped grant to write its bytes straight to object storage. |
POST /v1/projects/{slug}/domains/{host}/verify | Checks the DNS challenge for a pending custom hostname and, when it passes, promotes the host so it begins routing at the edge. |
DELETE /v1/projects/{slug}/domains/{host} | Gives a custom hostname back, so the name is free to reuse. |
GET /v1/projects/{slug}/domains | Returns every custom hostname this site holds: the live ones, plus any pending claim with the DNS records it still owes. |
POST /v1/projects/{slug}/domains | Attaches one or more CUSTOM public hostnames to this org's site. |
POST /v1/projects/{slug}/publish | Promotes a build output into a new release AND goes live with it — create+activate in one call, which is the 99% path. |
POST /v1/projects/{slug}/purge | Flushes the site's edge cache without redeploying anything. |
POST /v1/projects/{slug}/releases/{release}/activate | Points the site at an existing release — the go-live, and equally the ROLLBACK. |
GET /v1/projects/{slug}/releases | Returns a site's releases newest-first, marking the active one — the rollback menu. |
POST /v1/projects/{slug}/releases | Promotes a build output into a new immutable release WITHOUT serving it — the staged half of publishing, for when you want to check a release before… |
GET /v1/projects/{slug}/shot | Get a PNG of the project's live site |
PUT /v1/projects/{slug}/star | Bookmarks a project for the person calling, and answers whether it is starred afterwards. |
DELETE /v1/projects/{slug}/star | Removes the caller's own bookmark from a project, and answers whether it is starred afterwards. |
GET /v1/projects/{slug} | Returns one project of yours by slug — its settings, its live URL and the deployment currently serving it. |
PATCH /v1/projects/{slug} | Changes a project's settings, and only the settings you send. |
DELETE /v1/projects/{slug} | Deletes a project and takes its site off the internet. |
GET /v1/projects/edge | health reports whether a publish reaches readers, rather than whether it was accepted. |
POST /v1/projects/fork | Creates a project seeded from a PUBLISHED EXAMPLE — either a starter-kit template from the ONE embedded gallery catalog, or any live project on the… |
GET /v1/projects/sites/{slug} | Returns one site — the same row ListSites carries, for one slug. |
POST /v1/projects/sites/deploy | Deploys a caller-supplied file manifest — the deploy_site capability an agent calls — and answers with where it went live. |
GET /v1/projects/sites | Returns the org's deployed sites at the pretty URLs they serve at. |
POST /v1/projects/sites | Generates a self-contained, mobile-responsive static site from a natural-language brief and deploys it live in one call. |
GET /v1/projects | Returns every project your org owns. |
POST /v1/projects | Creates a project — the handle a site is deployed and served under — and answers 201 with it in draft. |
How is this guide?