Start a new session and get an authentication token that you can use to call other REST APIs. Use an email address and password to login and generate the token. You must already be registered as a user on this MediLedger Private Node. The tenant short name part of the path is required, even for single-tenant deployments. Use the token to make other REST API request by passing the authentication token in the HTTP header Authorization. Read the Authentication API introduction in this documentation for examples of how to use the token with cURL.

For a multi-tenant installation of a MediLedger Private Node, each email address is associated only with a single tenant. Therefore, any REST API calls that use this authentication token work only with the appropriate tenant data.

This API is typically used with email and password to generate a new token. Alternatively, you can use this API to log in with an existing token (instead of email and password) to generate a new token in case the previous one was compromised.

To end a session, make a DELETE /oauth/token request, which invalidates the token. To log in again, request a new token.

Log out of a session, which also invalidates the token.

See the beginning of the Authentication section of this documentation for examples of how to create and use tokens.

Submits a GS1-compliant verification request to the MediLedger PVS system. Distributors can use this API to integrate with their existing systems. For example, an ERP or warehouse system could call this REST API to verify a saleable return by specifying the product ID (GTIN), serial number, lot number, and expiration date.

This follows the GS1 lightweight verification messaging standard decribed in this GS1 specification.

The implementation of this API is as follows:

1. If the asset was stored locally on this Private Node, it is verified immediately. Locally stored assets (SGTINs) is a feature for use in manufacturer testing only as an alternative to setting up an EPCIS repository for this information during testing. For more details, see the POST /asset request.

2. The server uses blockchain data to determine which Private Node is responsible for that product code (GTIN). The blockchain registration for the product includes an endpoint route that includes an endpoint URL which is the URL to the MediLedger Private Node that can validate the request for that product.

3. The server contacts that Private Node and makes a peer-to-peer verification request (using a different internal REST API).

4. That server responds to the verification request, possibly calling out to external EPCIS systems to look up the product ID (GTIN), serial number, lot number, and expiration date. IMPORTANT: Omit the /api/2.0 URL prefix for this GS1 API.

This interface documents a webhook that allows a MediLedger application tenant that represents a manufacturer to connect an EPCIS repository. The EPCIS repository contains important information that is not stored on the MediLedger blockchain: product serial numbers, expiration dates, and lot numbers.

This is an OpenAPI specification of an interface that must be implemented by external EPCIS system or middleware that connects to an external EPCIS system. This is provided as a reference for manufacturers who need to implement this interface. Because this is based on a GS1 standard, an equivalent REST API is implemented on the MediLedger Private Node, but this OpenAPI REST API request is intended as your reference for what to implement.

With one exception, this is the GS1 lightweight verification messaging standard decribed in this GS1 specification.

IMPORTANT: There is one important difference between this interface and the GS1 verification request specification: the responder GLN (responderGLN) in the EPCIS response is optional not required. If the EPCIS system sets the responder GLN explicitly, by default the MediLedger node uses the EPCIS response GLN in its own response to the verification request that it received. If omitted, the MediLedger node uses its own tenant default GLN. If instead you want to always return verification responses with the tenant’s default GLN independent of the behavior of the EPCIS system response, contact support for help configuring an advanced setting that overrides the default behavior. There are two parts to this integration for the MediLedger PVS application:

1. This interface must be implemented by EPCIS repositories or middleware that interfaces with the EPCIS system.

2. When creating a new tenant on a MediLedger Private Node, you will run the add-tenant script, which generates a configuration file at tenants/TENANT_SHORT_NAME/config.yaml. See the Getting Started Guide for more details.

Before you run the start-tenant script, you must edit the tenant-specific config.yaml file to configure the webhooks property with mappings for one or more EPCIS servers. See the Getting Started Guide in the section EPCIS Configuration for Manufacturers Only. You cannot edit the webhook settings after you start the tenant.

For complete instructions, see the Getting Started Guide in the section EPCIS Configuration for Manufacturers Only. If you do not already have the Getting Started Guide, or if you have any questions, please email Chronicled Support at mlsupport@pulse.pharmacy.

IMPORTANT: Omit the /api/2.0 URL prefix for this GS1 API.

Returns basic information about MediLedger products that your organization has created, including ones that are still pending or had errors. The results also include plus all products that were ever involved with transfers with me, whether or not it was completed (or cancelled) and even if it was transferred to someone else since then.

