DPF Job Triggers API

openapi: 3.2.0
info:
  title: DPF Job Triggers API
  version: 1.1.0
  description: '## Common error responses


    Unless otherwise noted, any authenticated endpoint may also return the following

    responses, each with the standard `ErrorResponse` body. To avoid repetition they are

    not listed individually on each operation:


    - **400 Bad Request** — malformed JSON, unknown action, or missing/invalid fields

    - **401 Unauthorized** — missing or invalid JWT bearer token

    - **402 Payment Required** — the account has insufficient credits or an inactive subscription

    - **403 Forbidden** — authenticated but not permitted (no access to the resource, or a higher access level / plan tier is required)


    Operation-specific responses (e.g. `404`, `409`) are documented on each endpoint.'
  contact:
    name: Contact DPF
    url: mailto:contact@dpf-it.com
  license:
    name: Proprietary
    url: https://dpf-it.com/#terms
servers:
- url: https://api.dpf-it.com
  description: Production API
security: []
tags:
- name: Job Triggers
  description: Scheduled ingestion triggers (e.g. SFTP polling) with AI-generated pre/post-processing code
paths:
  /job-triggers:
    post:
      tags:
      - Job Triggers
      summary: Manage workspace ingestion triggers (SFTP, AWS S3, spec chaining)
      description: 'Multi-action endpoint for workspace job triggers. The `action` field determines the operation. Supported trigger `type`s are `sftp`, `aws_s3`, `spec_success`, and `schedule`; for `sftp`/`aws_s3`

        the type must match its connection''s type. For `aws_s3`, `s3Bucket` is required (the bucket to

        poll) and `s3Prefix` is optional (defaults to the whole bucket). **`aws_s3` listing cap:** each run lists at most 5000 objects from the bucket/prefix, oldest key

        first, and stops there. Once a bucket/prefix holds more than 5000 objects, newly delivered files

        can fall outside that window and never be seen by the trigger — it will report no new files even

        though delivery is working. Mitigate by attaching an S3 lifecycle rule that expires or transitions

        older objects out of the prefix so it stays under the cap. `create-trigger` returns a `warnings`

        array with this same note whenever `type: aws_s3`. A trigger references a spec (by `specName`) — the **downstream** spec it fires. For `sftp`/

        `aws_s3` it also references a connection (by `connectionId`); the natural-language `preRules`

        (which files to process) and `postRules` (what to do after upload) are converted by the backend

        into **executable JavaScript** (`preCode` / `postCode`) that is returned and shown read-only. Behavior is changed by editing the rules — the code is regenerated; raw code is never accepted

        from the client. A separate `dedupe` boolean enables per-spec "don''t load the same file twice": files already

        loaded into the spec by a previous run (matched by file name) are skipped. Not applicable to

        `spec_success`. An hourly dispatcher runs enabled `sftp`/`aws_s3` triggers according to `frequency`

        (`hourly`, `daily` + `hourOfDay`, or `monthly` + `dayOfMonth` + `hourOfDay`; all UTC). The

        referenced spec must already have been analyzed once (it must have transformation code) —

        a trigger feeds an analyzed spec, it does not bootstrap one. `spec_success` triggers fire reactively instead: when the spec named by `upstreamSpecId`/

        `upstreamSpecName` completes a successful job, its downstream spec (`specName`) is run

        automatically — no `frequency`/`connectionId`. Chains that would create a cycle (directly or

        through other `spec_success` triggers) are rejected with 409 `CYCLE_DETECTED`. `schedule` triggers fire on a plain cron-like `frequency` like sftp/aws_s3, but with no

        connection — the spec''s job is fired directly rather than pulling files. Use this for a

        table-source spec that should re-run periodically rather than (or in addition to) being

        chained off an upstream spec''s success. Both `spec_success` and `schedule` downstream specs (`specName`) must be table-source

        (`sourceType: ''tables''`) specs — each run re-executes the spec''s generated SQL query, windowed

        to rows since its last successful run, so there is no file for either trigger type to load. **Actions:**


        - **create-trigger**: Validate the spec (+ connection, for sftp/aws_s3), generate `preCode`/

        `postCode` from the rules (sftp/aws_s3 only), persist, and return the trigger. - Requires: JWT token, full access to the workspace

        - Fields: `workspaceId`, `type` (`sftp`, `aws_s3`, `spec_success`, or `schedule`), `specName`;

        for sftp/aws_s3: `connectionId`, `frequency`, optional `preRules`, `postRules`, `dedupe`;

        `s3Bucket` (required)/`s3Prefix` (optional) when `type: aws_s3`; for spec_success:

        `upstreamSpecName`; for schedule: `frequency`; `enabled` optional for all types. - For sftp/aws_s3, the connection''s most recent `lastTestStatus` must be `passed` (see the

        `Connection` schema) — returns 400 `CONNECTION_NOT_TESTED` otherwise. - Returns: the created trigger (with `preCode`/`postCode` for sftp/aws_s3) with status 201. For `type: aws_s3`, the response also includes a `warnings` array noting the 5000-object

        listing cap described above. - **get-triggers**: List all triggers for a workspace (each includes `preCode`/`postCode`).'
      operationId: manageJobTriggers
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/CreateTriggerRequest'
              - $ref: '#/components/schemas/GetTriggersRequest'
              - $ref: '#/components/schemas/UpdateTriggerRequest'
              - $ref: '#/components/schemas/DeleteTriggerRequest'
              - $ref: '#/components/schemas/RunTriggerNowRequest'
              - $ref: '#/components/schemas/ClearProcessedFilesRequest'
            examples:
              createTrigger:
                summary: Create an SFTP trigger
                value:
                  action: create-trigger
                  workspaceId: 550e8400-e29b-41d4-a716-446655440000
                  type: sftp
                  specName: web-logs
                  connectionId: 7b3f8a10-1c2d-4e5f-9a0b-1c2d3e4f5a6b
                  frequency:
                    unit: daily
                    hourOfDay: 6
                  dedupe: true
                  preRules: Process only *.csv files under /outbound
                  postRules: Rename each processed file with a .done suffix
              createAwsS3Trigger:
                summary: Create an aws_s3 trigger
                value:
                  action: create-trigger
                  workspaceId: 550e8400-e29b-41d4-a716-446655440000
                  type: aws_s3
                  specName: web-logs
                  connectionId: 7b3f8a10-1c2d-4e5f-9a0b-1c2d3e4f5a6b
                  s3Bucket: customer-data-bucket
                  s3Prefix: exports/daily/
                  frequency:
                    unit: daily
                    hourOfDay: 6
                  dedupe: true
              createSpecSuccessTrigger:
                summary: Chain a table-source spec off another spec's success
                value:
                  action: create-trigger
                  workspaceId: 550e8400-e29b-41d4-a716-446655440000
                  type: spec_success
                  specName: daily-signups-aggregate
                  upstreamSpecName: daily-signups-load
              createScheduleTrigger:
                summary: Run a table-source spec on a plain schedule (no upstream spec)
                value:
                  action: create-trigger
                  workspaceId: 550e8400-e29b-41d4-a716-446655440000
                  type: schedule
                  specName: daily-signups-aggregate
                  frequency:
                    unit: daily
                    hourOfDay: 7
              getTriggers:
                summary: List triggers
                value:
                  action: get-triggers
                  workspaceId: 550e8400-e29b-41d4-a716-446655440000
              runTriggerNow:
                summary: Fire a trigger now
                value:
                  action: run-trigger-now
                  workspaceId: 550e8400-e29b-41d4-a716-446655440000
                  triggerId: 9c1e2d3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f
      responses:
        '200':
          description: Triggers listed, updated, deleted, or run history returned
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/GetTriggersResponse'
                - $ref: '#/components/schemas/UpdateTriggerResponse'
                - $ref: '#/components/schemas/DeleteTriggerResponse'
                - $ref: '#/components/schemas/ClearProcessedFilesResponse'
        '201':
          description: Trigger created (includes generated preCode/postCode)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateTriggerResponse'
        '202':
          description: Trigger run started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunTriggerNowResponse'
        '403':
          description: No access, or read-only access attempting a mutating action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Trigger, spec, or connection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: Machine-readable error code
              example: INVALID_EMAIL
            message:
              type: string
              description: Human-readable error message
              example: Invalid email format
    DeleteTriggerRequest:
      type: object
      required:
      - action
      - workspaceId
      - triggerId
      properties:
        action:
          type: string
          enum:
          - delete-trigger
        workspaceId:
          type: string
          format: uuid
        triggerId:
          type: string
          format: uuid
    RunTriggerNowRequest:
      type: object
      required:
      - action
      - workspaceId
      - triggerId
      properties:
        action:
          type: string
          enum:
          - run-trigger-now
        workspaceId:
          type: string
          format: uuid
        triggerId:
          type: string
          format: uuid
    ClearProcessedFilesResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            triggerId:
              type: string
              format: uuid
            deleted:
              type: integer
              description: Number of processed-file ledger records deleted.
              example: 12
            message:
              type: string
              example: Cleared 12 processed file record(s)
    CreateTriggerRequest:
      type: object
      description: '`connectionId`/`frequency` are required when `type` is `sftp`/`aws_s3` (the

        default). `upstreamSpecName` is required instead when `type` is

        `spec_success`. `frequency` is required instead when `type` is `schedule`

        (no connection or upstream spec). Both `spec_success` and `schedule` require

        the downstream spec (`specName`) to already be a table-source

        (`sourceType: ''tables''`) or compaction (`sourceType: ''compaction''`) spec.

        '
      required:
      - action
      - workspaceId
      - specName
      properties:
        action:
          type: string
          enum:
          - create-trigger
        workspaceId:
          type: string
          format: uuid
        type:
          type: string
          enum:
          - sftp
          - aws_s3
          - spec_success
          - schedule
          description: Defaults to "sftp". For sftp/aws_s3 must match the referenced connection's type.
        specName:
          type: string
          description: The (downstream) spec this trigger fires.
          example: web-logs
        connectionId:
          type: string
          format: uuid
          description: Required when type is "sftp" or "aws_s3".
        s3Bucket:
          type: string
          description: Required when type is "aws_s3". The bucket this trigger polls.
          example: customer-data-bucket
        s3Prefix:
          type: string
          description: Optional when type is "aws_s3"; defaults to the whole bucket. Ignored otherwise.
          example: exports/daily/
        frequency:
          allOf:
          - $ref: '#/components/schemas/TriggerFrequency'
          description: Required when type is "sftp", "aws_s3", or "schedule". Not applicable to spec_success.
        upstreamSpecName:
          type: string
          description: Required when type is "spec_success" — the spec whose successful job completion fires this trigger.
          example: daily-signups-load
        preRules:
          type: string
        postRules:
          type: string
        dedupe:
          type: boolean
          description: Defaults to false.
        enabled:
          type: boolean
          description: Defaults to true.
    GetTriggersRequest:
      type: object
      required:
      - action
      - workspaceId
      properties:
        action:
          type: string
          enum:
          - get-triggers
        workspaceId:
          type: string
          format: uuid
    JobTrigger:
      type: object
      description: 'A workspace ingestion trigger. `preCode`/`postCode` are the JavaScript

        generated from `preRules`/`postRules`; they are read-only (regenerated when

        the rules change) and are always included in responses.


        `spec_success` triggers fire when another spec''s job completes successfully

        (`upstreamSpecId`/`upstreamSpecName`) instead of polling a connection — they

        have no `connectionId`/`frequency`/`preRules`/`postRules`/s3 fields. `schedule`

        triggers fire a spec directly on a plain cron-like schedule (`frequency`,

        same as sftp/aws_s3) with no connection and no upstream spec. Both

        `spec_success` and `schedule` require the trigger''s own `specId`/`specName`

        (the spec fired) to be a table-source (`sourceType: ''tables''`) or compaction

        (`sourceType: ''compaction''`) spec, since neither supplies a new file for a

        file-source spec to load — a table-source spec re-runs its generated query,

        windowed to rows since its last successful run, and a compaction spec re-compacts

        its tables, so both are just different ways to decide *when* to re-run them.

        '
      properties:
        triggerId:
          type: string
          format: uuid
          example: 9c1e2d3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f
        workspaceId:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        type:
          type: string
          enum:
          - sftp
          - aws_s3
          - spec_success
          - schedule
          example: sftp
        specId:
          type: string
          format: uuid
          description: The (downstream) spec this trigger fires.
        specName:
          type: string
          example: web-logs
        connectionId:
          type: string
          format: uuid
          description: sftp/aws_s3 only.
          example: 7b3f8a10-1c2d-4e5f-9a0b-1c2d3e4f5a6b
        s3Bucket:
          type: string
          description: aws_s3 only, required for that type. The bucket this trigger polls.
          example: customer-data-bucket
        s3Prefix:
          type: string
          description: aws_s3 only. Optional key prefix; defaults to the whole bucket.
          example: exports/daily/
        upstreamSpecId:
          type:
          - string
          - 'null'
          format: uuid
          description: spec_success only — the spec whose successful job completion fires this trigger.
        upstreamSpecName:
          type:
          - string
          - 'null'
          example: daily-signups-load
          description: spec_success only — denormalized name of upstreamSpecId, for display.
        frequency:
          $ref: '#/components/schemas/TriggerFrequency'
        preRules:
          type: string
          description: Natural-language "which files to process" prompt (may be empty).
          example: Process only *.csv files under /outbound
        postRules:
          type: string
          description: Natural-language "what to do after upload" prompt (may be empty).
          example: Rename each processed file with a .done suffix
        preCode:
          type: string
          description: Generated body of async selectFiles(files, ctx). Read-only.
        postCode:
          type: string
          description: Generated body of async postProcess(sftp, files, ctx). Read-only.
        dedupe:
          type: boolean
          description: Skip files already loaded into this spec (per-spec, matched by file name).
          example: true
        enabled:
          type: boolean
          example: true
        createdBy:
          type: string
          format: uuid
        createdAt:
          type: integer
          format: int64
          description: Unix timestamp in milliseconds
        updatedAt:
          type: integer
          format: int64
          description: Unix timestamp in milliseconds
        lastRunAt:
          type:
          - integer
          - 'null'
          format: int64
          description: Unix timestamp in milliseconds of the last run (absent if never run).
        lastRunStatus:
          type:
          - string
          - 'null'
          enum:
          - running
          - success
          - failed
          - no-files
          - null
        lastJobId:
          type:
          - string
          - 'null'
          format: uuid
        warnings:
          type: array
          items:
            type: string
          description: create-trigger only, aws_s3 only. Advisory notes about the created trigger — currently just the 5000-object S3 listing cap. Absent on get/update/delete responses and on other types.
          example:
          - Each run lists at most 5000 objects from this bucket/prefix, oldest key first. Once it holds more than 5000 objects, newly delivered files can fall outside that window and be missed entirely. Configure an S3 lifecycle rule to expire or transition older objects out of this prefix so it stays under the cap.
    UpdateTriggerResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          $ref: '#/components/schemas/JobTrigger'
    TriggerFrequency:
      type: object
      description: 'Polling cadence, evaluated in UTC by the hourly dispatcher.

        `hourOfDay` is required for `daily`/`monthly`; `dayOfMonth` for `monthly`.

        '
      required:
      - unit
      properties:
        unit:
          type: string
          enum:
          - hourly
          - daily
          - monthly
          example: daily
        hourOfDay:
          type: integer
          minimum: 0
          maximum: 23
          description: Hour of day (UTC). Required for daily and monthly.
          example: 6
        dayOfMonth:
          type: integer
          minimum: 1
          maximum: 31
          description: Day of month. Required for monthly.
          example: 1
    GetTriggersResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            triggers:
              type: array
              items:
                $ref: '#/components/schemas/JobTrigger'
            count:
              type: integer
              example: 1
    ClearProcessedFilesRequest:
      type: object
      required:
      - action
      - workspaceId
      - triggerId
      properties:
        action:
          type: string
          enum:
          - clear-processed-files
        workspaceId:
          type: string
          format: uuid
        triggerId:
          type: string
          format: uuid
    RunTriggerNowResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            triggerId:
              type: string
              format: uuid
            message:
              type: string
              example: Trigger run started
    DeleteTriggerResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            triggerId:
              type: string
              format: uuid
            message:
              type: string
              example: Trigger deleted successfully
    CreateTriggerResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          $ref: '#/components/schemas/JobTrigger'
    UpdateTriggerRequest:
      type: object
      description: 'Partial update. Changing `preRules`, `postRules`, or `dedupe` regenerates

        `preCode`/`postCode`. Raw code is never accepted. `s3Bucket`/`s3Prefix` only apply

        to (and are only accepted for) an existing `aws_s3` trigger. `upstreamSpecName`

        only applies to (and is only accepted for) an existing `spec_success` trigger,

        and is re-validated for cycles just like create-trigger. `frequency` applies to

        sftp/aws_s3/schedule triggers. A trigger''s `type` cannot be changed.

        '
      required:
      - action
      - workspaceId
      - triggerId
      properties:
        action:
          type: string
          enum:
          - update-trigger
        workspaceId:
          type: string
          format: uuid
        triggerId:
          type: string
          format: uuid
        frequency:
          $ref: '#/components/schemas/TriggerFrequency'
        preRules:
          type: string
        postRules:
          type: string
        dedupe:
          type: boolean
        enabled:
          type: boolean
        s3Bucket:
          type: string
          description: aws_s3 triggers only.
          example: customer-data-bucket
        s3Prefix:
          type: string
          description: aws_s3 triggers only.
          example: exports/daily/
        upstreamSpecName:
          type: string
          description: spec_success triggers only. Re-points the trigger at a different upstream spec.
          example: daily-signups-load
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained from login or registration