# Jobs

Once your [apps](https://docs.bytenite.com/create-with-bytenite/building-blocks/apps "mention"), [partitioning-engines](https://docs.bytenite.com/create-with-bytenite/building-blocks/partitioning-engines "mention"), and [assembling-engines](https://docs.bytenite.com/create-with-bytenite/building-blocks/assembling-engines "mention") are ready, and you've linked them together using [job-templates](https://docs.bytenite.com/create-with-bytenite/building-blocks/job-templates "mention"), you're prepared to launch test and production jobs.

ByteNite utilizes an API to handle job requests — the [customer-api](https://docs.bytenite.com/api-reference/customer-api "mention")— simplifying and standardizing the interaction with our server.

To begin using the API and familiarizing yourself with its endpoint, we recommend setting up a Postman collection. You can find more details at [#create-a-postman-collection-from-bytenites-oas](https://docs.bytenite.com/getting-started/onboarding#create-a-postman-collection-from-bytenites-oas "mention").

Below are the steps to configure and send a new job request, broken down and explained. You may refer to the official [jobs](https://docs.bytenite.com/api-reference/customer-api/jobs "mention") reference for a complete parameter list, response codes, and default code examples.

{% stepper %}
{% step %}

### Get an Access Token

Begin by obtaining a temporary access token to authenticate your requests.

{% tabs %}
{% tab title="Request URL" %} <mark style="color:yellow;">`POST`</mark> `https://api.bytenite.com/v1/auth/access_token`

***

*Main ref:* [#access\_token](https://docs.bytenite.com/api-reference/authentication-api/access-token#access_token "mention")
{% endtab %}

{% tab title="Body" %}

| Name         | Type     | Description           |
| ------------ | -------- | --------------------- |
| `apiKey`     | *string* | Your ByteNite API Key |
| {% endtab %} |          |                       |

{% tab title="Response \[200]" %}

| Name          | Type     | Description                      |
| ------------- | -------- | -------------------------------- |
| `token`       | *string* | Your ByteNite access token       |
| `expiresIn`   | *string* | An expiration timeout in seconds |
| {% endtab %}  |          |                                  |
| {% endtabs %} |          |                                  |

Example:

{% code title="POST /auth/access\_token" %}

```python
import requests

response = requests.post(
    "https://api.bytenite.com/v1/auth/access_token",
    json = {
        "apiKey": "ey2WmEsSMK7wdxpK5MaEHXeWCD5KEJZ79Koe68yrHL4kdnnTXT01hu2iss43BdaCCMgJ3dBh2IOVCycTt1mwkT3QR1dLxRFpK7TW7ExvcuCXio6nKsGjk9dYY8nbsFffrUVvYSQYsuQoF3NIb8sS4MDyZfOgGKZL9z8x22cwrwEck7vIokVhQ9fyWRVU2vwRiX3X4bQFuqTkkWCi5Vfy8IkGkga7ZPMPb21FxqK6cHRJ3zmI1JZZoZZxERnQcWJTpZRyCP4SNTuRm3ueVDNntFqYWYYrseNLcCIS42MpR00Z9rI9I5xxuQD6VQvHVrpOaPucg1E4Vw54xXr2LKEy9uHcM5WUQHkdfhiXo6zyVbZMrbjLpepgeS4nEja="
    }
)

token = response.json()["token"]
```

{% endcode %}

{% endstep %}

{% step %}

### Create a New Job

Submit a new job request using an existing job template, and give it a name.

{% tabs %}
{% tab title="Request URL" %} <mark style="color:yellow;">`POST`</mark> `https://api.bytenite.com/v1/customer/jobs`

***

*Main ref:* [#jobs](https://docs.bytenite.com/api-reference/customer-api/jobs/create#jobs "mention")
{% endtab %}

{% tab title="Headers" %}

| Name            | Type     | Description                       |
| --------------- | -------- | --------------------------------- |
| `Authorization` | *string* | An active ByteNite access `token` |
| {% endtab %}    |          |                                   |

{% tab title="Body" %}

| Name          | Type     | Description                                   |
| ------------- | -------- | --------------------------------------------- |
| `templateId`  | *string* | ID of the job template used for this job      |
| `name`        | *string* | A descriptive name for your job               |
| `description` | *string* | An optional description with more information |
| {% endtab %}  |          |                                               |

{% tab title="Response \[200]" %}

| Name          | Type     | Description                                  |
| ------------- | -------- | -------------------------------------------- |
| `job`         | *object* | A job object, containing job metadata        |
| ↳ `id`        | *string* | The job identifier (automatically generated) |
| {% endtab %}  |          |                                              |
| {% endtabs %} |          |                                              |

Example:

{% code title="POST /customer/jobs" %}

```python
response = requests.post(
    "https://api.bytenite.com/v1/customer/jobs",
    headers = {
        "Authorization": token
    },
    json = {
        "name": "My job with img-gen-diffusers template",
        "templateId": "img-gen-diffusers"
    }
)

jobId = response.json()["job"]["id"]
```

{% endcode %}

{% endstep %}

{% step %}

### Submit a Data Source and Destination

Link a data source and destination to your job, specifying input and output options as documented in the [data-sources](https://docs.bytenite.com/launch-with-bytenite/data-sources "mention") guide.

Connecting data sources is optional: if your app doesn't require any input data to work, or doesn't output data, you can specify a `bypass` data source descriptor.

{% tabs %}
{% tab title="Request URL" %} <mark style="color:purple;">`PATCH`</mark> `https://api.bytenite.com/v1/customer/jobs/{jobId}/datasource`

***

*Main ref:* [#jobs-jobid-datasource](https://docs.bytenite.com/api-reference/customer-api/jobs/update#jobs-jobid-datasource "mention")
{% endtab %}

{% tab title="Path Params" %}

| Name         | Type     | Description                |
| ------------ | -------- | -------------------------- |
| `jobId`      | *string* | The `jobId`of your new job |
| {% endtab %} |          |                            |

{% tab title="Headers" %}

| Name            | Type     | Description                       |
| --------------- | -------- | --------------------------------- |
| `Authorization` | *string* | An active ByteNite access `token` |
| {% endtab %}    |          |                                   |

{% tab title="Body" %}

| Name              | Type     | Description                                                                     |
| ----------------- | -------- | ------------------------------------------------------------------------------- |
| `dataSource`      | *object* | A data source object, containing a `dataSourceDescriptor` and optional `params` |
| `dataDestination` | *object* | A data source object, containing a `dataSourceDescriptor` and optional `params` |
| {% endtab %}      |          |                                                                                 |
| {% endtabs %}     |          |                                                                                 |

Example:

{% code title="PATCH /customer/jobs/{jobId}/datasource" %}

```python
response = requests.patch(
    f"https://api.bytenite.com/v1/customer/jobs/{jobId}/datasource",
    headers = {
        "Authorization": token
    },
    json = {  
        "dataSource": {
            "dataSourceDescriptor": "url",
            "params": {
                "@type": "type.googleapis.com/bytenite.data_source.HttpDataSource",
                "url": "https://storage.googleapis.com/my-public-bucket/my-input-file.txt"
            }
        },
        "dataDestination": {
            "dataSourceDescriptor": "bucket"
        }
    }
)
```

{% endcode %}

{% endstep %}

{% step %}

### Submit Job Parameters

If your app, partitioner, or assembler expect parameters, provide them at this step. Parameters are organized under three keys: `app`, `partitioner`, and `assembler` for clarity.

If your template includes parameter schemas, the parameters you submit here will be validated immediately, and any errors will be returned.

{% tabs %}
{% tab title="Request URL" %} <mark style="color:purple;">`PATCH`</mark> `https://api.bytenite.com/v1/customer/jobs/{jobId}/params`

***

*Main ref:* [#jobs-jobid-params](https://docs.bytenite.com/api-reference/customer-api/jobs/update#jobs-jobid-params "mention")
{% endtab %}

{% tab title="Path Params" %}

| Name         | Type     | Description                |
| ------------ | -------- | -------------------------- |
| `jobId`      | *string* | The `jobId`of your new job |
| {% endtab %} |          |                            |

{% tab title="Headers" %}

| Name            | Type     | Description                       |
| --------------- | -------- | --------------------------------- |
| `Authorization` | *string* | An active ByteNite access `token` |
| {% endtab %}    |          |                                   |

{% tab title="Body" %}

| Name          | Type     | Description                                                                 |
| ------------- | -------- | --------------------------------------------------------------------------- |
| `app`         | *object* | A JSON object containing parameters as expected by your app                 |
| `partitioner` | *object* | A JSON object containing parameters as expected by your partitioning engine |
| `assembler`   | *object* | A JSON object containing parameters as expected by your assembling engine   |
| {% endtab %}  |          |                                                                             |
| {% endtabs %} |          |                                                                             |

Example:

{% code title="PATCH /customer/jobs/{jobId}/params" %}

```python
response = requests.patch(
    f"https://api.bytenite.com/v1/customer/jobs/{jobId}/params",
    headers = {
        "Authorization": token
    },
    json = {
        "partitioner": {
            "numImages": 20
        },
        "app": {
            "prompt": "A beautiful sunset over the jungle"
        },
        "assembler": {
            "outExtension": "jpeg"
        }
    }
)
```

{% endcode %}

{% endstep %}

{% step %}

### Launch the Job

Run the job, including execution configurations if needed.&#x20;

Please note that you need this call to initiate the processing of your job. Without this step, your job will remain in a draft state.

{% tabs %}
{% tab title="Request URL" %} <mark style="color:yellow;">`POST`</mark> `https://api.bytenite.com/v1/customer/jobs/{jobId}/run`

***

*Main ref:* [#jobs-jobid-run](https://docs.bytenite.com/api-reference/customer-api/jobs/manage#jobs-jobid-run "mention")
{% endtab %}

{% tab title="Path Params" %}

| Name         | Type     | Description                |
| ------------ | -------- | -------------------------- |
| `jobId`      | *string* | The `jobId`of your new job |
| {% endtab %} |          |                            |

{% tab title="Headers" %}

| Name            | Type     | Description                       |
| --------------- | -------- | --------------------------------- |
| `Authorization` | *string* | An active ByteNite access `token` |
| {% endtab %}    |          |                                   |

{% tab title="Body" %}

| Name          | Type      | Description                                                                                               |
| ------------- | --------- | --------------------------------------------------------------------------------------------------------- |
| `taskTimeout` | *integer* | An optional timeout for tasks, in seconds. After this time, a task will be stopped.                       |
| `jobTimeout`  | *integer* | An optional timeout for jobs, in seconds. After this time, the job and any running tasks will be stopped. |
| `isTestJob`   | *boolean* | A flag for test jobs.                                                                                     |
| {% endtab %}  |           |                                                                                                           |
| {% endtabs %} |           |                                                                                                           |

Example:

{% code title="PATCH /customer/jobs/{jobId}/params" %}

```python
response = requests.post(
    f"https://api.bytenite.com/v1/customer/jobs/{jobId}/run",
    headers = {
        "Authorization": token
    },
    json = {
        "taskTimeout": 3600,
        "jobTimeout": 86400,
        "isTestJob": True
    }
)
```

{% endcode %}

{% endstep %}
{% endstepper %}