Introduction

Chemwatch API V2 (Beehive Platform) is a new generation GraphQL API which provides an easy and robust way of intergating Chemwatch data and solutions with other systems, such as ERPs/LIMS/LMS/etc. It exposes a GraphQL interface that can be implemented in any programming language capable of sending and processing web API requests.

GraphQL offers significant advantages over traditional REST APIs, including flexible data retrieval where clients request only the data they need, reducing over-fetching and under-fetching. It uses a single endpoint for multiple resources, improving efficiency. Its strongly typed schema enhances clarity and self-documentation, while supporting real-time data updates through subscriptions. Additionally, it provides a superior developer experience with tools like GraphiQL for interactive API exploration and ensures backward compatibility, making API changes seamless without affecting existing queries. These benefits collectively make GraphQL a robust and efficient solution for building scalable APIs.

Base URLs by Region

USA: beehive-usa.chemwatch.net- Australia: beehive.chemwatch.net`
EU: beehive-eu.chemwatch.net

Authentication

Endpoint

https://{Base URL}/webui-api/login

This endpoint authenticates a user by validating their credentials passed in JSON format. Upon successful authentication, an authentication token is returned in the response, which can be used for subsequent authenticated requests.

Request

URL: https://{Base URL}/webui-api/login

Method: POST

Headers:

Host: <base_URL>
Content-Type: application/json

Parameters:

domainName: Domain or account name
userName: User login name
password: User password

Example Request

curl -X POST \
  <base_URL>/webui-api/login \
  -H 'Content-Type: application/json' \
  -H 'Cookie: auth-token=<your token>' \
  -d '{"password":"password","userName":"name","domainName":"domain"}'

Getting Started

Graph QL

A GraphQL query type request is a type of request made to a GraphQL server that allows a client to retrieve data. Unlike traditional REST APIs where the client makes different requests to different endpoints to fetch various data, GraphQL allows the client to specify exactly what data they need in a single query. The server then returns only that data, often in a nested and hierarchical structure.

Here are the main components of a GraphQL query type request:

Endpoint: The URL of the GraphQL server where the request is sent.
Headers: Include necessary information such as content type and authentication tokens.
Query: The actual GraphQL query that specifies the data fields the client wants to retrieve.
Variables: (Optional) Used to pass dynamic values to the query.

Request Format

GraphQL request is a JSON representation of a query. Below is an example of a request:

 MyQuery {
  listFolders {
    parent
    location
    permissionId
    address {
      addAddressToSubFolders
      addressType
      city
      country
      streetAddress
      zipCode
    }
  }
}

This query retrieves information about folders, including their address details, from a GraphQL server.

Fields Requested

listFolders: This is the root field being queried. It returns a list of folder objects. Each folder object contains several fields.

Folder Fields

parent: Retrieves the parent identifier or name of the folder.
location: Retrieves the location associated with the folder.
permissionId: Retrieves the permission identifier for the folder.

Nested Address Fields

The address field is a nested object within each folder object. It contains additional fields that provide detailed address information for the folder:

addAddressToSubFolders: A boolean value indicating whether the address should be added to subfolders.
addressType: The type of address (e.g., Home, Office).
city: The city part of the address.
country: The country part of the address.
streetAddress: The street address part of the address.
zipCode: The zip code part of the address.

Sending Request

To send a request you should use the HTTP structure below.

URL: <base_URL>/webui-api/graphql
Method: POST
Headers:
- Host: <base_URL>
- Cookie: auth-token=; Path=/; Secure; HttpOnly; SameSite=Lax
- Content-Type: application/json
Body: JSON object containing the GraphQL query and variables (if any).

Example Request

curl -X POST \
  <base_URL>/webui-api/graphql \
  -H 'Content-Type: application/json' \
  -H 'Cookie: auth-token=<your token>' \
  -d '{"query":"query MyQuery { listFolders { parent location permissionId address { addAddressToSubFolders addressType city country streetAddress zipCode } } }","variables":{}}'

Methods

Queries

getSocket

Retrieves socket details based on input parameters.

Input: GetSocketInput
Output: [Socket]

example

 MyQuery {
  getSocket(input: {socketId: "id"}) {
    annexXIV {
      applicationDate
      sunsetDate
    }
    activePreferredName
    attachments
    casNumber
    classification
    classificationAgg
    countryCode
    cwNo
    datasetKey
    dateAdded
    dgc
    dgs1
    dgs2
    documentName
    documentKey
    domain
    extractionDate
    generalNotes
    goldSdsNotes
    hCodes {
      code
      phaseOut
    }
    hasesds
    hasgold
    hasugd
    hasvgd
    hazardRating
    isHidden
    licUnit
    languageCode
    issueDate
    licVolume
    location
    materialName
    maxVolume
    maxUnit
    msdsType
    name
    partNumber
    partNumbers
    phaseOut {
      authorizationRequired
      mode
      sunsetDate
      timeZone
    }
    phaseOutValue
    pkg
    preferredName
    rCodes {
      code
      phaseOut
    }
    regulatoryBurden {
      color
      level
      x
    }
    rootMaterialName
    socketId
    specificGravity
    state
    tagNames {
      module
      name
    }
    un
    unit
    vendorName
    volume
    weWriteOwnerDomain
    weWriteOwnerProfile
  }
}

listSockets

Lists sockets based on input parameters.

Input: ListSocketsInput
Output: [Socket]

example

 MyQuery {
  listSockets {
    location
    datasetKey
    documentKey
    classification
    classificationAgg
    isHidden
    generalNotes
    goldSdsNotes
    attachments
    weWriteOwnerDomain
    weWriteOwnerProfile
    msdsType
    un
    partNumber
    preferredName
    dateAdded
    activePreferredName
    maxVolume
    licVolume
    volume
    phaseOutValue
    dgc
    dgs1
    dgs2
    pkg
    hasgold
    hasvgd
    hasugd
    hasesds
    casNumber
    issueDate
    extractionDate
    documentName
    hazardRating
    state
    specificGravity
    unit
    maxUnit
    licUnit
    domain
    cwNo
    rootMaterialName
    vendorName
    countryCode
    languageCode
    materialName
    socketId
    name
  }
}

listSocketsByFolder

Lists sockets filtered by folder based on input parameters.

Input: ListSocketsByFolderInput
Output: [Socket]

example

 MyQuery {
  listSocketsByFolder(input: {location: "id"}) {
    location
    datasetKey
    documentKey
    classification
    classificationAgg
    isHidden
    generalNotes
    goldSdsNotes
    attachments
    weWriteOwnerDomain
    weWriteOwnerProfile
    msdsType
    un
    partNumber
    preferredName
    dateAdded
    activePreferredName
    maxVolume
    licVolume
    volume
    phaseOutValue
    dgc
    dgs1
    dgs2
    pkg
    hasgold
    hasvgd
    hasugd
    hasesds
    casNumber
    issueDate
    extractionDate
    documentName
    hazardRating
    state
    specificGravity
    unit
    maxUnit
    licUnit
    domain
    cwNo
    rootMaterialName
    vendorName
    countryCode
    languageCode
    materialName
    socketId
    name
  }
}

listFolders

Lists all folders available.

Output: [Location] `

