Create Job - Archetype AI Documentation

Create Job

curl --request POST \
  --url https://api.u1.archetypeai.app/v0.5/batch/jobs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "pipeline_type": "<string>",
  "pipeline_key": "<string>",
  "workflow_key": "<string>",
  "pipeline_version": "<string>",
  "inputs": {},
  "parameters": {}
}
'

import requests

url = "https://api.u1.archetypeai.app/v0.5/batch/jobs"

payload = {
    "name": "<string>",
    "pipeline_type": "<string>",
    "pipeline_key": "<string>",
    "workflow_key": "<string>",
    "pipeline_version": "<string>",
    "inputs": {},
    "parameters": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    pipeline_type: '<string>',
    pipeline_key: '<string>',
    workflow_key: '<string>',
    pipeline_version: '<string>',
    inputs: {},
    parameters: {}
  })
};

fetch('https://api.u1.archetypeai.app/v0.5/batch/jobs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.u1.archetypeai.app/v0.5/batch/jobs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'pipeline_type' => '<string>',
    'pipeline_key' => '<string>',
    'workflow_key' => '<string>',
    'pipeline_version' => '<string>',
    'inputs' => [
        
    ],
    'parameters' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.u1.archetypeai.app/v0.5/batch/jobs"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"pipeline_type\": \"<string>\",\n  \"pipeline_key\": \"<string>\",\n  \"workflow_key\": \"<string>\",\n  \"pipeline_version\": \"<string>\",\n  \"inputs\": {},\n  \"parameters\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.u1.archetypeai.app/v0.5/batch/jobs")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"pipeline_type\": \"<string>\",\n  \"pipeline_key\": \"<string>\",\n  \"workflow_key\": \"<string>\",\n  \"pipeline_version\": \"<string>\",\n  \"inputs\": {},\n  \"parameters\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.u1.archetypeai.app/v0.5/batch/jobs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"pipeline_type\": \"<string>\",\n  \"pipeline_key\": \"<string>\",\n  \"workflow_key\": \"<string>\",\n  \"pipeline_version\": \"<string>\",\n  \"inputs\": {},\n  \"parameters\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "org_id": "<string>",
  "name": "<string>",
  "pipeline_type": "<string>",
  "pipeline_key": "<string>",
  "workflow_key": "<string>",
  "pipeline_version": "<string>",
  "status": "<string>",
  "outcome": null,
  "parameters": {},
  "retry_count": 123,
  "preemption_count": 123,
  "queue_position": 123,
  "queue_depth": 123,
  "input_progress": {},
  "created_at": "<string>",
  "updated_at": "<string>",
  "started_at": "<string>",
  "completed_at": "<string>",
  "failed_at": "<string>",
  "cancelled_at": "<string>",
  "error": {}
}

POST

batch

jobs

Create Job

curl --request POST \
  --url https://api.u1.archetypeai.app/v0.5/batch/jobs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "pipeline_type": "<string>",
  "pipeline_key": "<string>",
  "workflow_key": "<string>",
  "pipeline_version": "<string>",
  "inputs": {},
  "parameters": {}
}
'

import requests

url = "https://api.u1.archetypeai.app/v0.5/batch/jobs"

payload = {
    "name": "<string>",
    "pipeline_type": "<string>",
    "pipeline_key": "<string>",
    "workflow_key": "<string>",
    "pipeline_version": "<string>",
    "inputs": {},
    "parameters": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    pipeline_type: '<string>',
    pipeline_key: '<string>',
    workflow_key: '<string>',
    pipeline_version: '<string>',
    inputs: {},
    parameters: {}
  })
};

