API Reference

Import tasks and job templates from NDJSON bundle

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 IDimportBundle

Authentication

BearerAuth·http bearer·API key token (envoy_<hex>). Create keys from Settings → API Keys — see Using the API.

Query parameters

modestring

Default: upsert_current
Allowed values: create_only, upsert_current, upsert_all_versions

conflict_policystring

Default: overwrite
Allowed values: skip, overwrite, error

dry_runboolean

Default: false

validate_onlyboolean

Default: false

archived_task_policystring

Default: skip
Allowed values: skip, restore, keep_archived

normalize_namesboolean

Default: false

actionstring

Only emit result lines with this action (summary is always full)

Allowed values: create, update, unchanged, skip, error

Request body

This request body is required.

Content typeapplication/x-ndjson

requeststring

Content typetext/plain

requeststring

Success response body

200NDJSON stream of result lines followed by a summary line

NDJSON stream of result lines followed by a summary line

Content typeapplication/x-ndjson

responseobject | object & BundleImportSummary

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

One of 1object

2 properties

kindstringrequired

Allowed values: result

resultobjectrequired

7 properties

kindstring

Allowed values: task, job_template

namestring

actionstring

Allowed values: create, update, unchanged, skip, error

from_versioninteger

to_versioninteger

messagestring

validationobject

Additional properties are allowed.

One of 2object

6 properties

kindstringrequired

Allowed values: summary

createdintegerrequired

updatedintegerrequired

skippedintegerrequired

unchangedintegerrequired

errorsintegerrequired

Error responses

400Validation or parse error

Validation or parse error

Content typeapplication/json

responseErrorResponse

Code examples

curl --request POST \
  --url 'https://your-envoy.example.com/api/import?mode=upsert_current&conflict_policy=overwrite&dry_run=false&validate_only=false&archived_task_policy=skip&normalize_names=false&action=create' \
  --header 'Authorization: Bearer $API_KEY' \
  --header 'Content-Type: text/plain' \
  --data 'string'

const response = await fetch("https://your-envoy.example.com/api/import?mode=upsert_current&conflict_policy=overwrite&dry_run=false&validate_only=false&archived_task_policy=skip&normalize_names=false&action=create", {
  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);