snapshot of https://github.com/mattermost/mattermost.git (master, 2026-09-16; blobs > 131072B omitted)

api/v4/source/jobs.yaml

@@ -0,0 +1,345 @@
+  /api/v4/jobs:
+    get:
+      tags:
+        - jobs
+      summary: Get the jobs.
+      description: |
+        Get a page of jobs. Use the query parameters to modify the behaviour of
+        this endpoint.
+
+        __Minimum server version: 4.1__
+
+        ##### Permissions
+        Must have permission to read at least one job type returned by this call.
+        When no `job_type` query parameter is set, the server only includes job types your session may read; required permission depends on the job type:
+
+        - `read_data_retention_job` — `data_retention`
+        - `read_compliance_export_job` — `message_export`
+        - `read_elasticsearch_post_indexing_job` — `elasticsearch_post_indexing`
+        - `read_elasticsearch_post_aggregation_job` — `elasticsearch_post_aggregation`
+        - `read_ldap_sync_job` — `ldap_sync`
+        - `read_jobs` — `migrations`, `plugins`, `product_notices`, `expiry_notify`, `active_users`, `import_process`, `import_delete`, `export_process`, `export_delete`, `cloud`, `mobile_session_metadata`, `extract_content`
+        - `manage_system` — `access_control_sync`
+
+        When `job_type` is set, you must have the permission that matches that type (same mapping as above).
+
+        This endpoint does not accept `team_id`. To list `access_control_sync` jobs scoped to a team without `manage_system`, use `GET /api/v4/jobs/type/access_control_sync` with query parameter `team_id` set to the team GUID (requires `manage_team_access_rules` on that team).
+      operationId: GetJobs
+      parameters:
+        - name: page
+          in: query
+          description: The page to select.
+          schema:
+            type: integer
+            default: 0
+        - name: per_page
+          in: query
+          description: The number of jobs per page.
+          schema:
+            type: integer
+            default: 5
+        - name: job_type
+          in: query
+          description: The type of jobs to fetch.
+          schema:
+            type: string
+        - name: status
+          in: query
+          description: The status of jobs to fetch.
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Job list retrieval successful
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Job"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+    post:
+      tags:
+        - jobs
+      summary: Create a new job.
+      description: |
+        Create a new job.
+        __Minimum server version: 4.1__
+        ##### Permissions
+        Must have permission to create the requested job type. Required permission depends on `type`:
+
+        - `create_data_retention_job` — `data_retention`
+        - `create_compliance_export_job` — `message_export`
+        - `create_elasticsearch_post_indexing_job` — `elasticsearch_post_indexing`
+        - `create_elasticsearch_post_aggregation_job` — `elasticsearch_post_aggregation`
+        - `create_ldap_sync_job` — `ldap_sync`
+        - `manage_jobs` — `migrations`, `plugins`, `product_notices`, `expiry_notify`, `active_users`, `import_process`, `import_delete`, `export_process`, `export_delete`, `cloud`, `extract_content`
+        - `access_control_sync` — `manage_system`, or `manage_channel_access_rules` on the channel given in job `data`, or `manage_team_access_rules` on the team in job `data` (see server logic for scoped sync jobs)
+      operationId: CreateJob
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - type
+              properties:
+                type:
+                  type: string
+                  description: The type of job to create
+                data:
+                  type: object
+                  description: An object containing any additional data required for this
+                    job type
+        description: Job object to be created
+        required: true
+      responses:
+        "201":
+          description: Job creation successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Job"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  "/api/v4/jobs/{job_id}":
+    get:
+      tags:
+        - jobs
+      summary: Get a job.
+      description: |
+        Gets a single job.
+        __Minimum server version: 4.1__
+        ##### Permissions
+        Must have permission to read the job's type:
+
+        - `read_data_retention_job` — `data_retention`
+        - `read_compliance_export_job` — `message_export`
+        - `read_elasticsearch_post_indexing_job` — `elasticsearch_post_indexing`
+        - `read_elasticsearch_post_aggregation_job` — `elasticsearch_post_aggregation`
+        - `read_ldap_sync_job` — `ldap_sync`
+        - `read_jobs` — `migrations`, `plugins`, `product_notices`, `expiry_notify`, `active_users`, `import_process`, `import_delete`, `export_process`, `export_delete`, `cloud`, `mobile_session_metadata`, `extract_content`
+        - `manage_system` — `access_control_sync`
+      operationId: GetJob
+      parameters:
+        - name: job_id
+          in: path
+          description: Job GUID
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Job retrieval successful
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Job"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+  "/api/v4/jobs/{job_id}/download":
+    get:
+      tags:
+        - jobs
+      summary: Download the results of a job.
+      description: |
+        Download the result of a single job.
+        __Minimum server version: 5.28__
+        ##### Permissions
+        Must have `download_compliance_export_result` permission for message export jobs.
+      operationId: DownloadJob
+      parameters:
+        - name: job_id
+          in: path
+          description: Job GUID
+          required: true
+          schema:
+            type: string
+      responses:
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+  "/api/v4/jobs/{job_id}/cancel":
+    post:
+      tags:
+        - jobs
+      summary: Cancel a job.
+      description: |
+        Cancel a job.
+        __Minimum server version: 4.1__
+        ##### Permissions
+        Same as creating that job type (cancel uses the create permission check):
+
+        - `create_data_retention_job` — `data_retention`
+        - `create_compliance_export_job` — `message_export`
+        - `create_elasticsearch_post_indexing_job` — `elasticsearch_post_indexing`
+        - `create_elasticsearch_post_aggregation_job` — `elasticsearch_post_aggregation`
+        - `create_ldap_sync_job` — `ldap_sync`
+        - `manage_jobs` — `migrations`, `plugins`, `product_notices`, `expiry_notify`, `active_users`, `import_process`, `import_delete`, `export_process`, `export_delete`, `cloud`, `extract_content`
+        - `access_control_sync` — `manage_system`, or `manage_channel_access_rules` / `manage_team_access_rules` for scoped jobs as when creating
+      operationId: CancelJob
+      parameters:
+        - name: job_id
+          in: path
+          description: Job GUID
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Job canceled successfully
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StatusOK"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+  "/api/v4/jobs/type/{job_type}":
+    get:
+      tags:
+        - jobs
+      summary: Get the jobs of the given type.
+      description: |
+        Get a page of jobs of the given type. Use the query parameters to modify
+        the behaviour of this endpoint.
+
+        __Minimum server version: 4.1__
+
+        ##### Permissions
+        Must have permission to read the path `job_type`, using the same mapping as `GET /api/v4/jobs`:
+
+        - `read_data_retention_job` — `data_retention`
+        - `read_compliance_export_job` — `message_export`
+        - `read_elasticsearch_post_indexing_job` — `elasticsearch_post_indexing`
+        - `read_elasticsearch_post_aggregation_job` — `elasticsearch_post_aggregation`
+        - `read_ldap_sync_job` — `ldap_sync`
+        - `read_jobs` — `migrations`, `plugins`, `product_notices`, `expiry_notify`, `active_users`, `import_process`, `import_delete`, `export_process`, `export_delete`, `cloud`, `mobile_session_metadata`, `extract_content`
+        - `manage_system` — `access_control_sync`
+
+        When `job_type` is `access_control_sync` and query parameter `team_id` is set to a valid team GUID, team admins with `manage_team_access_rules` on that team may list jobs scoped to that team without `manage_system`. When `team_id` is set, results include only jobs whose stored data matches that team for the requested type.
+      operationId: GetJobsByType
+      parameters:
+        - name: job_type
+          in: path
+          description: Job type
+          required: true
+          schema:
+            type: string
+        - name: team_id
+          in: query
+          description: |
+            Optional team GUID. When set, the server returns jobs of the given `job_type` whose job data includes this `team_id` (see server filtering). For `access_control_sync`, team admins with `manage_team_access_rules` on this team may use this parameter to read team-scoped jobs without `manage_system`.
+          schema:
+            type: string
+        - name: page
+          in: query
+          description: The page to select.
+          schema:
+            type: integer
+            default: 0
+        - name: per_page
+          in: query
+          description: The number of jobs per page.
+          schema:
+            type: integer
+            default: 60
+      responses:
+        "200":
+          description: Job list retrieval successful
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Job"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  "/api/v4/jobs/{job_id}/status":
+    patch:
+      tags:
+        - jobs
+      summary: Update the status of a job
+      description: |
+        Update the status of a job. Valid status updates:
+        - 'in_progress' -> 'pending'
+        - 'in_progress' | 'pending' -> 'cancel_requested'
+        - 'cancel_requested' -> 'canceled'
+
+        Add force to the body of the PATCH request to bypass the given rules, the only statuses you can go to are: pending, cancel_requested and canceled. This can have unexpected consequences and should be used with caution.
+
+        ##### Permissions
+        Must have permission to manage the job's type:
+
+        - `manage_data_retention_job` — `data_retention`
+        - `manage_compliance_export_job` — `message_export`
+        - `manage_elasticsearch_post_indexing_job` — `elasticsearch_post_indexing`
+        - `manage_elasticsearch_post_aggregation_job` — `elasticsearch_post_aggregation`
+        - `manage_ldap_sync_job` — `ldap_sync`
+        - `manage_jobs` — `migrations`, `plugins`, `product_notices`, `expiry_notify`, `active_users`, `import_process`, `import_delete`, `export_process`, `export_delete`, `cloud`, `extract_content`
+        - `manage_system` — `access_control_sync`
+      operationId: UpdateJobStatus
+      parameters:
+        - name: job_id
+          in: path
+          description: Job GUID
+          required: true
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - status
+              properties:
+                status:
+                  type: string
+                  description: The status you want to set
+                force:
+                  type: boolean
+                  description: Set this to true to bypass status restrictions
+      responses:
+        "200":
+          description: Status successfully set.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StatusOK"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"