---
title: "Create job"
method: POST
path: "/v4/automations/jobs"
tags: ["v4", "Automations"]
---

# Create job

`POST /v4/automations/jobs`

## Request body

- union
  - CreateDocAutomationJobRequest
    - `name` string, required — Job name (unique for resource)
    - `resourceId` union, required — Resource ID
      - string, uuid
      - string
    - `trigger` union, required — Trigger details
      - AutomationEventTriggerDetailsSchema
        - `type` 'event' — Trigger type
        - `config` union, required — Trigger configuration
          - AutomationOnJobEndEventTriggerConfig — Fires when the referenced upstream doc job completes successfully. `job_id` must reference a same-team doc automation job; save paths enforce this (and acyclicity) via `AutomationJobsTableClient.validate_trigger_references`. The field stays optional here so historical rows saved while the trigger was a no-op (DEF-2903) never break reads -- a null upstream is rejected on write.
            - `type` 'on_job_end' — Trigger configuration type
            - `job_id` union — Upstream doc automation job (same team) whose successful completion triggers this job
              - …
          - AutomationOnSyncEndEventTriggerConfig
            - `type` 'on_sync_end' — Trigger configuration type
            - `src_integration_id` union — Source integration ID
              - …
          - AutomationOnWebhookEventTriggerConfig
            - `type` 'webhook' — Trigger configuration type
      - AutomationScheduledTriggerDetailsSchema
        - `type` 'schedule' — Trigger type
        - `config` AutomationCronScheduledTriggerConfig, required
          - `type` 'cron' — Schedule type
          - `cron` string — Cron expression for schedule
      - AutomationNoneTriggerDetailsSchema
        - `type` 'none' — Trigger type
    - `maxAttempts` integer — Max attempts allowed for job run
    - `resourceType` 'doc', required — Resource type
    - `destination` union — Destination details
      - AutomationNoneDestinationSchema
        - `skipIfEmpty` boolean — Skip writing to destination if results are empty
        - `type` 'none' — Destination type
      - AutomationSlackDestinationSchema
        - `integrationId` union — Integration ID
          - string, uuid
          - string
        - `format` 'json' | 'parquet' | 'txt' | 'csv' | 'png' | 'pdf' | 'auto' — Export format
        - `skipIfEmpty` boolean — Skip writing to destination if results are empty
        - `type` 'slack' — Destination type
        - `channelId` string, nullable — Channel ID
      - AutomationEmailDestinationSchema
        - `format` 'json' | 'parquet' | 'txt' | 'csv' | 'png' | 'pdf' | 'auto' — Export format
        - `skipIfEmpty` boolean — Skip writing to destination if results are empty
        - `type` 'email' — Destination type
        - `address` string, nullable — Email address
      - AutomationSheetsDestinationSchema
        - `integrationId` union — Integration ID
          - string, uuid
          - string
        - `skipIfEmpty` boolean — Skip writing to destination if results are empty
        - `type` 'sheets' — Destination type
        - `spreadsheetId` string, nullable — Spreadsheet ID
        - `sheet` string, nullable — Sheet name
        - `header` boolean — Include header row
        - `range` string, nullable — Sheet range
        - `overwriteSheet` boolean, nullable — Overwrite sheet
        - `overwriteRange` boolean, nullable — Overwrite range
      - AutomationExcelDestinationSchema
        - `integrationId` union — Integration ID
          - string, uuid
          - string
        - `skipIfEmpty` boolean — Skip writing to destination if results are empty
        - `type` 'excel' — Destination type
        - `workbookId` string, nullable — Workbook ID
        - `worksheet` string, nullable — Worksheet name
        - `header` boolean — Include header row
        - `range` string, nullable — Sheet range
        - `overwriteSheet` boolean, nullable — Overwrite sheet
        - `overwriteRange` boolean, nullable — Overwrite range
      - AutomationGcsDestinationSchema
        - `format` 'json' | 'parquet' | 'txt' | 'csv' | 'png' | 'pdf' | 'auto' — Export format
        - `integrationId` union — Integration ID
          - string, uuid
          - string
        - `skipIfEmpty` boolean — Skip writing to destination if results are empty
        - `type` 'gcs' — Destination type
        - `bucket` string, nullable — Bucket name
        - `blobName` string, nullable — Blob name
      - AutomationWebhookDestinationSchema
        - `skipIfEmpty` boolean — Skip writing to destination if results are empty
        - `type` 'webhook' — Destination type
        - `url` string, required — URL where the data (JSON encoded) will be sent as a POST request
      - AutomationFiThreadDestinationSchema
        - `skipIfEmpty` boolean — Skip writing to destination if results are empty
        - `type` 'fi_thread' — Destination type
        - `thread_id` string, nullable — Thread UUID (required)
        - `row_cap` integer — Maximum rows to include in XML (default 100)
        - `slack_integration_id` string, nullable — Slack integration ID for optional follow-up message
        - `slack_channel_id` string, nullable — Slack channel ID for optional follow-up message
        - `slack_template` object, nullable — Slack message template (blocks + fallback text)
  - CreateDuckLakeMaintenanceAutomationJobRequest
    - `name` string, required — Job name (unique for resource)
    - `resourceId` union, required — Resource ID
      - string, uuid
      - string
    - `trigger` union, required — Trigger details
      - AutomationEventTriggerDetailsSchema
        - `type` 'event' — Trigger type
        - `config` union, required — Trigger configuration
          - AutomationOnJobEndEventTriggerConfig — Fires when the referenced upstream doc job completes successfully. `job_id` must reference a same-team doc automation job; save paths enforce this (and acyclicity) via `AutomationJobsTableClient.validate_trigger_references`. The field stays optional here so historical rows saved while the trigger was a no-op (DEF-2903) never break reads -- a null upstream is rejected on write.
            - `type` 'on_job_end' — Trigger configuration type
            - `job_id` union — Upstream doc automation job (same team) whose successful completion triggers this job
              - …
          - AutomationOnSyncEndEventTriggerConfig
            - `type` 'on_sync_end' — Trigger configuration type
            - `src_integration_id` union — Source integration ID
              - …
          - AutomationOnWebhookEventTriggerConfig
            - `type` 'webhook' — Trigger configuration type
      - AutomationScheduledTriggerDetailsSchema
        - `type` 'schedule' — Trigger type
        - `config` AutomationCronScheduledTriggerConfig, required
          - `type` 'cron' — Schedule type
          - `cron` string — Cron expression for schedule
      - AutomationNoneTriggerDetailsSchema
        - `type` 'none' — Trigger type
    - `maxAttempts` integer — Max attempts allowed for job run
    - `resourceType` 'ducklake_integration_maintenance', required — Resource type
    - `details` DuckLakeMaintenanceRequest
      - `steps` DuckLakeMaintenanceStepName[], nullable — Subset of maintenance steps to run. If omitted, all steps run. Steps are always executed in the canonical order regardless of input order.
      - `deleteThreshold` number, nullable — Delete ratio threshold for ducklake_rewrite_data_files (0.0–1.0). Files with a delete ratio above this value are rewritten. Default is 0.95 if omitted.
      - `expireSnapshotsOlderThan` string, nullable — Interval for ducklake_expire_snapshots older_than parameter (e.g. '1 week', '1 month'). Snapshots older than this are expired. If omitted, the integration's history_days setting is used.
      - `cleanupAll` boolean — When true, ducklake_cleanup_old_files and ducklake_delete_orphaned_files clean up all files regardless of age. When false, DuckLake's default age-based behaviour is used.
      - `cpu` string — CPU cores for the K8s job in Kubernetes format (e.g., '4', '15', '500m'). Defaults to 15 cores.
      - `memory` string — Memory for the K8s job in Kubernetes format (e.g., '96Gi', '192Gi'). Increase for catalogs with many files (150K+). Defaults to 96Gi.
      - `timeoutSeconds` integer — Pod timeout in seconds for the maintenance K8s job (60–604800). Defaults to 43200 (12 hours).
      - `thinKeepLast` integer — Always keep the N most recent snapshots (safety floor)
      - `thinKeepDailyForDays` integer — Keep 1 snapshot per day for the last D days
      - `vacuumFull` boolean — When true (default), the vacuum_catalog step runs VACUUM FULL ANALYZE, rewriting catalog metadata tables to reclaim bloat and refresh pg_stat row counts. When false, runs VACUUM ANALYZE only.
      - `mergeConcurrency` integer — Number of tables to merge in parallel. Higher values speed up catalogs with many tables but use more memory. Defaults to 4.
      - `runThreshold` 'any' | 'warning' | 'critical' — Minimum catalog health severity at which scheduled maintenance runs.

