Oden Technologies Maintenance Work Orders API

openapi: 3.0.0
info:
  version: 2.0.0
  title: Oden Dashboards Maintenance Work Orders API
  contact:
    name: Oden Support
    email: support@oden.io
    url: https://oden.io/contact/
  description: "The Oden Private Partner API exposes RESTful API endpoints for clients to get, create and update data on the Oden Platform.\n\nThe API is based on the OpenAPI 3.0 specification.\n### Current Version\nThe URL, and host, for the current version is [https://api.oden.app/v2](https://api.oden.app/v2).\n\n### Oden's Data Model\n- **Organization**: This represents the Organization registered as an Oden customer. An organization has an associated collection of users, factories, lines, etc. This is the entity a specific authentication token is associated with.\n- **Asset** or **Machinegroup**: Assets, or machinegroups, are collections of machines, which may either be a **Factory** or a **Line**:\n  - **Factory**: Factories are collections of lines, representing a particular manufacturing location.\n    - **Line**: Lines are collections of machines, often representing a particular production line. Lines may also have **Products** mapped to them, indicating what is currently being manufactured by the specific line.\n      - **Machine**: Machines are the physical machines that make up a line\n- **Product**: Products capture what entities a manufacturer produces\n- **Interval**: An interval is a period of time that takes place on a manufacturing line and expresses some business concern. It's Oden's way of making metrics aggregatable, traceable, and relatable to a manufacturer.\n  - **Run**: A run is a production interval that labels a period of production as being work on some single product\n  - **Batch**: A batch is a production interval that represents a portion of a particular run\n  - **State**: A state is an interval that tracks the availability or utilization of a line\n    - **State Category**: A state category describes what state a line is in - such as ex. uptime, downtime, scrapping, etc.\n    - **State Reason**: A state reason describes why a line is in a particular state - such as \"maintenance\" being a reason for the category \"downtime\".\n  - **Custom**: A custom interval can track any other type of interval-based data a manufacturer might want to analyze. These are created on a per-factory basis.\n- **Target**: Targets specify values and upper/lower thresholds for metrics when specific products are running on specific lines\n- **Scrap/Yield**: Scrap/yield output specifies amount of produced product on a line during either a run or batch interval. Oden will categorize all output as either scrap or yield - as specified by the Scrap Yield Schema for a given factory. If you have other categories, like rework/blocked/off-grade, you must choose between categorizing those amounts as either good or bad production by specifying as scrap or yield. Clients may also add scrap codes (i.e., reasons) to a given Scrap Yield Data entry.\n  - **Scrap Code**: A scrap code is a code that explains the reason for a scrap/yield raw data input - such as \"Rework\"\n- **Quality Test**: Quality Tests are results of quality assurance tests done on site, and uploaded to Oden. They may be attached to a single Batch or Run.\n- **Metric**: Known in factories as \"tags\", metrics are the raw data that is collected by Oden from the machines and devices on the factory floor.\n- **Metric Group**: Metric groups are metrics that represent the same thing across different lines. They provide common display names for tags and allow labeling groups of tags as measuring key types of data like performance or production.\n- **Maintenance Work Order**: A maintenance work order can be used to track work orders maintained in MaintainX and associate them with an Oden line. \n\n### Best Practices\nUnder the current implementation, the Oden API does not rate limit requests from clients.\n\nHowever, rate limiting will be introduced in the near future and it is recommended that users design their API\nclients to not exceed a request rate of **one per second**.\n\n### Schema\nAll v2 API access is over HTTPS and accessed from https://api.oden.app/v2\nAll data is sent and received as JSON.\n\nAPI requests with duplicate keys will process only the data for the first key detected and ignore the rest, so it's not recommended. Batching multiple messages in this way is currently not possible.\n  - Example of duplicate key in JSON: {\"raw_data\":{\"scrap\":\"10\",\"scrap\":\"100\"}}\n\nAll timestamps are returned in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601#Times) format:\n\n  `YYYY-MM-DDTHH:MM:SSZ`\n\nAll durations are returned in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601#Times) format with the largest unit of time being the hour:\n\n   `PT[n]H[n]M[n]S`\n\nAll timestamps sent to the API in POST requests should be in ISO 8601 format.\n### HTTP Verbs\nThe ONLY HTTP call type (sometimes called *verb* or *method*) used within Oden's API is **POST**.\nThere are three actions supported via a **POST**; call, search, set, and delete, together supporting CRUD operations;\n  - **search** requests are used to search for and *read* objects in the Oden Platform\n      - All Oden Objects may be uniquely identified by some combination of, or a single, parameter.\n        - Ex a `line` my be identified by either:\n          - `id`\n          - `name` AND `factory`\n  - **set** requests are used to *create* or *update* objects\n  - **delete** requests are used to *delete* objects. If a delete endpoint is not yet implemented for a given object, users may choose to update the values of a specific entity to null or 0 values.\n\n### URI Components\nAll endpoints may be accessed with the URI pattern:\n`https://api.oden.app/v2/{object}/{action}`\n\nWhere:\n  - `object` is the name of the object being requested:\n       - `factory`, `quality_test`, `interval`, `line`, etc...\n  - `action` is the name of the action being requested\n    - `search` , `set` , `delete`\n\ne.g. `https://api.oden.app/v2/factory/search`\n\n# Authentication\nClients can authenticate through the v2 API using a Token provided by Oden. Tokens are opaque strings similar to\n[Bearer](https://swagger.io/docs/specification/authentication/bearer-authentication/) tokens that the client must\npass in the [HTTP Authorization request header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization) in every request.\nThe syntax is as follows:\n\n`Authorization: <type> <credentials>`\n\nWhere \\<type\\> is \"Token\" and \\<credentials\\> is the Token string. For example:\n\n`Authorization: Token tokenStringProvidedByOden`\n\nAuthenticating with an invalid Token will return `401 Unauthorized Error`.\n\nAuthenticating with a Token that is not authorized to read requested data will return `403 Forbidden Error`.\n\nSome endpoints may require requests to be broken out by machinegroup (i.e., line or factory) and the number of\nrequests would scale accordingly. This multiplicity should be taken into consideration when deciding on the\nfrequency the API client makes requests to the Oden endpoints.\n\nTo authenticate in this [UI](https://api.oden.app/v2/ui/), click the Lock icon, and copy/paste the token into the Authorize box.\n"
