Developers
      Back to home
      1. Knowledge Base
      2. Getting Started with Pilario
      3. Developers

      Accessing Pilario via the API

      This article explains how to access Pilario via the API in order to automate your processes.

      Please note that the API access is only available on the Enterprise plan.

      Initial steps

      In order to access Pilario via the API, the user must decide and configure one of the two available identification systems:

      • Via individual and private keys
      • Using a short live token system

      Please configure one of the two access by following the subsections below

      Generating an API key

      1. Connect to the Pilario providing your usual credentials
      2. On the left menu, go to Settings – API keys – Add new API key
      3. You can give a name and a description of your specific API identification key.
      4. Three different access levels can be created:
        1. Viewer (read only)
        2. Editor (read and write)
        3. Admin (read, write and delete).
        This gives the rights for the creation, edition, deletion and reading of your products for all the calls with the new API key.
      5. Click on save
      6. Your unique API key will be automatically created, you can copy it to integrate it in your API calls.

      Please contact our Support team if this API Settings section is not accessible to your user profile.

      Using a short live token

      This option will be available soon.

      Fetch information about the LCA model

      Use the GET API as described in the swagger documentation:

      https://api.pilario.com/v1/docs/customers/home#/product-models

      For example:

      curl -X 'GET' \
        'https://api.pilario.com/v1/product-models/packaging' \
        -H 'accept: application/json' \
        -H 'apiKey: 88edf5a6-0a49-4b90-8135-xxxxxxx'

      The server will reply with the following (trimmed for readability):

      {
        "key": "packaging",
        "name": "Packaging",
        "type": "PRODUCTS",
        "inputs": [
          {
            "name": "pack_rawmat_l2comp_weight_tot",
            "type": "REAL",
            "readOnly": true,
            "computedField": true,
            "label": "Component weight"
          }
        ],
        "sections": [
          {
            "key": "155501a6-4d14-4edb-96a3-2fe5177b77b0",
            "name": "composition",
            "inputs": [
              {
                "name": "general_volume",
                "type": "REAL",
                "unit": "l",
                "minValue": 0,
                "minInclusive": true,
                "maxInclusive": true,
                "readOnly": false,
                "computedField": false,
                "label": "Product volume",
                "defaultValue": 1
              },
      ...
              {
                "name": "pack_rawmat_custom_weight",
                "type": "REAL",
                "unit": "g",
                "minValue": 0,
                "minInclusive": true,
                "maxInclusive": true,
                "readOnly": false,
                "computedField": false,
                "label": "Material weight",
                "defaultValue": 0
              }
            ]
          }
        ]
      }

      The answer from the API provides:

      • The list of used parameters, including, among other parameters:
        • The level of usage in the interface (level 0, 1 or 2)
        • The technical name of the parameter
        • The English translation of the parameter as it is shown in the UI
      • The list of possible values for the SELECT parameters, including:
        • The technical name of the possible value
        • The English translation of the possible value as it is shown in the UI

      Lors de la demande d'informations sur le modèle LCA, une clé spécifique doit être fournie conformément au tableau suivant.

      Nom du Model  Clé du Model 
      PETCORE LCA model Bêta petcore
      Pallet pallet
      Packaging packaging
      FEBE febe
      PackagingGlass packaging-glass
      PEFCR Beer pefcr-beer
      Recycling recycling
      Textile-Fr (not yet available)
      PEFCR Water pefcr-water
      Textile-EU textile-eu
      Carbon Footprint carbonfootprint
      Eco-contribution ecocontribution
      PackagingDemo packaging-demo
      Device device
      PEFCR Soda pefcr-soda

       

       

      Fetch information about your products, scenarios, etc

      Use the POST API as described in the swagger documentation:

      https://api.pilario.com/v1/docs/customers/home#/assets

      Pilario uses a query system to be used in the request to filter the API answer to some products only. There are two ways to use the query filtering system:

      • Create a query thanks to the query generator in the Pilario UI, save it and use the query key within the “queryKey” element in your request. 
        This can be used for reusable filtered API calls.
      • Type your own query within the API call within the “text” element in your request.
        This is to be used for individually parametrized API calls.

      Creating a saved query

      First connect to the Pilario platform as usual.

      1. On the left menu, go to Settings – Saved queries – Add query
      2. Give a name to your query
      3. Use the search field or the Filters button.
      4. Choose the parameter on which you want to filter.
      5. Give the value on which the products must be filtered.
      6. Click the save button

      Please contact our Support team if this section is not accessible to your user profile.

      Typing your own query

      The nomenclature follows the same structure as the one used in the UI in the product table filtering system. You can make some test in the UI interface and check the console of the browser to retrieve the query.

      These are some examples of queries that can be used.

      Retrieve any PRODUCT with specific External Id

      curl -X 'POST' \
        'https://api.pilario.com/v1/assets/search?type=PRODUCT' \
        -H 'accept: application/json' \
        -H 'apiKey: 88edf5a6-0a49-4b90-8135-xxxxxxxxxxx' \
        -H 'Content-Type: application/json' \
        -d '{
       "text": "{ \"externalId\": \"1322132131\" }"
      }'

      The server will reply with any product having as externalId the value “1322132131” as show below:

      {
          "text": "{ \"externalId\": \"1322132131\"}",
          "page": 0,
          "pageSize": 10,
          "count": 1,
          "data": [
              {
                  "id": "3f6e0105-20a1-461f-95ac-77b2475c8f2c",
                  "name": "Soda",
                  "images": [],
                  "type": "PRODUCT",
                  "labels": [],
                  "computedAttributesStatus": "VALID",
                  "updatedBy": "user@pilario.com",
                  "createdBy": "user@pilario.com",
                  "status": "DRAFT",
                  "visibility": "HIDDEN",
                  "attributes": {
                      "prod_functional_unit": 1.5,
                      "filling_volume_in": 1.02,
                      "transp_transported_weight": 1530,
                      "prod_use_stage_loss": 2,
                      "product_volume": 1.5
                  },
                  "computedAttributes": {
                      "prod_functional_unit": 1.5,
                      "filling_volume_in": 1.02,
                      "transp_transported_weight": 1530
                  },
                  "createdAt": "2024-07-03T13:48:59.037Z",
                  "updatedAt": "2024-07-03T15:09:00.139Z",
                  "externalId": "1322132131",
      ...

       

      Retrieve any PRODUCT matching a specific attribute condition 

      curl -X 'POST' \
        'https://api.pilario.com/v1/assets/search?type=PRODUCT' \
        -H 'accept: application/json' \
        -H 'apiKey: 88edf5a6-0a49-4b90-8135-xxxxxxxxx' \
        -H 'Content-Type: application/json' \
        -d '{
        "text": "{\"attributes.product_volume\":{\"$gt\":1}}"
      }'

      This will provide a response with all the products having a product volume greater than 1 l. In this case we can see how Pilario returns two products found under that condition.

      {
          "text": "{\"attributes.product_volume\":{\"$gt\":1}}",
          "page": 0,
          "pageSize": 10,
          "count": 2,
          "data": [
              {
                  "id": "3f6e0105-20a1-461f-95ac-77b2475c8f2c",
                  "name": "Soda",
                  "images": [],
                  "type": "PRODUCT",
                  "labels": [],
                  "computedAttributesStatus": "VALID",
                  "updatedBy": "user@pilario.com",
                  "createdBy": "user@pilario.com",
                  "status": "DRAFT",
                  "visibility": "HIDDEN",
                  "attributes": {
                      "prod_functional_unit": 1.5,
                      "filling_volume_in": 1.02,
                      "transp_transported_weight": 1530,
                      "prod_use_stage_loss": 2,
                      "product_volume": 1.5
                  },
                  "computedAttributes": {
                      "prod_functional_unit": 1.5,
                      "filling_volume_in": 1.02,
                      "transp_transported_weight": 1530
                  },
                  "createdAt": "2024-07-03T13:48:59.037Z",
                  "updatedAt": "2024-07-03T15:09:00.139Z",
                  "externalId": "1322132131",
                  "productModelKey": "pefcr-soda",
      ...

      Please note that attributes are model dependant, so you need to know which attribute you are querying. To get a list of all the attributes available you might want to perform a query about the LCA model as described in the previous section.

      Fetch a product using the Pilario UUID

      Use the GET API described in the swagger documentation:

      https://api.pilario.com/v1/docs/customers/home#/assets/GetAsset

      This endpoint allows the user to get all the available data for one single asset (product, scenario, etc) using it’s unique identifier in the Pilario Database.

      Note: the unique identifier Pilario UUID is automatically generated every time an asset is created in the Pilario database (either through a manual creation in the UI, through a manual mass importation or through an API creation call).

      For example:

      curl -X 'GET' \
        'https://api.pilario.com/v1/assets/4a05193a-1e44-4c78-aad8-4f4b9f49b417' \
        -H 'accept: application/json' \
        -H 'apiKey: 88edf5a6-0a49-4b90-8135-xxxxxx'

      The server will reply with the single asset:

      {
        "id": "4a05193a-1e44-4c78-aad8-4f4b9f49b417",
        "name": "Plastic bottle",
        "images": [],
        "type": "PRODUCT",
        "labels": [
          "PEFCR Water",
          "Example"
        ],
        "computedAttributesStatus": "QUEUED",
        "updatedBy": "user@pilario.com",
        "createdBy": "user@pilario.com",
        "status": "DRAFT",
        "visibility": "HIDDEN",
        "attributes": {
          "general_weight": 1000,
          "pack_petprod_weight": 300,
          "pack_tot_weight": 699,
          "filling_pack_in": 1,
          "pack_functional_unit": 1
        },
        "computedAttributes": {
          "general_weight": 1000,
          "pack_petprod_weight": 300,
          "pack_tot_weight": 699,
          "filling_pack_in": 1
        },
        "createdAt": "2024-07-03T11:26:48.407Z",
      ...

      Create a new product

      Use the POST API described in the swagger documentation:

      https://api.pilario.com/v1/docs/customers/home#/assets/AddAsset

      This allows the API user to create new product in the Pilario database. The structure, the parameter names and the possible values must be aligned with the information provided as the answer to the getProductModel API call.

      For example:

      curl -X 'POST' \
        'https://api.pilario.com/v1/assets' \
        -H 'accept: application/json' \
        -H 'apiKey: 88edf5a6-0a49-4b90-8135-xxxxxxx' \
        -H 'Content-Type: application/json' \
        -d '{
        "type": "PRODUCT",
        "name": "Another API created product",
        "description": "This product was created via an API POST call",
        "externalId": "APIproduct001",
        "attributes": {
          "product_volume": 2
        },
        "productModelKey": "pefcr-soda",
        "labels": [
          "API"
        ],
       "assets": []
      }'

      The response provides the unique Pilario identifier used for the new product. This information must be stored in order to use the GetAssets API (to fetch information about an existing product) or the UpdateAsset API (to update some information about an existing product).

      {
        "id": "b39c33b6-2a36-4ae1-92b2-aaad62b1e377",
        "externalId": "APIproduct001",
        "name": "Another API created product",
        "description": "This product was created via an API POST call",
        "images": [],
        "type": "PRODUCT",
        "labels": [
          "API"
        ],
        "attributes": {
          "product_volume": 2
        },
        "computedAttributes": {},
        "computedAttributesStatus": "EXPIRED",
        "createdBy": "api",
        "status": "DRAFT",
        "visibility": "HIDDEN",
        "createdAt": "2024-10-22T14:33:39.831Z",
        "updatedAt": "2024-10-22T14:33:39.831Z",
        "productModelKey": "pefcr-soda",
        "assets": [],
        "results": {
          "total": {},
          "ingredients": {},
          "packaging": {},
          "supply": {},
          "manufacturing": {},
          "distribution": {},
          "storage": {},
          "usage": {},
          "collect": {},
          "end_of_life": {}
        },
        "groups": {
          "total": {}
        }
      }

      We can see as well the success in the following screenshot

      Update an existing product

      Use the PATCH API described in the swagger documentation:

      https://api.pilario.com/v1/docs/customers/home#/assets/UpdateAsset

      This allows the API user to modify existing assets in the Pilario database. The structure, the parameter names and the possible values must be aligned with the information provided as the answer to the getProductModel API call.

      For example:

      curl -X 'PATCH' \
        'https://api.pilario.com/v1/assets/b39c33b6-2a36-4ae1-92b2-aaad62b1e377' \
        -H 'accept: application/json' \
        -H 'apiKey: 88edf5a6-0a49-4b90-8135-4a689f7c77dc' \
        -H 'Content-Type: application/json' \
        -d '{
        "id": "b39c33b6-2a36-4ae1-92b2-xxxxxx",
        "name": "Another API created product",
        "description": "This product was modified via an API POST call",
        "type": "PRODUCT",
        "productModelKey": "pefcr-soda",
        "assets": []
      }'

      The response provides the full asset information.

      {
        "id": "b39c33b6-2a36-4ae1-92b2-aaad62b1e377",
        "externalId": "APIproduct001",
        "name": "Another API created product",
        "description": "This product was modified via an API POST call",
        "images": [],
        "type": "PRODUCT",
        "labels": [
          "API"
        ],
        "attributes": {
          "product_volume": 2
        },
        "computedAttributes": {},
        "computedAttributesStatus": "EXPIRED",
      ...

      Publish an existing product

      Use the POST API described in the swagger documentation:

      https://api.pilario.com/v1/docs/customers/home#/assets/PublishAsset

      This allows the user to publish a product

      For example:

      curl -X 'POST' \
        'https://api.pilario.com/v1/assets/13f6abfd-dcb0-49b9-94b5-f784175dac36/publish' \
        -H 'accept: */*' \
        -H 'apiKey: 88edf5a6-0a49-4b90-8135-xxxxxxxxxx' \
        -d ''

      The server will reply with an empty 204 in the event of success. Or an error, in the event that the product is already published:

      {
        "timestamp": "2024-10-23T07:40:23.324Z",
        "message": "Asset has already been published.",
        "eventId": "a34d8841-e02d-4d0d-a9dc-0ee4e829fcd5"
      }

      Delete an existing product

      Use the DELETE API described in the swagger documentation:

      https://api.pilario.com/v1/docs/customers/home#/assets/DeleteAsset

      For example:

      curl -X 'DELETE' \
        'https://api.pilario.com/v1/assets/13f6abfd-dcb0-49b9-94b5-f784175dac36' \
        -H 'accept: */*' \
        -H 'apiKey: 88edf5a6-0a49-4b90-8135-xxxxxx'

      The server will reply with an empty simple 204 in the event of success.