Diamond Assets
API docs by Redocly

Clarity Pricing API (1.0.0)

Download OpenAPI specification:

E-mail: client.support@diamondassets.com URL: https://diamondassets.com/

Rate Limiting

We apply rate limiting to all API calls. Rate limits apply either to your IP address (for unauthenticated calls) or your API key. If you exceed your rate limit, you'll receive a 429 response. You can always inspect the status of your rate limit by looking at the response headers which are included in every response:

Header name Description
X-RateLimit-Limit The maximum number of requests allowed in the current time window.
X-RateLimit-Remaining The number of requests remaining in the current time window.
X-RateLimit-Used The number of requests you have made in the current time window.
X-RateLimit-Reset The time at which the current rate limit window resets, in UTC epoch seconds.

API keys

API keys are used to authenticate requests and authorize access to restricted operations. The API key workflow is designed to balance ease of onboarding with strong access controls.

Workflow Overview:

  • Creation (Unauthenticated): Users can create API keys without prior authentication. Newly created keys are in an inactive state and cannot be used for accessing protected endpoints until approved.
  • Review and Approval: Inactive API keys require manual review by an administrator. Once approved, the key becomes active and can be used for authenticated and restricted operations.
  • Token Rotation: Users can rotate (regenerate) the token associated with their API key at any time. This invalidates the previous token and issues a new one, without affecting the key's approval status or permissions.

API keys can be used by submitting their token in the X-API-Key header.

Create API key

Creates a new API key in inactive state.

The newly created API key will be in an inactive state by default and cannot be used to access protected resources until it is manually reviewed and approved by an administrator.

However, inactive keys can still be used to manage API key related operations.

You will receive a notification once the review process is complete.

The token for the API key is returned in the meta data. Make sure to save it, as it cannot be retrieved again.

Request Body schema: application/vnd.api+json
required
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "jsonapi": {
    },
  • "data": {
    },
  • "meta": {
    }
}

Get API key

Returns an API key.

You can either specify the API key ID directly in the URL or use current as ID in order to retrieve the currently used API key.

Authorizations:
ApiKey
path Parameters
required
API key ID (string) or Current (string)

Responses

Response samples

Content type
application/vnd.api+json
{
  • "jsonapi": {
    },
  • "data": {
    }
}

Rotate API key secret

Rotates the secret of an API key and returns a new token.

You can either specify the API key ID directly in the URL or use current as ID in order to rotate the currently used API key.

The old token may remain usable for a short period due to caching, but it is eventually invalidated. Token rotation is recommended as a security best practice to limit the lifespan of credentials.

All other properties of the API key remain unchanged.

Authorizations:
ApiKey
path Parameters
required
API key ID (string) or Current (string)
Request Body schema: application/vnd.api+json
required
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "jsonapi": {
    },
  • "data": {
    },
  • "meta": {
    }
}

Pricing reports

Create pricing report

Creates a new pricing report based on model queries.

Accepts one or more model queries, each specifying model attributes and devices. For each query, the system attempts to find matching models according to a prioritized matching strategy:

  1. If one or more models match all specified criteria, the model with the lowest unit price is selected, and the match type is set to "exact".
  2. If no exact matches are found, but one or more models match the model identifier, the model with the lowest unit price is selected, and the match type is set to "approximate".
  3. If no matches are found at all, the response includes a result with match type not_found for that query.

For each matched model, the response provides detailed information including pricing adjusted for the number of requested devices.

The total pricing values in the response account for the requested number of devices per model query by multiplying the unit price accordingly.

The operation returns a summary including the total number of hits and misses and the aggregated total value (sum of all total prices).

Request Body schema:
required
type
required
string
Value: "pricing_report"
required
object

Responses

Request samples

Content type
{
  • "type": "pricing_report",
  • "attributes": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "jsonapi": {
    },
  • "data": {
    }
}