servers:
- url: https://api.oden.app
  description: Oden API server
security:
- APIKeyAuth: []
tags:
- name: Maintenance Work Orders
paths:
  /v2/maintenance_work_order/search:
    post:
      operationId: search_maintenance_work_orders
      summary: Search maintenance work orders
      tags:
      - Maintenance Work Orders
      description: 'Search for Maintenance Work Orders by:

        - `id`

        - `external_id`

        - `line_id` with required `start_time` and `end_time` filters

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  format: uuid
                external_id:
                  type: string
                line:
                  $ref: '#/components/schemas/Line'
                start_time:
                  type: string
                  format: date-time
                end_time:
                  type: string
                  format: date-time
                match:
                  $ref: '#/components/schemas/Match'
            examples:
              Search by ID:
                summary: Search for maintenance work order by ID
                value:
                  id: 0012ab4d-1234-123a-8c76-6ea2344be6df
              Search by external ID:
                summary: Search for maintenance work order by external ID
                value:
                  external_id: MWO-12345
                  line:
                    id: 0012ab4d-1234-123a-8c76-6ea2344be6df
              Search by line with time range:
                summary: Search for maintenance work orders on a line within a time range
                value:
                  line:
                    id: 0012ab4d-1234-123a-8c76-6ea2344be6df
                  start_time: '2021-04-04T08:00:04Z'
                  end_time: '2021-04-10T08:00:04Z'
                  match: all
      responses:
        '200':
          description: A list of maintenance work orders.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MaintenanceWorkOrder'
        '400':
          $ref: '#/components/responses/ParameterError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/NotUniqueError'
        '500':
          $ref: '#/components/responses/InternalError'
        '501':
          $ref: '#/components/responses/UnimplementedError'
  /v2/maintenance_work_order/set:
    post:
      operationId: set_maintenance_work_order
      summary: Create or update a maintenance work order
      tags:
      - Maintenance Work Orders
      description: 'Create or update a Maintenance Work Order.


        To **create** a new Maintenance Work Order:

        - Include `name` and `line`, `external_id`, `started_at` (required)

        - Omit `id` field

        - include `completed_at`, `description`, `metadata`


        To **update** an existing Maintenance Work Order:

        - Include the `id` of the existing work order

        - Include any fields to update


        NOTE: Any fields not included in an update request will be left unchanged.

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MaintenanceWorkOrder'
            examples:
              Create a maintenance work order:
                summary: Create a new maintenance work order
                value:
                  name: Scheduled Maintenance Q1
                  line:
                    id: 0012ab4d-1234-123a-8c76-6ea2344be6df
                  description: Quarterly scheduled maintenance
                  external_id: MWO-2024-001
                  started_at: '2024-01-15T08:00:00Z'
                  completed_at: '2024-01-15T17:00:00Z'
                  metadata: '{"technician": "John Doe", "priority": "high"}'
              Update an existing maintenance work order:
                summary: Update an existing maintenance work order
                value:
                  id: 0012ab4d-1234-123a-8c76-6ea2344be6df
                  completed_at: '2024-01-15T18:30:00Z'
                  metadata:
                    technician: John Doe
                    priority: high
                    notes: Completed late due to parts delay
      responses:
        '200':
          description: A list containing the created or updated maintenance work order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MaintenanceWorkOrder'
        '400':
          $ref: '#/components/responses/ParameterError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/NotUniqueError'
        '500':
          $ref: '#/components/responses/InternalError'
        '501':
          $ref: '#/components/responses/UnimplementedError'
  /v2/maintenance_work_order/delete:
    post:
      operationId: delete_maintenance_work_order
      summary: Delete a maintenance work order
      tags:
      - Maintenance Work Orders
      description: 'Delete a Maintenance Work Order by unique identifier:

        - `id` OR `external_id`

        - `match: unique` or omit (only unique is supported)

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MaintenanceWorkOrder'
            examples:
              Delete by ID:
                summary: Delete maintenance work order by ID
                value:
                  id: 0012ab4d-1234-123a-8c76-6ea2344be6df
              Delete by external ID:
                summary: Delete maintenance work order by external ID
                value:
                  external_id: MWO-12345
                  line:
                    id: 0012ab4d-1234-123a-8c76-6ea2344be6df
                  match: unique
      responses:
        '200':
          description: A list containing the deleted maintenance work order.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MaintenanceWorkOrder'
        '400':
          $ref: '#/components/responses/ParameterError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/NotUniqueError'
        '500':
          $ref: '#/components/responses/InternalError'
        '501':
          $ref: '#/components/responses/UnimplementedError'
