Documentation | Zywrap

Workflow API live

Call AI by wrapper code, then inspect every run.

Zywrap turns wrapper codes, uploaded files, model choices, output formats, artifacts, and usage records into reliable API-driven workflows. Start in the playground, inspect the timeline, then move the same request into your product.

Runs

Sync or async wrapper-code workflow execution.

Wrapper codes

Use saved prompt behavior instead of rebuilding prompts.

Files & artifacts

Attach files and save generated outputs.

Ledger

Track tokens, cost, provider cost, and billing source.

Runtime models

Sync safe AI model metadata without catalog access.

Recommended integration path

Choose a wrapper code

Use Explore or the playground to find a production-ready wrapper behavior for your use case.

Create an API key

Use the dashboard API keys page. Keys support x-api-key and Bearer auth.

Sync runtime AI models

Keep local model pickers fresh with public runtime model sync. No Enterprise catalog access is required.

Call /v2/runs

Send wrapperCodes, model, input text, optional files, and output settings with an Idempotency-Key.

Inspect outputs and usage

Use runs, artifacts, and usage ledger records to debug production behavior.

Create a sync run

curl -X POST https://api.zywrap.com/v2/runs \
  -H "x-api-key: zw_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: run-001" \
  -d '{
    "model": "openai-gpt-4o-mini",
    "wrapperCodes": ["marketing_copywriting_cold_out_ema_b2b"],
    "input": {
      "text": "Product: Zywrap\nAudience: SaaS developers\nGoal: Write a concise outbound email."
    },
    "output": {
      "format": "markdown",
      "artifact": true
    }
  }'

Authentication

Use x-api-key for API calls. New zw_live_ keys can also be sent as Authorization: Bearer.

SDK examples

Use Node.js, Python, or PHP examples for live runs, file uploads, artifacts, Enterprise catalog sync, and public AI model runtime sync.

Runtime AI models

Normal API users can sync active model codes, provider names, availability, updates, and removals using an API key.

Production safety

Use trace IDs, rate-limit headers, idempotency, normalized errors, and usage ledger records.

Public runtime sync

Keep model lists current without Enterprise catalog access.

Runtime AI model sync is available to normal API users because model availability changes over time. It returns safe runtime metadata only, not wrappers, use cases, schemas, prompt logic, or offline catalog files.

Normal API keyFull snapshotDelta updatesNo catalog bundle

View runtime model docs

Files and artifacts workflow

For document analysis, CSV review, support summaries, contract checks, and report generation, upload files first, pass returned file IDs into input.files, and enable output.artifact to save the generated result.

Upload → run → download

# 1. Upload an input file
curl -X POST https://api.zywrap.com/v2/files \
  -H "x-api-key: zw_live_..." \
  -F "file=@./customer-feedback.csv" \
  -F "displayName=Customer feedback CSV"

# 2. Create a run with that uploaded file ID
curl -X POST https://api.zywrap.com/v2/runs \
  -H "x-api-key: zw_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: file-run-001" \
  -d '{
    "model": "openai-gpt-4o-mini",
    "wrapperCodes": ["customer_support_reply_summary"],
    "input": {
      "text": "Summarize this file and list the top action items.",
      "files": ["file_id_from_upload"]
    },
    "output": {
      "format": "markdown",
      "artifact": true
    }
  }'

# 3. Download the generated artifact
curl -L https://api.zywrap.com/v2/artifacts/artifact_id/download \
  -H "x-api-key: zw_live_..." \
  -o zywrap-output.md

Async workflows

Use async mode when a workflow should be queued first, reviewed, or executed later by your application or worker. The API supports manual execution through POST /v2/runs/:id/execute.

Queue and execute later

# 1. Create a queued async run
curl -X POST https://api.zywrap.com/v2/runs \
  -H "x-api-key: zw_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: async-run-001" \
  -d '{
    "mode": "async",
    "model": "openai-gpt-4o-mini",
    "wrapperCodes": ["product_launch_checklist"],
    "input": { "text": "Generate a launch checklist for a new SaaS feature." },
    "output": { "format": "markdown", "artifact": true }
  }'

# 2. Execute the queued run later
curl -X POST https://api.zywrap.com/v2/runs/RUN_ID/execute \
  -H "x-api-key: zw_live_..." \
  -H "Content-Type: application/json" \
  -d '{}'

Ready to build?

Open the playground, generate a real run, then copy the API shape into your app.

Open playground

Build reliable wrapper-code workflows.