openapi: 3.1.0
info:
  title: Loam Jobs API
  version: loam.jobs.v1 (design)
  description: '**Status: Planned.** Nothing on this page runs. It shows the designed `loam.jobs.v1` service
    so you can see where the Celery and BullMQ adapters will sit.


    One Rust core serves queues, leases with fencing tokens, schedules, flows and engine jobs over Connect,
    gRPC and gRPC-Web. Python and TypeScript clients are generated from it, and the adapters are thin
    layers over those clients:


    - **Celery:** a kombu transport (`loam://`) and a Loam result backend; beat entries become server-side
    schedules.

    - **BullMQ v6:** `@loam/bullmq`, a Loam backend behind BullMQ''s own unmodified classes.

    - **PySpark:** a per-namespace Sail server behind `sc://`.

    - **Flink:** Flink SQL on RisingWave; DataStream jobs run unmodified as managed jobs.


    Durable mode is opt-in through Resonate decorators. Jobs need TiKV on self-hosted clusters; `operon
    dev` uses a local file. The port is not decided yet.'
tags:
- name: JobsService
  description: Planned. Design only.
paths:
  /loam.jobs.v1.JobsService/Enqueue:
    post:
      tags:
      - JobsService
      summary: Enqueue
      operationId: Enqueue
      x-badges:
      - name: Planned
        color: '#6b8a98'
      description: 'Add one job to a queue.


        Design only: the protobuf messages are not written yet, so the fields below are the designed Rust
        types and will change.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                queue:
                  description: string
                task:
                  description: 'TaskSpec: name, payload, headers'
                opts:
                  description: 'EnqueueOpts: job_key, idempotency, dedup, not_before, priority, lifo,
                    attempts, backoff, visibility, timeout, expires, parent, retention, mode (queue or
                    durable)'
      responses:
        '200':
          description: Designed response; not final.
          content:
            application/json:
              schema:
                type: object
  /loam.jobs.v1.JobsService/EnqueueBulk:
    post:
      tags:
      - JobsService
      summary: EnqueueBulk
      operationId: EnqueueBulk
      x-badges:
      - name: Planned
        color: '#6b8a98'
      description: 'Add many jobs in one call.


        Design only: the protobuf messages are not written yet, so the fields below are the designed Rust
        types and will change.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                queue:
                  description: string
                jobs:
                  description: array of {task, opts}
      responses:
        '200':
          description: Designed response; not final.
          content:
            application/json:
              schema:
                type: object
  /loam.jobs.v1.JobsService/Lease:
    post:
      tags:
      - JobsService
      summary: Lease
      operationId: Lease
      x-badges:
      - name: Planned
        color: '#6b8a98'
      description: 'Long-poll for up to `max` jobs from one or more queues; each comes with a fencing
        token.


        Design only: the protobuf messages are not written yet, so the fields below are the designed Rust
        types and will change.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                queues:
                  description: array of string
                worker:
                  description: WorkerId
                max:
                  description: integer
                wait:
                  description: duration
                names:
                  description: optional task-name filter
      responses:
        '200':
          description: Designed response; not final.
          content:
            application/json:
              schema:
                type: object
  /loam.jobs.v1.JobsService/Extend:
    post:
      tags:
      - JobsService
      summary: Extend
      operationId: Extend
      x-badges:
      - name: Planned
        color: '#6b8a98'
      description: 'Extend a lease before it expires.


        Design only: the protobuf messages are not written yet, so the fields below are the designed Rust
        types and will change.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                token:
                  description: 'LeaseToken: queue, job, epoch'
                by:
                  description: duration
      responses:
        '200':
          description: Designed response; not final.
          content:
            application/json:
              schema:
                type: object
  /loam.jobs.v1.JobsService/Complete:
    post:
      tags:
      - JobsService
      summary: Complete
      operationId: Complete
      x-badges:
      - name: Planned
        color: '#6b8a98'
      description: 'Record the outcome of a leased job.


        Design only: the protobuf messages are not written yet, so the fields below are the designed Rust
        types and will change.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                token:
                  description: LeaseToken
                outcome:
                  description: Ok, Retry, Fail, Release, Delay, WaitChildren or RateLimited
      responses:
        '200':
          description: Designed response; not final.
          content:
            application/json:
              schema:
                type: object
  /loam.jobs.v1.JobsService/Report:
    post:
      tags:
      - JobsService
      summary: Report
      operationId: Report
      x-badges:
      - name: Planned
        color: '#6b8a98'
      description: 'Report progress or logs for a leased job.


        Design only: the protobuf messages are not written yet, so the fields below are the designed Rust
        types and will change.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                token:
                  description: LeaseToken
                progress:
                  description: object
      responses:
        '200':
          description: Designed response; not final.
          content:
            application/json:
              schema:
                type: object
  /loam.jobs.v1.JobsService/Schedule:
    post:
      tags:
      - JobsService
      summary: Schedule
      operationId: Schedule
      x-badges:
      - name: Planned
        color: '#6b8a98'
      description: 'Create a cron or interval schedule that enqueues a job or starts a durable function.


        Design only: the protobuf messages are not written yet, so the fields below are the designed Rust
        types and will change.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: string
                cron:
                  description: string
                target:
                  description: job template
      responses:
        '200':
          description: Designed response; not final.
          content:
            application/json:
              schema:
                type: object
  /loam.jobs.v1.JobsService/Unschedule:
    post:
      tags:
      - JobsService
      summary: Unschedule
      operationId: Unschedule
      x-badges:
      - name: Planned
        color: '#6b8a98'
      description: 'Delete a schedule.


        Design only: the protobuf messages are not written yet, so the fields below are the designed Rust
        types and will change.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: string
      responses:
        '200':
          description: Designed response; not final.
          content:
            application/json:
              schema:
                type: object
  /loam.jobs.v1.JobsService/Flow:
    post:
      tags:
      - JobsService
      summary: Flow
      operationId: Flow
      x-badges:
      - name: Planned
        color: '#6b8a98'
      description: 'Enqueue a graph of jobs: chain, group, chord or parent and children.


        Design only: the protobuf messages are not written yet, so the fields below are the designed Rust
        types and will change.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                flow:
                  description: job graph
      responses:
        '200':
          description: Designed response; not final.
          content:
            application/json:
              schema:
                type: object
  /loam.jobs.v1.JobsService/SubmitEngineJob:
    post:
      tags:
      - JobsService
      summary: SubmitEngineJob
      operationId: SubmitEngineJob
      x-badges:
      - name: Planned
        color: '#6b8a98'
      description: 'Submit a Spark Connect, streaming SQL or Flink job.


        Design only: the protobuf messages are not written yet, so the fields below are the designed Rust
        types and will change.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                engine:
                  description: sail, risingwave, arroyo or flink
                spec:
                  description: object
      responses:
        '200':
          description: Designed response; not final.
          content:
            application/json:
              schema:
                type: object
  /loam.jobs.v1.JobsService/ControlEngineJob:
    post:
      tags:
      - JobsService
      summary: ControlEngineJob
      operationId: ControlEngineJob
      x-badges:
      - name: Planned
        color: '#6b8a98'
      description: 'Savepoint, upgrade, roll back or stop an engine job.


        Design only: the protobuf messages are not written yet, so the fields below are the designed Rust
        types and will change.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                job:
                  description: string
                action:
                  description: string
      responses:
        '200':
          description: Designed response; not final.
          content:
            application/json:
              schema:
                type: object
  /loam.jobs.v1.JobsService/QueueAdmin:
    post:
      tags:
      - JobsService
      summary: QueueAdmin
      operationId: QueueAdmin
      x-badges:
      - name: Planned
        color: '#6b8a98'
      description: 'Create, configure, pause, resume, drain or delete queues.


        Design only: the protobuf messages are not written yet, so the fields below are the designed Rust
        types and will change.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                queue:
                  description: string
                action:
                  description: string
      responses:
        '200':
          description: Designed response; not final.
          content:
            application/json:
              schema:
                type: object
  /loam.jobs.v1.JobsService/JobAdmin:
    post:
      tags:
      - JobsService
      summary: JobAdmin
      operationId: JobAdmin
      x-badges:
      - name: Planned
        color: '#6b8a98'
      description: 'Inspect, retry, promote or remove jobs.


        Design only: the protobuf messages are not written yet, so the fields below are the designed Rust
        types and will change.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                job:
                  description: string
                action:
                  description: string
      responses:
        '200':
          description: Designed response; not final.
          content:
            application/json:
              schema:
                type: object
  /loam.jobs.v1.JobsService/Query:
    post:
      tags:
      - JobsService
      summary: Query
      operationId: Query
      x-badges:
      - name: Planned
        color: '#6b8a98'
      description: 'List and count jobs by state.


        Design only: the protobuf messages are not written yet, so the fields below are the designed Rust
        types and will change.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                queue:
                  description: string
                state:
                  description: one of the nine job states
      responses:
        '200':
          description: Designed response; not final.
          content:
            application/json:
              schema:
                type: object
  /loam.jobs.v1.JobsService/Watch:
    post:
      tags:
      - JobsService
      summary: Watch
      operationId: Watch
      x-badges:
      - name: Planned
        color: '#6b8a98'
      description: 'Stream queue events (server stream).


        Design only: the protobuf messages are not written yet, so the fields below are the designed Rust
        types and will change.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                queue:
                  description: string
      responses:
        '200':
          description: Designed response; not final.
          content:
            application/json:
              schema:
                type: object