openapi: 3.0.3
info:
  title: Workly API
  version: 0.1.0
  description: |
    Workly is an open-source HTTP task queue and scheduler.

    Queues deliver tasks you enqueue. Schedules are separate: they call an
    endpoint on a cron schedule, and each call is a run with its own
    attempts. Schedules never create tasks or use queues. Groups track a set
    of tasks and enqueue a callback task once they have all finished.
    Workflows run a DAG of HTTP steps, each delivered as a task; a step can
    hand its completion to a group with the `Workly-Wait-For` response
    header.

    Requests under `/v1` are scoped to a workspace, resolved from the
    `Authorization: Bearer <key>` header. The workspace never appears in paths.
servers:
  - url: http://localhost:7337
paths:
  /healthz:
    get:
      operationId: getHealthz
      summary: Liveness probe
      description: Returns 200 while the process is running. Does not touch the database.
      tags: [operational]
      responses:
        "200":
          description: Process is alive
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Health"
  /readyz:
    get:
      operationId: getReadyz
      summary: Readiness probe
      description: Returns 200 when the database is reachable and migrations are applied.
      tags: [operational]
      responses:
        "200":
          description: Ready to serve traffic
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Health"
        "503":
          description: Not ready
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/queues:
    get:
      operationId: listQueues
      summary: List queues
      tags: [queues]
      security: [{bearerAuth: []}]
      responses:
        "200":
          description: All queues in the workspace, by name, with their stats
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QueueList"
        default:
          $ref: "#/components/responses/Error"
  /v1/queues/{queue}:
    parameters:
      - $ref: "#/components/parameters/QueueName"
    get:
      operationId: getQueue
      summary: Get a queue
      tags: [queues]
      security: [{bearerAuth: []}]
      responses:
        "200":
          description: The queue, with its stats
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Queue"
        default:
          $ref: "#/components/responses/Error"
    put:
      operationId: putQueue
      summary: Create or update a queue
      description: |
        Declarative and idempotent: the queue ends up with exactly the given
        configuration, and omitted fields are reset to their defaults. This
        makes queue configuration easy to keep in code. It doesn't change
        whether the queue is paused.
      tags: [queues]
      security: [{bearerAuth: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/QueueConfig"
      responses:
        "200":
          description: Queue updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Queue"
        "201":
          description: Queue created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Queue"
        default:
          $ref: "#/components/responses/Error"
    delete:
      operationId: deleteQueue
      summary: Delete a queue and all its tasks
      description: |
        Workly's own queues, `_workflows` and `_callbacks`, can't be deleted
        (`invalid_state`): their tasks are workflow steps and callbacks in
        flight.
      tags: [queues]
      security: [{bearerAuth: []}]
      responses:
        "204":
          description: Queue deleted
        default:
          $ref: "#/components/responses/Error"
  /v1/queues/{queue}/pause:
    parameters:
      - $ref: "#/components/parameters/QueueName"
    post:
      operationId: pauseQueue
      summary: Pause a queue
      description: |
        Stops dispatching the queue's tasks. Deliveries already in flight
        finish, and tasks can still be enqueued.
      tags: [queues]
      security: [{bearerAuth: []}]
      responses:
        "200":
          description: The paused queue
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Queue"
        default:
          $ref: "#/components/responses/Error"
  /v1/queues/{queue}/resume:
    parameters:
      - $ref: "#/components/parameters/QueueName"
    post:
      operationId: resumeQueue
      summary: Resume a paused queue
      tags: [queues]
      security: [{bearerAuth: []}]
      responses:
        "200":
          description: The resumed queue
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Queue"
        default:
          $ref: "#/components/responses/Error"
  /v1/queues/{queue}/cancel-pending:
    parameters:
      - $ref: "#/components/parameters/QueueName"
    post:
      operationId: cancelPendingTasks
      summary: Cancel a queue's pending tasks
      description: |
        Cancels every pending task, including scheduled ones and ones waiting
        to retry, as `POST /v1/tasks/{id}/cancel` does for one task. Running
        tasks finish their attempt. Cancelled tasks stay in the history until
        retention removes them, and can be retried.
      tags: [queues]
      security: [{bearerAuth: []}]
      responses:
        "200":
          description: Tasks cancelled
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CancelPendingResult"
        default:
          $ref: "#/components/responses/Error"
  /v1/queues/{queue}/retry-failed:
    parameters:
      - $ref: "#/components/parameters/QueueName"
    post:
      operationId: retryFailedTasks
      summary: Retry every failed task in a queue
      description: |
        Replays every failed task in the queue now, each with a fresh set of
        `max_attempts`, as `POST /v1/tasks/{id}/retry` does for one task. Use
        it to recover after an outage of the endpoint. Pause the queue first
        or set a rate limit to control how fast the replays are delivered.

        With `last_error`, only the failed tasks whose latest error is exactly
        that (as `GET /v1/queues/{queue}/failures` groups them) are retried.
      tags: [queues]
      security: [{bearerAuth: []}]
      parameters:
        - $ref: "#/components/parameters/LastError"
      responses:
        "200":
          description: Tasks retried
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RetryFailedResult"
        default:
          $ref: "#/components/responses/Error"
  /v1/queues/{queue}/failures:
    parameters:
      - $ref: "#/components/parameters/QueueName"
    get:
      operationId: getQueueFailures
      summary: Group a queue's failed tasks by error
      description: |
        Groups the queue's failed tasks by their latest error, most common
        first, so one broken endpoint or bad payload shows up as one line.
        Only the 10,000 most recently failed tasks are grouped.
      tags: [queues]
      security: [{bearerAuth: []}]
      parameters:
        - name: limit
          in: query
          description: How many groups to return.
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 10
      responses:
        "200":
          description: The queue's failures, grouped
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QueueFailures"
        default:
          $ref: "#/components/responses/Error"
  /v1/queues/{queue}/activity:
    parameters:
      - $ref: "#/components/parameters/QueueName"
    get:
      operationId: getQueueActivity
      summary: Count a queue's finished tasks
      description: |
        Counts the tasks that finished since `since`, by final state, with
        percentiles of how long their latest attempt took. Finished
        tasks are deleted after the server's retention period, so a `since`
        further back than `retention_seconds` only counts what is left.
      tags: [queues]
      security: [{bearerAuth: []}]
      parameters:
        - name: since
          in: query
          description: Defaults to 7 days ago.
          schema:
            type: string
            format: date-time
      responses:
        "200":
          description: The queue's activity
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QueueActivity"
        default:
          $ref: "#/components/responses/Error"
  /v1/activity:
    get:
      operationId: getActivity
      summary: Count tasks created and finished over time
      description: |
        Counts the workspace's tasks created in each bucket of the range, per
        queue, and the tasks that finished in it, by final state; oldest
        bucket first, and every bucket is listed, empty ones too.
        Buckets are 5 minutes for `1h`, 1 hour for `24h` and 6 hours for `7d`,
        aligned to UTC. Finished tasks are deleted after the server's
        retention period, so buckets further back than `retention_seconds`
        only count what is left.
      tags: [queues]
      security: [{bearerAuth: []}]
      parameters:
        - name: range
          in: query
          schema:
            type: string
            enum: [1h, 24h, 7d]
            default: 24h
      responses:
        "200":
          description: Tasks created per bucket and queue
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Activity"
        default:
          $ref: "#/components/responses/Error"
  /v1/queues/{queue}/tasks:
    parameters:
      - $ref: "#/components/parameters/QueueName"
    post:
      operationId: createTask
      summary: Enqueue a task
      description: |
        The queue is created with default settings if it doesn't exist, unless
        the server runs with `WORKLY_AUTO_CREATE_QUEUES=false`.

        If `idempotency_key` matches an existing task in the queue, that task
        is returned with status 200 and nothing is enqueued.
      tags: [tasks]
      security: [{bearerAuth: []}]
      parameters:
        - name: traceparent
          in: header
          description: W3C trace context, propagated on delivery.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EnqueueRequest"
      responses:
        "201":
          description: Task enqueued
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Task"
        "200":
          description: A task with this idempotency key already exists
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Task"
        default:
          $ref: "#/components/responses/Error"
    get:
      operationId: listTasks
      summary: List a queue's tasks
      description: Newest first, unless `sort` and `order` say otherwise.
      tags: [tasks]
      security: [{bearerAuth: []}]
      parameters:
        - name: state
          in: query
          schema:
            $ref: "#/components/schemas/TaskState"
        - $ref: "#/components/parameters/LastError"
        - $ref: "#/components/parameters/TaskSort"
        - $ref: "#/components/parameters/SortOrder"
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: A page of tasks
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TaskList"
        default:
          $ref: "#/components/responses/Error"
  /v1/queues/{queue}/tasks:batch:
    parameters:
      - $ref: "#/components/parameters/QueueName"
    post:
      operationId: createTasks
      summary: Enqueue up to 100 tasks at once
      description: |
        Enqueues all the tasks or none: if any task is invalid, nothing is
        enqueued and the error names the first invalid one (`tasks[3]: ...`).
        Idempotency keys work as for a single enqueue, including between
        tasks in the same batch.

        The whole request is limited to the payload limit plus 256 KB.
      tags: [tasks]
      security: [{bearerAuth: []}]
      parameters:
        - name: traceparent
          in: header
          description: W3C trace context, propagated on delivery of every task.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BatchEnqueueRequest"
      responses:
        "200":
          description: The tasks, in request order
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BatchEnqueueResponse"
        default:
          $ref: "#/components/responses/Error"
  /v1/tasks:
    get:
      operationId: searchTasks
      summary: Search tasks across queues
      description: |
        All filters are optional and combine with AND. To find one task by
        ID, use `GET /v1/tasks/{id}`. Newest first, unless `sort` and
        `order` say otherwise.
      tags: [tasks]
      security: [{bearerAuth: []}]
      parameters:
        - name: queue
          in: query
          schema:
            type: string
        - name: state
          in: query
          schema:
            $ref: "#/components/schemas/TaskState"
        - name: idempotency_key
          in: query
          schema:
            type: string
        - name: group_id
          in: query
          description: Only the tasks of this group.
          schema:
            type: string
        - $ref: "#/components/parameters/LastError"
        - name: created_after
          in: query
          description: Only tasks created at or after this time.
          schema:
            type: string
            format: date-time
        - name: created_before
          in: query
          description: Only tasks created before this time.
          schema:
            type: string
            format: date-time
        - $ref: "#/components/parameters/TaskSort"
        - $ref: "#/components/parameters/SortOrder"
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: A page of tasks
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TaskList"
        default:
          $ref: "#/components/responses/Error"
  /v1/tasks/{id}:
    parameters:
      - $ref: "#/components/parameters/TaskID"
    get:
      operationId: getTask
      summary: Get a task
      tags: [tasks]
      security: [{bearerAuth: []}]
      responses:
        "200":
          description: The task
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Task"
        default:
          $ref: "#/components/responses/Error"
  /v1/tasks/{id}/attempts:
    parameters:
      - $ref: "#/components/parameters/TaskID"
    get:
      operationId: listAttempts
      summary: List a task's delivery attempts, oldest first
      tags: [tasks]
      security: [{bearerAuth: []}]
      responses:
        "200":
          description: The task's attempts
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AttemptList"
        default:
          $ref: "#/components/responses/Error"
  /v1/tasks/{id}/delivery:
    parameters:
      - $ref: "#/components/parameters/TaskID"
    get:
      operationId: getTaskDelivery
      summary: Get the request that delivers a task
      description: |
        The HTTP request Workly sends to deliver the task, as it would be sent
        now: the task's own headers plus Workly's (`Workly-Task-Id`,
        `Workly-Signature`, ...), and the exact body. The signature is fresh,
        so replaying the request (for example with curl) while fixing an
        endpoint passes verification until the timestamp is too old. Nothing
        is sent and the task doesn't change. `Workly-Attempt` is the next
        attempt for a pending task, otherwise the latest.
      tags: [tasks]
      security: [{bearerAuth: []}]
      responses:
        "200":
          description: The delivery request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Delivery"
        default:
          $ref: "#/components/responses/Error"
  /v1/tasks/{id}/cancel:
    parameters:
      - $ref: "#/components/parameters/TaskID"
    post:
      operationId: cancelTask
      summary: Cancel a task
      description: |
        Cancels a pending or running task. A running task's current attempt
        finishes and is recorded, but the task isn't retried. Cancelling a
        cancelled task does nothing; a succeeded or failed task can't be
        cancelled (`invalid_state`).
      tags: [tasks]
      security: [{bearerAuth: []}]
      responses:
        "200":
          description: The cancelled task
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Task"
        default:
          $ref: "#/components/responses/Error"
  /v1/tasks/{id}/retry:
    parameters:
      - $ref: "#/components/parameters/TaskID"
    post:
      operationId: retryTask
      summary: Retry a task now
      description: |
        Makes the task due now. A succeeded, failed or cancelled task is
        replayed with a fresh set of `max_attempts`; its attempt numbers keep
        counting. A pending task (scheduled or waiting to retry) just runs
        sooner. A task can't be retried while an attempt is in flight
        (`invalid_state`).
      tags: [tasks]
      security: [{bearerAuth: []}]
      responses:
        "200":
          description: The task, now pending
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Task"
        default:
          $ref: "#/components/responses/Error"
  /v1/groups:
    post:
      operationId: createGroup
      summary: Create a task group
      description: |
        Creates an open group. Enqueue tasks into it with `group_id`, then
        close it with `POST /v1/groups/{id}/close`. Once it is closed and
        every task in it has succeeded, failed or been cancelled, it
        completes and enqueues its `on_complete` callback, once.

        If `idempotency_key` matches an existing group, that group is
        returned with status 200 and nothing is created.
      tags: [groups]
      security: [{bearerAuth: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewGroup"
      responses:
        "201":
          description: Group created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Group"
        "200":
          description: A group with this idempotency key already exists
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Group"
        default:
          $ref: "#/components/responses/Error"
    get:
      operationId: listGroups
      summary: List task groups
      description: Newest first. List a group's tasks with `GET /v1/tasks?group_id=`.
      tags: [groups]
      security: [{bearerAuth: []}]
      parameters:
        - name: status
          in: query
          schema:
            $ref: "#/components/schemas/GroupStatus"
        - name: name
          in: query
          schema:
            type: string
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: A page of groups
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GroupList"
        default:
          $ref: "#/components/responses/Error"
  /v1/groups/{id}:
    parameters:
      - $ref: "#/components/parameters/GroupID"
    get:
      operationId: getGroup
      summary: Get a task group
      tags: [groups]
      security: [{bearerAuth: []}]
      responses:
        "200":
          description: The group
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Group"
        default:
          $ref: "#/components/responses/Error"
  /v1/groups/{id}/close:
    parameters:
      - $ref: "#/components/parameters/GroupID"
    post:
      operationId: closeGroup
      summary: Close a task group
      description: |
        Stops the group from accepting tasks; enqueueing into it then fails
        with `group_closed`. If its tasks have all finished (or it has none),
        it completes at once. Closing a closed group does nothing.
      tags: [groups]
      security: [{bearerAuth: []}]
      responses:
        "200":
          description: The group, now running or completed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Group"
        default:
          $ref: "#/components/responses/Error"
  /v1/schedules:
    get:
      operationId: listSchedules
      summary: List schedules
      tags: [schedules]
      security: [{bearerAuth: []}]
      responses:
        "200":
          description: All schedules in the workspace, by name
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ScheduleList"
        default:
          $ref: "#/components/responses/Error"
  /v1/schedules/{schedule}:
    parameters:
      - $ref: "#/components/parameters/ScheduleName"
    get:
      operationId: getSchedule
      summary: Get a schedule
      tags: [schedules]
      security: [{bearerAuth: []}]
      responses:
        "200":
          description: The schedule
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Schedule"
        default:
          $ref: "#/components/responses/Error"
    put:
      operationId: putSchedule
      summary: Create or update a schedule
      description: |
        Declarative and idempotent: the schedule ends up with exactly the
        given settings, and omitted fields are reset to their defaults. It
        doesn't change whether the schedule is paused. The response's
        `next_runs` shows when it will run, so a cron expression can be
        checked before relying on it.

        Runs already created keep the request they were created with; retries
        use the schedule's current retry policy and timeout.
      tags: [schedules]
      security: [{bearerAuth: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ScheduleConfig"
      responses:
        "200":
          description: Schedule updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Schedule"
        "201":
          description: Schedule created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Schedule"
        default:
          $ref: "#/components/responses/Error"
    delete:
      operationId: deleteSchedule
      summary: Delete a schedule and all its runs
      description: A run in flight finishes, but its result isn't recorded.
      tags: [schedules]
      security: [{bearerAuth: []}]
      responses:
        "204":
          description: Schedule deleted
        default:
          $ref: "#/components/responses/Error"
  /v1/cron/preview:
    get:
      operationId: previewCron
      summary: Preview a cron timetable
      description: |
        The next times a schedule with this cron expression and timezone
        would run, from now, without creating it. For forms that check a
        timetable as it's typed.

        With `from` and `until`, it also lists every run in that window
        (at most 35 days) as `spans`, for calendars of what runs when.
      tags: [schedules]
      security: [{bearerAuth: []}]
      parameters:
        - name: cron
          in: query
          required: true
          schema:
            type: string
        - name: timezone
          in: query
          description: IANA name. Defaults to UTC.
          schema:
            type: string
        - name: from
          in: query
          description: The start of the window to list runs in. Requires `until`.
          schema:
            type: string
            format: date-time
        - name: until
          in: query
          description: The end of the window, exclusive. Requires `from`.
          schema:
            type: string
            format: date-time
      responses:
        "200":
          description: The next runs
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CronPreview"
        default:
          $ref: "#/components/responses/Error"
  /v1/schedules/{schedule}/pause:
    parameters:
      - $ref: "#/components/parameters/ScheduleName"
    post:
      operationId: pauseSchedule
      summary: Pause a schedule
      description: |
        Stops the schedule from firing. Runs already pending or in flight
        still finish, and "run now" still works.
      tags: [schedules]
      security: [{bearerAuth: []}]
      responses:
        "200":
          description: The paused schedule
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Schedule"
        default:
          $ref: "#/components/responses/Error"
  /v1/schedules/{schedule}/resume:
    parameters:
      - $ref: "#/components/parameters/ScheduleName"
    post:
      operationId: resumeSchedule
      summary: Resume a paused schedule
      description: |
        The schedule fires again from its next slot after now. Slots that
        passed while it was paused are not run.
      tags: [schedules]
      security: [{bearerAuth: []}]
      responses:
        "200":
          description: The resumed schedule
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Schedule"
        default:
          $ref: "#/components/responses/Error"
  /v1/schedules/{schedule}/trigger:
    parameters:
      - $ref: "#/components/parameters/ScheduleName"
    post:
      operationId: triggerSchedule
      summary: Run a schedule now
      description: |
        Creates a run that is delivered right away, with `trigger: manual`.
        It runs even if the schedule is paused or a run is in flight, and
        doesn't change when the schedule next fires.
      tags: [schedules]
      security: [{bearerAuth: []}]
      responses:
        "201":
          description: The new run
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Run"
        default:
          $ref: "#/components/responses/Error"
  /v1/runs:
    get:
      operationId: listRuns
      summary: List runs, newest first
      description: |
        Runs of every schedule, or of one with `schedule`. A `schedule` that
        doesn't exist is `schedule_not_found`.
      tags: [schedules]
      security: [{bearerAuth: []}]
      parameters:
        - name: schedule
          in: query
          description: Only this schedule's runs.
          schema:
            type: string
        - name: state
          in: query
          schema:
            $ref: "#/components/schemas/RunState"
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: A page of runs
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RunList"
        default:
          $ref: "#/components/responses/Error"
  /v1/runs/{id}:
    parameters:
      - $ref: "#/components/parameters/RunID"
    get:
      operationId: getRun
      summary: Get a run
      tags: [schedules]
      security: [{bearerAuth: []}]
      responses:
        "200":
          description: The run
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Run"
        default:
          $ref: "#/components/responses/Error"
  /v1/runs/{id}/attempts:
    parameters:
      - $ref: "#/components/parameters/RunID"
    get:
      operationId: listRunAttempts
      summary: List a run's delivery attempts, oldest first
      tags: [schedules]
      security: [{bearerAuth: []}]
      responses:
        "200":
          description: The run's attempts
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AttemptList"
        default:
          $ref: "#/components/responses/Error"
  /v1/runs/{id}/delivery:
    parameters:
      - $ref: "#/components/parameters/RunID"
    get:
      operationId: getRunDelivery
      summary: Get the request that delivers a run
      description: |
        The HTTP request Workly sends to deliver the run, as it would be sent
        now, with a fresh signature, as for `GET /v1/tasks/{id}/delivery`.
        Nothing is sent.
      tags: [schedules]
      security: [{bearerAuth: []}]
      responses:
        "200":
          description: The delivery request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Delivery"
        default:
          $ref: "#/components/responses/Error"
  /v1/runs/{id}/cancel:
    parameters:
      - $ref: "#/components/parameters/RunID"
    post:
      operationId: cancelRun
      summary: Cancel a run
      description: |
        Cancels a pending or running run. A running run's current attempt
        finishes and is recorded, but the run isn't retried. Cancelling a
        cancelled run does nothing; a finished or skipped run can't be
        cancelled (`invalid_state`).
      tags: [schedules]
      security: [{bearerAuth: []}]
      responses:
        "200":
          description: The cancelled run
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Run"
        default:
          $ref: "#/components/responses/Error"
  /v1/runs/{id}/retry:
    parameters:
      - $ref: "#/components/parameters/RunID"
    post:
      operationId: retryRun
      summary: Retry a run now
      description: |
        Makes the run due now. A succeeded, failed, cancelled or skipped run
        is delivered again with a fresh set of `max_attempts`; a pending run
        just runs sooner. A run can't be retried while an attempt is in
        flight (`invalid_state`).
      tags: [schedules]
      security: [{bearerAuth: []}]
      responses:
        "200":
          description: The run, now pending
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Run"
        default:
          $ref: "#/components/responses/Error"
  /v1/workflows:
    get:
      operationId: listWorkflows
      summary: List workflows
      tags: [workflows]
      security: [{bearerAuth: []}]
      responses:
        "200":
          description: All workflows in the workspace, by name
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkflowList"
        default:
          $ref: "#/components/responses/Error"
  /v1/workflows/{workflow}:
    parameters:
      - $ref: "#/components/parameters/WorkflowName"
    get:
      operationId: getWorkflow
      summary: Get a workflow
      tags: [workflows]
      security: [{bearerAuth: []}]
      responses:
        "200":
          description: The workflow
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Workflow"
        default:
          $ref: "#/components/responses/Error"
    put:
      operationId: putWorkflow
      summary: Create or update a workflow
      description: |
        Declarative and idempotent: the workflow ends up with exactly the
        given steps and settings. A changed definition gets a new `version`.
        Runs already started keep the definition they started with; new runs
        use this one.
      tags: [workflows]
      security: [{bearerAuth: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WorkflowConfig"
      responses:
        "200":
          description: Workflow updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Workflow"
        "201":
          description: Workflow created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Workflow"
        default:
          $ref: "#/components/responses/Error"
    delete:
      operationId: deleteWorkflow
      summary: Delete a workflow
      description: |
        Deletes the definition only. Its runs are kept (under retention), and
        runs still going finish under the definition they started with.
      tags: [workflows]
      security: [{bearerAuth: []}]
      responses:
        "204":
          description: Workflow deleted
        default:
          $ref: "#/components/responses/Error"
  /v1/workflows/{workflow}/runs:
    parameters:
      - $ref: "#/components/parameters/WorkflowName"
    post:
      operationId: startWorkflowRun
      summary: Start a workflow run
      description: |
        Starts a run and enqueues the steps without dependencies. With an
        `idempotency_key` already used for a run of this workflow, that run
        is returned (200) and nothing starts.
      tags: [workflows]
      security: [{bearerAuth: []}]
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StartWorkflowRun"
      responses:
        "200":
          description: The run with that idempotency key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkflowRun"
        "201":
          description: The new run
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkflowRun"
        default:
          $ref: "#/components/responses/Error"
  /v1/workflow-runs:
    get:
      operationId: listWorkflowRuns
      summary: List workflow runs, newest first
      description: |
        Runs of every workflow, or of one with `workflow` (including a
        deleted one's).
      tags: [workflows]
      security: [{bearerAuth: []}]
      parameters:
        - name: workflow
          in: query
          description: Only this workflow's runs.
          schema:
            type: string
        - name: status
          in: query
          schema:
            $ref: "#/components/schemas/WorkflowRunStatus"
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: A page of runs, without their steps
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkflowRunList"
        default:
          $ref: "#/components/responses/Error"
  /v1/workflow-runs/{id}:
    parameters:
      - $ref: "#/components/parameters/WorkflowRunID"
    get:
      operationId: getWorkflowRun
      summary: Get a workflow run with its steps
      tags: [workflows]
      security: [{bearerAuth: []}]
      responses:
        "200":
          description: The run
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkflowRun"
        default:
          $ref: "#/components/responses/Error"
  /v1/workflow-runs/{id}/cancel:
    parameters:
      - $ref: "#/components/parameters/WorkflowRunID"
    post:
      operationId: cancelWorkflowRun
      summary: Cancel a workflow run
      description: |
        Steps that haven't started are skipped, and their pending tasks
        cancelled. Requests already being delivered finish and are recorded,
        but start nothing. Cancelling a cancelled run is a no-op; other
        finished runs are `invalid_state`.
      tags: [workflows]
      security: [{bearerAuth: []}]
      responses:
        "200":
          description: The cancelled run
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkflowRun"
        default:
          $ref: "#/components/responses/Error"
  /v1/workflow-runs/{id}/retry:
    parameters:
      - $ref: "#/components/parameters/WorkflowRunID"
    post:
      operationId: retryWorkflowRun
      summary: Retry a workflow run
      description: |
        Reopens a failed or cancelled run, under the definition it started
        with and with the same input: steps that succeeded stay, and the
        rest run again. Each step that runs again gets its task back,
        pending with a fresh set of attempts. A step that was waiting for a
        group follows the group: it succeeds if the group has since
        succeeded, and waits for it again if it is still going. The run's
        `attempt` goes up by one, and its `max_duration_seconds` starts
        over. Other runs are `invalid_state`.
      tags: [workflows]
      security: [{bearerAuth: []}]
      responses:
        "200":
          description: The run, running again
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkflowRun"
        default:
          $ref: "#/components/responses/Error"
  /v1/alert-channels:
    get:
      operationId: listAlertChannels
      summary: List alert channels
      description: |
        Where the workspace's alerts go. When tasks in a queue or runs of a
        schedule fail (after their last attempt), every channel gets an
        alert within about a minute, naming the errors. After that, a queue
        or schedule gets at most one alert every 30 minutes, covering the
        failures since its previous one.
      tags: [alerts]
      security: [{bearerAuth: []}]
      responses:
        "200":
          description: The workspace's channels, oldest first
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AlertChannelList"
        default:
          $ref: "#/components/responses/Error"
    post:
      operationId: createAlertChannel
      summary: Add an alert channel
      description: |
        A workspace has at most 10 channels. Email channels need a server
        that can send email (`email_enabled` in the list); a Slack channel
        takes an incoming webhook URL (`https://hooks.slack.com/...`).
      tags: [alerts]
      security: [{bearerAuth: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewAlertChannel"
      responses:
        "201":
          description: Channel added
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AlertChannel"
        default:
          $ref: "#/components/responses/Error"
  /v1/alert-channels/{id}:
    parameters:
      - $ref: "#/components/parameters/AlertChannelID"
    delete:
      operationId: deleteAlertChannel
      summary: Remove an alert channel
      tags: [alerts]
      security: [{bearerAuth: []}]
      responses:
        "204":
          description: Channel removed
        default:
          $ref: "#/components/responses/Error"
  /v1/alert-channels/{id}/test:
    parameters:
      - $ref: "#/components/parameters/AlertChannelID"
    post:
      operationId: testAlertChannel
      summary: Send a test alert
      description: |
        Sends a test message to the channel now, to check it's set up
        right. If it can't be sent, the error (`alert_failed`, 502) says
        why.
      tags: [alerts]
      security: [{bearerAuth: []}]
      responses:
        "204":
          description: Sent
        default:
          $ref: "#/components/responses/Error"
components:
  parameters:
    QueueName:
      name: queue
      in: path
      required: true
      description: |
        Queue name. Lowercase letters, digits, `-` and `_`; at most 64
        characters. Names starting with `_` are reserved for Workly's own
        queues, such as `_callbacks`: they can be configured and their tasks
        listed, but not enqueued into.
      schema:
        type: string
    Cursor:
      name: cursor
      in: query
      description: |
        The `next_cursor` of the previous page, requested with the same
        filters and order.
      schema:
        type: string
    Limit:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 50
    TaskSort:
      name: sort
      in: query
      description: |
        What to order tasks by:

        - `created_at` (the default): when the task was enqueued.
        - `run_at`: when it runs next. Pending tasks are delivered in this
          order, so ascending lists them as they'll run.
        - `last_attempt_at`: when its latest attempt finished. Tasks never
          attempted count as oldest.
        - `attempt_count`: how many attempts it has had.

        Ties are broken by task ID.
      schema:
        type: string
        enum: [created_at, run_at, last_attempt_at, attempt_count]
    SortOrder:
      name: order
      in: query
      description: |
        `asc` or `desc`. Defaults to `asc` (soonest first) for `run_at` and
        to `desc` (newest or most first) for the rest.
      schema:
        type: string
        enum: [asc, desc]
    LastError:
      name: last_error
      in: query
      description: Only tasks whose latest error is exactly this.
      schema:
        type: string
    TaskID:
      name: id
      in: path
      required: true
      schema:
        type: string
    ScheduleName:
      name: schedule
      in: path
      required: true
      description: Schedule name. Lowercase letters, digits, `-` and `_`; at most 64 characters.
      schema:
        type: string
    GroupID:
      name: id
      in: path
      required: true
      schema:
        type: string
    RunID:
      name: id
      in: path
      required: true
      schema:
        type: string
    WorkflowName:
      name: workflow
      in: path
      required: true
      description: Workflow name. Lowercase letters, digits, `-` and `_`; at most 64 characters.
      schema:
        type: string
    WorkflowRunID:
      name: id
      in: path
      required: true
      schema:
        type: string
    AlertChannelID:
      name: id
      in: path
      required: true
      schema:
        type: string
  responses:
    Error:
      description: |
        An error. Codes include `invalid_request`, `unauthorized`,
        `queue_not_found`, `task_not_found`, `group_not_found`,
        `group_closed` (409), `schedule_not_found`, `run_not_found`,
        `workflow_not_found`, `workflow_run_not_found`,
        `alert_channel_not_found`,
        `alert_channel_exists` (409), `email_unavailable`, `alert_failed` (502),
        `invalid_state` (409), `payload_too_large` and
        `internal`.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  schemas:
    Health:
      type: object
      required: [status]
      properties:
        status:
          type: string
          example: ok
    QueueConfig:
      type: object
      description: A queue's delivery policy. Omitted fields take the default.
      properties:
        max_attempts:
          type: integer
          minimum: 1
          maximum: 1000
          default: 5
          description: Total delivery attempts before a task fails. Tasks can override it.
        min_backoff_seconds:
          type: number
          format: double
          minimum: 0
          default: 2
        max_backoff_seconds:
          type: number
          format: double
          minimum: 0
          default: 3600
        backoff_multiplier:
          type: number
          format: double
          minimum: 1
          default: 2
          description: |
            Retry n waits a random time between `min_backoff_seconds` and
            `min_backoff_seconds * backoff_multiplier^(n-1)`, capped at
            `max_backoff_seconds`. `Retry-After` response headers are honoured.
        timeout_seconds:
          type: number
          format: double
          minimum: 1
          maximum: 1800
          default: 30
          description: How long to wait for a response. Tasks can override it.
        retry_on_4xx:
          type: boolean
          default: false
          description: |
            Retry 4xx responses. By default only 408 and 429 are retried, as
            other client errors usually fail again.
        rate_per_second:
          type: number
          format: double
          minimum: 0
          exclusiveMinimum: true
          maximum: 10000
          description: |
            Most deliveries started per second. Omit for no limit. Retries
            count; recovering a lost attempt does too. Deliveries are spread
            out evenly: after an idle spell, at most a tenth of a second's
            worth (at least 1) start at once.
        max_concurrency:
          type: integer
          minimum: 1
          maximum: 10000
          default: 3
          description: |
            Most deliveries in flight at once. There is always a limit; the
            default is low so a new queue can't overwhelm its endpoint.
        auto_pause:
          $ref: "#/components/schemas/AutoPauseConfig"
    AutoPauseConfig:
      type: object
      description: |
        Pause the queue by itself when its endpoint looks down: after
        `after_failures` attempts in a row end with a 5xx, a timeout or a
        network error. Other 4xx responses, 429 and lost attempts don't
        count, and only a success resets the count. While auto-paused, tasks
        wait without using attempts, and one task at a time goes as a probe:
        30 seconds after the pause, then after twice as long each time it
        fails, up to every 10 minutes. The first success resumes the queue.
        Resuming it by hand does too. Omit for no auto-pause. Not for queues
        whose tasks go to many endpoints, where one being down would hold up
        the rest; Workly's own queues can't have it.
      required: [after_failures]
      properties:
        after_failures:
          type: integer
          minimum: 1
          maximum: 10000
    AutoPaused:
      type: object
      description: |
        The queue paused itself after failures in a row (see `auto_pause`).
        Absent when it hasn't, or once it resumed.
      required: [since, error, probes, next_probe_at]
      properties:
        since:
          type: string
          format: date-time
          description: When it paused.
        error:
          type: string
          description: The error of the attempt that paused it, or of the latest failed probe.
        probes:
          type: integer
          description: Probes that failed since it paused.
        next_probe_at:
          type: string
          format: date-time
          description: |
            When the next probe goes, unless one is in flight, in which case
            its result sets the next. No probes go while the queue is also
            paused by hand.
    Queue:
      allOf:
        - $ref: "#/components/schemas/QueueConfig"
        - type: object
          required: [name, paused, max_attempts, min_backoff_seconds, max_backoff_seconds, backoff_multiplier, timeout_seconds, retry_on_4xx, max_concurrency, created_at, updated_at]
          properties:
            name:
              type: string
            paused:
              type: boolean
              description: Paused by hand. See `auto_paused` for a pause the queue made itself.
            auto_paused:
              $ref: "#/components/schemas/AutoPaused"
            stats:
              $ref: "#/components/schemas/QueueStats"
            created_at:
              type: string
              format: date-time
            updated_at:
              type: string
              format: date-time
    QueueStats:
      type: object
      description: |
        The queue's current work. Returned when getting or listing queues.
        Counts stop at 10,000, so 10000 means "10,000 or more".
      required: [due, scheduled, running, failed]
      properties:
        due:
          type: integer
          description: Pending tasks that are due now.
        scheduled:
          type: integer
          description: Pending tasks due later, including ones waiting to retry.
        running:
          type: integer
          description: Tasks with a delivery in flight.
        failed:
          type: integer
          description: |
            Failed tasks still retained (see `WORKLY_RETENTION`). Retry them
            with `POST /v1/queues/{queue}/retry-failed`.
        oldest_due_at:
          type: string
          format: date-time
          description: |
            When the longest-waiting due task became due, i.e. how far behind
            the queue is. Absent when nothing is due.
    QueueActivity:
      type: object
      description: Counts stop at 10,000, so 10000 means "10,000 or more".
      required: [since, succeeded, failed, cancelled, duration_samples]
      properties:
        since:
          type: string
          format: date-time
          description: The start of the period counted.
        succeeded:
          type: integer
        failed:
          type: integer
        cancelled:
          type: integer
        duration_samples:
          type: integer
          description: |
            How many latest attempts with a recorded duration the percentiles
            are taken over (at most 2,000). 0 when there are no percentiles.
        p50_duration_ms:
          type: integer
          description: |
            Median duration of the latest attempt of the succeeded and failed
            tasks counted (at most the last 1,000 of each). Absent if none
            has one.
        p95_duration_ms:
          type: integer
          description: 95th percentile of the same durations.
        retention_seconds:
          type: number
          format: double
          description: |
            How long the server keeps finished tasks (`WORKLY_RETENTION`).
            Absent if it keeps them forever.
    Activity:
      type: object
      required: [range, bucket_seconds, buckets]
      properties:
        range:
          type: string
          enum: [1h, 24h, 7d]
        bucket_seconds:
          type: integer
        buckets:
          type: array
          items:
            $ref: "#/components/schemas/ActivityBucket"
        retention_seconds:
          type: number
          format: double
          description: |
            How long the server keeps finished tasks (`WORKLY_RETENTION`).
            Absent if it keeps them forever.
    ActivityBucket:
      type: object
      required: [start, counts, succeeded, failed]
      properties:
        start:
          type: string
          format: date-time
        counts:
          type: object
          description: Tasks created in the bucket, by queue; queues with none are left out.
          additionalProperties:
            type: integer
        succeeded:
          type: integer
          description: Tasks of every queue that finished in the bucket and succeeded.
        failed:
          type: integer
          description: Tasks of every queue that finished in the bucket and failed.
    CronPreview:
      type: object
      required: [next_runs, interval_seconds]
      properties:
        next_runs:
          type: array
          description: The next 5 runs, from now.
          items:
            type: string
            format: date-time
        interval_seconds:
          type: integer
          description: The shortest time between two of its runs.
        spans:
          type: array
          description: |
            With `from` and `until`: every run in the window, earliest first,
            as runs at a fixed interval, so a schedule running every minute is
            one span rather than thousands of times.
          items:
            $ref: "#/components/schemas/CronSpan"
    CronSpan:
      type: object
      description: "`count` runs, `every_seconds` apart, the first at `start`."
      required: [start, every_seconds, count]
      properties:
        start:
          type: string
          format: date-time
        every_seconds:
          type: integer
          description: 0 when `count` is 1.
        count:
          type: integer
    QueueFailures:
      type: object
      required: [groups]
      properties:
        groups:
          type: array
          items:
            $ref: "#/components/schemas/FailureGroup"
    FailureGroup:
      type: object
      description: Failed tasks whose latest attempt ended the same way.
      required: [error, count, last_failed_at, latest_task_id]
      properties:
        outcome:
          $ref: "#/components/schemas/Outcome"
        status_code:
          type: integer
          description: Absent if there was no response.
        error:
          type: string
          description: The tasks' `last_error`. Pass it as `last_error` to list or retry them.
        count:
          type: integer
        last_failed_at:
          type: string
          format: date-time
        latest_task_id:
          type: string
          description: The most recently failed task in the group.
        response_body:
          type: string
          description: The start (500 bytes) of the latest task's last response body, if it had one.
    QueueList:
      type: object
      required: [queues]
      properties:
        queues:
          type: array
          items:
            $ref: "#/components/schemas/Queue"
    CancelPendingResult:
      type: object
      required: [cancelled]
      properties:
        cancelled:
          type: integer
          description: How many pending tasks were cancelled.
    RetryFailedResult:
      type: object
      required: [retried]
      properties:
        retried:
          type: integer
          description: How many failed tasks were made pending again.
    HTTPMethod:
      type: string
      enum: [GET, POST, PUT, PATCH, DELETE]
    TaskState:
      type: string
      enum: [pending, running, succeeded, failed, cancelled]
      description: |
        A `pending` task with `run_at` in the future is scheduled. A `failed`
        task has exhausted its attempts or got a non-retryable response.
    Outcome:
      type: string
      enum: [success, http_error, timeout, network_error, lost]
      description: |
        How a delivery attempt ended. `lost` means the result is unknown: the
        dispatcher crashed or shut down mid-delivery, and the endpoint may
        have processed the request.
    EnqueueRequest:
      type: object
      required: [url]
      properties:
        url:
          type: string
          description: The http(s) URL to deliver the task to.
          example: https://api.example.com/send-email
        method:
          $ref: "#/components/schemas/HTTPMethod"
        headers:
          type: object
          additionalProperties:
            type: string
          description: Headers sent with every delivery. `Workly-*` headers are reserved.
        payload:
          description: "A JSON body, sent with `Content-Type: application/json`. Use this or `body`."
          x-go-type: json.RawMessage
        body:
          type: string
          description: A raw text body. Use this or `payload`.
        content_type:
          type: string
          description: Content type of `body`. Defaults to `text/plain; charset=utf-8`.
        delay_seconds:
          type: number
          format: double
          minimum: 0
          description: Deliver after this delay. Use this or `run_at`.
        run_at:
          type: string
          format: date-time
          description: Deliver at this time. Use this or `delay_seconds`.
        idempotency_key:
          type: string
          maxLength: 256
          description: Deduplicates enqueues within the queue.
        max_attempts:
          type: integer
          minimum: 1
          maximum: 1000
          description: Overrides the queue's `max_attempts`.
        timeout_seconds:
          type: number
          format: double
          minimum: 1
          maximum: 1800
          description: Overrides the queue's `timeout_seconds`.
        group_id:
          type: string
          description: |
            Adds the task to this group, which must be open (`group_closed`
            otherwise). A task enqueued again with the same
            `idempotency_key` isn't added twice.
        on_complete:
          $ref: "#/components/schemas/Callback"
    BatchEnqueueRequest:
      type: object
      required: [tasks]
      properties:
        tasks:
          type: array
          minItems: 1
          maxItems: 100
          items:
            $ref: "#/components/schemas/EnqueueRequest"
    BatchEnqueueResponse:
      type: object
      required: [results]
      properties:
        results:
          type: array
          items:
            $ref: "#/components/schemas/BatchEnqueueResult"
    BatchEnqueueResult:
      type: object
      required: [created, task]
      properties:
        created:
          type: boolean
          description: False if a task with the same idempotency key already existed.
        task:
          $ref: "#/components/schemas/Task"
    Task:
      type: object
      required: [id, queue, state, method, url, headers, run_at, attempt_count, created_at, updated_at]
      properties:
        id:
          type: string
          example: task_01J9ZK3M5Q8R2T4V6W8X0Y2Z4A
        queue:
          type: string
        state:
          $ref: "#/components/schemas/TaskState"
        method:
          $ref: "#/components/schemas/HTTPMethod"
        url:
          type: string
        headers:
          type: object
          additionalProperties:
            type: string
        payload:
          description: The body, when it is JSON.
          x-go-type: json.RawMessage
        body:
          type: string
          description: The body, when it is not JSON.
        run_at:
          type: string
          format: date-time
          description: When the task is next eligible for delivery.
        attempt_count:
          type: integer
        max_attempts:
          type: integer
          description: Per-task override, if set.
        timeout_seconds:
          type: number
          format: double
          description: Per-task override, if set.
        idempotency_key:
          type: string
        last_status:
          type: integer
          description: HTTP status of the latest attempt, if it got a response.
        last_outcome:
          $ref: "#/components/schemas/Outcome"
        last_error:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        finished_at:
          type: string
          format: date-time
          description: When the task succeeded, failed or was cancelled.
        last_attempt_at:
          type: string
          format: date-time
          description: When the latest attempt finished. Absent before the first attempt.
        started_at:
          type: string
          format: date-time
          description: |
            When the first delivery attempt started; `started_at` minus
            `created_at` is how long the task waited in the queue. Retries by
            hand don't change it. Absent before the first attempt.
        last_duration_ms:
          type: integer
          description: How long the latest finished attempt took. Absent before the first attempt finishes.
        retried_at:
          type: string
          format: date-time
          description: |
            When the task was last retried by hand (`POST /v1/tasks/{id}/retry`
            or `POST /v1/queues/{queue}/retry-failed`). Absent if never.
        group_id:
          type: string
          description: The group the task belongs to, if any.
        on_complete:
          $ref: "#/components/schemas/Callback"
        callback_task_id:
          type: string
          description: The callback task enqueued when the task last finished, if it has `on_complete`.
        workflow_step:
          $ref: "#/components/schemas/TaskWorkflowStep"
    TaskWorkflowStep:
      type: object
      description: |
        The workflow step a task delivers, if it is one. A step's task can't be
        retried on its own: retry its workflow run instead.
      required: [id, name, workflow, run_id]
      properties:
        id:
          type: string
          description: The step, `wfs_…`.
          example: wfs_01M7AH8EPATE4EPK37FWTA5TBQ
        name:
          type: string
          description: The step's name in its workflow.
        workflow:
          type: string
        run_id:
          type: string
          description: The workflow run, `wfr_…`.
          example: wfr_01M7AH8EP90ZQ4E9228337GGVR
    TaskSummary:
      type: object
      description: The body of a task's callback.
      required: [task_id, queue, state, attempt_count, finished_at]
      properties:
        task_id:
          type: string
        queue:
          type: string
        state:
          $ref: "#/components/schemas/TaskState"
        attempt_count:
          type: integer
        last_status:
          type: integer
          description: HTTP status of the latest attempt, if it got a response.
        last_outcome:
          $ref: "#/components/schemas/Outcome"
        last_error:
          type: string
        idempotency_key:
          type: string
        group_id:
          type: string
        finished_at:
          type: string
          format: date-time
    Delivery:
      type: object
      required: [method, url, headers, body]
      properties:
        method:
          $ref: "#/components/schemas/HTTPMethod"
        url:
          type: string
        headers:
          type: object
          description: Every header Workly sets, including the task's own.
          additionalProperties:
            type: string
        body:
          type: string
          description: The body exactly as sent; the signature covers these bytes.
    TaskList:
      type: object
      required: [tasks]
      properties:
        tasks:
          type: array
          items:
            $ref: "#/components/schemas/Task"
        next_cursor:
          type: string
          description: Pass as `cursor` to get the next page. Absent on the last page.
    Attempt:
      type: object
      required: [id, number, started_at, finished_at, duration_ms, outcome, response_headers]
      properties:
        id:
          type: string
        number:
          type: integer
        started_at:
          type: string
          format: date-time
        finished_at:
          type: string
          format: date-time
        duration_ms:
          type: integer
        status_code:
          type: integer
          description: Absent if there was no response.
        outcome:
          $ref: "#/components/schemas/Outcome"
        error:
          type: string
        response_body:
          type: string
          description: The first 4 KB of the response body.
        response_headers:
          type: object
          additionalProperties:
            type: string
          description: Selected response headers (Content-Type, Retry-After, Location).
        retried_at:
          type: string
          format: date-time
          description: |
            Set when the task or run was retried by hand between the previous
            attempt and this one: when that happened. Absent for automatic
            retries.
    AttemptList:
      type: object
      required: [attempts]
      properties:
        attempts:
          type: array
          items:
            $ref: "#/components/schemas/Attempt"
    GroupStatus:
      type: string
      enum: [open, running, succeeded, failed]
      description: |
        `open`: accepting tasks. `running`: closed, with tasks still to
        finish. `succeeded`: every task succeeded. `failed`: every task
        finished and at least one failed or was cancelled. Completed groups
        (`succeeded` and `failed`) don't change again, even if a task in
        them is retried.
    Callback:
      type: object
      required: [url]
      description: |
        A task Workly enqueues when something completes: a `POST` to `url`
        whose JSON body says what completed (`TaskSummary` for a task,
        `RunSummary` for a schedule's run, `GroupSummary` for a group).
        Callbacks go to `_callbacks`, a queue Workly creates for them,
        and are delivered like any task in it, with its retries; its
        settings can be changed like any queue's.

        A task's or a schedule's callback is called each time the task or
        a run succeeds, fails or is cancelled, and again if it is retried
        by hand and finishes again; skipped runs don't call it. A group's
        is called once, when the group completes.
      properties:
        url:
          type: string
          description: The http(s) URL to deliver the callback to.
          example: https://api.example.com/jobs/refresh-views
        headers:
          type: object
          additionalProperties:
            type: string
          description: Headers sent with the callback. `Workly-*` headers are reserved.
    GroupSummary:
      type: object
      description: The body of a group's callback.
      required: [group_id, status, total, succeeded, failed, cancelled]
      properties:
        group_id:
          type: string
        name:
          type: string
        status:
          $ref: "#/components/schemas/GroupStatus"
        total:
          type: integer
        succeeded:
          type: integer
        failed:
          type: integer
        cancelled:
          type: integer
    NewGroup:
      type: object
      properties:
        name:
          type: string
          maxLength: 256
          description: A label, e.g. the job the group is one run of. Names needn't be unique.
          example: daily-stock-prices
        idempotency_key:
          type: string
          maxLength: 256
          description: Deduplicates group creation within the workspace.
        on_complete:
          $ref: "#/components/schemas/Callback"
    Group:
      type: object
      required: [id, status, total, succeeded, failed, cancelled, remaining, created_at]
      properties:
        id:
          type: string
          example: grp_01J9ZK3M5Q8R2T4V6W8X0Y2Z4A
        name:
          type: string
        status:
          $ref: "#/components/schemas/GroupStatus"
        idempotency_key:
          type: string
        total:
          type: integer
          description: Tasks enqueued into the group (less those whose queue was deleted).
        succeeded:
          type: integer
        failed:
          type: integer
        cancelled:
          type: integer
        remaining:
          type: integer
          description: Tasks still pending or running.
        on_complete:
          $ref: "#/components/schemas/Callback"
        callback_task_id:
          type: string
          description: The callback task, once the group has completed.
        created_at:
          type: string
          format: date-time
        closed_at:
          type: string
          format: date-time
        finished_at:
          type: string
          format: date-time
          description: When the group completed.
    GroupList:
      type: object
      required: [groups]
      properties:
        groups:
          type: array
          items:
            $ref: "#/components/schemas/Group"
        next_cursor:
          type: string
          description: Pass as `cursor` to get the next page. Absent on the last page.
    ScheduleConfig:
      type: object
      description: |
        A schedule's settings. Omitted fields take the default. The request
        fields (`url` to `content_type`) work as in `EnqueueRequest`. Set
        `url` to call an endpoint, or `workflow` to start a run of that
        workflow instead.
      required: [cron]
      properties:
        cron:
          type: string
          description: |
            When to run: five fields (minute, hour, day of month, month, day
            of week) with `*`, lists, ranges, steps and names (`jan`, `mon`),
            or `@yearly`, `@monthly`, `@weekly`, `@daily` or `@hourly`. When
            both day fields are restricted, a day matches either.
          example: "0 3 * * *"
        timezone:
          type: string
          default: UTC
          description: |
            IANA timezone the cron expression is read in, e.g.
            `Europe/Stockholm`. A slot in the hour skipped by a daylight
            saving change runs right after it; a slot in a repeated hour runs
            once.
        url:
          type: string
          description: The http(s) URL to call. Use this or `workflow`.
          example: https://api.example.com/reports/nightly
        workflow:
          type: string
          description: |
            A workflow to start a run of instead of calling a URL. The
            `payload`, if any, is the run's `input`; `method`, `headers` and
            `body` don't apply. Each run's attempt starts the workflow run
            (`workflow_run_id`), which then goes on independently: the run
            succeeding means the workflow started, not that it succeeded.
          example: daily-refresh
        method:
          $ref: "#/components/schemas/HTTPMethod"
        headers:
          type: object
          additionalProperties:
            type: string
          description: Headers sent with every run. `Workly-*` headers are reserved.
        payload:
          description: "A JSON body, sent with `Content-Type: application/json`. Use this or `body`."
          x-go-type: json.RawMessage
        body:
          type: string
          description: A raw text body. Use this or `payload`.
        content_type:
          type: string
          description: Content type of `body`. Defaults to `text/plain; charset=utf-8`.
        timeout_seconds:
          type: number
          format: double
          minimum: 1
          maximum: 1800
          default: 30
          description: How long to wait for a response.
        max_attempts:
          type: integer
          minimum: 1
          maximum: 1000
          default: 3
          description: Total delivery attempts before a run fails.
        min_backoff_seconds:
          type: number
          format: double
          minimum: 0
          default: 5
        max_backoff_seconds:
          type: number
          format: double
          minimum: 0
          default: 300
        backoff_multiplier:
          type: number
          format: double
          minimum: 1
          default: 2
          description: Retries back off as for queues (see `QueueConfig`).
        retry_on_4xx:
          type: boolean
          default: false
          description: Retry 4xx responses. By default only 408 and 429 are retried.
        overlap:
          $ref: "#/components/schemas/OverlapPolicy"
        missed:
          $ref: "#/components/schemas/MissedPolicy"
        on_complete:
          $ref: "#/components/schemas/Callback"
    OverlapPolicy:
      type: string
      enum: [skip, allow]
      default: skip
      description: |
        What happens when a slot comes up while the previous run is still
        pending or running, or, for a schedule with `workflow`, while the
        workflow run it started is still running. `skip` records the slot as
        a `skipped` run; `allow` runs it alongside.
    MissedPolicy:
      type: string
      enum: [skip, catch_up]
      default: skip
      description: |
        What happens to slots missed while the server was down (a slot is
        missed if it can't fire within a minute). `skip` records the most
        recent missed slot as a `skipped` run; `catch_up` runs it. Either
        way, at most one run is created for the missed slots.
    Schedule:
      type: object
      required: [name, cron, timezone, method, url, headers, timeout_seconds, max_attempts, min_backoff_seconds, max_backoff_seconds, backoff_multiplier, retry_on_4xx, overlap, missed, paused, next_runs, created_at, updated_at]
      properties:
        name:
          type: string
        workflow:
          type: string
          description: The workflow each run starts, for a schedule that starts one. `url` is then empty.
        cron:
          type: string
        timezone:
          type: string
        method:
          $ref: "#/components/schemas/HTTPMethod"
        url:
          type: string
        headers:
          type: object
          additionalProperties:
            type: string
        payload:
          description: The body, when it is JSON.
          x-go-type: json.RawMessage
        body:
          type: string
          description: The body, when it is not JSON.
        timeout_seconds:
          type: number
          format: double
        max_attempts:
          type: integer
        min_backoff_seconds:
          type: number
          format: double
        max_backoff_seconds:
          type: number
          format: double
        backoff_multiplier:
          type: number
          format: double
        retry_on_4xx:
          type: boolean
        overlap:
          $ref: "#/components/schemas/OverlapPolicy"
        missed:
          $ref: "#/components/schemas/MissedPolicy"
        paused:
          type: boolean
        paused_at:
          type: string
          format: date-time
          description: |
            When a paused schedule was paused. Absent while it runs.
        next_run_at:
          type: string
          format: date-time
          description: When the schedule next fires. Absent while paused.
        next_runs:
          type: array
          description: The next five slots. Empty while paused; see `next_runs_if_resumed`.
          items:
            type: string
            format: date-time
        next_runs_if_resumed:
          type: array
          description: |
            While paused, the five slots the schedule would run at if resumed
            now, to check its cron expression. Absent while it runs.
          items:
            type: string
            format: date-time
        last_run:
          $ref: "#/components/schemas/LastRun"
        on_complete:
          $ref: "#/components/schemas/Callback"
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    LastRun:
      type: object
      description: The schedule's most recent run. Absent before the first.
      required: [id, state, trigger, scheduled_for]
      properties:
        id:
          type: string
        state:
          $ref: "#/components/schemas/RunState"
        trigger:
          $ref: "#/components/schemas/RunTrigger"
        scheduled_for:
          type: string
          format: date-time
        finished_at:
          type: string
          format: date-time
        last_status:
          type: integer
        last_error:
          type: string
        workflow_run_id:
          type: string
          description: The workflow run it started, for a schedule that starts a workflow.
        workflow_run_status:
          $ref: "#/components/schemas/WorkflowRunStatus"
          description: That workflow run's status, now.
    ScheduleList:
      type: object
      required: [schedules]
      properties:
        schedules:
          type: array
          items:
            $ref: "#/components/schemas/Schedule"
    RunState:
      type: string
      enum: [pending, running, succeeded, failed, cancelled, skipped]
      description: |
        A `skipped` run was never delivered: see `skip_reason`. It can be
        retried to deliver it now.
    RunTrigger:
      type: string
      enum: [schedule, manual]
      description: "`schedule` for a cron slot, `manual` for \"run now\"."
    SkipReason:
      type: string
      enum: [overlap, missed]
      description: |
        `overlap`: the previous run, or the workflow run it started, was
        still going (overlap policy `skip`). `missed`: the server was down at the slot (missed
        policy `skip`).
    Run:
      type: object
      required: [id, schedule, state, trigger, scheduled_for, method, url, headers, run_at, attempt_count, created_at, updated_at]
      properties:
        id:
          type: string
          example: run_01J9ZK3M5Q8R2T4V6W8X0Y2Z4A
        schedule:
          type: string
        workflow_run_id:
          type: string
          description: The workflow run this run started, for a schedule that starts a workflow.
        workflow_run_status:
          $ref: "#/components/schemas/WorkflowRunStatus"
          description: |
            The status of the workflow run in `workflow_run_id`, now. The run
            itself succeeds once it has started the workflow run, so this says
            whether the workflow is still going or how it ended.
        state:
          $ref: "#/components/schemas/RunState"
        trigger:
          $ref: "#/components/schemas/RunTrigger"
        scheduled_for:
          type: string
          format: date-time
          description: The cron slot, or when a manual run was triggered. Sent as `Workly-Scheduled-For`.
        skip_reason:
          $ref: "#/components/schemas/SkipReason"
        method:
          $ref: "#/components/schemas/HTTPMethod"
        url:
          type: string
        headers:
          type: object
          additionalProperties:
            type: string
        payload:
          description: The body, when it is JSON.
          x-go-type: json.RawMessage
        body:
          type: string
          description: The body, when it is not JSON.
        run_at:
          type: string
          format: date-time
          description: When the run is next eligible for delivery.
        attempt_count:
          type: integer
        last_status:
          type: integer
          description: HTTP status of the latest attempt, if it got a response.
        last_outcome:
          $ref: "#/components/schemas/Outcome"
        last_error:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        finished_at:
          type: string
          format: date-time
          description: When the run succeeded, failed, was cancelled or was skipped.
        last_attempt_at:
          type: string
          format: date-time
        started_at:
          type: string
          format: date-time
          description: When the first delivery attempt started. Retries by hand don't change it. Absent before the first attempt.
        last_duration_ms:
          type: integer
          description: How long the latest finished attempt took. Absent before the first attempt finishes.
        retried_at:
          type: string
          format: date-time
          description: When the run was last retried by hand. Absent if never.
        callback_task_id:
          type: string
          description: The callback task enqueued when the run last finished, if its schedule has `on_complete`.
        callback_state:
          $ref: "#/components/schemas/TaskState"
          description: |
            The state of the task in `callback_task_id`, now: whether the
            callback has been delivered. Absent without a callback task, or
            once retention has removed it.
    RunSummary:
      type: object
      description: The body of a schedule's callback.
      required: [run_id, schedule, state, trigger, scheduled_for, attempt_count, finished_at]
      properties:
        run_id:
          type: string
        schedule:
          type: string
        state:
          $ref: "#/components/schemas/RunState"
        trigger:
          $ref: "#/components/schemas/RunTrigger"
        scheduled_for:
          type: string
          format: date-time
        attempt_count:
          type: integer
        last_status:
          type: integer
        last_outcome:
          $ref: "#/components/schemas/Outcome"
        last_error:
          type: string
        finished_at:
          type: string
          format: date-time
    RunList:
      type: object
      required: [runs]
      properties:
        runs:
          type: array
          items:
            $ref: "#/components/schemas/Run"
        next_cursor:
          type: string
          description: Pass as `cursor` to get the next page. Absent on the last page.
    WorkflowStepConfig:
      type: object
      description: |
        A step: an HTTP request, sent as a task once every step in
        `depends_on` has succeeded. The request fields (`url` to
        `content_type`) work as in `EnqueueRequest`. A step without `payload`
        or `body` is sent the run's context as JSON (`workflow_run_id`,
        `workflow`, `step`, `step_id`, `run_attempt`, `input`); every step
        gets the `Workly-Workflow`, `Workly-Workflow-Run-Id`,
        `Workly-Workflow-Step`, `Workly-Workflow-Step-Id` and
        `Workly-Workflow-Run-Attempt` headers. The step ID is the same on
        every delivery of the step, so it can serve as an idempotency key;
        with the run attempt, it keys work that a retried run should redo.
      required: [name, url]
      properties:
        name:
          type: string
          description: Unique within the workflow. Lowercase letters, digits, `-` and `_`; at most 64 characters.
          example: prices
        depends_on:
          type: array
          items:
            type: string
          description: Steps that must succeed before this one starts.
        url:
          type: string
          example: https://api.example.com/jobs/prices
        method:
          $ref: "#/components/schemas/HTTPMethod"
        headers:
          type: object
          additionalProperties:
            type: string
          description: "`Workly-*` headers are reserved."
        payload:
          description: "A JSON body, sent with `Content-Type: application/json`. Use this or `body`."
          x-go-type: json.RawMessage
        body:
          type: string
          description: A raw text body. Use this or `payload`.
        content_type:
          type: string
          description: Content type of `body`. Defaults to `text/plain; charset=utf-8`.
        queue:
          type: string
          default: _workflows
          description: |
            The queue the step's task goes to, for its retry policy, timeout
            and rate and concurrency limits. `_workflows` is created on
            demand; another queue must exist when the step starts.
        timeout_seconds:
          type: number
          format: double
          minimum: 1
          maximum: 1800
          description: Overrides the queue's timeout.
        max_attempts:
          type: integer
          minimum: 1
          maximum: 1000
          description: Overrides the queue's max attempts.
    WorkflowConfig:
      type: object
      required: [steps]
      properties:
        steps:
          type: array
          minItems: 1
          maxItems: 100
          items:
            $ref: "#/components/schemas/WorkflowStepConfig"
          description: The steps, which must form a DAG.
        max_duration_seconds:
          type: number
          format: double
          minimum: 1
          default: 86400
          description: |
            How long a run may take. A run still going after it fails, and a
            step still waiting fails with it.
    Workflow:
      type: object
      required: [name, steps, max_duration_seconds, version, created_at, updated_at]
      properties:
        name:
          type: string
        steps:
          type: array
          items:
            $ref: "#/components/schemas/WorkflowStepConfig"
        max_duration_seconds:
          type: number
          format: double
        version:
          type: integer
          description: Counts changes to the definition, from 1.
        last_run:
          $ref: "#/components/schemas/WorkflowRunSummary"
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    WorkflowList:
      type: object
      required: [workflows]
      properties:
        workflows:
          type: array
          items:
            $ref: "#/components/schemas/Workflow"
    StartWorkflowRun:
      type: object
      properties:
        input:
          description: JSON passed to every step that has no body of its own.
          x-go-type: json.RawMessage
        idempotency_key:
          type: string
          maxLength: 256
          description: Deduplicates runs of the workflow.
    WorkflowRunStatus:
      type: string
      enum: [running, succeeded, failed, cancelled]
    StepStatus:
      type: string
      description: |
        `blocked` waits for its dependencies; `pending` has its task
        enqueued (or retrying); `running` is being delivered; `waiting`
        succeeded and waits for the resource its response named in
        `Workly-Wait-For`; `skipped` never ran, or stopped waiting, because
        the run stopped.
      enum: [blocked, pending, running, waiting, succeeded, failed, skipped]
    WorkflowRunSummary:
      type: object
      required: [id, workflow, version, status, attempt, created_at]
      properties:
        id:
          type: string
          example: wfr_01J9ZK3M5Q8R2T4V6W8X0Y2Z4A
        workflow:
          type: string
        version:
          type: integer
        status:
          $ref: "#/components/schemas/WorkflowRunStatus"
        error:
          type: string
          description: Why the run failed or was cancelled.
        idempotency_key:
          type: string
        schedule_run_id:
          type: string
          description: The schedule run that started it, if any.
        attempt:
          type: integer
          description: |
            1, plus one for each time the run was retried. Steps are sent it
            as `Workly-Workflow-Run-Attempt`.
        retried_at:
          type: string
          format: date-time
          description: When the run was last retried. Absent if never.
        created_at:
          type: string
          format: date-time
        deadline_at:
          type: string
          format: date-time
          description: When a run still going fails (`max_duration_seconds`).
        finished_at:
          type: string
          format: date-time
        duration_ms:
          type: integer
          description: From start to finish, or to now while running.
    WorkflowRun:
      allOf:
        - $ref: "#/components/schemas/WorkflowRunSummary"
        - type: object
          required: [steps]
          properties:
            input:
              x-go-type: json.RawMessage
            steps:
              type: array
              items:
                $ref: "#/components/schemas/WorkflowStep"
              description: In definition order.
    WorkflowRunList:
      type: object
      required: [workflow_runs]
      properties:
        workflow_runs:
          type: array
          items:
            $ref: "#/components/schemas/WorkflowRunSummary"
        next_cursor:
          type: string
          description: Pass as `cursor` to get the next page. Absent on the last page.
    WaitFor:
      type: object
      description: The resource a step handed its completion to.
      required: [type, id]
      properties:
        type:
          type: string
          enum: [group]
        id:
          type: string
    WorkflowStepTask:
      type: object
      description: The step's task, which records its attempts.
      required: [id, queue, state, attempt_count]
      properties:
        id:
          type: string
        queue:
          type: string
        state:
          $ref: "#/components/schemas/TaskState"
        attempt_count:
          type: integer
        last_status:
          type: integer
        last_outcome:
          $ref: "#/components/schemas/Outcome"
        last_error:
          type: string
        run_at:
          type: string
          format: date-time
          description: When a pending task is next delivered.
    WorkflowStep:
      type: object
      required: [id, name, status, depends_on, blocked_by]
      properties:
        id:
          type: string
          example: wfs_01J9ZK3M5Q8R2T4V6W8X0Y2Z4A
        name:
          type: string
        status:
          $ref: "#/components/schemas/StepStatus"
        depends_on:
          type: array
          items:
            type: string
        blocked_by:
          type: array
          items:
            type: string
          description: Dependencies that haven't succeeded yet.
        task_id:
          type: string
        task:
          $ref: "#/components/schemas/WorkflowStepTask"
        wait_for:
          $ref: "#/components/schemas/WaitFor"
        error:
          type: string
        created_at:
          type: string
          format: date-time
        ready_at:
          type: string
          format: date-time
          description: When its task was enqueued.
        http_done_at:
          type: string
          format: date-time
          description: When its request succeeded.
        finished_at:
          type: string
          format: date-time
        blocked_ms:
          type: integer
          description: Time spent waiting for dependencies.
        waiting_ms:
          type: integer
          description: Time spent waiting for the `wait_for` resource.
        duration_ms:
          type: integer
          description: From its task being enqueued to the step finishing (or now).
    AlertChannelType:
      type: string
      enum: [email, slack]
    NewAlertChannel:
      type: object
      required: [type, target]
      properties:
        type:
          $ref: "#/components/schemas/AlertChannelType"
        target:
          type: string
          description: An email address, or a Slack incoming webhook URL.
          example: oncall@example.com
    AlertChannel:
      type: object
      required: [id, type, target, created_at]
      properties:
        id:
          type: string
          example: ach_01J9ZK3M5Q8R2T4V6W8X0Y2Z4A
        type:
          $ref: "#/components/schemas/AlertChannelType"
        target:
          type: string
          description: |
            The email address, or the Slack webhook URL with its secret part
            hidden.
        created_at:
          type: string
          format: date-time
    AlertChannelList:
      type: object
      required: [channels, email_enabled]
      properties:
        channels:
          type: array
          items:
            $ref: "#/components/schemas/AlertChannel"
        email_enabled:
          type: boolean
          description: Whether this server can send email, so email channels can be added.
    Error:
      type: object
      required: [error]
      properties:
        error:
          $ref: "#/components/schemas/ErrorBody"
    ErrorBody:
      type: object
      required: [code, message]
      properties:
        code:
          type: string
          description: Stable, machine-readable error code.
          example: queue_not_found
        message:
          type: string
          description: Human-readable description.
