Skip to main content
POST
/
api
/
v1
/
jobs
POST jobs instances
curl --request POST \
  --url https://app.onecodex.com/api/v1/jobs \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "image_uri": "<string>",
  "name": "<string>",
  "script": "<string>",
  "arguments_schema": [
    {
      "description": "<string>",
      "fa_icon": "<string>",
      "fields": [
        {
          "name": "<string>",
          "choices": [
            "<string>"
          ],
          "default": null,
          "description": "<string>",
          "env_name": "",
          "fa_icon": "<string>",
          "help_text": "<string>",
          "pattern": "<string>",
          "required": false
        }
      ],
      "title": "<string>"
    }
  ],
  "assets": [
    {
      "__DOLLAR_REF__": "/api/v1/assets/a1b2c3d4e5f67890"
    }
  ],
  "cpu": 123,
  "dependencies": [
    {
      "job": {
        "__DOLLAR_REF__": "/api/v1/jobs/a1b2c3d4e5f67890"
      },
      "output_dir": "<string>"
    }
  ],
  "description": "<string>",
  "inject_bearer_token": false,
  "job_type": "shell_script",
  "ram_gb": 123,
  "repository": {
    "url": "<string>",
    "tag": "<string>"
  },
  "storage_gb": 123
}
'
import requests

url = "https://app.onecodex.com/api/v1/jobs"

payload = {
    "image_uri": "<string>",
    "name": "<string>",
    "script": "<string>",
    "arguments_schema": [
        {
            "description": "<string>",
            "fa_icon": "<string>",
            "fields": [
                {
                    "name": "<string>",
                    "choices": ["<string>"],
                    "default": None,
                    "description": "<string>",
                    "env_name": "",
                    "fa_icon": "<string>",
                    "help_text": "<string>",
                    "pattern": "<string>",
                    "required": False
                }
            ],
            "title": "<string>"
        }
    ],
    "assets": [{ "__DOLLAR_REF__": "/api/v1/assets/a1b2c3d4e5f67890" }],
    "cpu": 123,
    "dependencies": [
        {
            "job": { "__DOLLAR_REF__": "/api/v1/jobs/a1b2c3d4e5f67890" },
            "output_dir": "<string>"
        }
    ],
    "description": "<string>",
    "inject_bearer_token": False,
    "job_type": "shell_script",
    "ram_gb": 123,
    "repository": {
        "url": "<string>",
        "tag": "<string>"
    },
    "storage_gb": 123
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)
const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    image_uri: '<string>',
    name: '<string>',
    script: '<string>',
    arguments_schema: [
      {
        description: '<string>',
        fa_icon: '<string>',
        fields: [
          {
            name: '<string>',
            choices: ['<string>'],
            default: null,
            description: '<string>',
            env_name: '',
            fa_icon: '<string>',
            help_text: '<string>',
            pattern: '<string>',
            required: false
          }
        ],
        title: '<string>'
      }
    ],
    assets: [{__DOLLAR_REF__: '/api/v1/assets/a1b2c3d4e5f67890'}],
    cpu: 123,
    dependencies: [
      {job: {__DOLLAR_REF__: '/api/v1/jobs/a1b2c3d4e5f67890'}, output_dir: '<string>'}
    ],
    description: '<string>',
    inject_bearer_token: false,
    job_type: 'shell_script',
    ram_gb: 123,
    repository: {url: '<string>', tag: '<string>'},
    storage_gb: 123
  })
};

