The OpenTHC API Specification is not an API for a specific system, rather it is an approach towards a common API for the cannabis industry. This document, and it’s contents should be viewed as proposed guidelines.

1. Authentication

Authentication to OpenTHC can occur through different methods with a preference for oAuth2 When OpenTHC is connecting through to a back-end system some of those parameters may need to be passed as well.

1.1. Open Connecxion

Authentication occurs through a request that looks something like this:

# With shell, you can just pass the correct header with each request
curl "$BASE/auth/open" \
	--data "rce=wa" \
	--data "license=ABC" \
	--data "client-key=ZYX"

OpenTHC will will respond to both set a cookie your client libraries can use to retain the session. Or, this token can be included in a request header as a Bearer token.

1.1.1. Variations

No all API compatible systems will use the same authentication methods. For example

  • the OpenTHC Core system uses credential pairs and HMACs;

  • the OpenTHC Pipe service uses mapped-pass-through credentials dependent on the backend.

  • the OpenTHC P2P system uses pre-shared keys for authentication and signing

Refer to the implementation specific documentation for authentication methods

1.2. Ping

The /auth/ping endpoint provides a method for a client to check the status of their connexion. It should respond with some type of JSON, which may be dependent on which upstream system is in play.

curl "$BASE/auth/ping" \
	--header "Authorization: Bearer $HASH"

	"status": "success"
	"detail": "All Systems are Go"

1.3. Shut

Any request to /auth/shut with a session or access token will terminate/revoke this session or token. This request should always respond with an HTTP Staus of 206 for success or an appropriate HTTP Status on error.

curl "$BASE/auth/shut" \
	--header "Authorization: Bearer $HASH"

2. Core Data

A Company is a container object, which will contain one or more License objects, and one or more Contact objects.

A License is a container for the tracked materials, the license will have a LicenseType and is generally tied to a specific physical address.

A Contact is a human, as a member of a Company. A Contact may be a User or and Employee or simply a record for a visitor to a Company/License location.

3. Plants

Plants are growing items in the System

3.1. Plants :: Create

Creating new Plants from either Clones or Seeds or other allowed Inventory Lot types.

3.1.1. Parameters

  • Source: the Source Inventory Identifier

  • Strain: Strain Name

  • Batch: Some systems operate with a Batch concept, which could be provided here

  • Stage: Descriptive text of the Stage of the plant

  • Planted: Date Planted, ISO Date format

  • Zone: The Room/Zone the Plant is located in