You can optionally filter the results list by various criteria. For example, return product IDs (GTINs) with a specified prefix by setting gtin_prefix. Return products in the process of transfer by setting transfer_pending to true. See the parameters list for details and other filter criteria.

To understand the business meaning of the products in the results, it is important to distinguish between products that you currently own versus products that appear in results because of past transfers or attempted transfers with you. You can check if you currently own a product in the results by checking the owned field in the JSON results. Alternatively, you could check to see if the owner_id field matches your member ID. If you want to only return products you currently own, on your request set the owned filter parameter to true.

The products in results include the following five categories:

• Products that you officially own right now, independent of whether you created it or it was transferred to you from someone else and you accepted it. The owned field has the value true.

• Recently created products that are still pending creation and confirmation on the blockchain. Technically, no one owns it yet. The owned field has the value false.

• You used to own it, but you successfully transferred it to another MediLedger member (a completed outgoing transfer). It will be visible to you in your API results forever, even if the new owner transfers it to another member eventually. The owned field has the value false. Note: If a recipient later transfers it back to you and you accept it, you own it again and owned again becomes true.

• It is pending transfer to you (an incoming transfer), but you have not yet accepted or rejected the request. It will be visible to you in your API results forever, even if the new owner transfers it to another member eventually. The owned field has the value false. The transfer_pending field has the value true.

• Another member initiated a transfer of it to you but cancelled it. It will be visible to you in your API results forever, even if the new owner transfers it to another member eventually. The owned field has the value false. The transfer_pending field has the value false (unless a transfer is attemped again).

Creates a new product. The most important information you need to create a product is the GS1 GTIN-14 code for the product.

Additionally, for each GTIN you must also provide an ID for a Validation Endpoint. Validation Endpoints are objects on the blockchain that encapsulate validation URLs. A validation URL represents a MediLedger Private Node (or in some cases a Gateway Node) that can validate product information for a saleable return using MediLedger REST APIs. To register a new Validation Endpoint on the blockchain, use the separate REST API resource called /endpoint, which is documented in a separate OpenAPI document. Each Validation Endpoint has an ID. For the POST /product request, encapsulate the ID for a Validation Endpoint in an object called an endpoint route. See the description of the parameter endpoint_routes for its structure.

Update product display name

Begins a transfer of a product. The product is considered pending transfer until such time as one of the following happens:

• The recipient (transferee) accepts the transfer. If this happens, the product's owner ID changes to the new recipient.

• The recipient (transferee) rejects the transfer. If this happens, your organization continues to own the product.

• You cancel the transfer before the recipient can accept or reject the transfer. If this happens, your organization continues to own the product.

If your organization does not own the product, this returns error HTTP response code 409.

Accepts the transfer of a product. If you do not want to accept the transfer, instead use a Reject Product Transfer request (/product/{public_product_uri}/reject).

If the product's owner did not initiate transfer of this product to your organization, this returns error HTTP 404. If the product is already owned by you, this returns error HTTP 400.

Reject a pending transfer of a product. This API assumes that a product transfer of the product has already been initiated by another member.

If you initiated a pending transfer and do not want it to succeed, instead use a Cancel Product Transfer request (/product/{public_product_uri}/cancel).

If the product's owner did not initiate transfer of this product to your organization, this returns error HTTP 404. If the product is already owned by you, this returns error HTTP 400.

Cancels the transfer of a Product. Use this API to cancel a product transfer that you previously initiated.

If you are the recipient of a pending transfer and do not want to accept it, instead use a Reject Product Transfer request (/product/{public_product_uri}/reject).

If you are not the product owner and initiated transfer of this product to your organization, this returns error HTTP 409.

Update the endpoint routes of a product. For the MediLedger PVS product, endpoints are always Validation Endpoints, which are objects on the blockchain that encapsulate validation URLs.

A validation URL represents a MediLedger Private Node (or in some cases a Gateway Node) that can validate product information for a saleable return using MediLedger REST APIs.

Only manufacturers (not distributors) need to register an endpoint for a product. For every product spcified by its GTIN, the blockchain tells other MediLedger members which server to contact to validate serial numbers for that product.

Get basic information of a product, specified by its Chronicled ID (which is unique to this Private Node) or its product URI (which includes its GTIN).

Delete a product. You must currently own this product. Also, the product must NOT have been deleted before.

