Laravel Scheduled Jobs API

openapi: 3.2.0
info:
  title: Forge Scheduled Jobs API
  version: 0.0.1
  description: Laravel Forge - API Documentation
servers:
- url: https://forge.laravel.com/api
security:
- http: []
- oauth2: []
tags:
- name: Scheduled Jobs
paths:
  /orgs/{organization}/servers/{server}/scheduled-jobs:
    get:
      operationId: organizations.servers.scheduled-jobs.index
      description: 'List all scheduled jobs associated with the server.


        Processing mode: sync'
      summary: List server scheduled jobs
      tags:
      - Scheduled Jobs
      parameters:
      - name: organization
        in: path
        required: true
        description: The organization slug
        schema:
          type: string
      - name: server
        in: path
        required: true
        description: The server ID
        schema:
          type: integer
      - name: page[size]
        in: query
        description: The number of results that will be returned per page.
        schema:
          type: integer
          default: 30
      - name: page[cursor]
        in: query
        description: The cursor to start the pagination from.
        schema:
          type: string
      - name: filter[status]
        in: query
        schema:
          type: string
      - name: filter[user]
        in: query
        schema:
          type: string
      - name: sort
        in: query
        schema:
          type: array
          items:
            type: string
            enum:
            - created_at
            - -created_at
            - updated_at
            - -updated_at
            - status
            - -status
        explode: false
      responses:
        '200':
          description: Paginated set of `JobResource`
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/JobResource'
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                      last:
                        type: string
                      prev:
                        type: string
                      next:
                        type: string
                  meta:
                    type: object
                    properties:
                      path:
                        type:
                        - string
                        - 'null'
                        description: Base path for paginator generated URLs.
                      per_page:
                        type: integer
                        description: Number of items shown per page.
                        minimum: 0
                      next_cursor:
                        type:
                        - string
                        - 'null'
                        description: The "cursor" that points to the next set of items.
                      prev_cursor:
                        type:
                        - string
                        - 'null'
                        description: The "cursor" that points to the previous set of items.
                    required:
                    - path
                    - per_page
                    - next_cursor
                    - prev_cursor
                required:
                - data
                - links
                - meta
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
      security:
      - oauth2:
        - server:view
      x-permissions:
      - server:view
      x-mint:
        metadata:
          noindex: true
      x-processingMode: sync
    post:
      operationId: organizations.servers.scheduled-jobs.store
      description: 'Create a specific scheduled job.


        Processing mode: async'
      summary: Create scheduled job
      tags:
      - Scheduled Jobs
      parameters:
      - name: organization
        in: path
        required: true
        description: The organization slug
        schema:
          type: string
      - name: server
        in: path
        required: true
        description: The server ID
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateScheduledJobRequest'
      responses:
        '202':
          description: '`JobResource`'
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/JobResource'
                required:
                - data
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
      security:
      - oauth2:
        - server:view
      x-permissions:
      - server:view
      x-mint:
        metadata:
          noindex: true
      x-processingMode: async
  /orgs/{organization}/servers/{server}/scheduled-jobs/{job}:
    get:
      operationId: organizations.servers.scheduled-jobs.show
      description: 'Show a specific scheduled job.


        Processing mode: sync'
      summary: Get scheduled job
      tags:
      - Scheduled Jobs
      parameters:
      - name: organization
        in: path
        required: true
        description: The organization slug
        schema:
          type: string
      - name: server
        in: path
        required: true
        description: The server ID
        schema:
          type: integer
      - name: job
        in: path
        required: true
        description: The job ID
        schema:
          type: integer
      responses:
        '200':
          description: '`JobResource`'
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/JobResource'
                required:
                - data
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
      security:
      - oauth2:
        - server:view
      x-permissions:
      - server:view
      x-mint:
        metadata:
          noindex: true
      x-processingMode: sync
    delete:
      operationId: organizations.servers.scheduled-jobs.destroy
      description: 'Delete a specific scheduled job.


        Processing mode: async'
      summary: Delete scheduled job
      tags:
      - Scheduled Jobs
      parameters:
      - name: organization
        in: path
        required: true
        description: The organization slug
        schema:
          type: string
      - name: server
        in: path
        required: true
        description: The server ID
        schema:
          type: integer
      - name: job
        in: path
        required: true
        description: The job ID
        schema:
          type: integer
      responses:
        '202':
          description: Removal of scheduled job from server accepted
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
      security:
      - oauth2:
        - server:view
      x-permissions:
      - server:view
      x-mint:
        metadata:
          noindex: true
      x-processingMode: async
  /orgs/{organization}/servers/{server}/scheduled-jobs/{job}/output:
    get:
      operationId: organizations.servers.scheduled-jobs.outputs.show
      description: 'Show a specific scheduled job output.


        Processing mode: sync'
      summary: Get scheduled job output
      tags:
      - Scheduled Jobs
      parameters:
      - name: organization
        in: path
        required: true
        description: The organization slug
        schema:
          type: string
      - name: server
        in: path
        required: true
        description: The server ID
        schema:
          type: integer
      - name: job
        in: path
        required: true
        description: The job ID
        schema:
          type: integer
      responses:
        '200':
          description: '`JobOutputResource`'
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/JobOutputResource'
                required:
                - data
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
      security:
      - oauth2:
        - server:view
      x-permissions:
      - server:view
      x-mint:
        metadata:
          noindex: true
      x-processingMode: sync
  /orgs/{organization}/servers/{server}/sites/{site}/scheduled-jobs:
    get:
      operationId: organizations.servers.sites.scheduled-jobs.index
      description: 'List all scheduled jobs associated with the site.


        Processing mode: sync'
      summary: List site scheduled jobs
      tags:
      - Scheduled Jobs
      parameters:
      - name: organization
        in: path
        required: true
        description: The organization slug
        schema:
          type: string
      - name: server
        in: path
        required: true
        description: The server ID
        schema:
          type: integer
      - name: site
        in: path
        required: true
        description: The site ID
        schema:
          type: integer
      - name: page[size]
        in: query
        description: The number of results that will be returned per page.
        schema:
          type: integer
          default: 30
      - name: page[cursor]
        in: query
        description: The cursor to start the pagination from.
        schema:
          type: string
      - name: filter[status]
        in: query
        schema:
          type: string
      - name: filter[user]
        in: query
        schema:
          type: string
      - name: sort
        in: query
        schema:
          type: array
          items:
            type: string
            enum:
            - created_at
            - -created_at
            - updated_at
            - -updated_at
            - status
            - -status
        explode: false
      responses:
        '200':
          description: Paginated set of `JobResource`
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/JobResource'
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                      last:
                        type: string
                      prev:
                        type: string
                      next:
                        type: string
                  meta:
                    type: object
                    properties:
                      path:
                        type:
                        - string
                        - 'null'
                        description: Base path for paginator generated URLs.
                      per_page:
                        type: integer
                        description: Number of items shown per page.
                        minimum: 0
                      next_cursor:
                        type:
                        - string
                        - 'null'
                        description: The "cursor" that points to the next set of items.
                      prev_cursor:
                        type:
                        - string
                        - 'null'
                        description: The "cursor" that points to the previous set of items.
                    required:
                    - path
                    - per_page
                    - next_cursor
                    - prev_cursor
                required:
                - data
                - links
                - meta
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
      security:
      - oauth2:
        - server:view
      x-permissions:
      - server:view
      x-mint:
        metadata:
          noindex: true
      x-processingMode: sync
    post:
      operationId: organizations.servers.sites.scheduled-jobs.store
      description: 'Create a specific scheduled job for the site.


        Processing mode: async'
      summary: Create site scheduled job
      tags:
      - Scheduled Jobs
      parameters:
      - name: organization
        in: path
        required: true
        description: The organization slug
        schema:
          type: string
      - name: server
        in: path
        required: true
        description: The server ID
        schema:
          type: integer
      - name: site
        in: path
        required: true
        description: The site ID
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateScheduledJobRequest'
      responses:
        '202':
          description: '`JobResource`'
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/JobResource'
                required:
                - data
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '422':
          $ref: '#/components/responses/ValidationException'
      security:
      - oauth2:
        - server:view
      x-permissions:
      - server:view
      x-mint:
        metadata:
          noindex: true
      x-processingMode: async
  /orgs/{organization}/servers/{server}/sites/{site}/scheduled-jobs/{job}:
    get:
      operationId: organizations.servers.sites.scheduled-jobs.show
      description: 'Show a specific scheduled job.


        Processing mode: sync'
      summary: Get site scheduled job
      tags:
      - Scheduled Jobs
      parameters:
      - name: organization
        in: path
        required: true
        description: The organization slug
        schema:
          type: string
      - name: server
        in: path
        required: true
        description: The server ID
        schema:
          type: integer
      - name: site
        in: path
        required: true
        description: The site ID
        schema:
          type: integer
      - name: job
        in: path
        required: true
        description: The job ID
        schema:
          type: integer
      responses:
        '200':
          description: '`JobResource`'
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/JobResource'
                required:
                - data
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
      security:
      - oauth2:
        - server:view
      x-permissions:
      - server:view
      x-mint:
        metadata:
          noindex: true
      x-processingMode: sync
    delete:
      operationId: organizations.servers.sites.scheduled-jobs.destroy
      description: 'Delete a specific scheduled job associated with the site.


        Processing mode: async'
      summary: Delete site scheduled job
      tags:
      - Scheduled Jobs
      parameters:
      - name: organization
        in: path
        required: true
        description: The organization slug
        schema:
          type: string
      - name: server
        in: path
        required: true
        description: The server ID
        schema:
          type: integer
      - name: site
        in: path
        required: true
        description: The site ID
        schema:
          type: integer
      - name: job
        in: path
        required: true
        description: The job ID
        schema:
          type: integer
      responses:
        '202':
          description: Removal of scheduled job from server accepted
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
      security:
      - oauth2:
        - server:view
      x-permissions:
      - server:view
      x-mint:
        metadata:
          noindex: true
      x-processingMode: async
  /orgs/{organization}/servers/{server}/sites/{site}/scheduled-jobs/{job}/output:
    get:
      operationId: organizations.servers.sites.scheduled-jobs.outputs.show
      description: 'Show a specific scheduled job output associated with the site.


        Processing mode: sync'
      summary: Get site scheduled job output
      tags:
      - Scheduled Jobs
      parameters:
      - name: organization
        in: path
        required: true
        description: The organization slug
        schema:
          type: string
      - name: server
        in: path
        required: true
        description: The server ID
        schema:
          type: integer
      - name: site
        in: path
        required: true
        description: The site ID
        schema:
          type: integer
      - name: job
        in: path
        required: true
        description: The job ID
        schema:
          type: integer
      responses:
        '200':
          description: '`JobOutputResource`'
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/JobOutputResource'
                required:
                - data
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
      security:
      - oauth2:
        - server:view
      x-permissions:
      - server:view
      x-mint:
        metadata:
          noindex: true
      x-processingMode: sync
