> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scanoss.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SCANOSS API

> Provides cryptographic intelligence for software components including algorithm detection, encryption hints and cryptographic assessment across version ranges.

## Prerequisites

Before using the SCANOSS API, ensure you have:

* SCANOSS API key
* curl: Command-line tool (pre-installed on Linux/macOs)
* jq (optional): JSON processor for readable output

## Authentication Setup

Configure your API key as an environment variable:

```bash theme={null}
# Set API key
export SCANOSS_API_KEY="your-api-key-here"

# Verify configuration
echo $SCANOSS_API_KEY
```

**Persistent Configuration (Optional)**:

```bash theme={null}
# Add to shell profile for persistence
echo 'export SCANOSS_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc
```

## GetComponentAlgorithms

Retrieves cryptographic algorithms detected in a single software component identified in a software component.

### Request Format

See [Common API Types](https://github.com/scanoss/papi/blob/49b124f3075fc8776630ba1e068646bda23f174a/protobuf/scanoss/api/common/v2/README.md#componentrequest) for `ComponentRequest` documentation.

### HTTP Request Example

```bash theme={null}
# Get cryptographic algorithms for a component
curl -X GET 'https://api.scanoss.com/v2/cryptography/algorithms/component?purl=pkg:github/scanoss/engine' \
  -H "X-Api-Key: $SCANOSS_API_KEY" | jq
```

### Response Examples

#### Successful Response

```bash theme={null}
{
  "component": {
    "purl": "pkg:github/scanoss/engine",
    "version": "5.0.0",
    "requirement": ">=5.0.0",
    "algorithms": [
      {
        "algorithm": "AES",
        "strength": "Strong"
      },
      {
        "algorithm": "RSA",
        "strength": "Strong"
      }
    ]
  },
  "status": {
    "status": "SUCCESS",
    "message": "Algorithms Successfully retrieved"
  }
}
```

#### Error Response - Component Not Found

```bash theme={null}
{
  "component": {
    "purl": "pkg:github/unknown/component",
    "version": "",
    "requirement": ">=1.0.0",
    "algorithms": [],
    "error_message": "Component not found in database",
    "error_code": "COMPONENT_NOT_FOUND"
  },
  "status": {
    "status": "SUCCESS",
    "message": "Request processed"
  }
}
```

#### Error Response - Invalid PURL

```bash theme={null}
{
  "component": {
    "purl": "invalid-purl-format",
    "version": "",
    "requirement": ">=1.0.0",
    "algorithms": [],
    "error_message": "Invalid PURL format provided",
    "error_code": "INVALID_PURL"
  },
  "status": {
    "status": "SUCCESS",
    "message": "Request processed"
  }
}
```

### Error Handling

Component responses include optional error fields when issues occur during processing:

* `error_message`: Human-readable description of the error
* `error_code`: Machine-readable error code for programmatic handling

#### Error Codes

* INVALID\_PURL: The provided PURL format is invalid
* COMPONENT\_NOT\_FOUND: The component was not found in the database
* NO\_INFO: No cryptographic information available for the component
* INVALID\_SEMVER: The provided semantic version or requirement is invalid

> When a component-level error occurs, the overall response status remains "SUCCESS" since the request was processed. Individual component errors are indicated within the component block itself.

## GetComponentsAlgorithms

See [Common API Types](https://github.com/scanoss/papi/blob/49b124f3075fc8776630ba1e068646bda23f174a/protobuf/scanoss/api/common/v2/README.md#componentsrequest) for `ComponentsRequest` documentation.

### HTTP Request Example

```bash theme={null}
curl -X POST 'https://api.scanoss.com/v2/cryptography/algorithms/components' \
  -H 'Content-Type: application/json' \
  -H "X-Api-Key: $SCANOSS_API_KEY" \
  -d '{
    "components": [
      {"purl": "pkg:github/scanoss/engine", "requirement": ">=5.0.0"},
      {"purl": "pkg:github/scanoss/scanoss.py", "requirement": "~1.30.0"}
    ]
  }' | jq
```

### Response Examples

#### Successful Response

```bash theme={null}
{
  "components": [
    {
      "purl": "pkg:github/scanoss/engine",
      "requirement": ">=5.0.0",
      "version": "5.0.0",
      "algorithms": [
        {
          "algorithm": "AES",
          "strength": "Strong"
        },
        {
          "algorithm": "RSA",
          "strength": "Strong"
        }
      ]
    },
    {
      "purl": "pkg:github/scanoss/scanoss.py",
      "requirement": "~1.30.0",
      "version": "v1.30.0",
      "algorithms": [
        {
          "algorithm": "SHA-256",
          "strength": "Strong"
        }
      ]
    }
  ],
  "status": {
    "status": "SUCCESS",
    "message": "Algorithms Successfully retrieved"
  }
}
```

#### Mixed Response with Error

```bash theme={null}
{
  "components": [
    {
      "purl": "pkg:github/scanoss/engine",
      "requirement": ">=5.0.0",
      "version": "5.0.0",
      "algorithms": [
        {
          "algorithm": "AES",
          "strength": "Strong"
        }
      ]
    },
    {
      "purl": "pkg:github/unknown/component",
      "requirement": ">=1.0.0",
      "version": "",
      "algorithms": [],
      "error_message": "Component not found in database",
      "error_code": "COMPONENT_NOT_FOUND"
    }
  ],
  "status": {
    "status": "SUCCESS",
    "message": "Batch request processed"
  }
}
```

## GetComponentAlgorithmsInRange

Analyses a single software component across specified version ranges and returns all cryptographic algorithms detected along with the versions where they appear. This is useful for tracking cryptographic evolution across component development.

### Request Format

See [Common API Types](https://github.com/scanoss/papi/blob/49b124f3075fc8776630ba1e068646bda23f174a/protobuf/scanoss/api/common/v2/README.md#componentrequest) for `ComponentRequest` documentation.

### HTTP Request Example

```bash theme={null}
curl -X GET 'https://api.scanoss.com/v2/cryptography/algorithms/range/component?purl=pkg:github/scanoss/engine&requirement=>=1.0.0' \
  -H "X-Api-Key: $SCANOSS_API_KEY" | jq
```

### Response Format

The method returns comprehensive algorithm information including:

* `component` object: Contains the component analysis results
  * `purl` field: the requested component
  * `versions` array: List of component versions where cryptographic algorithms were detected
  * `algorithms` array: List of all cryptographic algorithms found across the version range
* `status` field: Response status indicating success or failure

Each algorithm object contains:

* Algorithm name and strength classification
* Detection metadata and analysis results

### Response Examples

#### Component with Algorithms Across Versions

```json theme={null}
{
  "component": {
    "purl": "pkg:github/scanoss/engine",
    "versions": ["1.0.0", "2.0.0", "3.0.0", "5.0.0"],
    "algorithms": [
      {
        "algorithm": "AES",
        "strength": "Strong"
      },
      {
        "algorithm": "RSA",
        "strength": "Strong"
      },
      {
        "algorithm": "MD5",
        "strength": "Weak"
      }
    ]
  },
  "status": {
    "status": "SUCCESS",
    "message": "Algorithms in range Successfully retrieved"
  }
}
```

#### Component with No Cryptographic Algorithms

```bash theme={null}
{
  "component": {
    "purl": "pkg:github/example/simple-utility",
    "versions": [],
    "algorithms": [],
    "error_message": "Component not found: 'pkg:github/example/simple-utility'",
    "error_code": "COMPONENT_NOT_FOUND"
  },
  "status": {
    "status": "SUCCESS",
    "message": "Algorithms in range Successfully retrieved"
  }
}
```

## GetComponentsAlgorithmsInRange

Batch version of GetComponentAlgorithmsInRange - analyses multiple components across version ranges and returns cryptographic algorithms for each in a single request.

### Request Format

See [Common API Types](https://github.com/scanoss/papi/blob/49b124f3075fc8776630ba1e068646bda23f174a/protobuf/scanoss/api/common/v2/README.md#componentsrequest) for `ComponentsRequest` documentation.

### HTTP Request Example

```bash theme={null}
curl -X POST 'https://api.scanoss.com/v2/cryptography/algorithms/range/components' \
  -H 'Content-Type: application/json' \
  -H "X-Api-Key: $SCANOSS_API_KEY" \
  -d '{
    "components": [
      {"purl": "pkg:github/scanoss/engine", "requirement": ">=1.0.0"},
      {"purl": "pkg:github/scanoss/scanoss.py", "requirement": "~1.30.0"}
    ]
  }'
```

## ComponentVersionsInRange

Analyses a software component and returns lists of versions that either contain cryptographic algorithms or don't, helping assess cryptographic presence across component evolution.

### Request Format

See [Common API Types](https://github.com/scanoss/papi/blob/49b124f3075fc8776630ba1e068646bda23f174a/protobuf/scanoss/api/common/v2/README.md#componentrequest) for `ComponentRequest` documentation.

### HTTP Request Example

```bash theme={null}
curl -X GET 'https://api.scanoss.com/v2/cryptography/algorithms/versions/range/component?purl=pkg:github/scanoss/engine&requirement=>=1.0.0' \
  -H "X-Api-Key: $SCANOSS_API_KEY" | jq
```

### Response Example

```bash theme={null}
{
  "component": {
    "purl": "pkg:github/scanoss/engine",
    "versions_with": ["2.0.0", "3.0.0", "4.0.0", "5.0.0"],
    "versions_without": ["1.0.0", "1.5.0"]
  },
  "status": {
    "status": "SUCCESS",
    "message": "Version ranges Successfully retrieved"
  }
}
```

## ComponentHintsInRange

Retrieves cryptographic hints for a single component, providing insights about cryptographic protocols, libraries, SDKs and frameworks used by the component.

### Request Format

See [Common API Types](https://github.com/scanoss/papi/blob/49b124f3075fc8776630ba1e068646bda23f174a/protobuf/scanoss/api/common/v2/README.md#componentrequest) for `ComponentRequest` documentation.

### HTTP Request Example

```bash theme={null}
curl -X GET 'https://api.scanoss.com/v2/cryptography/hints/component?purl=pkg:github/scanoss/engine&requirement=>=5.0.0' \
  -H "X-Api-Key: $SCANOSS_API_KEY" | jq
```

### Response Format

The method returns comprehensive cryptographic hint information including:

* `purl` field: the requested component
* `hints` array: List of cryptographic hints detected in the component
* `version` field: Shows the specific version that was analyzed
* `status` field: Response status indicating success or failure

Each hint object contains:

* Unique identifier and name of the cryptographic entity
* Description of the detected usage or implementation
* Category classification (protocol/library/sdk/framework)
* Reference URL and PURL information

Hint Categories

Hints are classified into the following categories:

* `protocol`: Cryptographic protocols (e.g., TLS, SSH, HTTPS)
* `library`: Cryptographic libraries (e.g., OpenSSL, Bouncy Castle)
* `sdk`: Software Development Kits with cryptographic capabilities
* `framework`: Frameworks that include cryptographic functionality

### Response Examples

#### Component with Cryptographic Hints

```json theme={null}
{
  "component": {
    "purl": "pkg:github/scanoss/engine",
    "version": "5.0.0",
    "hints": [
      {
        "id": "openssl-hint-001",
        "name": "OpenSSL",
        "description": "Industry standard cryptographic library providing SSL/TLS protocols",
        "category": "library",
        "url": "https://www.openssl.org/",
        "purl": "pkg:generic/openssl@3.0.0"
      },
      {
        "id": "tls-protocol-001",
        "name": "TLS 1.3",
        "description": "Transport Layer Security protocol implementation",
        "category": "protocol",
        "url": "https://tools.ietf.org/html/rfc8446",
        "purl": ""
      }
    ]
  },
  "status": {
    "status": "SUCCESS",
    "message": "Cryptographic hints Successfully retrieved"
  }
}
```

#### Component with No Cryptographic Hints

```json theme={null}
{
  "component": {
    "purl": "pkg:github/example/simple-utility",
    "version": "1.0.0",
    "hints": [],
    "error_message": "No info found for: pkg:github/example/simple-utility",
    "error_code": "NO_INFO"
    
  },
  "status": {
    "status": "SUCCESS",
    "message": "Cryptographic hints Successfully retrieved"
  }
}
```

## ComponentsHintsInRange

Batch version of ComponentHintsInRange - retrieves cryptographic hints for multiple components in a single request, providing insights into cryptographic dependencies across multiple components.

### Request Format

See [Common API Types](https://github.com/scanoss/papi/blob/49b124f3075fc8776630ba1e068646bda23f174a/protobuf/scanoss/api/common/v2/README.md#componentsrequest) for `ComponentsRequest` documentation.

### HTTP Request Example

```bash theme={null}
curl -X POST 'https://api.scanoss.com/v2/cryptography/hints/components' \
  -H 'Content-Type: application/json' \
  -H "X-Api-Key: $SCANOSS_API_KEY" \
  -d '{
    "components": [
      {"purl": "pkg:github/scanoss/engine", "requirement": ">=5.0.0"},
      {"purl": "pkg:github/scanoss/scanoss.py", "requirement": "~1.30.0"}
    ]
  }' | jq
```