WARNING: It is unsupported to attempt delete a product more than once. Deleting an already-deleted product can result in unexpected behaviors or disruption to services.

Get a list of your own organization's products that were previously deleted.

To page results, use the _page and _per_page parameters. This API does not support the expand parameter to look at the details of the blockchain transactions and events. This API alwyas returns the IDs only. If you want to see the whole object, use the /product/deleted/{product_uri} API to return a single product from its product URI.

Get one of your own organization's products that was previously deleted, specified by its product URI.

Get information about public products, which are the set of products visible to all members and confirmed on the blockchain.

IMPORTANT: Unlike the GET /product request, a GET /public-product request will never include pending products, error products, or endpoint routes that were recently changed but are pending confirmation on the blockchain. To support paging results, see the _page and _per_page parameters.

Get information about public products, which are the set of products visible to all members and confirmed on the blockchain.

IMPORTANT: Unlike the GET /product request, a GET /public-product request will never include pending products, error products, or endpoint routes that were recently changed but are pending confirmation on the blockchain.

Get information about a public product by its URI. Public products are the set of products visible to all members and confirmed on the blockchain.

IMPORTANT: Unlike the GET /product request, a GET /public-product request will never include pending products, error products, or endpoint routes that were recently changed but are pending confirmation on the blockchain.

Returns basic information about all MediLedger endpoints that your organization has attempted to register. Includes endpoints that are still pending or had errors during creation. Each result includes a status field that indicates whether the endpoint is still pending, successfully on the blockchain, or had errors during creation

Registers a new MediLedger endpoint for your company. Save the id field from the result. An endpoint ID is necessary to pass to some other APIs to represent this endpoint. For exampe, when creating a new product with a POST /product request. The return result includes a status field that indicates whether the endpoint is still pending, successfully on the blockchain, or had errors during creation.

In the normal case, the endpoint URL would be to the api-server domain with no REST API specific suffix like /api/2.0. For example, https://api-server.mediledger.mycompany.com. However, you might use proxies that use domain names or URLs that forward connections to that URL, in which case your endpoint URL might look different and might use specific port numbers.

curl -X POST -H "Content-Type: application/json;charset=utf-8" -H "$authtoken" \ -d '{"url": "https://api-server.mediledger.example.com"}' \ https://api-server.mediledger.example.com/api/2.0/endpoint It returns a JSON result such as:

{"updated_at":"2019-05-08T17:14:45.540Z", "url":"https://api-server.mediledger.example.com", "status":"pending", "blockchain_transactions":[], "created_at":"2019-05-08T17:14:45.539Z", "id":"cxAgv1W", "member":"1", "uris":["ml:endpoint:1:32a835a6b09d4033a2580f483292dd81"], "blockchain_events":[]}

It is important to understand the URI in the response. Look at the first result in the uris property. The full value of that string is the URI for this endpoint. You can use that URI for other /endpoint requests, such as a GET /endpoint/{uri} request for information about the endpoint.

However, for the API that creates GTIN (POST /product), you need to use only the endpoint URI part after the last colon as its ID. In this example it is 32a835a6b09d4033a2580f483292dd81. Do not use the entire URI for the endpoint ID in the POST /product request.

Returns basic information about a specific MediLedger endpoint that you created. The return result includes a status field that indicates whether the endpoint is still pending, successfully on the blockchain, or had errors during creation.

Updates an existing Endpoint that the company owns. Note that update requires a POST not a PUT request. PUT is unsupported.

The return result includes a status field that indicates whether the endpoint is still pending, successfully on the blockchain, or had errors during creation

Returns information from the public blockchain about all MediLedger endpoints from all members. The list of public endpoints never includes endpoints that are still pending or had errors during creation.

IMPORTANT: Unlike the GET /endpoint request, a GET /public-endpoint request will never include pending endpoints, error endpoints, or endpoints that were recently changed but are pending confirmation on the blockchain.

Returns basic information about a specific public endpoint on the public blockchain. The endpoint is specified by URI. It can be from any MediLedger member.

IMPORTANT: Unlike the GET /endpoint request, a GET /public-endpoint request will never include pending endpoints, error endpoints, or endpoints that were recently changed but are pending confirmation on the blockchain.

Returns a list of all blocks. Pagination is supported. Filtering is unsupported.

Returns a block, specified by its block number.