example

 MyQuery {
  listSocketsByFolder(input: {location: "id"}) {
    location
    datasetKey
    documentKey
    classification
    classificationAgg
    isHidden
    generalNotes
    goldSdsNotes
    attachments
    weWriteOwnerDomain
    weWriteOwnerProfile
    msdsType
    un
    partNumber
    preferredName
    dateAdded
    activePreferredName
    maxVolume
    licVolume
    volume
    phaseOutValue
    dgc
    dgs1
    dgs2
    pkg
    hasgold
    hasvgd
    hasugd
    hasesds
    casNumber
    issueDate
    extractionDate
    documentName
    hazardRating
    state
    specificGravity
    unit
    maxUnit
    licUnit
    domain
    cwNo
    rootMaterialName
    vendorName
    countryCode
    languageCode
    materialName
    socketId
    name
  }
}

ownSearch

Performs a customized search based on input parameters.

Input: OwnSearchInput
Output: OwnSearchResponse

example

 OwnSearchQuery($input: OwnSearchInput!) {
  ownSearch(input: $input) {
    cursor {
      location
      datasetKey
      documentKey
      classification
      classificationAgg
      isHidden
      generalNotes
      goldSdsNotes
      attachments
      weWriteOwnerDomain
      weWriteOwnerProfile
      msdsType
      un
      partNumber
      preferredName
      dateAdded
      activePreferredName
      maxVolume
      licVolume
      volume
      regulatoryBurden {
        x
        color
        level
      }
      phaseOut {
        mode
        sunsetDate
        timeZone
        authorizationRequired
      }
      annexXIV {
        sunsetDate
        applicationDate
      }
      phaseOutValue
      dgc
      dgs1
      dgs2
      pkg
      hCodes {
        code
        phaseOut
      }
      rCodes {
        code
        phaseOut
      }
      hasgold
      hasvgd
      hasugd
      hasesds
      tagNames {
        name
        module
      }
      partNumbers
      casNumber
      issueDate
      extractionDate
      documentName
      hazardRating
      state
      specificGravity
      unit
      maxUnit
      licUnit
      domain
      cwNo
      rootMaterialName
      vendorName
      countryCode
      languageCode
      materialName
      socketId
      name
    }
    lookup {
      classifications {
        cnt
        name
      }
      countries {
        cnt
        name
      }
      languages {
        cnt
        name
      }
      tags {
        cnt
        name
      }
      vendors {
        cnt
        name
      }
    }
    totalRows
  }
}