components:
  responses:
    ValidationException:
      description: Validation error
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                description: Errors overview.
              errors:
                type: object
                description: A detailed description of each field that failed validation.
                additionalProperties:
                  type: array
                  items:
                    type: string
            required:
            - message
            - errors
    AuthorizationException:
      description: Authorization error
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                description: Error overview.
            required:
            - message
    ModelNotFoundException:
      description: Not found
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                description: Error overview.
            required:
            - message
  schemas:
    Link:
      type: object
      properties:
        href:
          type: string
          format: uri
        rel:
          type: string
        describedby:
          type: string
        title:
          type: string
        type:
          type: string
        hreflang:
          anyOf:
          - type: string
          - type: array
            items:
              type: string
        meta:
          type: object
      required:
      - href
      title: Link
    JobOutputResource:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum:
          - scheduledJobOutputs
        attributes:
          type: object
          properties:
            output:
              type: string
          required:
          - output
        links:
          type: object
          properties:
            self:
              $ref: '#/components/schemas/Link'
          required:
          - self
      required:
      - id
      - type
      - links
      title: JobOutputResource
    HeartbeatGracePeriod:
      type: integer
      enum:
      - 1
      - 2
      - 5
      - 10
      - 30
      - 60
      title: HeartbeatGracePeriod
    CreateScheduledJobRequest:
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
          description: The name of the command.
          examples:
          - My scheduled job
        command:
          type: string
          description: The command to run.
          examples:
          - echo $(whoami)
        user:
          type: string
          description: The user to run the scheduled job as.
          examples:
          - root
        frequency:
          description: The frequency of the scheduled job.
          examples:
          - hourly
          $ref: '#/components/schemas/CronFrequency'
        cron:
          type:
          - string
          - 'null'
          description: The cron expression to use for the scheduled job. Only used if frequency is set to Custom.
          examples:
          - 0 * * * *
        heartbeat:
          type:
          - boolean
          - 'null'
          description: Whether a heartbeat should be created for the scheduled job.
          examples:
          - true
        grace_period:
          description: The grace period, in minutes, for the heartbeat.
          examples:
          - 5
          $ref: '#/components/schemas/HeartbeatGracePeriod'
      required:
      - command
      - user
      - frequency
      title: CreateScheduledJobRequest
    JobResource:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum:
          - scheduledJobs
        attributes:
          type: object
          properties:
            name:
              type:
              - string
              - 'null'
            command:
              type: string
            status:
              type: string
            user:
              type: string
            frequency:
              type: string
            cron:
              type: string
            next_run_time:
              type: string
            created_at:
              type:
              - string
              - 'null'
              format: date-time
            updated_at:
              type:
              - string
              - 'null'
              format: date-time
          required:
          - name
          - command
          - status
          - user
          - frequency
          - cron
          - next_run_time
          - created_at
          - updated_at
        links:
          type: object
          properties:
            self:
              $ref: '#/components/schemas/Link'
          required:
          - self
      required:
      - id
      - type
      - links
      title: JobResource
    CronFrequency:
      type: string
      enum:
      - minutely
      - hourly
      - nightly
      - weekly
      - monthly
      - reboot
      - custom
      title: CronFrequency
  securitySchemes:
    http:
      type: http
      scheme: bearer
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://forge.laravel.com/oauth/authorize
          tokenUrl: https://forge.laravel.com/oauth/token
          scopes:
            organization:view: Allow members to view the organization
            organization:manage: Allow members to manage the organization
            organization:delete: Allow members to delete the organization
            server:view: Allow members to view servers
            server:create: Allow members to create servers
            server:delete: Allow members to delete servers
            server:archive: Allow members to archive servers
            server:transfer: Allow members to transfer servers to another Forge account
            server:manage-meta: Allow members to change server settings such as name and IP address
            server:manage-packages: Allow members to configure and remove server and site package authentication
            server:manage-php: Allow members to install and change PHP installations
            server:manage-logs: Allow members to clear server and site logs
            server:manage-network: Allow members to change the server‘s firewall
            server:manage-nginx-templates: Allow members to manage Nginx templates
            server:manage-services: Allow members to start, stop and restart services
            server:manage-password: Allow members to reset the sudo password
            server:create-keys: Allow members to add SSH keys to servers
            server:delete-keys: Allow members to remove SSH keys from servers
            server:create-monitors: Allow members to create server monitors
            server:delete-monitors: Allow members to delete server monitors
            server:create-databases: Allow members to create databases and database users
            server:delete-databases: Allow members to delete databases and database users
            server:create-backups: Allow members to create database backup configurations
            server:delete-backups: Allow members to delete database backup configurations
            server:create-daemons: Allow members to create daemons
            server:delete-daemons: Allow members to delete daemons
            server:create-schedulers: Allow members to create scheduled jobs
            server:delete-schedulers: Allow members to delete scheduled jobs
            server:web-terminal: Allow members to start web terminal sessions
            site:create: Allow members to create sites
            site:delete: Allow members to delete sites
            site:meta: Allow members to update site meta data such as domain name and aliases
            site:manage-commands: Allow members to run arbitrary commands from the site‘s root directory
            site:manage-deploys: Allow members to deploy the site and update the deployment script
            site:manage-nginx: Allow members to manage the site‘s Nginx configuration file
            site:manage-project: Allow members to install Git repositories, phpMyAdmin and WordPress applications
            site:manage-environment: Allow members to update the site‘s environment file
            site:manage-notifications: Allow members to configure deployment notifications
            site:manage-queues: Allow members to configure queue workers
            site:manage-redirects: Allow members to configure URL redirects
            site:manage-security: Allow members to configure HTTP Basic Authentication
            site:manage-ssl: Allow members to configure SSL and Let‘s Encrypt certificates
            site:manage-integrations: Allow members to manage site integrations
            site:manage-heartbeats: Allow members to manage heartbeats
            credential:view: Allow members to view credentials
            credential:manage: Allow members to manage credentials
            team:view: Allow members to view teams
            team:create: Allow members to create teams
            team:delete: Allow members to delete teams and team members
            recipe:view: Allow members to view recipes
            recipe:manage: Allow members to manage recipes
            billing:manage: Allow members to manage the organization's subscription
            storage:manage: Allow members to manage the organization's storage providers.
            integrations:manage: Allow members to manage the organization's integrations
            user:view: Allow members to view user details
            resources:view: Allow members to view resources
            resources:create-databases: Allow members to create managed database & cache clusters
            resources:delete-databases: Allow members to delete managed database & cache clusters
            resources:manage-databases: Allow members to manage managed database & cache clusters settings
            resources:create-buckets: Allow members to create object storage buckets
            resources:delete-buckets: Allow members to delete object storage buckets
            resources:manage-buckets: Allow members to manage object storage buckets and their access keys