components:
  schemas:
    GenericError:
      type: object
      required:
      - error
      - retryable
      properties:
        error:
          type: string
        retryable:
          type: boolean
    Factory:
      type: object
      description: An entity representing a factory.
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        secondary_name:
          type: string
          nullable: true
        timezone:
          type: string
        match:
          $ref: '#/components/schemas/Match'
    Match:
      type: string
      enum:
      - first
      - last
      - unique
      - all
      default: unique
      description: 'Describes which item(s) to match when searching for an entity:

        - `unique` (default): will return an error if the search object matches multiple entities

        - `all`: will return every item that matches search entity

        - `last`: will return the most recent object, where applicable

        - `first`: will return the least recent object, where applicable

        '
    MaintenanceWorkOrder:
      type: object
      description: An object representing a maintenance work order on a line.
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        external_id:
          type: string
        line:
          $ref: '#/components/schemas/Line'
        started_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
        metadata:
          type: object
          additionalProperties: true
        match:
          $ref: '#/components/schemas/Match'
    Line:
      type: object
      description: An entity representing a single line of production.
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        secondary_name:
          type: string
        factory:
          $ref: '#/components/schemas/Factory'
        match:
          $ref: '#/components/schemas/Match'
  responses:
    ParameterError:
      description: An error occurred regarding one of the input parameters
      content:
        application/json:
          schema:
            type: object
            required:
            - error
            - name
            - retryable
            properties:
              error:
                type: string
              name:
                type: string
              retryable:
                type: boolean
    UnimplementedError:
      description: Endpoint is not yet implemented
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenericError'
    InternalError:
      description: 'An internal server error has occurred. If reporting the error to Oden, include the ID returned in this response to aid in debugging.

        '
      content:
        application/json:
          schema:
            type: object
            required:
            - error
            - retryable
            - id
            properties:
              error:
                type: string
              retryable:
                type: boolean
              id:
                type: string
                format: uuid
    ForbiddenError:
      description: 'User has provided valid credentials but is not authorized to access the entity

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenericError'
    NotFoundError:
      description: Entity not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenericError'
    NotUniqueError:
      description: 'A {match: "unique"} was requested, but multiple entities matched the search parameters.

        '
      content:
        application/json:
          schema:
            type: object
            required:
            - entity_name
            - num_matches
            - error
            - retryable
            properties:
              entity_name:
                type: string
              num_matches:
                type: integer
              error:
                type: string
              retryable:
                type: boolean
    UnauthorizedError:
      description: User has provided either no credentials or invalid credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenericError'
  securitySchemes:
    APIKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Prefix the value with \"Token\" to indicate the custom authorization type