curl -X POST $API_BASE/plant

	license: {
		guid: "ABC123"
	source: {
		guid: "I1A",
	strain: {
		guid: "S2B"

	guid: "P3C"
	strain: {
		name: "Alpha"
		guid: "S2B"

3.2. Plants :: Modify

Change either the Strain Name, Planting Date or Mother Designation Or …​ ?

3.3. Plants :: Delete

Creating new Plants from either Clones or Seeds.

Then later confirm deletion

3.4. Growth

Add documentation about feed, fertilizer, nutrients, pesticides and other things added to or on the plants.

3.5. Plants :: Grow

Additives record the application of some material to the plants, including pesticies and nutrients.

3.5.1. Apply Grow Materials

3.5.2. Attach Grow Notes to Multiple Plants

3.6. Plants :: Notes

Notes on the plants record the application of nutrieinets, pesticides and other matter. Farmers may also use the Note field to attach comments or photos to the records.

3.6.1. Create a Plant Note

3.6.2. Attach Note to multiple Plants

3.7. Collecting Materials

A Wet Collection, sometimes called a Harvest or Manicure, is the process of taking raw materials from the crop.

A Dry Collection, sometimes called a Cure, is the process of collecting refined Wet Materials from Plants

3.8. Plants :: Wet Collect

Wet materials collection is also known as Harvesting or Manicuring. Generally the phrase harvesting means collection from the entire plant, while manicuring implies that collections will be made a bit at a time.

From Plants one or more Wet Collections can be made. A Wet collection is to enter materials that have been directly collected from the plants.

A Plant Batch is created to bundle these

Then Plants are added to this Plant Batch, including the weight in grams.

Once the Harvest is complete, as determined by farmer, this harvest bundle is closed

3.9. Plants :: Dry Collect

Dry materials collection is also known as Curing.

These dry materials are pulled from plant batches and classified by the farmer.

The reply includes the ID of the inventory items that were created from this process and includes and advisory value of the new weight of the affected batch.

This call can be repeated for each kind of material collected.

4. Inventory

Inventory represents all Source, Product, Processing and Retail materials

4.1. Listing Inventory

curl $API_BASE/inventory

4.2. Inventory / Adjust

A regulatory system specific type of adjustment to the inventory, generally requires a note.

curl -X POST $API_BASE/inventory/{OID}/adjust

	quantity: 55,
	code: 'audit',
	note: 'mis-count in processing'

4.3. Inventory / Modify

Only Permitted Modifications will be Allowed For Modification of Weight or Volume requires docuemntation

4.3.1. Inventory / Move

For Moving Inventory to a New Zone (aka Area or Room)

4.4. Inventory / Convert

The process of taking one or more Source lots and converting into one, or more, Output lots.

4.5. Inventory / Split

Slice off a portion of an existing inventory, also known as Sub-Lotting.

5. Quality Assurance

Take a Sample from a product, provide Sample Results

5.1. Create a QA Sample

From an Inventory Lot create a QA Sample Lot, which is a special type of sub-lot from the primary Inventory Lot. This Sample item will have a unique identifier and a child relationship to the source.

curl -X POST $API_BASE/lot/{OID}/sample

	type: "QA",
	quantity: "5"

5.2. QA Sample Detail

Return the details of the QA Sample, including which tests are required/requested. Similar to requiredlabtestbatches API call in METRC.

curl $API_BASE/qa/{OID}


5.3. QA Result :: Update

Generally the Labratory (or sometimes the Licensed Operator) will update the QA results in the system. Either through the WebUI or via API.

curl -X POST $API_BASE/qa/{OID}

	"status": "failed",
	"metric": {
		"general": { ... },
		"potency": { ... },
		"microbe": { ... },

5.4. QA Result :: Void

Generally the Labratory (or sometimes the Licensed Operator) will update the QA results in the system. Either through the WebUI or via API.


	"status": "warning",
	"detail": "Call Delete again to confirm"

6. Transfer

A Transfer manifest is prepared to indicate the Transfer of materials from one license holder to another.

6.1. Outgoing

Export is the process of selecting one or more Inventory items and preparing them for delivery. Items and Quantities (or Sub-Lots) are placed on a Transfer Manifest. And this Manifest is filed with the regulatory system.

6.1.1. Outgoing / Create

6.1.2. Outgoing / Commit

6.1.3. Outgoing / Update

6.2. Incoming

Incoming Transfers is the process of receiving a request, processing the materials into the target License inventory.

6.2.1. Incoming / Accept

7. Retail Sales

8. Adminstration

8.1. Configuration Accounts

The OpenTHC API also supports interactions to keep track of the companies, licensees and locations.

9. Company

A Company is a container for one or more Contact objects.

A Company will have one or more Contacts and one or more Licenses.

10. Contact

A Contact is an Employee and/or User of the system associated with one Company. A Contact may authenticate to the system.

11. User Accounts

Each user is identified by their email address, which must be unique across the system.

12. User Security

User access to the system is logged. Group ownership is checked on all object access. Each user has an access control list expressed for them.

12.1. Permissions

12.2. Grow Materials

Inputs for grow supplies; adding a bulk item, with cost and the removing portions.

Inputs for grow journals; adding a note and a metric to a plant (or group of plants, but tracked per-plant)

12.3. Units of Measure

The system store all values internally in grams or liters, accurate to four decimal places. That is, accurate to 0.1 milligram/milliliter; expressed internally as grams or liters.

Weights can be input in any of the following values:

  • Grams

  • Milligrams

  • Kilograms

  • US Pounds

  • US Ounces

Volume can be input in any of the following values

  • Liters

  • Milliliters

  • US Ounces