Create application

Overview

Create application registers a system under test in your organization: name, application type (web, API, desktop), team ownership, and environment URLs used when dispatching validation. This is the programmatic equivalent of Platform → Applications → Create.

Use this endpoint when onboarding services from a CMDB, Terraform pipeline, or internal developer portal so engineers inherit correct team scope and staging URLs before creating reliability projects.

Who should read this

• Platform engineers integrating CI/CD, internal tooling, or data pipelines with Zof.

Prerequisites

• Valid organization API key with permission for this resource
• Resource ID when path includes {id}, copy from Console or list endpoint
• Staging environment for first integration test

When to use this workflow

• Provisioning a new microservice before first Zof project
• Syncing application registry from internal service catalog nightly
• Terraform or Backstage scaffolder creating Zof resources alongside repo creation

Step-by-step procedure

Key concepts

Permission

Requires applications:create (typically QA Lead or custom automation role).

name

Display name shown in Console and reports; unique per organization recommended.

type

web | api | desktop; drives default agent categories and execution plane hints.

team_id

Team that owns the application for RBAC and reporting scope.

urls

Map of environment keys (staging, production) to HTTPS base URLs agents will target.

Best practices

• Use idempotency keys for POST operations in automation
• Handle 429 responses with exponential backoff and jitter
• Log X-Request-Id from response headers for support escalation
• Test against staging project IDs before production automation

Common issues

422 validation_error

Missing team_id or invalid URL scheme; URLs must be https:// in production paths.

409 duplicate_name

Application name already exists; use PATCH update or unique naming convention.

403 Forbidden

API key lacks applications:create; assign role in Admin Center.

Create application (curl)

curl -X POST https://api.zof.ai/v1/applications \
  -H "Authorization: Bearer $ZOF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: app-checkout-$(date +%Y%m%d)" \
  -d '{
    "name": "Checkout Web",
    "type": "web",
    "team_id": "team_01HXXXX",
    "urls": {
      "staging": "https://staging.example.com",
      "production": "https://checkout.example.com"
    }
  }'

API operations

Related documentation