Recipes API

Recipes API

Recipes configure which operations run on a sign or verify call. The Recipes API lets you list preset recipes, create custom recipes, and retrieve recipe details.

GET /v1/recipes

List all recipes available to your tenant (presets + any custom recipes you have created).

GET https://api.verbitas.io/v1/recipes
Authorization: Bearer vb_live_...

curl -H "Authorization: Bearer $VERBITAS_API_KEY" \
  https://api.verbitas.io/v1/recipes | jq '.recipes[] | {id, media_type, description}'

Response

{
  "recipes": [
    {
      "id": "image-genai-v1",
      "version": 1,
      "media_type": "image",
      "description": "Standard AI image provenance",
      "is_preset": true,
      "created_at": "2026-01-01T00:00:00Z"
    },
    {
      "id": "my-pipeline-v1",
      "version": 1,
      "media_type": "image",
      "description": "My custom pipeline",
      "is_preset": false,
      "created_at": "2026-05-09T10:00:00Z"
    }
  ]
}

GET /v1/recipes/{id}

Retrieve a specific recipe by ID. Returns the full YAML body as recipe_yaml plus parsed fields.

GET https://api.verbitas.io/v1/recipes/image-genai-v1
Authorization: Bearer vb_live_...

curl -H "Authorization: Bearer $VERBITAS_API_KEY" \
  https://api.verbitas.io/v1/recipes/image-genai-v1 | jq .

Response

{
  "id": "image-genai-v1",
  "version": 1,
  "media_type": "image",
  "description": "Standard AI image provenance",
  "is_preset": true,
  "created_at": "2026-01-01T00:00:00Z",
  "recipe_yaml": "id: image-genai-v1\nversion: 1\n..."
}

POST /v1/recipes

Create a custom recipe. Requires admin-scoped key.

Custom recipes must:

• Extend one of the 10 preset recipes using extends: <preset-id>@<version>
• Pass validation against packages/recipes/schema/recipe.schema.json
• Use only step.kind values from the closed enum

POST https://api.verbitas.io/v1/recipes
Authorization: Bearer vb_admin_...
Content-Type: application/yaml

curl -X POST https://api.verbitas.io/v1/recipes \
  -H "Authorization: Bearer $VERBITAS_API_KEY" \
  -H "Content-Type: application/yaml" \
  --data-binary @my-pipeline-v1.yaml

Or as JSON:

curl -X POST https://api.verbitas.io/v1/recipes \
  -H "Authorization: Bearer $VERBITAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"recipe_yaml": "id: my-pipeline-v1\nversion: 1\nextends: image-genai-v1@1\n..."}'

Response: 201 Created

{
  "recipe_id": "my-pipeline-v1",
  "version": 1,
  "created_at": "2026-05-09T10:00:00Z"
}

Immutability

Once a recipe has been used to sign an asset, it is immutable. To change the recipe, increment the version and create a new recipe (my-pipeline-v2). Existing assets continue verifying against the recipe version used at sign time.

Error codes

HTTP	Code	Meaning
400	verbitas.recipes.invalid_schema	YAML fails recipe.schema.json validation; detail includes specific field errors
400	verbitas.recipes.unknown_step_kind	step.kind is not in the closed enum
400	verbitas.recipes.invalid_extends	Base preset not found or version mismatch
401	verbitas.auth.invalid_key	API key invalid
403	verbitas.auth.insufficient_scope	admin scope required
402	verbitas.recipes.byok_plan_required	kms_mode: byok requires Enterprise BYOK plan
409	verbitas.recipes.conflict	Recipe ID + version already exists

SDK examples

Python

import verbitas

client = verbitas.Client()

# List recipes
recipes = client.recipes.list()
for r in recipes:
    print(r.id, r.media_type)

# Get a recipe
recipe = client.recipes.get("image-genai-v1")
print(recipe.recipe_yaml)

# Create a custom recipe
with open("my-pipeline-v1.yaml") as f:
    result = client.recipes.create(f.read())
print(result.recipe_id)

TypeScript

import { VerbitasClient } from "@verbitas/sdk";

const client = new VerbitasClient();

const recipes = await client.recipes.list();
const recipe = await client.recipes.get("image-genai-v1");
const created = await client.recipes.create(recipeYaml);