## Response `201`

Success

- SuccessResponseAutomationJobsSchema
  - `success` true, required — Flag for it request was successful
  - `data` AutomationJobsSchema, required
    - `id` union — Job ID
      - string, uuid
      - string
    - `team_id` union, required — Team ID
      - string, uuid
      - string
    - `name` string, required — Job name (unique for resource)
    - `resource_id` union, required — Associated resource ID
      - string, uuid
      - string
    - `resource_type` 'doc' | 'ducklake_integration_maintenance', required — Associated resource type
    - `trigger` union, required — Trigger details
      - AutomationEventTriggerDetailsSchema
        - `type` 'event' — Trigger type
        - `config` union, required — Trigger configuration
          - AutomationOnJobEndEventTriggerConfig — Fires when the referenced upstream doc job completes successfully. `job_id` must reference a same-team doc automation job; save paths enforce this (and acyclicity) via `AutomationJobsTableClient.validate_trigger_references`. The field stays optional here so historical rows saved while the trigger was a no-op (DEF-2903) never break reads -- a null upstream is rejected on write.
            - `type` 'on_job_end' — Trigger configuration type
            - `job_id` union — Upstream doc automation job (same team) whose successful completion triggers this job
              - …
          - AutomationOnSyncEndEventTriggerConfig
            - `type` 'on_sync_end' — Trigger configuration type
            - `src_integration_id` union — Source integration ID
              - …
          - AutomationOnWebhookEventTriggerConfig
            - `type` 'webhook' — Trigger configuration type
      - AutomationScheduledTriggerDetailsSchema
        - `type` 'schedule' — Trigger type
        - `config` AutomationCronScheduledTriggerConfig, required
          - `type` 'cron' — Schedule type
          - `cron` string — Cron expression for schedule
      - AutomationNoneTriggerDetailsSchema
        - `type` 'none' — Trigger type
    - `destination` union — Destination details
      - AutomationNoneDestinationSchema
        - `skipIfEmpty` boolean — Skip writing to destination if results are empty
        - `type` 'none' — Destination type
      - AutomationSlackDestinationSchema
        - `integrationId` union — Integration ID
          - string, uuid
          - string
        - `format` 'json' | 'parquet' | 'txt' | 'csv' | 'png' | 'pdf' | 'auto' — Export format
        - `skipIfEmpty` boolean — Skip writing to destination if results are empty
        - `type` 'slack' — Destination type
        - `channelId` string, nullable — Channel ID
      - AutomationEmailDestinationSchema
        - `format` 'json' | 'parquet' | 'txt' | 'csv' | 'png' | 'pdf' | 'auto' — Export format
        - `skipIfEmpty` boolean — Skip writing to destination if results are empty
        - `type` 'email' — Destination type
        - `address` string, nullable — Email address
      - AutomationSheetsDestinationSchema
        - `integrationId` union — Integration ID
          - string, uuid
          - string
        - `skipIfEmpty` boolean — Skip writing to destination if results are empty
        - `type` 'sheets' — Destination type
        - `spreadsheetId` string, nullable — Spreadsheet ID
        - `sheet` string, nullable — Sheet name
        - `header` boolean — Include header row
        - `range` string, nullable — Sheet range
        - `overwriteSheet` boolean, nullable — Overwrite sheet
        - `overwriteRange` boolean, nullable — Overwrite range
      - AutomationExcelDestinationSchema
        - `integrationId` union — Integration ID
          - string, uuid
          - string
        - `skipIfEmpty` boolean — Skip writing to destination if results are empty
        - `type` 'excel' — Destination type
        - `workbookId` string, nullable — Workbook ID
        - `worksheet` string, nullable — Worksheet name
        - `header` boolean — Include header row
        - `range` string, nullable — Sheet range
        - `overwriteSheet` boolean, nullable — Overwrite sheet
        - `overwriteRange` boolean, nullable — Overwrite range
      - AutomationGcsDestinationSchema
        - `format` 'json' | 'parquet' | 'txt' | 'csv' | 'png' | 'pdf' | 'auto' — Export format
        - `integrationId` union — Integration ID
          - string, uuid
          - string
        - `skipIfEmpty` boolean — Skip writing to destination if results are empty
        - `type` 'gcs' — Destination type
        - `bucket` string, nullable — Bucket name
        - `blobName` string, nullable — Blob name
      - AutomationWebhookDestinationSchema
        - `skipIfEmpty` boolean — Skip writing to destination if results are empty
        - `type` 'webhook' — Destination type
        - `url` string, required — URL where the data (JSON encoded) will be sent as a POST request
      - AutomationFiThreadDestinationSchema
        - `skipIfEmpty` boolean — Skip writing to destination if results are empty
        - `type` 'fi_thread' — Destination type
        - `thread_id` string, nullable — Thread UUID (required)
        - `row_cap` integer — Maximum rows to include in XML (default 100)
        - `slack_integration_id` string, nullable — Slack integration ID for optional follow-up message
        - `slack_channel_id` string, nullable — Slack channel ID for optional follow-up message
        - `slack_template` object, nullable — Slack message template (blocks + fallback text)
    - `enabled` boolean — Job enabled flag
    - `disabled_by` 'user' | 'definite-admin', nullable — Who disabled this job. Null iff enabled=true.
    - `max_attempts` integer — Max attempts for job
    - `details` object — Resource-type-specific job configuration. Must be empty for doc jobs. For ducklake_integration_maintenance: a DuckLakeMaintenanceRequest payload plus optional `created_by` (UUID) for acting-user fallback.
    - `created_at` string, date-time — Job created at timestamp
  - `meta` ResponseMeta
    - `requestId` string — Unique request identifier for tracing
    - `timestamp` string, date-time — Response timestamp (UTC)
    - `durationMs` integer, nullable — Request processing time in milliseconds

## Other responses

- `401` — Auth Invalid Token
- `403` — Forbidden Insufficient Permissions
- `404` — Resource Not Found
- `422` — Validation Failed
- `426` — Business Quota Exceeded
- `500` — Internal Error

---

[API](https://skmtc.dev/definite/apis/defapi.md) · [All operations](https://skmtc.dev/definite/apis/defapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/definite/defapi/revisions/5ea378187147/schema)