tread.io Materials API

openapi: 3.0.3
info:
  title: Horizon API V1 AccountExternalTruckIdentifier Materials API
  version: '1.0'
  contact:
    name: Tread
    url: https://tread.io
    email: developers@tread.io
  description: 'This is the Version 1 implementation.


    When in doubt we default to the practices outlined [here](https://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api#advanced-queries)'
  license:
    name: Private
    url: https://tread.io
servers:
- description: production
  url: https://api.tread-horizon.com
security:
- bearerAuth: []
tags:
- name: Materials
paths:
  /v1/companies/{company-id}/materials:
    parameters:
    - schema:
        type: string
      name: company-id
      in: path
      required: true
      description: Company ID
    - $ref: '#/components/parameters/Accept-Language'
    post:
      summary: Create a Material for a Company
      tags:
      - Materials
      operationId: post-v1-companies-company-id-materials
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/Material-Read'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/UnauthenticatedError'
        '403':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '406':
          $ref: '#/components/responses/Error'
        '415':
          $ref: '#/components/responses/Error'
        '422':
          $ref: '#/components/responses/ModelError'
      x-stoplight:
        id: omi29o8m9tdc4
      description: 'Create `Materials` for a `Company`


        This endpoint requires the `create_materials` permission'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Material-Create'
    get:
      summary: Retrieve Materials that belong to a Company
      tags:
      - Materials
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    x-stoplight:
                      id: 7611vnq3mszru
                    items:
                      $ref: '#/components/schemas/Material-Read'
                required:
                - data
          headers:
            Link:
              schema:
                type: string
              description: Contains prev and next links for pagination
        '401':
          $ref: '#/components/responses/UnauthenticatedError'
        '404':
          $ref: '#/components/responses/Error'
        '406':
          $ref: '#/components/responses/Error'
      operationId: get-v1-companies-company-id-materials
      x-stoplight:
        id: a7zdk9y0109my
      description: "Retrieve `Materials` for a `Company`\n\nDatagrid search (`search[datagrid]`) queries against the following properties:\n * `name`\n * `external_id`\n * `material_type.name`"
      parameters:
      - $ref: '#/components/parameters/page-limit'
      - $ref: '#/components/parameters/page-after'
      - $ref: '#/components/parameters/page-before'
      - $ref: '#/components/parameters/search-datagrid'
  /v1/companies/{company-id}/materials/typeahead:
    parameters:
    - schema:
        type: string
      name: company-id
      in: path
      required: true
      description: Company ID
    - $ref: '#/components/parameters/Accept-Language'
    get:
      summary: Typeahead search on Material for a Company
      tags:
      - Materials
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Material-Read-Typeahead'
                required:
                - data
          headers:
            Link:
              schema:
                type: string
              description: Contains prev and next links for pagination
        '401':
          $ref: '#/components/responses/UnauthenticatedError'
        '404':
          $ref: '#/components/responses/Error'
        '406':
          $ref: '#/components/responses/Error'
      operationId: get-v1-companies-company-id-material-typeahead
      description: Typeahead search against the `name` property on `Material` for a `Company`.
      parameters:
      - $ref: '#/components/parameters/page-limit'
      - $ref: '#/components/parameters/page-after'
      - $ref: '#/components/parameters/page-before'
      - $ref: '#/components/parameters/search-query'
      x-stoplight:
        id: k2n1ug9xevn42
      x-internal: true
  /v1/companies/{company-id}/orders/{order-id}/materials/typeahead:
    parameters:
    - schema:
        type: string
        format: uuid
      name: company-id
      in: path
      required: true
      description: Company ID
    - schema:
        type: string
        format: uuid
      name: order-id
      in: path
      required: true
      description: Order ID
    - $ref: '#/components/parameters/Accept-Language'
    get:
      summary: Typeahead search on Materials that belong to Order's Company
      tags:
      - Materials
      responses:
        '200':
          description: OK
          headers:
            Link:
              schema:
                type: string
              description: Contains prev and next links for pagination
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    x-stoplight:
                      id: xr3m6ssu8y6ed
                    items:
                      $ref: '#/components/schemas/Material-Read-Typeahead'
        '401':
          $ref: '#/components/responses/UnauthenticatedError'
        '404':
          $ref: '#/components/responses/Error'
        '406':
          $ref: '#/components/responses/Error'
      operationId: get-v1-companies-company-id-orders-order-id-materials-typeahead
      x-stoplight:
        id: bmjq2ylkh3y25
      description: Typeahead search against the `name` property for `Materials` that belong to the `Order`'s `Company`
      parameters:
      - $ref: '#/components/parameters/page-limit'
      - $ref: '#/components/parameters/page-after'
      - $ref: '#/components/parameters/page-before'
      - $ref: '#/components/parameters/search-query'
  /v1/materials:
    parameters:
    - $ref: '#/components/parameters/Accept-Language'
    post:
      summary: Create a Material
      tags:
      - Materials
      operationId: post-v1-materials
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/Material-Read'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/UnauthenticatedError'
        '403':
          $ref: '#/components/responses/Error'
        '406':
          $ref: '#/components/responses/Error'
        '415':
          $ref: '#/components/responses/Error'
        '422':
          $ref: '#/components/responses/ModelError'
      x-stoplight:
        id: 27dur2xjkdn98
      description: 'Create a new Material


        This endpoint requires the `create_materials` permission'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Material-Create'
    get:
      summary: Retrieve Materials that belong to the current Company
      tags:
      - Materials
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    x-stoplight:
                      id: 5l8c4sizu62bj
                    items:
                      $ref: '#/components/schemas/Material-Read'
                required:
                - data
          headers:
            Link:
              schema:
                type: string
              description: Contains prev and next links for pagination
        '401':
          $ref: '#/components/responses/UnauthenticatedError'
        '406':
          $ref: '#/components/responses/Error'
      operationId: get-v1-materials
      x-stoplight:
        id: ex8sbs07p4lok
      description: "Retrieve `Materials` visible to the currently authenticated `Company`.\n\nDatagrid search (`search[datagrid]`) queries against the following properties:\n * `name`\n * `external_id`\n * `material_type.name`\n "
      parameters:
      - $ref: '#/components/parameters/page-limit'
      - $ref: '#/components/parameters/page-after'
      - $ref: '#/components/parameters/page-before'
      - $ref: '#/components/parameters/search-datagrid'
  /v1/materials/typeahead:
    parameters:
    - $ref: '#/components/parameters/Accept-Language'
    get:
      summary: Typeahead search on Materials
      tags:
      - Materials
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Material-Read-Typeahead'
                required:
                - data
          headers:
            Link:
              schema:
                type: string
              description: Contains prev and next links for pagination
        '401':
          $ref: '#/components/responses/UnauthenticatedError'
        '406':
          $ref: '#/components/responses/Error'
      operationId: get-v1-material-typeahead
      description: 'Typeahead search against the `name` property for `Material` visible to the currently authenticated `Company`.

        '
      x-internal: true
      parameters:
      - $ref: '#/components/parameters/page-limit'
      - $ref: '#/components/parameters/page-after'
      - $ref: '#/components/parameters/page-before'
      - $ref: '#/components/parameters/search-query'
      x-stoplight:
        id: g1vnefs3m2mdt
  /v1/materials/{id}:
    parameters:
    - schema:
        type: string
      name: id
      in: path
      required: true
      description: Material ID
    - $ref: '#/components/parameters/Accept-Language'
    get:
      summary: Retrieve a single Material
      tags:
      - Materials
      operationId: get-v1-materials-id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Material-Read'
                required:
                - data
        '401':
          $ref: '#/components/responses/UnauthenticatedError'
        '404':
          $ref: '#/components/responses/Error'
        '406':
          $ref: '#/components/responses/Error'
      x-stoplight:
        id: yo1jdwvr7x93k
      description: Retrieve a `Material` by ID
    patch:
      summary: Update a Material
      tags:
      - Materials
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/Material-Read'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/UnauthenticatedError'
        '403':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '406':
          $ref: '#/components/responses/Error'
        '415':
          $ref: '#/components/responses/Error'
        '422':
          $ref: '#/components/responses/ModelError'
      operationId: patch-v1-materials-id
      x-stoplight:
        id: czlg6jh55ey3i
      description: 'Update `Material` by ID


        This endpoint required the `edit_material` permission'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Material-Update'
    delete:
      summary: Delete a Material
      tags:
      - Materials
      operationId: delete-v1-materials-id
      responses:
        '204':
          description: No Content
        '401':
          $ref: '#/components/responses/UnauthenticatedError'
        '403':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '406':
          $ref: '#/components/responses/Error'
        '422':
          $ref: '#/components/responses/ModelError'
      x-stoplight:
        id: 252bxk4epppji
      description: 'Delete a `Material` by ID


        This endpoint requires the `delete_material` permission'
  /v1/materials/{material-id}/activate:
    parameters:
    - schema:
        type: string
      name: material-id
      in: path
      required: true
      description: Material ID
    - $ref: '#/components/parameters/Accept-Language'
    put:
      summary: Activate a Material
      tags:
      - Materials
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Material-Read'
                required:
                - data
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/UnauthenticatedError'
        '403':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '406':
          $ref: '#/components/responses/Error'
        '409':
          $ref: '#/components/responses/StateError'
        '415':
          $ref: '#/components/responses/Error'
      operationId: put-v1-materials-material-id-activate
      x-stoplight:
        id: 4y5ta1v0pa28s
      description: 'Activate a `Material` by ID


        This endpoint requires the `edit_material` permission'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties: {}
  /v1/materials/{material-id}/deactivate:
    parameters:
    - schema:
        type: string
      name: material-id
      in: path
      required: true
      description: Material ID
    - $ref: '#/components/parameters/Accept-Language'
    put:
      summary: Deactivate a Material
      tags:
      - Materials
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Material-Read'
                required:
                - data
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/UnauthenticatedError'
        '403':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '406':
          $ref: '#/components/responses/Error'
        '409':
          $ref: '#/components/responses/StateError'
        '415':
          $ref: '#/components/responses/Error'
      operationId: put-v1-materials-material-id-deactivate
      x-stoplight:
        id: m1v1iij2wksdp
      description: 'Deactivate a `Material` by ID


        This endpoint requires the `edit_material` permission'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties: {}
  /v1/orders/{order-id}/materials/typeahead:
    parameters:
    - schema:
        type: string
      name: order-id
      in: path
      required: true
      description: Order ID
    - $ref: '#/components/parameters/Accept-Language'
    get:
      summary: Typeahead search on Materials that belong to Order's Company
      tags:
      - Materials
      responses:
        '200':
          description: OK
          headers:
            Link:
              schema:
                type: string
              description: Contains prev and next links for pagination
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    x-stoplight:
                      id: xr3m6ssu8y6ed
                    items:
                      $ref: '#/components/schemas/Material-Read-Typeahead'
        '401':
          $ref: '#/components/responses/UnauthenticatedError'
        '404':
          $ref: '#/components/responses/Error'
        '406':
          $ref: '#/components/responses/Error'
      operationId: get-v1-orders-order-id-materials-typeahead
      x-stoplight:
        id: j0ap9rwx29chq
      description: Typeahead search against the `name` property for `Materials` that belong to the `Order`'s `Company`
      parameters:
      - $ref: '#/components/parameters/page-limit'
      - $ref: '#/components/parameters/page-after'
      - $ref: '#/components/parameters/page-before'
      - $ref: '#/components/parameters/search-query'
      deprecated: true
components:
  responses:
    ModelError:
      description: ''
      content:
        application/json:
          schema:
            type: object
            $ref: '#/components/schemas/ModelError-Response'
    Error:
      description: Error response
      content:
        application/json:
          schema:
            type: object
            $ref: '#/components/schemas/Error-Response'
    UnauthenticatedError:
      description: Example response
      content:
        application/json:
          schema:
            type: object
            $ref: '#/components/schemas/UnauthenticatedError-Response'
    StateError:
      description: Example response
      content:
        application/json:
          schema:
            type: object
            $ref: '#/components/schemas/StateError-Response'
  parameters:
    Accept-Language:
      name: Accept-Language
      in: header
      schema:
        type: string
        default: en
        example: en
      description: 'The Accept-Language request HTTP header indicates the natural language and locale that the client prefers. '
    search-datagrid:
      name: search[datagrid]
      in: query
      required: false
      schema:
        type: string
      description: Search string for datagrid queries
    search-query:
      name: search[query]
      in: query
      required: false
      schema:
        type: string
      description: Search string for queries
    page-limit:
      name: page[limit]
      in: query
      schema:
        type: integer
        format: int32
        default: 25
        maximum: 100
      description: The maximum number of paginated results to return
    page-before:
      name: page[before]
      in: query
      required: false
      schema:
        type: string
      description: The cursor to stop paginating at
    page-after:
      name: page[after]
      in: query
      required: false
      schema:
        type: string
      description: The cursor to start paginating after
  schemas:
    StateError-Response:
      title: StateError-Response
      x-stoplight:
        id: i0wsk2gmnaqup
      type: object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/StateError'
      additionalProperties: false
    Error-Response:
      title: Error-Response
      x-stoplight:
        id: 52cydhphee3qe
      type: object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/Error'
      additionalProperties: false
    Material-Read:
      title: Material-Read
      x-stoplight:
        id: zykrikmo6ku9d
      allOf:
      - $ref: '#/components/schemas/Identifier'
      - type: object
        x-stoplight:
          id: qdq705bx4imz5
        properties:
          name:
            type: string
            x-stoplight:
              id: ulmm18mglklba
          system:
            type: boolean
            x-stoplight:
              id: 0vn6xeslme5b2
          company:
            $ref: '#/components/schemas/Company-Read-Nested'
          material_type:
            $ref: '#/components/schemas/MaterialType-Read-Nested'
          state:
            $ref: '#/components/schemas/MaterialState'
          external_id:
            type: string
            x-stoplight:
              id: dr0e9kppho1yy
            nullable: true
        required:
        - name
        - system
        - company
        - material_type
        - state
        - external_id
      - $ref: '#/components/schemas/Timestamps'
    MaterialState:
      title: MaterialState
      x-stoplight:
        id: li8t934rfnen9
      enum:
      - active
      - inactive
      default: active
      description: Material States
    TreadId:
      title: TreadId
      x-stoplight:
        id: 43k4t5tl359m4
      type: object
      required:
      - tread_id
      properties:
        tread_id:
          type: string
          x-stoplight:
            id: zi3ld7djflw6f
          pattern: ^[0-9A-F]{6}$
          minLength: 6
          maxLength: 6
          example: ABC123
          description: Tread ID
      additionalProperties: false
    Material-Read-Typeahead:
      title: Material-Read-Typeahead
      x-stoplight:
        id: 30glh3las0ydb
      allOf:
      - $ref: '#/components/schemas/Identifier'
      - type: object
        required:
        - name
        - external_id
        properties:
          name:
            type: string
            description: Material name
          external_id:
            type: string
            description: Material external_id
            x-stoplight:
              id: ml0l0yvuz5u6d
            nullable: true
    Error:
      title: Error
      x-stoplight:
        id: 3g57kkik3l464
      type: object
      description: An Error.
      required:
      - code
      properties:
        code:
          type: string
          x-stoplight:
            id: 7o9x1t8v0bgfo
      additionalProperties: false
    ModelError-Item:
      title: ModelError-Item
      x-stoplight:
        id: b93chwval2t8d
      type: object
      required:
      - model
      - field
      - message
      properties:
        model:
          type: string
          x-stoplight:
            id: 30myfyjkno8ao
          description: The Model associated with this Error
        field:
          type: string
          x-stoplight:
            id: 8gl4ed3uxhdws
          description: The field associated with this Error
        message:
          type: string
          x-stoplight:
            id: bmgbrtmw17qsj
          description: The Error message
      additionalProperties: false
    UnauthenticatedError:
      title: UnauthenticatedError
      x-stoplight:
        id: 202o69l0fs40h
      allOf:
      - $ref: '#/components/schemas/Error'
      - type: object
        x-stoplight:
          id: tg10dt7s0l6bw
        properties:
          error_type:
            type: string
            x-stoplight:
              id: wvq8c0qsym4hz
        required:
        - error_type
    ModelError:
      title: ModelError
      x-stoplight:
        id: nhp6714o4j1qt
      description: A Model-specific error
      allOf:
      - $ref: '#/components/schemas/Error'
      - type: object
        required:
        - errors
        properties:
          errors:
            type: array
            x-stoplight:
              id: m4ul9vcq2deh6
            items:
              $ref: '#/components/schemas/ModelError-Item'
    StateError:
      title: StateError
      x-stoplight:
        id: zgcsl4t8bsn3c
      allOf:
      - $ref: '#/components/schemas/Error'
      - type: object
        x-stoplight:
          id: ntvt2atfotcge
        required:
        - errors
        properties:
          errors:
            type: array
            x-stoplight:
              id: noi1jg6o8psl7
            items:
              $ref: '#/components/schemas/StateError-Item'
    Timestamps:
      title: Timestamps
      x-stoplight:
        id: t82ecgfu0oj00
      type: object
      required:
      - created_at
      - updated_at
      properties:
        created_at:
          type: string
          x-stoplight:
            id: gjj950jpq0ga9
          format: date-time
          description: ISO8601 timestamp with local timezone
        updated_at:
          type: string
          x-stoplight:
            id: bwcuyfwc7aj0e
          format: date-time
          description: ISO8601 timestamp with local timezone
      additionalProperties: false
    Identifier:
      title: Identifier
      x-stoplight:
        id: gnd39lue5v7ol
      type: object
      required:
      - id
      properties:
        id:
          type: string
          x-stoplight:
            id: 2e38hjk4zd58m
          format: uuid
      additionalProperties: false
    MaterialType-Read-Nested:
      type: object
      x-stoplight:
        id: eb0713e9ab180
      required:
      - id
      - name
      - system
      properties:
        id:
          type: string
          x-stoplight:
            id: ttpt631g6p07c
          format: uuid
        name:
          type: string
          x-stoplight:
            id: lwt1eafxok791
        system:
          type: boolean
          x-stoplight:
            id: 1z3wyp0ckkusa
      additionalProperties: false
    Company-Read-Nested:
      title: Company-Read-Nested
      x-stoplight:
        id: cb2kn77qmf1l7
      description: Compact Company model for nested reads.
      allOf:
      - $ref: '#/components/schemas/Identifier'
        x-stoplight:
          id: jwsufva4znm91
      - $ref: '#/components/schemas/TreadId'
      - type: object
        properties:
          legal_name:
            type: string
            x-stoplight:
              id: yc10t8hieecwk
            description: The Company's name. Must be globally unique.
          company_type:
            $ref: '#/components/schemas/CompanyType'
        required:
        - legal_name
        - company_type
    StateError-Item:
      title: StateError-Item
      x-stoplight:
        id: dgw2jdmi7ozjj
      allOf:
      - $ref: '#/components/schemas/ModelError-Item'
      - type: object
        x-stoplight:
          id: jrgi7oapao3e5
        required:
        - state
        - event
        properties:
          state:
            type: string
            x-stoplight:
              id: mah8jye43io32
            description: The current state value of the field on this Model
          event:
            type: string
            x-stoplight:
              id: dtgu62ni9ofuh
            description: The failed state event called on the Model
    Material-Update:
      title: Material-Update
      x-stoplight:
        id: n895nez95yq3o
      type: object
      description: The model for updating Materials
      properties:
        name:
          type: string
          description: Name of the `Material`.
        material_type_id:
          x-stoplight:
            id: esz3iuitl0yg2
          type: string
          format: uuid
          description: ID of `MaterialType`
        external_id:
          type: string
          x-stoplight:
            id: 2ky5fn1mftpam
          nullable: true
        state:
          $ref: '#/components/schemas/MaterialState'
      additionalProperties: false
    Material-Create:
      title: Material-Create
      x-stoplight:
        id: 6picifuuj3fqg
      type: object
      description: The model for creating Materials
      required:
      - name
      properties:
        name:
          type: string
          x-stoplight:
            id: 2ehiqmkv42lqu
          description: Name of the `Material` to be created.
        material_type_id:
          type: string
          x-stoplight:
            id: 1x76pf7jqilp5
          format: uuid
          description: 'This is the id for `MaterialType`. If not provided, it will default to a `MaterialType` of `Other` '
        external_id:
          type: string
          x-stoplight:
            id: kqklkbp3i54q0
          nullable: true
        state:
          $ref: '#/components/schemas/MaterialState'
      additionalProperties: false
    CompanyType:
      title: CompanyType
      x-stoplight:
        id: dkzo7gjbtb1b3
      enum:
      - broker
      - contractor
      - hauler
      - owner_operator
      - producer
      - super
      example: hauler
      description: Company Type
    UnauthenticatedError-Response:
      title: UnauthenticatedError-Response
      x-stoplight:
        id: o477eph7ttbzt
      type: object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/UnauthenticatedError'
      additionalProperties: false
    ModelError-Response:
      title: ModelError-Response
      x-stoplight:
        id: payf9ndh3l6np
      type: object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ModelError'
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
x-stoplight:
  id: 75rfxjepk4523