fetch('https://app.onecodex.com/api/v1/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://app.onecodex.com/api/v1/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([
    'image_uri' => '<string>',
    'name' => '<string>',
    'script' => '<string>',
    'arguments_schema' => [
        [
                'description' => '<string>',
                'fa_icon' => '<string>',
                'fields' => [
                                [
                                                                'name' => '<string>',
                                                                'choices' => [
                                                                                                                                '<string>'
                                                                ],
                                                                'default' => null,
                                                                'description' => '<string>',
                                                                'env_name' => '',
                                                                'fa_icon' => '<string>',
                                                                'help_text' => '<string>',
                                                                'pattern' => '<string>',
                                                                'required' => false
                                ]
                ],
                'title' => '<string>'
        ]
    ],
    'assets' => [
        [
                '__DOLLAR_REF__' => '/api/v1/assets/a1b2c3d4e5f67890'
        ]
    ],
    'cpu' => 123,
    'dependencies' => [
        [
                'job' => [
                                '__DOLLAR_REF__' => '/api/v1/jobs/a1b2c3d4e5f67890'
                ],
                'output_dir' => '<string>'
        ]
    ],
    'description' => '<string>',
    'inject_bearer_token' => false,
    'job_type' => 'shell_script',
    'ram_gb' => 123,
    'repository' => [
        'url' => '<string>',
        'tag' => '<string>'
    ],
    'storage_gb' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$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://app.onecodex.com/api/v1/jobs"

	payload := strings.NewReader("{\n  \"image_uri\": \"<string>\",\n  \"name\": \"<string>\",\n  \"script\": \"<string>\",\n  \"arguments_schema\": [\n    {\n      \"description\": \"<string>\",\n      \"fa_icon\": \"<string>\",\n      \"fields\": [\n        {\n          \"name\": \"<string>\",\n          \"choices\": [\n            \"<string>\"\n          ],\n          \"default\": null,\n          \"description\": \"<string>\",\n          \"env_name\": \"\",\n          \"fa_icon\": \"<string>\",\n          \"help_text\": \"<string>\",\n          \"pattern\": \"<string>\",\n          \"required\": false\n        }\n      ],\n      \"title\": \"<string>\"\n    }\n  ],\n  \"assets\": [\n    {\n      \"__DOLLAR_REF__\": \"/api/v1/assets/a1b2c3d4e5f67890\"\n    }\n  ],\n  \"cpu\": 123,\n  \"dependencies\": [\n    {\n      \"job\": {\n        \"__DOLLAR_REF__\": \"/api/v1/jobs/a1b2c3d4e5f67890\"\n      },\n      \"output_dir\": \"<string>\"\n    }\n  ],\n  \"description\": \"<string>\",\n  \"inject_bearer_token\": false,\n  \"job_type\": \"shell_script\",\n  \"ram_gb\": 123,\n  \"repository\": {\n    \"url\": \"<string>\",\n    \"tag\": \"<string>\"\n  },\n  \"storage_gb\": 123\n}")

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

	req.Header.Add("X-API-Key", "<api-key>")
	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://app.onecodex.com/api/v1/jobs")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"image_uri\": \"<string>\",\n  \"name\": \"<string>\",\n  \"script\": \"<string>\",\n  \"arguments_schema\": [\n    {\n      \"description\": \"<string>\",\n      \"fa_icon\": \"<string>\",\n      \"fields\": [\n        {\n          \"name\": \"<string>\",\n          \"choices\": [\n            \"<string>\"\n          ],\n          \"default\": null,\n          \"description\": \"<string>\",\n          \"env_name\": \"\",\n          \"fa_icon\": \"<string>\",\n          \"help_text\": \"<string>\",\n          \"pattern\": \"<string>\",\n          \"required\": false\n        }\n      ],\n      \"title\": \"<string>\"\n    }\n  ],\n  \"assets\": [\n    {\n      \"__DOLLAR_REF__\": \"/api/v1/assets/a1b2c3d4e5f67890\"\n    }\n  ],\n  \"cpu\": 123,\n  \"dependencies\": [\n    {\n      \"job\": {\n        \"__DOLLAR_REF__\": \"/api/v1/jobs/a1b2c3d4e5f67890\"\n      },\n      \"output_dir\": \"<string>\"\n    }\n  ],\n  \"description\": \"<string>\",\n  \"inject_bearer_token\": false,\n  \"job_type\": \"shell_script\",\n  \"ram_gb\": 123,\n  \"repository\": {\n    \"url\": \"<string>\",\n    \"tag\": \"<string>\"\n  },\n  \"storage_gb\": 123\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://app.onecodex.com/api/v1/jobs")

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

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"image_uri\": \"<string>\",\n  \"name\": \"<string>\",\n  \"script\": \"<string>\",\n  \"arguments_schema\": [\n    {\n      \"description\": \"<string>\",\n      \"fa_icon\": \"<string>\",\n      \"fields\": [\n        {\n          \"name\": \"<string>\",\n          \"choices\": [\n            \"<string>\"\n          ],\n          \"default\": null,\n          \"description\": \"<string>\",\n          \"env_name\": \"\",\n          \"fa_icon\": \"<string>\",\n          \"help_text\": \"<string>\",\n          \"pattern\": \"<string>\",\n          \"required\": false\n        }\n      ],\n      \"title\": \"<string>\"\n    }\n  ],\n  \"assets\": [\n    {\n      \"__DOLLAR_REF__\": \"/api/v1/assets/a1b2c3d4e5f67890\"\n    }\n  ],\n  \"cpu\": 123,\n  \"dependencies\": [\n    {\n      \"job\": {\n        \"__DOLLAR_REF__\": \"/api/v1/jobs/a1b2c3d4e5f67890\"\n      },\n      \"output_dir\": \"<string>\"\n    }\n  ],\n  \"description\": \"<string>\",\n  \"inject_bearer_token\": false,\n  \"job_type\": \"shell_script\",\n  \"ram_gb\": 123,\n  \"repository\": {\n    \"url\": \"<string>\",\n    \"tag\": \"<string>\"\n  },\n  \"storage_gb\": 123\n}"

response = http.request(request)
puts response.read_body
{
  "$uri": "/api/v1/jobs/0d77065796f8d173",
  "analysis_type": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "job_args_schema": {},
  "name": "<string>",
  "public": true
}
Register a new Job. The request body specifies the job’s name, analysis type, container image, arguments schema, and reference assets. After a job is created, you can run it against a sample via Run A Job.

Authorizations

​
X-API-Key
string
header
required

Body

application/json
​
image_uri
string
required

Fully qualified, publicly available OCI image URI containing every tool the script uses. Examples: docker.io/biocontainers/fastqc:v0.11.9_cv8, docker.io/library/python:3.12. Don't use Docker Hub shorthand forms such as python:3.12 or python/3.12

Minimum string length: 1
​
name
string
required

The human-readable name of the job

Minimum string length: 1
​
script
string
required

The script to be executed, runs as non-root user

Minimum string length: 1
​
arguments_schema
FieldGroup · object[] | null

The schema for the arguments to parametrize this job. Each field is exposed in the script as $ARGS_<UPPER_NAME>. Example: [{"fields": [{"name": "min_quality", "type": "integer"}, {"name": "adapter", "type": "string"}]}]. The input sample is not a parameter; it is passed separately at run time

​
assets
Assets · object[] | null

An optional list of assets associated with this job

​
cpu
number | null

The number of CPU cores used for this job, set only for shell script jobs

​
dependencies
JobDependencySchema · object[] | null

Optional job dependencies for this job. If provided, will be triggered automatically when this job is run

​
description
string | null

The human-readable description of the job. Supports markdown

​
inject_bearer_token
boolean
default:false

Whether to inject the user's One Codex bearer token into the analysis job, exposed as $ONE_CODEX_BEARER_TOKEN

​
job_type
enum<string>
default:shell_script

Whether this is a shell script or a Nextflow job

Available options:
shell_script,
nextflow
​
ram_gb
number | null

The amount of RAM used for this job in GB, set only for shell script jobs

​
repository
RepositorySchema · object | null

The git repository that this job runs against

​
storage_gb
number | null

The amount of storage used for this job in GB, set only for shell script jobs

Response

200 - application/json

OK

​
$uri
string
required
read-only
Pattern: ^/api/v1/jobs/[a-f0-9]{16}$
Example:

"/api/v1/jobs/0d77065796f8d173"

​
analysis_type
string
required

The type of analysis. See the analysis resource for more details.

​
created_at
string<date-time>
required

Timestamp for when the object was created on the One Codex platform, encoded as a RFC 3339 timestamp.

​
job_args_schema
Job Args Schema · object
required

The JSON schema for the arguments taken by the job (can be an empty object, i.e., {}).

​
name
string
required

The name of the job (this is displayed in the dropdown on the analysis page of the One Codex web application).

​
public
boolean
required

Whether the job is publicly available. For most jobs this will be true. Custom, private jobs are also available, and will only be visible to users whose samples (or samples shared with them) have been analyzed using that job.