Create records a prompt for the caller's org and answers 201 with it.

POST /v1/prompt

Prompt → · All API references → · Six flows, four surfaces →


Address	`https://api.hanzo.ai/v1/prompt`
Method	`POST`
Operation	`post_prompt`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Create records a prompt for the caller's org and answers 201 with it. A name the org already uses is NOT an error and NOT an overwrite: it appends a new version, so the library keeps real, inspectable history and the response carries the whole version list. The name is also the URL segment the prompt is fetched by, which is why its shape is constrained and a handful of names are reserved.

Request

5 fields, body application/json (required).

Field	In	Type	Required	Description
`labels`	body	string[]	—	Labels is free-form taxonomy, each up to 64 characters, capped at 32 entries.
`name`	body	string	—	Name is the org-unique handle AND the URL segment the prompt is addressed by: 1-64 characters matching ^[A-Za-z0-9][A-Za-z0-9._-]*$.
`prompt`	body	string	—	Prompt is the template body, capped at 64 KiB.
`tags`	body	string[]	—	Tags is free-form taxonomy under the same bounds as Labels.
`type`	body	string	—	Type labels the template's kind; defaults to "text".

Response

Status	Body	Meaning
`201`	promptDetail	created

201 body — 12 fields.

Field	In	Type	Always	Description
`createdAt`	body	string	—	CreatedAt is when version 1 was written, RFC 3339 UTC.
`labels`	body	string[]	—	Labels is the current version's free-form taxonomy.
`lastUpdatedAt`	body	string	—	UpdatedAt is when the current version was appended, RFC 3339 UTC.
`name`	body	string	—	Name is the prompt's org-unique handle and the URL segment it is addressed by.
`prompt`	body	string	—	Prompt is the CURRENT version's template body — the only content this service returns.
`tags`	body	string[]	—	Tags is the second free-form taxonomy, same rules as Labels.
`type`	body	string	—	Type labels the current version's kind; "text" unless the creator said otherwise.
`version`	body	integer	—	Version is the current version number, starting at 1 and incremented by one on every create against an existing name.
`versionHistory`	body	versionView[]	—	Versions is the history METADATA, newest first, capped at the last 100 — no bodies, so a long history cannot inflate this response.
`versionHistory[].createdAt`	body	string	—	CreatedAt is when this revision was appended, RFC 3339 UTC.
`versionHistory[].type`	body	string	—	Type is the kind this revision was written with, which may differ from the current one.
`versionHistory[].version`	body	integer	—	Version is this revision's number, 1 for the first.

Failure carries the platform error shape — see Errors.

Examples

hanzo prompts create

import { Configuration, PromptApi } from 'hanzoai';

const api = new PromptApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postPrompt({ labels: ["<labels>"], name: "<name>" });

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

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = PromptApi(client).post_prompt(labels=["<labels>"], name="<name>")

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

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

use hanzo_cloud::apis::{configuration::Configuration, prompt_api};

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

let result = prompt_api::post_prompt(&cfg, Default::default()).await?;

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

ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));

var result = new PromptApi(client).postPrompt();

The method above is the one at the current release of the document. [email protected] (npm) and [email protected] (PyPI) were 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 -X POST https://api.hanzo.ai/v1/prompt \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "labels": [
         "<labels>"
       ],
       "name": "<name>"
     }'

The door reaches prompt through the prompts tool, which names its 6 operations with its own verbs — this one among them, under a name only the door 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": "list_prompts"
         }
       }
     }'

Prompt API · All Hanzo APIs · Interactive reference

Create records a prompt for the caller's org and answers 201 with it.

Request

Response

Examples

On this page