Skip to content

Dashboard — Integration API Reference

This document describes the server-to-server Integration API exposed by the WEARFITS Dashboard. It is intended for backend systems — such as the legacy product system or custom integrations — that need to report usage events and synchronise data back to the Dashboard.

Overview

Property Value
Base URL https://dash.wearfits.com
Authentication Handshake token in the request body (handshake field)
Content-Type application/json
Method POST for all integration endpoints

All requests must include a valid handshake token. If the token is missing or does not match, the API returns 401 Unauthorized.

Endpoints

POST /api/v1/integration/increase-tryon-usage-count

Increments the try-on usage counter for a user. AR and AI try-ons are tracked with separate counters.

Request body

Field Type Required Description
handshake string Yes Security handshake token.
type string Yes Type of try-on: "AR" or "AI".
count number Yes Positive integer — the amount to add to the counter.
user_id string No* The user whose counter to update.
api_key string No* The API key associated with the try-on. If both user_id and api_key are provided, the API verifies ownership before updating.

At least one of user_id or api_key must be present in every request.

Response — 200 OK

{
  "success": true,
  "message": "AR tryon usage increased successfully",
  "warnings": ["Usage limit exceeded for this period"]
}

The warnings array is only present when a soft usage limit has been exceeded. The operation still succeeds; warnings serve as informational notices.

Error codes

Code Meaning
400 Missing or invalid fields in the request body.
401 Handshake token is invalid.
403 API key not found, or key ownership does not match the supplied user_id.

Example — increment AR try-on count

curl -X POST https://dash.wearfits.com/api/v1/integration/increase-tryon-usage-count \
  -H "Content-Type: application/json" \
  -d '{
    "handshake": "<your-handshake-token>",
    "type": "AR",
    "count": 1,
    "api_key": "footwear_xxxxxxxxxxxx"
  }'

Example — increment AI try-on count by user ID

curl -X POST https://dash.wearfits.com/api/v1/integration/increase-tryon-usage-count \
  -H "Content-Type: application/json" \
  -d '{
    "handshake": "<your-handshake-token>",
    "type": "AI",
    "count": 3,
    "user_id": "usr_abc123"
  }'

POST /api/v1/integration/increase-api-key-usage-count

Increments the general API usage counter for a specific key. This data feeds the API Calls metric visible in the Dashboard's Usage Analytics section.

Request body

Field Type Required Description
handshake string Yes Security handshake token.
api_key string Yes The API key whose usage counter to increment.
count number Yes Positive integer — the amount to add.
user_id string No If provided, the API verifies that the key belongs to this user before updating.

Response — 200 OK

{
  "success": true,
  "message": "API key usage increased successfully"
}

Example

curl -X POST https://dash.wearfits.com/api/v1/integration/increase-api-key-usage-count \
  -H "Content-Type: application/json" \
  -d '{
    "handshake": "<your-handshake-token>",
    "api_key": "footwear_xxxxxxxxxxxx",
    "count": 5,
    "user_id": "usr_abc123"
  }'

POST /api/v1/integration/set-user-product-number

Synchronises the total number of products in a user's catalog. Use this endpoint to keep the Dashboard's product count in sync with the state of an external product system.

Request body

Field Type Required Description
handshake string Yes Security handshake token.
user_id string Yes The user whose product count to update.
value number Yes The total product count as a non-negative integer (replaces the stored value rather than adding to it).

Response — 200 OK

{
  "success": true,
  "message": "Product count set successfully",
  "warnings": ["Product limit exceeded for current plan"]
}

As with try-on usage, a warnings array is included when the user's plan limit is exceeded. The value is still updated.

Example

curl -X POST https://dash.wearfits.com/api/v1/integration/set-user-product-number \
  -H "Content-Type: application/json" \
  -d '{
    "handshake": "<your-handshake-token>",
    "user_id": "usr_abc123",
    "value": 150
  }'

Rate Limiting & Security

Rate limiting: All integration endpoints are rate-limited. If your system exceeds the allowed request rate, the API returns 429 Too Many Requests. Implement exponential back-off or a retry queue to handle this gracefully.

CORS: Endpoints support cross-origin requests from authorised domains under .wearfits.com.

Payload size: Request bodies must not exceed 16 KB.

Error Format

All error responses follow a consistent structure:

{
  "success": false,
  "error": "Descriptive error message"
}

HTTP status codes

Code Meaning
400 Bad Request Validation failure — missing required fields or incorrect data types.
401 Unauthorized Handshake token is missing or does not match.
403 Forbidden Authentication succeeded but the operation is not permitted (e.g., the API key is inactive or owned by a different user).
405 Method Not Allowed A GET request was sent to an endpoint that only accepts POST.
429 Too Many Requests Rate limit exceeded — back off and retry.
500 Internal Server Error Unexpected failure on the server side.