fetch('https://api.u1.archetypeai.app/v0.5/batch/jobs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.u1.archetypeai.app/v0.5/batch/jobs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'pipeline_type' => '<string>',
    'pipeline_key' => '<string>',
    'workflow_key' => '<string>',
    'pipeline_version' => '<string>',
    'inputs' => [
        
    ],
    'parameters' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.u1.archetypeai.app/v0.5/batch/jobs"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"pipeline_type\": \"<string>\",\n  \"pipeline_key\": \"<string>\",\n  \"workflow_key\": \"<string>\",\n  \"pipeline_version\": \"<string>\",\n  \"inputs\": {},\n  \"parameters\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.u1.archetypeai.app/v0.5/batch/jobs")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"pipeline_type\": \"<string>\",\n  \"pipeline_key\": \"<string>\",\n  \"workflow_key\": \"<string>\",\n  \"pipeline_version\": \"<string>\",\n  \"inputs\": {},\n  \"parameters\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.u1.archetypeai.app/v0.5/batch/jobs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"pipeline_type\": \"<string>\",\n  \"pipeline_key\": \"<string>\",\n  \"workflow_key\": \"<string>\",\n  \"pipeline_version\": \"<string>\",\n  \"inputs\": {},\n  \"parameters\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "org_id": "<string>",
  "name": "<string>",
  "pipeline_type": "<string>",
  "pipeline_key": "<string>",
  "workflow_key": "<string>",
  "pipeline_version": "<string>",
  "status": "<string>",
  "outcome": null,
  "parameters": {},
  "retry_count": 123,
  "preemption_count": 123,
  "queue_position": 123,
  "queue_depth": 123,
  "input_progress": {},
  "created_at": "<string>",
  "updated_at": "<string>",
  "started_at": "<string>",
  "completed_at": "<string>",
  "failed_at": "<string>",
  "cancelled_at": "<string>",
  "error": {}
}

Requires version 1.1.0 or later of the Archetype platform.

Overview

This endpoint creates a new job with the specified pipeline configuration and optional input files. The job is placed into the queue and will be processed when resources are available. Inputs are organized by port name. The available ports depend on the pipeline — call Get Pipeline Schema first if you don’t know them. The two batch pipelines deployed on the platform today are:

machine-state-classification — time-series sensor classification via an Omega encoder + KNN. Input ports: worker.inference (CSV files to classify), worker.n_shots (labeled CSV example files with metadata.class). Output port: worker.results.
activity-detection — Newton C language model over a JSONL prompt file. Input port: worker.data (one JSONL file, each line an InferenceRecord). Output port: worker.result.

Request

string

required

A human-readable name for the job

string

deprecated

Deprecated; kept for backward compatibility. The type of pipeline to run. One of: batch, training.

string

deprecated

Deprecated; kept for backward compatibility: use workflow_key instead. The key identifying the pipeline to use from the registry (e.g. machine-state-classification, activity-detection)

string

Key of the workflow to run. One of workflow_key or the deprecated pipeline_key parameter must be provided. If both are provided, they must be equal. v1.1.7+

string

Specific pipeline version to use. If omitted, the latest published version is used.

object

Input files organized by port name. Each key is a port name (see the pipeline schema) and the value is an array of input file objects:

file_id (string, required) — The file ID returned from the Files API
metadata (object) — Optional per-input metadata. For n-shot ports this carries the class label ({"class": "..."}).

object

Pipeline parameters organized by component name (e.g. worker). Each value is an object with:

parallelism (integer) — Number of parallel workers for this component
config (object) — Free-form configuration passed to the container. The accepted shape is defined by the pipeline’s user_config_schema — fetch it via Get Pipeline Schema.

Response

string

Unique job identifier (TypeID, job_ prefix)

string

Organization identifier

string

Job name

string

Pipeline type (batch or training)

string

Pipeline key. The value is the same as workflow_key. This property is retained for backward compatibility.

string

Key of the workflow this job runs. The value is the same as pipeline_key, which is retained for backward compatibility. v1.1.8+

string

Pipeline version used

string

Initial job status (typically PENDING)

null

Omitted for any job whose status is not COMPLETED. v1.1.5+

object

Resolved job parameters (user-supplied values merged onto the pipeline’s default_config)

integer

Number of times the job has been retried (always 0 on create)

integer

Number of times the job has been preempted (always 0 on create)

integer

Position in the queue at admission time. Omitted from the response when not queued (e.g. terminal-state jobs).

integer

Total queue depth at admission time. Omitted from the response when not queued.

object

Per-status counts of tracked inputs (pending, processing, completed, failed). Omitted from this response — populated only on read paths like GET /batch/jobs and GET /batch/jobs/{id}.

string

Creation timestamp in RFC 3339 format

string

Last update timestamp

string

Start timestamp, or null if not yet started

string

Completion timestamp, or null

string

Failure timestamp, or null

string

Cancellation timestamp, or null

object

Error details, or null

Examples

The two batch pipelines deployed on the platform take very different request bodies. Switch tabs to compare.

machine-state-classification
activity-detection

Classify time-series sensor data using n-shot example files. Inputs split across two ports — worker.inference for the CSVs to classify and worker.n_shots for the labeled example files (class declared via metadata.class).

