Legacy API Documentation
      Back to home
      1. Stairwell Help Center
      2. API Documentation
      3. Legacy API Documentation

      How to use the Variants API

      Learn how to use the Inception API to locate object variants

      Table of Contents

      1. Overview
      2. Access the API
      3. Example output

      Overview

      The Inception Variants API enables organizations to retrieve data surrounding objects and other objects considered to be variants of the initial object in the API call.

      Access the API

      Use the following information to access the API:

      • HTTP REST endpoint: https://app.stairwell.com/v202112/variants/<FILE HASH>
      • Authentication: Pass Authorization header with your Auth Token

      Example with curl:

      curl -H "Authorization: YOURAPIKEY" https://app.stairwell.com/v202112/variants/<FILE HASH>

      Example output

      The following is an example output of what you can expect when the object is found

      Object found:

      {
          "name": "variants/64ec615c046a59c08f0ddf3fe9f93e0c9e1bed227d980628cc09600e94adcd25",
          "variants": [
              {
                  "similarity": 0.99375,
                  "sha256": "0a275e054b62efc2f809977840c196f77feff24564ce134d08af9a2eafa43896",
                  "sha1": "07e08d65196cd53af64d4c162e65bad05d3b93ef",
                  "md5": "7d2ef03934fa4d4fbf55b490416b128a"
              },
              {
                  "similarity": 0.98125,
                  "sha256": "3f2114326f2b2e5096038a675611d087c9ea61af505a15a51429973bc82037dc",
                  "sha1": "f5aa2c169cb8cc6f5af89ac86e181dbaf5c73355",
                  "md5": "0fde65789e7b4f8155483b26225aae6d"
              },
              {
                  "similarity": 0.9625,
                  "sha256": "8db65d24557d199d395c31ec82791d8a70c1807098b26c04ca3a20c32cc4b649",
                  "sha1": "cd1e77719af780c2b9724283603b73858b90f5e9",
                  "md5": "25f8b8816b2a840e56ba9da60f726110"
              },
              {
                  "similarity": 0.9625,
                  "sha256": "4773b7c78b41c5a04af56db2fdfc127ad23d3a627d46dac7f53338e5e669a4a1",
                  "sha1": "a3b1310118ad57dd5f690f961cc920a136bee621",
                  "md5": "36d3ba8d20059c57cdf9316ebb741ddb"
              },
              {
                  "similarity": 0.9625,
                  "sha256": "50354b1a93910c04b9ab80f0cc2f1032e1057e2457fa15fbb23010f375e0fe17",
                  "sha1": "c30026485424e0d52770c101de751245ef4c496d",
                  "md5": "66494a3ceab97ba461e4dd6a1c1065e8"
              },
              {
                  "similarity": 0.9625,
                  "sha256": "c00a9965c5c693b582b12bedbf5c263107195e3c85fce14a5f2148aec91a7972",
                  "sha1": "c021a0d1d1d2aebd39a8c4c85a50130a280172d5",
                  "md5": "657279b258276242aa673ddf8d21c4b3"
              },
              {
                  "similarity": 0.9625,
                  "sha256": "dfe027d10700dd47b88d572ecb693b0f64055017f16872a2a2a93b51bc318eb6",
                  "sha1": "61a1dfb4d2608cfc2ae99a72dab9478b4925597a",
                  "md5": "dd4c80afdbb63dc2feffafadef35e595"
              },
              {
                  "similarity": 0.95625,
                  "sha256": "348ab3c14c0c617eedc8be74d1f5b6a50f045d455f37aaed34957feb6614771f",
                  "sha1": "734cfe9ba262e83d3a54473623dc33437fd6b48b",
                  "md5": "d32b210a9e123f7eb4f4de383b7502a7"
              },
              {
                  "similarity": 0.96875,
                  "sha256": "b22c172ee8c52f7c6a15520986af33327bda7b3f4f1cdc4e19da8d77abbabf4e",
                  "sha1": "18e5e6fa9f911751d990cf60c25831eca125466e",
                  "md5": "b469ea6a958397cc81693bb910e452ae"
              },
              {
                  "similarity": 0.9625,
                  "sha256": "a3cb5b931f9c7f3c03585efc99398665ed6eeccf4279804fa2228c589c4cef9f",
                  "sha1": "4735a35f9540985dd50a84a88b5211bc197d5458",
                  "md5": "ab7a405196c344c4f59616883b47ac0c"
              }
          ],
          "variant_count": 10,
          "original_object": "64ec615c046a59c08f0ddf3fe9f93e0c9e1bed227d980628cc09600e94adcd25"
      }

      The following is an example output of what you can expect when there are no recorded variants found

      No variants discovered:

      {
        "name": "variants/77960b916c6ed1c856c69c0d969bc0731b7d5311d8b1138b3ef9642605638e16",
        "original_object": "77960b916c6ed1c856c69c0d969bc0731b7d5311d8b1138b3ef9642605638e16",
        "info": "No variants discovered."
      }

      The following is an example output of what you can expect when the object is not found

      Object not found:

      {
        "error": "Error when querying for object: rpc error: code = NotFound desc = no object found for identifier: sha256:\"9569b0d2bd15beb7ae6ec17a3fb656f016693971d12c8d38b4de998c320550f1\"",
        "code": 2,
        "message": "Error when querying for object: rpc error: code = NotFound desc = no object found for identifier: sha256:\"9569b0d2bd15beb7ae6ec17a3fb656f016693971d12c8d38b4de998c320550f1\"",
        "details": [
          {
            "@type": "type.googleapis.com/google.rpc.RequestInfo",
            "request_id": "fc5908a3-0bd1-41e5-add6-574e38d6f79f"
          },
          {
            "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
            "locale": "en-US",
            "message": "Error when querying for object: rpc error: code = NotFound desc = no object found for identifier: sha256:\"9569b0d2bd15beb7ae6ec17a3fb656f016693971d12c8d38b4de998c320550f1\""
          }
        ]
      }

      You may experience other messages if the hash is of improper length or type