team/api/v4/source/jobs.yaml at master

mirror of https://github.com/hanzoai/team.git synced 2026-09-30 01:57:35 +00:00

Files

T

zeekayandHanzo Dev 404de134f3 Point the API spec and its route checker at the new base

The OpenAPI document keys every operation by its full path, so the spec
described endpoints that no longer exist the moment the server moved.

The openApiSync analyzer cross-checks each registered subrouter against
that document and reconstructs the prefix from a literal of its own, so
spec and analyzer have to move together or every route reports as
missing. Its special case for the v5 root goes away with the root
itself.

The api/v4 directory keeps its name: it is where the spec sources live,
not a URL anyone requests.

Co-authored-by: Hanzo Dev <[email protected]>

2026-08-14 10:58:08 -07:00

346 lines

13 KiB

YAML

Raw Permalink Blame History

   /v1/team/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 /v1/team/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"
   "/v1/team/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"
   "/v1/team/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"
   "/v1/team/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"
   "/v1/team/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 /v1/team/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"
   "/v1/team/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"

346 lines 13 KiB YAML Raw Permalink Blame History

346 lines

13 KiB

YAML

Raw Permalink Blame History