--- title: "CreateAsyncJob" method: POST path: "/v1/namespaces/{tenant_meta.namespace}/async-jobs" tags: ["AsyncJobService"] --- # CreateAsyncJob `POST /v1/namespaces/{tenant_meta.namespace}/async-jobs` ## Request - Base URL: `https://api.endorlabs.com` - URL: `https://api.endorlabs.com/v1/namespaces/{tenant_meta.namespace}/async-jobs` - Auth: none declared Initiates asynchronous execution of a job. Returns immediately with the job UUID and state=JOB_STATE_NEW; poll GetAsyncJob to track progress. ## Path parameters - `tenant_meta.namespace` string, required ## Request body - AsyncJobServiceCreateAsyncJobBody: AsyncJob is an asynchronous job — SBOM export or VEX export types today, with more types added as they ship. - `meta` V1Meta, required: Common fields for all Endor Labs resources. - `annotations` object: Annotations can be used to attach metadata to a resource message. Annotation values can be small or large, structured or unstructured, and may include characters not permitted by labels. The keys may contain alphanumerics, underscores (_), dots (.) and dashes (-). The values of an annotation must be 16384 bytes or smaller. - `create_time` string, date-time: Time the resource was created. Format: 2017-01-15T01:30:15.01Z RFC 3339: https://www.ietf.org/rfc/rfc3339.txt. - `created_by` string: Name and authentication source of the user who created the object, for example, ewok@endor.ai@google@api-key. - `description` string: Resource description. Must be less than 1024 bytes. - `index_data` V1IndexData: IndexData is used to index the resource for search. It's an internal object. - `data` string[] - `search_score` number, float: search_score is the score of the resource for search. Internal use only. - `tenant` string - `will_be_deleted_at` string, date-time: Time that the resource will be deleted. - `kind` string: Resource kind, for example, HelloResponse. Auto-generated using the protobuf message proto.MessageName().Name(). - `name` string, required: Resource name. Must be 63 characters or less. - `parent_kind` string: Parent object resource kind, for example, Project. - `parent_uuid` string: Parent object UUID. - `references` object: Map of objects referenced in a query API. - `tags` string[]: List of tags attached to the resource. Tags can be used to select objects and to find collections of objects that satisfy certain conditions. A tag must be 255 characters or less. - `update_time` string, date-time: Time the resource was last updated. Note: Updated on all create/patch/delete operations. Format: 2017-01-15T01:30:15.01Z RFC 3339: https://www.ietf.org/rfc/rfc3339.txt. - `updated_by` string: Name and authentication source of the last user who updated the object, for example, vulnerabilityingestor@endor.ai@x509. - `upsert_time` string, date-time: Time the resource was last upserted. Note: create_time is only set the first time the resource is created. upsert_time is set every time the resource is upseted. Format: 2017-01-15T01:30:15.01Z RFC 3339: https://www.ietf.org/rfc/rfc3339.txt. - `version` string: Message version. - `spec` V1AsyncJobSpec, required: AsyncJob inputs and outputs. - `request` V1AsyncJobSpecRequest, required: Wrapper holding the type-specific request arm. - `sbom` V1SBOMExportJobRequest: Request holds the input parameters for running an SBOM export job. - `component_type` 'COMPONENT_TYPE_UNSPECIFIED' | 'COMPONENT_TYPE_LIBRARY' | 'COMPONENT_TYPE_APPLICATION', required: The kind of component for which we are creating an SBOM. This is a mandatory field. - `cyclonedx_spec_version` 'CYCLONE_DX_SPEC_VERSION_UNSPECIFIED' | 'CYCLONE_DX_SPEC_VERSION_1_5' | 'CYCLONE_DX_SPEC_VERSION_1_6' | 'CYCLONE_DX_SPEC_VERSION_1_7': CycloneDx specification versions Endor emits. Values are added as Endor adds support, so this list is the supported set. - CYCLONE_DX_SPEC_VERSION_UNSPECIFIED: Unset. The export uses CycloneDx 1.5. - CYCLONE_DX_SPEC_VERSION_1_5: CycloneDx 1.5. The default when no version is requested. - CYCLONE_DX_SPEC_VERSION_1_6: CycloneDx 1.6. - CYCLONE_DX_SPEC_VERSION_1_7: CycloneDx 1.7. - `export_parameters` V1ExportParameters: Parameters to export a SBOM/VEX. - `package_version_uuids` object[]: List of package version UUIDs. - `project_name` string: Name of the project. - `project_uuid` string: The UUID of the project. - `repository_version` string: Repository version is used to select the package versions for the export. This is an optional field, If not set then the default repository version will be used. - `format` 'FORMAT_UNSPECIFIED' | 'FORMAT_JSON' | 'FORMAT_XML' | 'FORMAT_TAG_VALUE': Specifies the output of SBOM. (For example, JSON and XML). - FORMAT_JSON: SBOM of JSON format output. - FORMAT_XML: SBOM of XML format output. - FORMAT_TAG_VALUE: SBOM of Tag Value format output. - `hide_private_components` boolean: Whether to hide private (internal) packages in the SBOM output. - `include_test_dependencies` boolean: Whether to include test/dev/build/optional dependencies. When false (default), non-production dependencies are excluded along with any transitive dependencies reachable only through them. - `include_vulnerabilities` boolean: When true, embed the scope's vulnerabilities as a top-level vulnerabilities[] array in the SBOM, producing one unified document. CycloneDx only. - `kind` 'SBOM_KIND_UNSPECIFIED' | 'SBOM_KIND_CYCLONEDX' | 'SBOM_KIND_SPDX': SBOM type. - `package_version_uuid` string: UUID of a single PackageVersion to export. When set, the handler generates an SBOM containing just this package version. Mutually exclusive with export_parameters. - `spdx_spec_version` 'SPDX_SPEC_VERSION_UNSPECIFIED' | 'SPDX_SPEC_VERSION_2_3': SPDX specification versions Endor emits. Values are added as Endor adds support, so this list is the supported set. - SPDX_SPEC_VERSION_UNSPECIFIED: Unset. The export uses the current SPDX default. - SPDX_SPEC_VERSION_2_3: SPDX 2.3. - `vex` V1VEXExportJobRequest: Request holds the input parameters for running a VEX export job. - `component_type` 'COMPONENT_TYPE_UNSPECIFIED' | 'COMPONENT_TYPE_LIBRARY' | 'COMPONENT_TYPE_APPLICATION', required: The kind of component for which we are creating an SBOM. This is a mandatory field. - `cyclonedx_spec_version` 'CYCLONE_DX_SPEC_VERSION_UNSPECIFIED' | 'CYCLONE_DX_SPEC_VERSION_1_5' | 'CYCLONE_DX_SPEC_VERSION_1_6' | 'CYCLONE_DX_SPEC_VERSION_1_7': CycloneDx specification versions Endor emits. Values are added as Endor adds support, so this list is the supported set. - CYCLONE_DX_SPEC_VERSION_UNSPECIFIED: Unset. The export uses CycloneDx 1.5. - CYCLONE_DX_SPEC_VERSION_1_5: CycloneDx 1.5. The default when no version is requested. - CYCLONE_DX_SPEC_VERSION_1_6: CycloneDx 1.6. - CYCLONE_DX_SPEC_VERSION_1_7: CycloneDx 1.7. - `export_parameters` V1ExportParameters: Parameters to export a SBOM/VEX. - `package_version_uuids` object[]: List of package version UUIDs. - `project_name` string: Name of the project. - `project_uuid` string: The UUID of the project. - `repository_version` string: Repository version is used to select the package versions for the export. This is an optional field, If not set then the default repository version will be used. - `format` 'FORMAT_UNSPECIFIED' | 'FORMAT_JSON' | 'FORMAT_XML': The output of VEX. (For example, JSON and XML). - FORMAT_JSON: SBOM of the JSON format output. - FORMAT_XML: SBOM of the XML format output. - `include_test_dependencies` boolean: Whether to include findings against test/dev/build/optional dependencies. When false (default), findings whose target dependency is non-production — or only reachable from the root through non-production paths — are excluded. - `kind` 'SBOM_KIND_UNSPECIFIED' | 'SBOM_KIND_CYCLONEDX' | 'SBOM_KIND_SPDX': SBOM type. - `package_version_uuid` string: UUID of a single PackageVersion to export. When set, the handler generates a VEX containing just this package version's findings. Mutually exclusive with export_parameters. - `response` V1AsyncJobSpecResponse: Wrapper holding the type-specific response arm and any error message. - `error_message` string: Reason for failure. Populated when state = Job.Spec.JobState.JOB_STATE_FAILED. - `sbom` V1SBOMExportJobResponse: Response holds the output after the SBOM export job completes. - `file_path` string: The file path of the generated SBOM in object storage. Stored on the Job by the handler; the apiserver Job RPC layer reads this on every GetJob and produces a fresh signed download URL. - `report_url` string: The signed download URL for the generated SBOM. Populated by the apiserver Job RPC layer on each GetJob call (5-minute TTL). - `resource_namespace` string: Namespace jobctl read the referenced resources from — the caller's tenant, or "oss" if the fallback fired. - `sbom_size_bytes` string, uint64: Byte length of the generated SBOM artifact in object storage. Useful for clients deciding whether to display a download progress indicator and for operational reporting on export sizes. - `vex` V1VEXExportJobResponse: Response holds the output after the VEX export job completes. - `file_path` string: The file path of the generated VEX document in object storage. Stored on the Job by the handler; the apiserver Job RPC layer reads this on every GetJob and produces a fresh signed download URL. - `report_url` string: The signed download URL for the generated VEX document. Populated by the apiserver Job RPC layer on each GetJob call (5-minute TTL). - `resource_namespace` string: Namespace jobctl read the referenced resources from — the caller's tenant, or "oss" if the fallback fired. - `vex_size_bytes` string, uint64: Byte length of the generated VEX artifact in object storage. Useful for clients deciding whether to show a download progress indicator and for operational reporting on export sizes. - `state` 'JOB_STATE_UNSPECIFIED' | 'JOB_STATE_NEW' | 'JOB_STATE_RUNNING' | 'JOB_STATE_SUCCESS' | 'JOB_STATE_FAILED' | 'JOB_STATE_CANCELLED' | 'JOB_STATE_RETRY': - JOB_STATE_NEW: The job was just created but never executed. - JOB_STATE_RUNNING: The job is running. - JOB_STATE_SUCCESS: The job has been successfully executed. - JOB_STATE_FAILED: The job has failed and will not be retried. - JOB_STATE_CANCELLED: The job has been cancelled/aborted by the service and will be retried. - JOB_STATE_RETRY: The job has failed but will be retried up to the max_retries limit. - `type` 'TYPE_UNSPECIFIED' | 'TYPE_SBOM' | 'TYPE_VEX', required: The kind of async job being run. - TYPE_UNSPECIFIED: Unset. - TYPE_SBOM: Software Bill of Materials. - TYPE_VEX: Vulnerability Exploitability eXchange. - `tenant_meta` object: Tenant the async job belongs to. - `uuid` string: UUID of the AsyncJob. Assigned by the server on Create; use it to fetch the job via GetAsyncJob. ## Response `200` A successful response. - V1AsyncJob: AsyncJob is an asynchronous job — SBOM export or VEX export types today, with more types added as they ship. - `meta` V1Meta, required: Common fields for all Endor Labs resources. - `annotations` object: Annotations can be used to attach metadata to a resource message. Annotation values can be small or large, structured or unstructured, and may include characters not permitted by labels. The keys may contain alphanumerics, underscores (_), dots (.) and dashes (-). The values of an annotation must be 16384 bytes or smaller. - `create_time` string, date-time: Time the resource was created. Format: 2017-01-15T01:30:15.01Z RFC 3339: https://www.ietf.org/rfc/rfc3339.txt. - `created_by` string: Name and authentication source of the user who created the object, for example, ewok@endor.ai@google@api-key. - `description` string: Resource description. Must be less than 1024 bytes. - `index_data` V1IndexData: IndexData is used to index the resource for search. It's an internal object. - `data` string[] - `search_score` number, float: search_score is the score of the resource for search. Internal use only. - `tenant` string - `will_be_deleted_at` string, date-time: Time that the resource will be deleted. - `kind` string: Resource kind, for example, HelloResponse. Auto-generated using the protobuf message proto.MessageName().Name(). - `name` string, required: Resource name. Must be 63 characters or less. - `parent_kind` string: Parent object resource kind, for example, Project. - `parent_uuid` string: Parent object UUID. - `references` object: Map of objects referenced in a query API. - `tags` string[]: List of tags attached to the resource. Tags can be used to select objects and to find collections of objects that satisfy certain conditions. A tag must be 255 characters or less. - `update_time` string, date-time: Time the resource was last updated. Note: Updated on all create/patch/delete operations. Format: 2017-01-15T01:30:15.01Z RFC 3339: https://www.ietf.org/rfc/rfc3339.txt. - `updated_by` string: Name and authentication source of the last user who updated the object, for example, vulnerabilityingestor@endor.ai@x509. - `upsert_time` string, date-time: Time the resource was last upserted. Note: create_time is only set the first time the resource is created. upsert_time is set every time the resource is upseted. Format: 2017-01-15T01:30:15.01Z RFC 3339: https://www.ietf.org/rfc/rfc3339.txt. - `version` string: Message version. - `spec` V1AsyncJobSpec, required: AsyncJob inputs and outputs. - `request` V1AsyncJobSpecRequest, required: Wrapper holding the type-specific request arm. - `sbom` V1SBOMExportJobRequest: Request holds the input parameters for running an SBOM export job. - `component_type` 'COMPONENT_TYPE_UNSPECIFIED' | 'COMPONENT_TYPE_LIBRARY' | 'COMPONENT_TYPE_APPLICATION', required: The kind of component for which we are creating an SBOM. This is a mandatory field. - `cyclonedx_spec_version` 'CYCLONE_DX_SPEC_VERSION_UNSPECIFIED' | 'CYCLONE_DX_SPEC_VERSION_1_5' | 'CYCLONE_DX_SPEC_VERSION_1_6' | 'CYCLONE_DX_SPEC_VERSION_1_7': CycloneDx specification versions Endor emits. Values are added as Endor adds support, so this list is the supported set. - CYCLONE_DX_SPEC_VERSION_UNSPECIFIED: Unset. The export uses CycloneDx 1.5. - CYCLONE_DX_SPEC_VERSION_1_5: CycloneDx 1.5. The default when no version is requested. - CYCLONE_DX_SPEC_VERSION_1_6: CycloneDx 1.6. - CYCLONE_DX_SPEC_VERSION_1_7: CycloneDx 1.7. - `export_parameters` V1ExportParameters: Parameters to export a SBOM/VEX. - `package_version_uuids` object[]: List of package version UUIDs. - `project_name` string: Name of the project. - `project_uuid` string: The UUID of the project. - `repository_version` string: Repository version is used to select the package versions for the export. This is an optional field, If not set then the default repository version will be used. - `format` 'FORMAT_UNSPECIFIED' | 'FORMAT_JSON' | 'FORMAT_XML' | 'FORMAT_TAG_VALUE': Specifies the output of SBOM. (For example, JSON and XML). - FORMAT_JSON: SBOM of JSON format output. - FORMAT_XML: SBOM of XML format output. - FORMAT_TAG_VALUE: SBOM of Tag Value format output. - `hide_private_components` boolean: Whether to hide private (internal) packages in the SBOM output. - `include_test_dependencies` boolean: Whether to include test/dev/build/optional dependencies. When false (default), non-production dependencies are excluded along with any transitive dependencies reachable only through them. - `include_vulnerabilities` boolean: When true, embed the scope's vulnerabilities as a top-level vulnerabilities[] array in the SBOM, producing one unified document. CycloneDx only. - `kind` 'SBOM_KIND_UNSPECIFIED' | 'SBOM_KIND_CYCLONEDX' | 'SBOM_KIND_SPDX': SBOM type. - `package_version_uuid` string: UUID of a single PackageVersion to export. When set, the handler generates an SBOM containing just this package version. Mutually exclusive with export_parameters. - `spdx_spec_version` 'SPDX_SPEC_VERSION_UNSPECIFIED' | 'SPDX_SPEC_VERSION_2_3': SPDX specification versions Endor emits. Values are added as Endor adds support, so this list is the supported set. - SPDX_SPEC_VERSION_UNSPECIFIED: Unset. The export uses the current SPDX default. - SPDX_SPEC_VERSION_2_3: SPDX 2.3. - `vex` V1VEXExportJobRequest: Request holds the input parameters for running a VEX export job. - `component_type` 'COMPONENT_TYPE_UNSPECIFIED' | 'COMPONENT_TYPE_LIBRARY' | 'COMPONENT_TYPE_APPLICATION', required: The kind of component for which we are creating an SBOM. This is a mandatory field. - `cyclonedx_spec_version` 'CYCLONE_DX_SPEC_VERSION_UNSPECIFIED' | 'CYCLONE_DX_SPEC_VERSION_1_5' | 'CYCLONE_DX_SPEC_VERSION_1_6' | 'CYCLONE_DX_SPEC_VERSION_1_7': CycloneDx specification versions Endor emits. Values are added as Endor adds support, so this list is the supported set. - CYCLONE_DX_SPEC_VERSION_UNSPECIFIED: Unset. The export uses CycloneDx 1.5. - CYCLONE_DX_SPEC_VERSION_1_5: CycloneDx 1.5. The default when no version is requested. - CYCLONE_DX_SPEC_VERSION_1_6: CycloneDx 1.6. - CYCLONE_DX_SPEC_VERSION_1_7: CycloneDx 1.7. - `export_parameters` V1ExportParameters: Parameters to export a SBOM/VEX. - `package_version_uuids` object[]: List of package version UUIDs. - `project_name` string: Name of the project. - `project_uuid` string: The UUID of the project. - `repository_version` string: Repository version is used to select the package versions for the export. This is an optional field, If not set then the default repository version will be used. - `format` 'FORMAT_UNSPECIFIED' | 'FORMAT_JSON' | 'FORMAT_XML': The output of VEX. (For example, JSON and XML). - FORMAT_JSON: SBOM of the JSON format output. - FORMAT_XML: SBOM of the XML format output. - `include_test_dependencies` boolean: Whether to include findings against test/dev/build/optional dependencies. When false (default), findings whose target dependency is non-production — or only reachable from the root through non-production paths — are excluded. - `kind` 'SBOM_KIND_UNSPECIFIED' | 'SBOM_KIND_CYCLONEDX' | 'SBOM_KIND_SPDX': SBOM type. - `package_version_uuid` string: UUID of a single PackageVersion to export. When set, the handler generates a VEX containing just this package version's findings. Mutually exclusive with export_parameters. - `response` V1AsyncJobSpecResponse: Wrapper holding the type-specific response arm and any error message. - `error_message` string: Reason for failure. Populated when state = Job.Spec.JobState.JOB_STATE_FAILED. - `sbom` V1SBOMExportJobResponse: Response holds the output after the SBOM export job completes. - `file_path` string: The file path of the generated SBOM in object storage. Stored on the Job by the handler; the apiserver Job RPC layer reads this on every GetJob and produces a fresh signed download URL. - `report_url` string: The signed download URL for the generated SBOM. Populated by the apiserver Job RPC layer on each GetJob call (5-minute TTL). - `resource_namespace` string: Namespace jobctl read the referenced resources from — the caller's tenant, or "oss" if the fallback fired. - `sbom_size_bytes` string, uint64: Byte length of the generated SBOM artifact in object storage. Useful for clients deciding whether to display a download progress indicator and for operational reporting on export sizes. - `vex` V1VEXExportJobResponse: Response holds the output after the VEX export job completes. - `file_path` string: The file path of the generated VEX document in object storage. Stored on the Job by the handler; the apiserver Job RPC layer reads this on every GetJob and produces a fresh signed download URL. - `report_url` string: The signed download URL for the generated VEX document. Populated by the apiserver Job RPC layer on each GetJob call (5-minute TTL). - `resource_namespace` string: Namespace jobctl read the referenced resources from — the caller's tenant, or "oss" if the fallback fired. - `vex_size_bytes` string, uint64: Byte length of the generated VEX artifact in object storage. Useful for clients deciding whether to show a download progress indicator and for operational reporting on export sizes. - `state` 'JOB_STATE_UNSPECIFIED' | 'JOB_STATE_NEW' | 'JOB_STATE_RUNNING' | 'JOB_STATE_SUCCESS' | 'JOB_STATE_FAILED' | 'JOB_STATE_CANCELLED' | 'JOB_STATE_RETRY': - JOB_STATE_NEW: The job was just created but never executed. - JOB_STATE_RUNNING: The job is running. - JOB_STATE_SUCCESS: The job has been successfully executed. - JOB_STATE_FAILED: The job has failed and will not be retried. - JOB_STATE_CANCELLED: The job has been cancelled/aborted by the service and will be retried. - JOB_STATE_RETRY: The job has failed but will be retried up to the max_retries limit. - `type` 'TYPE_UNSPECIFIED' | 'TYPE_SBOM' | 'TYPE_VEX', required: The kind of async job being run. - TYPE_UNSPECIFIED: Unset. - TYPE_SBOM: Software Bill of Materials. - TYPE_VEX: Vulnerability Exploitability eXchange. - `tenant_meta` V1TenantMeta: Tenant related data for the tenant containing the resource. - `namespace` string, required: Namespaces are a way to organize organizational units into virtual groupings of resources. Namespaces must be a fully qualified name, for example, the child namespace of namespace "endor.prod" called "app" is called "endor.prod.app". - `uuid` string: UUID of the AsyncJob. Assigned by the server on Create; use it to fetch the job via GetAsyncJob. ## Other responses - `default`: An unexpected error response. ## Changes - **2026-11-03** `4acd9fe15140`: 1 info - endpoint added [Operation history](https://skmtc.dev/endorlabs/apis/endor-labs-rest-api-reference/changes/v1/namespaces/:tenant_meta.namespace/async-jobs/post.md) --- [API](https://skmtc.dev/endorlabs/apis/endor-labs-rest-api-reference.md) - [All operations](https://skmtc.dev/endorlabs/apis/endor-labs-rest-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/endorlabs/apis/endor-labs-rest-api-reference/revisions/4acd9fe15140?raw)