Getting Started

Welcome to the Kloopify API. This guide covers the basics of making requests and understanding responses.

Base URL

All API requests are made to:

https://api.kloopify.com

Request Format

The API accepts JSON request bodies and returns JSON responses. Set the following headers on every request:

Content-Type: application/json
Authorization: Bearer <your-token>

Response Format

Successful responses return a 2xx status code with a JSON body. Error responses include a message describing the issue:

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

Pagination

List endpoints support pagination via offset and limit query parameters:

Rate Limiting

API requests are rate-limited per account. If you exceed the limit, you'll receive a 429 Too Many Requests response. Back off and retry after the duration indicated in the Retry-After header.

Authentication

The Kloopify API uses JWT Bearer tokens for authentication. Every request must include a valid token in the Authorization header.

Obtaining a Token

Tokens are issued by our identity provider. Authenticate with your credentials to receive an access token:

POST https://auth.kloopify.com/oauth/token
Content-Type: application/json

{
  "client_id": "<your-client-id>",
  "client_secret": "<your-client-secret>",
  "audience": "https://api.kloopify.com",
  "grant_type": "client_credentials"
}

The response includes an access_token and its expiry:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 86400
}

Using the Token

Include the token in the Authorization header of every API request:

Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

Token Expiry

Tokens expire after the duration specified in expires_in (in seconds). When a token expires, the API returns 401 Unauthorized. Request a new token and retry.

Scopes

Access is controlled by scopes embedded in the token. If your token lacks the required scope for an endpoint, the API returns 403 Forbidden.

Running a Cost Analysis

This guide walks through submitting a cost analysis job, tracking its progress, and retrieving the results.

Overview

A cost analysis is an asynchronous operation. You submit a request describing a product and its manufacturer, the system processes it in the background, and you poll for the result. Once complete, the result contains IDs you can use to fetch the full cost analysis, bill of materials, product, and manufacturer records.

Step 1: Submit the Job

Create a cost analysis by posting to the pipeline endpoint:

POST /pipeline/cost-analysis
Content-Type: application/json
Authorization: Bearer <your-token>

{
  "productName": "EcoBottle 500ml",
  "manufacturerName": "GreenPack Industries",
  "countryOfOrigin": "DE",
  "productContext": "Reusable water bottle made from recycled stainless steel",
  "pricesPaid": [
    { "price": 1250, "currency": "USD", "date": "2025-01-15" }
  ]
}

The only required fields are productName and manufacturerName. Providing additional context improves the accuracy of the analysis:

The response is 201 Created with a job object:

{
  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "type": "cost-analysis",
  "status": "pending",
  "step": null,
  "result": null,
  "started": null,
  "completed": null
}

Save the id — you'll use it to check on the job.

Step 2: Poll for Completion

Check the status of your job by its ID:

GET /pipeline/cost-analysis/{id}
Authorization: Bearer <your-token>

The status field progresses through these values:

Poll every 5–10 seconds until status is completed or failed. The step field provides a human-readable description of what the system is currently working on.

When the job completes, the response includes a result object with IDs for all generated records:

{
  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "type": "cost-analysis",
  "status": "completed",
  "step": "done",
  "result": {
    "costAnalysisId": "ca-uuid-here",
    "bomId": "bom-uuid-here",
    "productId": "product-uuid-here",
    "manufacturerId": "manufacturer-uuid-here"
  },
  "started": "2025-06-01T12:00:00.000Z",
  "completed": "2025-06-01T12:01:30.000Z"
}

If the job fails, errorMessage describes what went wrong.

Step 3: Retrieve the Results

Use the IDs from the result to fetch the generated records.

Cost Analysis

GET /cost-analysis/{costAnalysisId}
Authorization: Bearer <your-token>

Returns the cost analysis record including the shouldCostAmount and shouldCostStdErr (both in minor currency units, e.g. cents), the currency, and the analysisDate.

Bill of Materials

GET /bom/{bomId}
Authorization: Bearer <your-token>

Returns the bill of materials with a components list. Each component includes its name, type, cost, quantity, unitType, and countryOfOrigin.

To retrieve the full component details separately:

GET /bom/{bomId}/components
Authorization: Bearer <your-token>

Product and Manufacturer

The productId and manufacturerId can be used to retrieve the product and manufacturer (company) records:

GET /product/{productId}
GET /company/{manufacturerId}

Error Handling

• 404 Not Found — The job or record ID does not exist.
• 401 Unauthorized — Token is missing or expired. See the Authentication guide.
• status: "failed" — The job did not complete. Check errorMessage on the job for details and resubmit if appropriate.