curl -X POST https://api.u1.archetypeai.app/v0.5/batch/jobs \
  -H "Authorization: Bearer $ATAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "tep-classification",
    "workflow_key": "machine-state-classification",
    "inputs": {
      "worker.inference": [
        {"file_id": "tep_inference.csv"}
      ],
      "worker.n_shots": [
        {"file_id": "tep_normal.csv", "metadata": {"class": "normal"}},
        {"file_id": "tep_fault.csv",  "metadata": {"class": "fault"}}
      ]
    },
    "parameters": {
      "worker": {
        "parallelism": 1,
        "config": {
          "model_type": "omega_1_4_base",
          "batch_size": 32,
          "reader_config": {
            "data_columns": ["xmeas_1", "xmeas_2", "xmv_11"],
            "timestamp_column": "timestamp",
            "window_size": 64,
            "step_size": 1
          },
          "classifier_config": {
            "n_neighbors": 5,
            "metric": "euclidean",
            "weights": "uniform",
            "normalize_embeddings": false
          },
          "flush_every_n_iteration": 150
        }
      }
    }
  }'

import requests
import os

api_key = os.environ.get("ATAI_API_KEY")

response = requests.post(
    "https://api.u1.archetypeai.app/v0.5/batch/jobs",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "name": "tep-classification",
        "workflow_key": "machine-state-classification",
        "inputs": {
            "worker.inference": [
                {"file_id": "tep_inference.csv"},
            ],
            "worker.n_shots": [
                {"file_id": "tep_normal.csv", "metadata": {"class": "normal"}},
                {"file_id": "tep_fault.csv",  "metadata": {"class": "fault"}},
            ],
        },
        "parameters": {
            "worker": {
                "parallelism": 1,
                "config": {
                    "model_type": "omega_1_4_base",
                    "batch_size": 32,
                    "reader_config": {
                        "data_columns": ["xmeas_1", "xmeas_2", "xmv_11"],
                        "timestamp_column": "timestamp",
                        "window_size": 64,
                        "step_size": 1,
                    },
                    "classifier_config": {
                        "n_neighbors": 5,
                        "metric": "euclidean",
                        "weights": "uniform",
                        "normalize_embeddings": False,
                    },
                    "flush_every_n_iteration": 150,
                },
            }
        },
    },
)

job = response.json()
print(f"Job created: {job['id']} — Status: {job['status']}")

const response = await fetch('https://api.u1.archetypeai.app/v0.5/batch/jobs', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.ATAI_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'tep-classification',
    workflow_key: 'machine-state-classification',
    inputs: {
      'worker.inference': [
        { file_id: 'tep_inference.csv' }
      ],
      'worker.n_shots': [
        { file_id: 'tep_normal.csv', metadata: { class: 'normal' } },
        { file_id: 'tep_fault.csv',  metadata: { class: 'fault' } }
      ]
    },
    parameters: {
      worker: {
        parallelism: 1,
        config: {
          model_type: 'omega_1_4_base',
          batch_size: 32,
          reader_config: {
            data_columns: ['xmeas_1', 'xmeas_2', 'xmv_11'],
            timestamp_column: 'timestamp',
            window_size: 64,
            step_size: 1
          },
          classifier_config: {
            n_neighbors: 5,
            metric: 'euclidean',
            weights: 'uniform',
            normalize_embeddings: false
          },
          flush_every_n_iteration: 150
        }
      }
    }
  })
});

const job = await response.json();
console.log(`Job created: ${job.id} — Status: ${job.status}`);

Response — 201 Created

{
  "id": "job_2abc3def4ghi5jkl6mno7pqr",
  "org_id": "org_1abc2def3ghi4jkl",
  "name": "tep-classification",
  "pipeline_type": "batch",
  "pipeline_key": "machine-state-classification",
  "pipeline_version": "1.1.1",
  "status": "PENDING",
  "parameters": {
    "worker": {
      "parallelism": 1,
      "config": {
        "model_type": "omega_1_4_base",
        "batch_size": 32,
        "reader_config": {
          "data_columns": ["xmeas_1", "xmeas_2", "xmv_11"],
          "timestamp_column": "timestamp",
          "window_size": 64,
          "step_size": 1
        },
        "classifier_config": {
          "n_neighbors": 5,
          "metric": "euclidean",
          "weights": "uniform",
          "normalize_embeddings": false
        },
        "flush_every_n_iteration": 150
      }
    }
  },
  "retry_count": 0,
  "preemption_count": 0,
  "created_at": "2026-04-14T10:00:00Z",
  "updated_at": "2026-04-14T10:00:00Z",
  "started_at": null,
  "completed_at": null,
  "failed_at": null,
  "cancelled_at": null,
  "error": null
}

