Zywrap
Developer documentation

Build reliable wrapper-code workflows.

Learn how to authenticate, run wrapper codes, upload files, download artifacts, track usage, and integrate Zywrap into production applications.

API-first workflow guide

Move from wrapper discovery to production API calls.

Wrapper-code runsPOST /v2/runs
FilesUpload and attach inputs
ArtifactsDownload generated outputs
Production controlsKeys, retries, usage ledger
Workflow API reference

Production workflow endpoints

The current /v2 API is organized around wrapper-code runs, files, artifacts, and usage records. Send wrapperCodes instead of raw prompt templates, use idempotency for POST requests, and use trace IDs plus ledger records for production visibility.

Authentication

Use x-api-key for all API keys, including legacy keys. New zw_live_ keys may also use Bearer auth.

Idempotency

Send Idempotency-Key on POST /v2/runs. Retries return the existing run instead of duplicating execution.

Rate limits

V2 responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.

Base URL

LIVEhttps://api.zywrap.com
Recommended
x-api-key: zw_live_...
Bearer API key
Authorization: Bearer zw_live_...
Dashboard JWT
Authorization: Bearer <JWT>
Content type
application/json or multipart/form-data
GET/v2/runs

List runs

Returns paginated runs for the authenticated user or API key.

POST/v2/runs

Create a run

Creates and optionally executes a sync or async wrapper-code workflow run. Supports wrapperCodes, model, input.text, input.files, output.format, output.artifact, model params, metadata, and overrides.

GET/v2/runs/{runId}

Get run detail

Returns the run, steps, events, files, artifacts, approvals, and usage ledger entries.

POST/v2/runs/{runId}/execute

Execute queued run

Executes a queued async run. Completed runs cannot be executed again.

POST/v2/runs/{runId}/cancel

Cancel run

Cancels a queued/running run when it is not already terminal.

Create run request
{
  "model": "openai-gpt-4o-mini",
  "mode": "sync",
  "wrapperCodes": ["marketing_copywriting_cold_out_ema_b2b"],
  "input": {
    "text": "Product: Zywrap\nAudience: SaaS developers\nGoal: Write a concise outbound email.",
    "files": ["file_id"]
  },
  "output": {
    "format": "markdown",
    "artifact": true
  },
  "temperature": 0.4,
  "metadata": {
    "source": "my-app"
  }
}
Completed run response
{
  "executed": true,
  "run": {
    "id": "run_id",
    "status": "completed",
    "selectedModelCode": "openai-gpt-4o-mini",
    "selectedFiles": ["file_id"],
    "outputSummary": "AI output summary...",
    "outputMetadata": {
      "billing": {
        "mode": "observe_only",
        "source": "SUBSCRIPTION",
        "amountCredits": "13",
        "amountUsd": 0.00013,
        "providerCost": 0.0000642,
        "ledgerId": "usage_ledger_id"
      }
    },
    "artifacts": [
      { "id": "artifact_id", "type": "markdown", "status": "ready" }
    ]
  }
}

Create run request fields

model
System model code, for example openai-gpt-4o-mini
wrapperCodes
Array of wrapper behavior codes to apply
input.text
Plain instructions, user data, or serialized schema fields
input.files
Uploaded file IDs from POST /v2/files
output.format
markdown, json, text, or another supported format
output.artifact
true to save the generated output as an artifact
Files

Files are user-provided inputs. Zywrap extracts supported content and can attach it to future runs.

GET/v2/files

List files

Paginated uploaded files.

POST/v2/files

Upload file

multipart/form-data with field name file.

GET/v2/files/{fileId}/download

Download file

Downloads the original uploaded file.

Artifacts

Artifacts are generated outputs from runs. They are saved for preview, download, and downstream automation.

GET/v2/artifacts

List artifacts

Paginated generated outputs.

GET/v2/artifacts/{artifactId}/download

Download artifact

Downloads markdown/text now; PDF/DOCX/XLSX can be added later.

Usage ledger

Every successful provider call creates a ledger debit record with the run, API key, token usage, provider cost, customer cost, billing mode, and source.

GET/v2/usage-ledger

List usage ledger

Supports page, limit, runId, source, and type filters.

GET/v2/admin/observability/summary

Admin observability

Admin-only summary of runs, costs, files, artifacts, API keys, and errors.

Ledger response
{
  "items": [
    {
      "id": "ledger_id",
      "runId": "run_id",
      "apiKeyId": "api_key_id",
      "type": "debit",
      "source": "SUBSCRIPTION",
      "amountCredits": "13",
      "amountUsd": 0.00013,
      "providerCost": 0.0000642,
      "description": "V2 run usage recorded for review."
    }
  ],
  "totals": {
    "amountCredits": "13",
    "amountUsd": 0.00013,
    "providerCost": 0.0000642
  }
}
Upload 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"
Download artifact
curl -L https://api.zywrap.com/v2/artifacts/artifact_id/download \
  -H "x-api-key: zw_live_..." \
  -o output.md

Complete file-to-artifact flow

This is the production pattern for workflows that need user documents, CSVs, specs, transcripts, support exports, or other uploaded context. Upload once, reference the file ID in input.files, then download the saved artifact.

Upload → run → artifact
# 1. Upload 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. Run wrapper with file input and artifact output
curl -X POST https://api.zywrap.com/v2/runs \
  -H "x-api-key: zw_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: file-artifact-run-001" \
  -d '{
    "wrapperCodes": ["customer_support_reply_summary"],
    "model": "openai-gpt-4o-mini",
    "input": {
      "text": "Summarize this file and list the top action items.",
      "files": ["file_id"]
    },
    "output": { "format": "markdown", "artifact": true }
  }'

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

Need the raw OpenAPI schema?

Use the backend OpenAPI endpoint for SDK generation and API tooling.

Open OpenAPI