fullSearch

Performs a comprehensive search based on input parameters.

Input: FullSearchInput
Output: FullSearchResponse

example

 FullSearchQuery($input: FullSearchInput!) {
  fullSearch(input: $input) {
    cursor {
      documentKey
      datasetKey
      documentName
      issueDate
      catalogueName
      rootMaterialName
      cwNo
      countryCode
      languageCode
      vendor
      origin {
        doc_no
      }
      vendorName
      materialName
      hasgold
      hasvgd
      haswewrite
      casNumber
    }
    totalRows
  }
}

data

Retrieves data points based on input parameters.

Input: DataInput
Output: [DataPoint]

example

 DataQuery($input: DataInput!) {
  data(input: $input) {
    socketId
    data {
      name
      value
      description
    }
  }
}

updates

Retrieves history items based on update input parameters.

Input: updatesInput
Output: [historyItem]

example

 UpdatesQuery($input: UpdatesInput!) {
  updates(input: $input) {
    id
    domain
    user
    action
    timestamp
    originvalue
    targetvalue
    locationorigin
    locationtarget
    socketidorigin
    socketidtarget
    cwnumber
    materialname
    vendor
    documentkey
    gridtype
    productkey
    cataloguename
    module
    isfromsisot
  }
}

document

Retrieves document details based on input parameters.

Input: documentInput
Output: String

example

 {
  document(input: {
    documentKey: "6d2d9c5a-5569-4cbd-91b9-977a310c0dc5"
  })
}

dictionary

Retrieves dictionaries for countries and languages.

Output: Dictionary

example

 {
  dictionary {
    countries {
      code
      name
    }
    languages {
      code
      name
    }
  }
}

fullData

Retrieves full data points.

Input: FullDataInput
Output: [FullDataResult]

example

 FullDataQuery($input: FullDataInput!) {
  fullData(input: $input) {
    datasetKey
    data {
      name
      value
      description
    }
  }
}

userId

Retrieves user ID information based on domain and username.

Input: UserIdInput
Output: String

example

 UserIdQuery($input: UserIdInput!) {
  userId(input: $input)
}

domainUsers

Retrieves domain users information.

Input: DomainUsersInput
Output: [DomainUsersResponse]

