openapi: 3.2.0
info:
  description: Backend API for the Stanford Digital Repository
  version: 1.0.0
  title: DOR Services Workflows API
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://dor-services-{env}.stanford.edu
  description: Production service
  variables:
    env:
      default: prod
- url: https://dor-services-{env}.stanford.edu
  description: Staging service
  variables:
    env:
      default: stage
- url: https://dor-services-{env}.stanford.edu
  description: QA service
  variables:
    env:
      default: qa
security:
- bearerAuth: []
tags:
- name: workflows
  description: Operations about workflows
paths:
  /v1/workflow_templates:
    get:
      tags:
      - workflows
      summary: List all workflow templates
      operationId: workflow_templates#index
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
  /v1/workflow_templates/{id}:
    get:
      tags:
      - workflows
      summary: View a workflow template (e.g., its associated processes)
      operationId: workflow_templates#show
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Workflow template not found for given ID/name
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      parameters:
      - name: id
        in: path
        description: Name of workflow
        required: true
        example: accessionWF
        schema:
          type: string
  /v1/objects/{object_id}/lifecycles:
    get:
      tags:
      - workflows
      summary: List the lifecycles for this object
      operationId: workflow_lifecycles#index
      responses:
        '200':
          description: OK
          content:
            application/xml:
              schema:
                type: string
                example: "<lifecycle objectId=\"druid:ct011cv6501\">\n  <milestone date=\"2010-04-27T11:34:17-0700\">registered</milestone>\n  <milestone date=\"2010-04-29T10:12:51-0700\">inprocess</milestone>\n  <milestone date=\"2010-06-15T16:08:58-0700\">released</milestone>\n</lifecycle>\n"
        '404':
          description: Object not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      parameters:
      - name: object_id
        in: path
        description: ID of object
        required: true
        schema:
          $ref: https://raw.githubusercontent.com/sul-dlss/cocina-models/refs/tags/v0.113.0/schema.json#/$defs/Druid
      - name: version
        in: query
        description: The version of the object to get the lifecycles for
        required: false
        schema:
          type: integer
  /v1/objects/{object_id}/workflows:
    get:
      tags:
      - workflows
      summary: List the workflows for this object
      operationId: workflows#index
      responses:
        '200':
          description: OK
          content:
            application/xml:
              schema:
                type: string
      parameters:
      - name: object_id
        in: path
        description: ID of object
        required: true
        schema:
          $ref: https://raw.githubusercontent.com/sul-dlss/cocina-models/refs/tags/v0.113.0/schema.json#/$defs/Druid
  /v1/objects/{object_id}/workflows/{id}:
    get:
      tags:
      - workflows
      summary: Get the status for a workflow for this object.
      operationId: workflow#show
      responses:
        '200':
          description: OK
          content:
            application/xml:
              schema:
                type: string
      parameters:
      - name: object_id
        in: path
        description: ID of object
        required: true
        schema:
          $ref: https://raw.githubusercontent.com/sul-dlss/cocina-models/refs/tags/v0.113.0/schema.json#/$defs/Druid
      - name: id
        in: path
        description: Name of the workflow
        required: true
        schema:
          type: string
    post:
      tags:
      - workflows
      summary: Create a new workflow for this object
      operationId: workflow#create
      responses:
        '201':
          description: Created
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      parameters:
      - name: object_id
        in: path
        description: ID of object
        required: true
        schema:
          $ref: https://raw.githubusercontent.com/sul-dlss/cocina-models/refs/tags/v0.113.0/schema.json#/$defs/Druid
      - name: id
        in: path
        description: Name of the workflow to create
        required: true
        schema:
          type: string
      - name: version
        in: query
        description: The version of the object to create the workflow for
        required: true
        schema:
          type: integer
      - name: lane-id
        in: query
        schema:
          $ref: '#/components/schemas/LaneId'
      requestBody:
        description: Context for the workflow.
        content:
          application/json:
            schema:
              type: object
              properties:
                context:
                  type: object
                  additionalProperties: true
  /v1/objects/{object_id}/workflows/{id}/skip_all:
    post:
      tags:
      - workflows
      summary: Skip all processes in a workflow for this object.
      operationId: workflow#skip_all
      parameters:
      - name: object_id
        in: path
        description: ID of object
        required: true
        schema:
          $ref: https://raw.githubusercontent.com/sul-dlss/cocina-models/refs/tags/v0.113.0/schema.json#/$defs/Druid
      - name: id
        in: path
        description: Name of the workflow to skip
        required: true
        schema:
          type: string
      - name: note
        in: query
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Skipped all processes
        '404':
          description: Object or workflow not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/objects/{object_id}/workflows/{workflow_id}/processes/{id}:
    put:
      tags:
      - workflows
      summary: Update a workflow process (step) for this object.
      operationId: workflow_processes#update
      responses:
        '204':
          description: Updated
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Object, workflow, or process not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Expected current status does not match the actual status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      parameters:
      - name: object_id
        in: path
        description: ID of object
        required: true
        schema:
          $ref: https://raw.githubusercontent.com/sul-dlss/cocina-models/refs/tags/v0.113.0/schema.json#/$defs/Druid
      - name: workflow_id
        in: path
        description: Name of the workflow to update
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Name of the workflow step to update (e.g. "shelve")
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  $ref: '#/components/schemas/WorkflowProcessStatus'
                current_status:
                  $ref: '#/components/schemas/WorkflowProcessStatus'
                elapsed:
                  type: number
                lifecycle:
                  type: string
                note:
                  type: string
                error_text:
                  type: string
                error_message:
                  type: string
                version:
                  type: integer
              required:
              - status
components:
  schemas:
    LaneId:
      description: Lane for prioritizing the work
      type: string
      enum:
      - default
      - low
      - high
      default: default
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
    Error:
      type: object
      properties:
        title:
          type: string
          description: a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem.
          example: Invalid Attribute
        detail:
          type: string
          description: a human-readable explanation specific to this occurrence of the problem.
          example: Title must contain at least three characters.
        meta:
          type: object
          description: used to include non-standard meta-information
          example:
            backtrace:
            - where things went wrong
        source:
          type: object
          properties:
            pointer:
              type: string
              example: /data/attributes/title
    WorkflowProcessStatus:
      type: string
      enum:
      - waiting
      - completed
      - error
      - queued
      - skipped
      - started
      - retrying
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT