Create a job from a template

POST /api/job-templates/{id}/jobs

Instantiates a job by snapshotting the template's current YAML and pinning each referenced task to its current DB version. The job is then independent of future changes to the template or tasks.

Validates that:

• All required connectors are mapped and types match.
• All tasks referenced in the template DAG exist in the database.

Operation ID: createJobFromTemplate

Authentication

Option 1

• BearerAuth (http bearer) API key token. Create via POST /api/api-keys. Format: envoy_<hex>

Option 2

• CookieAuth (apiKey) Session cookie set after login + TOTP verification

Path parameters

• id — integer, required Resource ID

Request body

The request body is required.

application/json

• Type: object
• Properties:
  • name (string, required)
  • description (string)
  • connector_mapping (object, required) — Map of template connector name to connector ID
    • Description: Map of template connector name to connector ID
    • Additional properties:
      • Type: integer

Success responses

201

Job created

Content type: application/json

• Reference: Job
  • Type: object
  • Properties:
    • id (integer)
    • job_template_id (integer)
    • name (string)
    • description (string | null)
      • Nullable: yes
    • connector_mapping (string) — JSON-encoded map of template connector name to connector ID
    • status (string)
      • Allowed values: active, archived
    • overridden_task_keys (array<string>) — DAG node keys with a per-job task YAML override. Present on GET detail.
      • Description: DAG node keys with a per-job task YAML override. Present on GET detail.
      • Items:
        • Type: string
    • created_at (string)
      • Format: date-time
    • updated_at (string)
      • Format: date-time

Error responses

400

Validation error

Content type: application/json

• Reference: Error
  • Type: object
  • Properties:
    • error (string)
      • Example: NOT_FOUND
    • message (string)
      • Example: Resource not found

Example:

{
  "error": "VALIDATION_ERROR",
  "message": "Invalid input"
}

404

Resource not found

Content type: application/json

• Reference: Error
  • Type: object
  • Properties:
    • error (string)
      • Example: NOT_FOUND
    • message (string)
      • Example: Resource not found

Example:

{
  "error": "NOT_FOUND",
  "message": "Resource not found"
}

Examples

cURL

curl --request POST \
  --url 'https://your-envoy.example.com/api/job-templates/YOUR_ID/jobs' \
  --header 'Authorization: Bearer $API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "string",
  "connector_mapping": {}
}'

JavaScript (fetch)

const response = await fetch('https://your-envoy.example.com/api/job-templates/YOUR_ID/jobs', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "string",
    "connector_mapping": {}
  }),
});
 
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const data = response.status === 204 ? null : await response.json();
console.log(data);