Varity Public API Reference

Varity Team Core Contributors Updated July 2026

Varity’s public API is a resource API for apps, deployments, templates, pricing, credits, API keys, and webhooks. Use it for direct integrations, custom agents, launchpads, internal tools, and backend services that need to deploy or operate Varity apps without the dashboard.

The machine-readable source is:

• https://docs.varity.so/openapi.yaml
• https://varity.app/api/openapi.json

Note

Older thin-client compatibility routes are not the public resource contract. New direct integrations should use the /api/* routes below.

Base URL And Auth

All public API calls use:

https://varity.app/api

For non-browser callers, send your Varity API key as a bearer credential:

Authorization: Bearer $VARITY_API_KEY

Create API keys in the Developer Portal settings page. API key plaintext is shown once. Listing and revoking keys require an authenticated Developer Portal session; plaintext keys are never returned after creation.

Deploy

POST /api/deployments creates a deployment from one source: repository, image, or template. Use Idempotency-Key on create requests so normal retries and replays cannot create duplicate deployments. Do not fire concurrent create requests with the same idempotency key; atomic concurrent idempotency is a backend hardening follow-up for v1.

Repository

curl -X POST https://varity.app/api/deployments \
  -H "Authorization: Bearer $VARITY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: deploy-my-app-001" \
  -d '{
    "name": "my-app",
    "repository": {
      "url": "https://github.com/me/my-app"
    }
  }'

Image

curl -X POST https://varity.app/api/deployments \
  -H "Authorization: Bearer $VARITY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: deploy-my-api-001" \
  -d '{
    "name": "my-api",
    "image": {
      "ref": "ghcr.io/me/my-api:latest",
      "port": 8080
    }
  }'

Template

curl -X POST https://varity.app/api/templates/agent-zero/deploy \
  -H "Authorization: Bearer $VARITY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: deploy-agent-zero-001" \
  -d '{ "name": "my-agent" }'

The response includes a Varity deployment id, public URL, run id, and status_url. Poll the run until it reaches succeeded or failed:

curl "https://varity.app/api/deployments/runs/$RUN_ID?app=my-app" \
  -H "Authorization: Bearer $VARITY_API_KEY"

Operate

List deployments:

curl https://varity.app/api/deployments \
  -H "Authorization: Bearer $VARITY_API_KEY"

Read one deployment:

curl https://varity.app/api/deployments/$DEPLOYMENT_ID \
  -H "Authorization: Bearer $VARITY_API_KEY"

Read logs and events:

curl https://varity.app/api/deployments/$DEPLOYMENT_ID/logs \
  -H "Authorization: Bearer $VARITY_API_KEY"

curl https://varity.app/api/deployments/$DEPLOYMENT_ID/events \
  -H "Authorization: Bearer $VARITY_API_KEY"

Both responses include a complete flag and an observed_at timestamp. When complete is false, the returned window may be partial (for example when the live runtime source was momentarily unavailable) and a warning_code is set. The read is safe to retry for a complete window.

Read durable runtime and route health history:

curl "https://varity.app/api/deployments/$DEPLOYMENT_ID/health-history?limit=100" \
  -H "Authorization: Bearer $VARITY_API_KEY"

The response contains a summary with the latest runtime and route health state and reasons, consecutive failure counts, a freshness_at timestamp, and bounded per-service facts (replica, endpoint, and port counts), plus an observations array of recent health checks, bounded by limit (default 100, maximum 500). Per-service entries report restart_count_supported: false and a null restart_count; restart counting is not supported by the current runtime substrate.

List environment variable keys. Values are write-only and are not returned:

curl https://varity.app/api/deployments/$DEPLOYMENT_ID/env \
  -H "Authorization: Bearer $VARITY_API_KEY"

Update environment variables and redeploy in place:

curl -X PATCH https://varity.app/api/deployments/$DEPLOYMENT_ID/env \
  -H "Authorization: Bearer $VARITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "env": { "FEATURE_FLAG": "on" } }'

Redeploy, restart, or delete:

curl -X POST https://varity.app/api/deployments/$DEPLOYMENT_ID/redeploy \
  -H "Authorization: Bearer $VARITY_API_KEY"

curl -X POST https://varity.app/api/deployments/$DEPLOYMENT_ID/restart \
  -H "Authorization: Bearer $VARITY_API_KEY"

curl -X DELETE https://varity.app/api/deployments/$DEPLOYMENT_ID \
  -H "Authorization: Bearer $VARITY_API_KEY"

Templates, Pricing, And Credits

Templates are deployable app starters. Pricing is estimated from the live API, not a hardcoded table, and returns fixed monthly hardware-reservation cost for the requested profile. Credits show whether the caller can deploy with a payment method or active starter credit.

curl https://varity.app/api/templates \
  -H "Authorization: Bearer $VARITY_API_KEY"

curl "https://varity.app/api/pricing/estimate?profile=web-app" \
  -H "Authorization: Bearer $VARITY_API_KEY"

curl https://varity.app/api/credits \
  -H "Authorization: Bearer $VARITY_API_KEY"

Webhooks

Create a webhook:

curl -X POST https://varity.app/api/webhooks \
  -H "Authorization: Bearer $VARITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/varity/webhook",
    "events": ["deployment.accepted", "deployment.live", "deployment.failed"]
  }'

The response includes signing_secret once. Store it to verify webhook deliveries. Varity signs each delivery with:

• X-Varity-Event-Id
• X-Varity-Timestamp
• X-Varity-Signature

The signature is v1= plus an HMAC-SHA256 over timestamp.body using the webhook signing secret. Webhook endpoint URLs must be public HTTPS URLs; local and private hosts are rejected.

Webhook handlers should be idempotent. Delivery-time DNS/IP revalidation, durable delivery queue hardening, and additional signing-secret custody hardening remain non-blocking v1 follow-ups.

List webhooks and delivery status:

curl "https://varity.app/api/webhooks?include_deliveries=true" \
  -H "Authorization: Bearer $VARITY_API_KEY"

Delete a webhook:

curl -X DELETE https://varity.app/api/webhooks/$WEBHOOK_ID \
  -H "Authorization: Bearer $VARITY_API_KEY"

Endpoint Summary

The OpenAPI document contains these 18 public paths:

Methods	Path	Purpose
GET, POST	/api/deployments	List or create deployments
GET	/api/deployments/runs/{run_id}	Get deployment run status
GET, DELETE	/api/deployments/{deployment_id}	Read or delete a deployment
GET	/api/deployments/{deployment_id}/logs	Read deployment logs
GET	/api/deployments/{deployment_id}/events	Read deployment events
GET, PATCH	/api/deployments/{deployment_id}/env	List environment variable keys or update values
POST	/api/deployments/{deployment_id}/redeploy	Redeploy in place
POST	/api/deployments/{deployment_id}/restart	Restart in place
GET	/api/templates	List templates
GET	/api/templates/{template_id}	Read a template
POST	/api/templates/{template_id}/deploy	Deploy a template
GET	/api/pricing/estimate	Estimate fixed monthly cost
GET	/api/credits	Read credit and deploy eligibility
GET, POST	/api/webhooks	List or create webhooks
DELETE	/api/webhooks/{webhook_id}	Delete a webhook
GET, POST	/api/api-keys	List or create API keys in the Developer Portal
DELETE	/api/api-keys/{key_id}	Revoke an API key in the Developer Portal
GET	/api/openapi.json	Read the live OpenAPI contract

Caution

Public API responses use Varity product resources only. Internal implementation details are not part of this contract.

Note

API-key management endpoints are Developer Portal session routes in v1. API keys authenticate non-browser API callers, but API keys cannot create, list, or revoke other API keys. Revoked keys can have a short cache-propagation window before every edge rejects them.

Next Steps

• MCP Server Spec: the tool reference for AI editors
• Deploy a Docker Image: image-deploy details
• Environment Variables: runtime configuration