See the newton-machine-state-batch skill for model selection (omega_1_4_base vs the legacy 1.3 variants), window_size / step_size guidance at high sample rates, and the within-distribution vs cross-condition accuracy pitfall.

Run the Newton C language model over a JSONL prompt file. Single input port worker.data containing one JSONL file; each line is an InferenceRecord (system?, instruction?, prompt?, optional inputs[] carrying text/image/video evidence as inline base64). Output is one JSON line per record: {"line_index": N, "prediction": "..."}.

curl -X POST https://api.u1.archetypeai.app/v0.5/batch/jobs \
  -H "Authorization: Bearer $ATAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "narrative-generation",
    "workflow_key": "activity-detection",
    "inputs": {
      "worker.data": [{"file_id": "my_prompts.jsonl"}]
    },
    "parameters": {
      "worker": {
        "parallelism": 1,
        "config": {
          "generation": {
            "max_new_tokens": 1024,
            "do_sample": true,
            "temperature": 0.7,
            "top_p": 0.8,
            "top_k": 20,
            "repetition_penalty": 1
          }
        }
      }
    }
  }'

import requests
import os

api_key = os.environ.get("ATAI_API_KEY")

response = requests.post(
    "https://api.u1.archetypeai.app/v0.5/batch/jobs",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "name": "narrative-generation",
        "workflow_key": "activity-detection",
        "inputs": {
            "worker.data": [{"file_id": "my_prompts.jsonl"}],
        },
        "parameters": {
            "worker": {
                "parallelism": 1,
                "config": {
                    "generation": {
                        "max_new_tokens": 1024,
                        "do_sample": True,
                        "temperature": 0.7,
                        "top_p": 0.8,
                        "top_k": 20,
                        "repetition_penalty": 1,
                    }
                },
            }
        },
    },
)

job = response.json()
print(f"Job created: {job['id']} — Status: {job['status']}")

const response = await fetch('https://api.u1.archetypeai.app/v0.5/batch/jobs', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.ATAI_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'narrative-generation',
    workflow_key: 'activity-detection',
    inputs: {
      'worker.data': [{ file_id: 'my_prompts.jsonl' }]
    },
    parameters: {
      worker: {
        parallelism: 1,
        config: {
          generation: {
            max_new_tokens: 1024,
            do_sample: true,
            temperature: 0.7,
            top_p: 0.8,
            top_k: 20,
            repetition_penalty: 1
          }
        }
      }
    }
  })
});

const job = await response.json();
console.log(`Job created: ${job.id} — Status: ${job.status}`);

Response — 201 Created

{
  "id": "job_3xyz4abc5def6ghi7jkl8mno",
  "org_id": "org_1abc2def3ghi4jkl",
  "name": "narrative-generation",
  "pipeline_type": "batch",
  "pipeline_key": "activity-detection",
  "pipeline_version": "1.1.1",
  "status": "PENDING",
  "parameters": {
    "worker": {
      "parallelism": 1,
      "config": {
        "generation": {
          "max_new_tokens": 1024,
          "do_sample": true,
          "temperature": 0.7,
          "top_p": 0.8,
          "top_k": 20,
          "repetition_penalty": 1
        }
      }
    }
  },
  "retry_count": 0,
  "preemption_count": 0,
  "created_at": "2026-04-14T10:00:00Z",
  "updated_at": "2026-04-14T10:00:00Z",
  "started_at": null,
  "completed_at": null,
  "failed_at": null,
  "cancelled_at": null,
  "error": null
}

See the newton-activity-detection-batch skill for the full InferenceRecord schema (text / image / video inputs), the ~4K-token quality cliff for CSV-heavy inputs, MapReduce / hierarchical reduce patterns, and the two silent join bugs to watch for when chaining reduce stages.

Error responses

400 - Invalid Request

{
  "code": "INVALID_REQUEST",
  "message": "workflow_key 'nonexistent-pipeline' not found in registry",
  "error_uid": "err_abc123",
  "suggestion": "Check available pipelines with GET /batch/registry/pipelines"
}

401 - Unauthorized

{
  "detail": "Invalid access with key: api_key_not_found"
}

404 - Not Found

{
  "code": "NOT_FOUND",
  "error_uid": "err_abc123",
  "message": "Pipeline '{workflow_key}' has no active versions."
}

​Overview

​Request

​Response

​Examples

​Error responses

Overview

Request

Response

Examples

Error responses