example

 DomainUsersQuery($input: DomainUsersInput!) {
  domainUsers(input: $input) {
    userId
    name
  }
}

container

Retrieves detailed information about a container.

Input: ContainerInput
Output: [Container]

example

 ContainerQuery($input: ContainerInput!) {
  container(input: $input) {
    productName
    cas
    barcode
    manufacture
    cat
    uom
    containerType
    containerSize
    physicalForm
    inventoryDate
    folderPath
  }
}

getContainer

Retrieves container detail based on container ID.

Input: ContainerInput
Output: ContainerDetail

example

 GetContainerQuery($input: ContainerInput!) {
  getContainer(input: $input) {
    containerKey
    productKey
    barcode
    catalogueName
    vendor
    location
    statusId
  }
}

listContainers

Lists containers based on inputs.

Input: ListContainersInput
Output: [ListContainerDetail]

example

 ListContainersQuery($input: ListContainersInput!) {
  listContainers(input: $input) {
    containerKey
    productKey
    documentKey
    location
    ContainerType
    ContainerStatus
  }
}

listContainersByFolder

Lists containers based on folder location.

Input: ListContainersByFolderInput
Output: ListContainersByFolderResponse

ownSearchContainer

Performs a customized search for containers.

Input: OwnSearchContainerInput
Output: OwnSearchContainerResponse

getRiskAssessment

Retrieves a specific risk assessment.

Input: GetRiskAssessmentInput
Output: RiskAssessmentResponse

example

 GetRiskAssessmentQuery($input: GetRiskAssessmentInput!) {
  getRiskAssessment(input: $input) {
    statusCode
    riskAssessment {
      id
      status
      task
    }
  }
}

listRiskAssessments

Lists risk assessments.

Input: ListRiskAssessmentsInput
Output: RiskAssessmentListResponse

retrieveContainerInfo

Retrieves info about a container.

Input: RetrieveContainerInfoInput
Output: RetrieveContainerInfoResponse

Mutations

createSocket

Creates a new socket with the specified input parameters.

Input: CreateSocketInput
Output: CreateSocketResult

example

 CreateSocketMutation($input: CreateSocketInput!) {
  createSocket(input: $input) {
    statusCode
    duplicateMessage
    duplicate
    socketIds
  }
}

updateSocket

Updates an existing socket based on the input parameters.

Input: UpdateSocketInput
Output: StatusCode

example

 UpdateSocketMutation($input: UpdateSocketInput!) {
  updateSocket(input: $input) {
    statusCode
  }
}

deleteSocket

Deletes a socket based on the input parameters.

Input: DeleteSocketInput
Output: StatusCode

example

 DeleteSocketMutation($input: DeleteSocketInput!) {
  deleteSocket(input: $input) {
    statusCode
  }
}

createLocation

Creates a new location with the specified input parameters.

Input: CreateLocationInput
Output: StatusCode

example

 CreateLocationMutation($input: CreateLocationInput!) {
  createLocation(input: $input) {
    statusCode
  }
}

deleteLocation

Deletes a location based on the input parameters.

Input: DeleteLocationInput
Output: StatusCode

example

 DeleteLocationMutation($input: DeleteLocationInput!) {
  deleteLocation(input: $input) {
    statusCode
  }
}

msdsRequest

Submits a MSDS (Material Safety Data Sheet) request using the provided input parameters.

Input: MsdsRequestInput
Output: StatusCode

example

 MsdsRequestMutation($input: MsdsRequestInput!) {
  msdsRequest(input: $input) {
    statusCode
  }
}

createContainer

Creates a new container.

Input: CreateContainerInput
Output: CreateContainerResponse

addUserPartNumber

Adds a user part number.

Input: SaveUserPartNumberInput
Output: SaveUserPartNumberResponse

deleteUserPartNumber

Deletes a user part number.

Input: SaveUserPartNumberInput
Output: SaveUserPartNumberResponse

Contacts

Please direct your questions to mailto:it@chemwatch.net.