Import tasks and job templates from NDJSON bundle

Accepts a newline-delimited JSON bundle in the request body. Streams an NDJSON response: one { "kind": "result", "result": ... } line per imported item (as it is processed), the…

POST /api/import

Accepts a newline-delimited JSON bundle in the request body. Streams an NDJSON response: one { "kind": "result", "result": ... } line per imported item (as it is processed), then a final { "kind": "summary", ... } line with full counts. Optional action filters which result lines are emitted; the summary always covers every record. Requires admin or superadmin role.

Operation ID: importBundle

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

Query parameters

mode — string Example: upsert_current
- Allowed values: create_only, upsert_current, upsert_all_versions
- Default: upsert_current
conflict_policy — string Example: overwrite
- Allowed values: skip, overwrite, error
- Default: overwrite
dry_run — boolean Example: false
- Default: false
validate_only — boolean Example: false
- Default: false
archived_task_policy — string Example: skip
- Allowed values: skip, restore, keep_archived
- Default: skip
normalize_names — boolean Example: false
- Default: false
action — string Only emit result lines with this action (summary is always full)
- Allowed values: create, update, unchanged, skip, error

Request body

The request body is required.

`application/x-ndjson`

Type: string

`text/plain`

Type: string

Success responses

200

NDJSON stream of result lines followed by a summary line

Content type: application/x-ndjson

Reference: BundleImportStreamLine
- Type: object | object & BundleImportSummary
- Description: One NDJSON line from POST /api/import. Result lines stream as each record is processed; a final summary line always closes the stream.
- One of:
  - Variant 1:
    - Type: object
    - Properties:
      - kind (string, required)
        
        Allowed values: result
      - result (BundleImportResultItem, required)
        
        Reference: BundleImportResultItem
        
        Properties:
        
        kind (string)
        
        Allowed values: task, job_template
        
        name (string)
        
        action (string)
        
        Allowed values: create, update, unchanged, skip, error
        
        from_version (integer)
        
        to_version (integer)
        
        message (string)
        
        validation (object)
        
        Additional properties: allowed
  - Variant 2:
    - Type: object & BundleImportSummary
    - All of:
      - Variant 1:
        
        Type: object
        
        Properties:
        
        kind (string, required)
        
        Allowed values: summary
      - Variant 2:
        
        Reference: BundleImportSummary
        
        Type: object
        
        Properties:
        
        created (integer, required)
        
        updated (integer, required)
        
        skipped (integer, required)
        
        unchanged (integer, required)
        
        errors (integer, required)

Error responses

400

Validation or parse error

Content type: application/json

Reference: ErrorResponse
- Unresolved local reference.

Examples

cURL

curl --request POST \
  --url 'https://your-envoy.example.com/api/import' \
  --header 'Authorization: Bearer $API_KEY' \
  --header 'Content-Type: text/plain' \
  --data 'string'

JavaScript (fetch)

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