## Overview
<p align="justify">
This endpoint is used to create a new job from a specified workflow. You must provide the `workflow_id` as a path parameter and the associated `project_id` as a query parameter. The response returns full job metadata including execution details, status, and task results. Authentication is required.

- Method: `POST`

- URL: `/v0/workflows/{workflow_id}/jobs`

- Operation: Create a new job from a workflow

- Authentication Required: Yes
</p>


## Authorization
<p align="justify">
You need the **api key** which you can get from the **API** tab in **Organization Settings**. The api key is required in almost all the commands

```json
Authorization: <YOUR_API_KEY>
```
</p>

## Path Parameters
<p align="justify">
The `workflow_id` path parameter identifies the specific workflow from which the job should be created. It ensures that the job is associated with the correct workflow logic, configurations, and processing structure. This parameter is essential to determine the template or pipeline that the job will execute.

| Name         | Type   | Required | Description                                       |
|--------------|--------|----------|---------------------------------------------------|
| `workflow_id`  | string | Yes      | Unique ID of the workflow to create the job from |
</p>

## Query Parameters
<p align="justify">
The `project_id` query parameter links the job creation to a specific project. It validates that the user has access to the project under which the workflow exists. This scoping is important to enforce security boundaries and maintain proper organizational ownership of workflows and jobs within the platform.

| Name        | Type   | Required | Description                                 |
|-------------|--------|----------|---------------------------------------------|
| `project_id`  | string | Yes      | Identifier of the project the workflow is part of |
</p>

## Response
<p align="justify">
A **200 OK** response returns complete metadata for the newly created job, including progress, cost, status, and timestamps. It also includes any validation errors or task-level results, enabling users to track and manage job execution immediately after it has been queued or started.

| Name              | Type       | Description                                                       |
|-------------------|------------|-------------------------------------------------------------------|
| `created_by`        | `string`     | User ID of the person who created the job                         |
| `status`           | `string`     | Current status of the job (e.g., running, completed, failed)      |
| `time_taken`        | `string`     | Total time taken by the job (human-readable)                      |
| `id`                | `string`     | Unique identifier of the job                                      |
| `tasks`             | `object[]`   | List of tasks executed within the job                             |
| `val_errors`        | `object[]`   | List of validation errors encountered during execution            |
| `spec`              | `integer[]`  | Raw specification data of the job                                 |
| `cost`              | `integer`    | Token or compute cost of the job                                  |
| `workflow_id`       | `string`     | ID of the workflow this job belongs to                            |
| `updated_at`        | `string`     | Timestamp when the job was last updated                           |
| `finished_at`       | `string`     | Timestamp when the job completed (nullable if still running)      |
| `exec_created_at`   | `string`     | Timestamp when the job execution was initialized                  |
| `exec_updated_at`   | `string`     | Timestamp of the last execution update                            |
| `created_at`        | `string`     | Timestamp when the job was created                                |
| `estimated_duration`| `integer`    | Estimated time to complete the job in seconds                     |
| `progress`          | `string`     | Current completion progress (e.g., "45%")                         |

Here is a sample **200 OK** response: 

```json 200
{
  "created_by": "<string>",
  "status": "<string>",
  "time_taken": "<string>",
  "id": "<string>",
  "tasks": [
    {
      "id": "<string>",
      "info_logs": [
        123
      ],
      "created_at": "<string>",
      "updated_at": "<string>",
      "finished_at": "<string>",
      "estimated_time_duration": 123,
      "time_taken": "<string>",
      "status": "<string>",
      "state_msg": "<string>",
      "inputs": [
        123
      ],
      "result": [
        123
      ],
      "depends_on": [
        "<string>"
      ],
      "name": "<string>",
      "progress": 123,
      "disclaimer": [
        "<string>"
      ],
      "recv_time": "<string>",
      "send_time": "<string>",
      "block_inf_start_time": "<string>",
      "block_inf_end_time": "<string>",
      "block_info": {
        "id": "<string>",
        "name": "<string>",
        "version": "<string>"
      },
      "err_msg": "<string>",
      "failure_type": "<string>"
    }
  ],
  "val_errors": [
    {
      "from": "<string>",
      "to": "<string>",
      "err": "<string>",
      "reason": "<string>",
      "component_name": "<string>"
    }
  ],
  "spec": [
    123
  ],
  "cost": 123,
  "workflow_id": "<string>",
  "updated_at": "<string>",
  "finished_at": "<string>",
  "exec_created_at": "<string>",
  "exec_updated_at": "<string>",
  "created_at": "<string>",
  "estimated_duration": 123,
  "progress": "<string>"
}
```

A **400 Bad Request** occurs if required parameters like `project_id` or `workflow_id` are missing or invalid. A **403 Forbidden** response indicates lack of permission to create a job under the given workflow. Structured error responses include a code, message, and optional details for debugging.

```json 400 403
{
  "error": {
    "code": "<string>",
    "details": "<any>",
    "message": "<string>"
  }
}
```
</p>

## How to use the endpoint
<p align="justify">
- **Construct your Request:**  
    Ensure you have the workflow_id as a path parameter and project_id as a query parameter. Add your Authorization token to the header.

- **Send the Request:**  
    After required json body and path parameters are added make a POST request to `https://api.pixxel.space/v0/workflows/{workflow_id}/jobs?project_id={project_id}`

- **Examine the Response:**  
    A successful response will return the new job object. Use its metadata to monitor progress or access task results. Handle any 400/403 errors using the returned error object.
</p>