> For the complete documentation index, see [llms.txt](https://docs.tagshelf.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tagshelf.dev/endpoints/job.md). # Job A **Job** in Alfred represents a single unit of work that performs a sequence of operations on one or more files for the purpose of document classification, extraction, and indexing. It is an asynchronous entity, orchestrated by a state machine that manages its progress through various stages. For example, a **Job** could be responsible for ingesting a batch of scanned invoices, classifying them, extracting relevant fields, and then indexing them in a searchable database. ### Responsibilities * Executes pre-defined workflows for document processing. * Manages state transitions and retries. * Orchestrates the processing of multiple files if applicable. * Emits events to signal significant changes in its lifecycle. ## List all Jobs associated with the authorized user's company. `GET` `https://.tagshelf.com/api/job/all` This endpoint provides a list of Jobs that are specific to the company to which the authorized user belongs. It does not list all Jobs in the entire system but rather filters them based on company affiliation. This ensures that users only access and manage Jobs relevant to their organizational context. #### Query Parameters
NameTypeDescription
currentPageIntegerThe currentPage parameter specifies the page number in the paginated list of Jobs. Default value is 1.
pageSizeInteger

The pageSize parameter determines the number of Jobs displayed on each page of the paginated response. Default value is 10.

Value must be greater than 0.

Value must be less than 40.

sortDirectionString

Specifies whether the results are presented in ascending or descending order based on their creation date. Allowed values are:

ASC for ascending order (oldest to newest)

DESCfor descending order (newest to oldest).

Default value is DESC

startDateStringStart of the job date window (date-only, UTC day), format yyyy-MM-dd. If provided alone, results include jobs from that day through today.
endDateStringEnd of the job date window (date-only, UTC day), format yyyy-MM-dd. Requires startDate; used to close the range through the end of the specified day.
#### Headers | Name | Type | Description | | ----------------- | ------ | --------------------------------------------- | | X-TagshelfAPI-Key | String | Application API Key | | Authorization | String | Bearer \ or amx \ | {% tabs %} {% tab title="200 OK" %} ```json { "result": [ { "id": "78dd6181-00aa-4ded-aeaf-57803bbddae3", "creation_date": "2021-08-06T15:15:54.12", "update_date": "2022-11-17T21:12:27.813", "user_name": "Alfred Pennyworth", "channel": "api", "merge": false, "decompose": true, "propagate_metadata": false, "file_sources_count": 0, "file_count": 19, "finished_files": 7, "retries": 0, "metadata": "Job Specific Metadada", "exceeded_retries": false, "stage": "in_progress", "priority": "normal", "start_date": "2021-08-06T15:16:00.257", }, ... ], "total": 20, "is_empty": false } ``` {% endtab %} {% tab title="400 BAD REQUEST" %} ```json { "error": "Invalid Pagination Parameters", "message": "The 'pageSize' parameter must be an integer between 10 and 40. The 'currentPage' parameter must be a positive integer." } ``` {% endtab %} {% endtabs %} ## Retrieve detailed information about a specific Job. `GET` `https://.tagshelf.com/api/job/detail/:id` This endpoint provides comprehensive details about a Job identified by its unique `id`. It's used to fetch the current status, progress, results, and any other relevant information about a specific Job. This is particularly useful for monitoring the ongoing process of a Job, understanding its current state, and for diagnostic purposes. The endpoint is essential for users or systems needing to track the progress and outcome of document processing tasks. #### Path Parameters | Name | Type | Description | | ------------------------------------ | ---- | --------------------------------- | | id\* | UUID | The unique identifier of the Job. | #### Headers | Name | Type | Description | | ----------------- | ------ | --------------------------------------------- | | X-TagshelfAPI-Key | String | Application API Key | | Authorization | String | Bearer \ or amx \ | {% tabs %} {% tab title="200 OK" %} ```json { "id": "78dd6181-00aa-4ded-aeaf-57803bbddae3", "cancellation_reason": "", "last_canceled_by": "", "company_id": "company-id", "user_name": "MagicianApp", "channel": "api", "source": "", "container": "", "remote_file_name": "", "merge": false, "decompose": false, "propagate_metadata": true, "parent_file_prefix": "", "metadata": "{\"Key\":\"Value\",\"Key2\":\"Value2\"}", "file_count": 1, "total_file_count": 1, "file_sources_count": 1, "metadata_objects_count": 1, "finished_files": 1, "files": [ { "id": "file-id", "creation_date": "2026-01-28T20:22:06.44Z", "update_date": "2026-01-29T12:49:57.02Z", "file_name": "file-name.jpeg", "content_type": "image/jpeg", "tag_name": "Tag 1", "is_parent": false, "is_children": false, "status": "finished", "is_reextracting": false } ], "retries": 0, "cancel_count": 0, "restart_count": 0, "cached_restart_count": 0, "redownload_restart_count": 0, "restarted_by": "", "exceeded_retries": false, "file_urls": [ "https://upload.wikimedia.org/wikipedia/commons/4/4d/Cat_November_2010-1a.jpg" ], "error_messages": [], "stage": "completed", "remote_sources_available": false, "unavailable_source_urls": [], "priority": "High", "start_date": "2026-01-28T20:22:02.847Z", "has_failed_files": false, "has_broken_input_sources": false, "creation_date": "2026-01-28T20:21:57.22Z", "update_date": "2026-01-29T12:49:57.567Z" } ``` {% endtab %} {% tab title="404 Not Found" %} {% endtab %} {% tab title="400 Bad Request" %} ```json { "message": "The request is invalid." // Invalid UUID } ``` {% endtab %} {% endtabs %} ## Create a new Job and close the deferred upload session. `POST` `https://.tagshelf.com/api/job/create` This endpoint is used for creating a new Job in Alfred. It serves a dual purpose: it finalizes the deferred upload session, ensuring that all files needed for the Job are uploaded, and initiates the Job itself. This process includes transitioning from the file upload phase to the document processing phase, where the files undergo classification, extraction, and indexing based on predefined workflows. The endpoint is crucial for starting the document processing task and is invoked once all necessary files are in place. #### Headers | Name | Type | Description | | ----------------- | ------ | --------------------------------------------- | | X-TagshelfAPI-Key | string | Application API Key | | Authorization | string | Bearer \ or amx \ | #### Request Body | Name | Type | Description | | --------------------------------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | session\_id\* | UUID | Session ID | | metadata | Object or array of Objects |

This parameter accepts a JSON object that encapsulates various metadata fields for the Job.

The metadata provided here serves as a set of descriptors or attributes that apply to the Job as a whole. Once defined, this metadata is automatically propagated to each file that is part of the Job. This means that every file within this Job will inherit the specified metadata, ensuring consistency and contextual relevance across all files associated with the Job.

This feature is particularly useful for maintaining uniformity in file attributes, aiding in categorization, and enhancing the searchability and traceability of files within a Job.

| | merge | boolean |

The merge parameter is a directive that instructs the file processor on how to handle multiple files within a Job. When set, and provided all files in the Job are either images or PDFs, this parameter signals that these files should be treated as a single unit of work. This means that instead of processing each file independently, the system combines them into a single file for the purpose of processing.

This approach is particularly beneficial when the files are parts of a larger document or dataset that need to be handled cohesively.

For example, if multiple scanned images of a document or several PDFs are part of a Job, setting merge ensures they are processed together, maintaining the continuity and integrity of the document. This results in the Job having a singular output file, despite originating from multiple input files.

| | decompose | boolean |

The decompose parameter plays a critical role in how the file processor handles the input files. When enabled, this parameter triggers the decomposition of file inputs into multiple, distinct units of work. This is applicable in scenarios where a single file contains multiple separable components.

For example, in the case of a multi-page PDF, each page is treated as an individual file. Similarly, for an image or a PDF page containing multiple documents, each document is separated and processed independently.

This parameter is vital for tasks that require individual attention to each component of a file, such as detailed analysis, classification, or extraction of data from each part of a larger document. Decomposition enhances the granularity of processing, enabling more precise and targeted handling of each segment within a file.

| | propagate\_metadata | boolean | This parameter enables the specification of a single metadata object to be applied across multiple files from remote URLs or remote sources. When used, `propagate_metadata` ensures that the defined metadata is consistently attached to all the specified files during their upload and processing. This feature is particularly useful for maintaining uniform metadata across a batch of files, streamlining data organization and retrieval. | | priority | string | Sets the Job's priority in the processing queue. Valid values are: low, normal or high. | {% tabs %} {% tab title="200 OK" %} ```json { "job_id": "ce533119-4266-4bfe-aa32-9466f751ca61" } ``` {% endtab %} {% tab title="400 BAD REQUEST" %} ```json { "error": "Bad Request", "message": "Invalid input parameters. Please check your data." } ``` {% endtab %} {% endtabs %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.tagshelf.dev/endpoints/job.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.