LUCAS API

The LUCAS API provides programmatic access to physical asset verification. Request inspections, retrieve cryptographically signed proofs, and integrate real-world condition data into your applications.

https://api.lucas.app/v1

Verified Data

GPS-stamped, cryptographically signed

On-chain Ready

Anchor proofs to any EVM chain

Real-time

Webhooks for instant updates

SDKs

JavaScript, Python, Go

Quick Start

curl https://api.lucas.app/v1/proofs \
  -H "Authorization: Bearer lcs_live_xxx" \
  -H "Content-Type: application/json"import Lucas from '@lucas/sdk';

const lucas = new Lucas('lcs_live_xxx');
const proofs = await lucas.proofs.list();

console.log(proofs);import lucas

client = lucas.Client('lcs_live_xxx')
proofs = client.proofs.list()

print(proofs)

Install SDK: npm install @lucas/sdk

Response 200 OK

{
  "object": "list",
  "data": [
    {
      "proof_id": "prf_2x8K9mNqLr",
      "asset_id": "ast_marina_1205",
      "status": "verified",
      "condition_score": 87
    }
  ]
}

Authentication

The LUCAS API uses API keys to authenticate requests. You can view and manage your API keys in the Dashboard. All requests must be made over HTTPS.

API Key Types

Key Prefix	Environment	Description
lcs_live_	Production	Live data, real inspections
lcs_test_	Sandbox	Test data, no real inspections

Example Request

curl https://api.lucas.app/v1/proofs \
  -H "Authorization: Bearer lcs_live_xxx"

Error Response401

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key"
  }
}

LUCAS Proofs

A LUCAS Proof is a cryptographically signed, immutable record of a physical asset's condition. Each proof contains inspection data, photos, GPS verification, and condition scores.

GET/proofsList all proofs

GET/proofs/{id}Retrieve a proof

POST/proofs/requestRequest inspection

The Proof Object

Attribute	Type	Description
proof_id	string	Unique identifier
asset_id	string	Associated asset
condition_score	integer	Score 0-100
issues	array	Detected issues
signature	object	Cryptographic signature

Response200 OK

{
  "proof_id": "prf_2x8K9mNqLr",
  "asset_id": "ast_marina_1205",
  "status": "verified",
  "condition": {
    "score": 87,
    "grade": "A"
  },
  "issues": [
    {
      "category": "hvac",
      "severity": "low",
      "description": "AC filter needs replacement"
    }
  ],
  "signature": {
    "hash": "0x8f3a...",
    "anchor_tx": "0xabc..."
  },
  "created_at": "2024-12-05T14:32:00Z"
}

Assets

Assets represent physical properties registered in LUCAS. Each asset has a unique identifier and can have multiple proofs associated over time.

GET/assetsList all assets

GET/assets/{id}Retrieve an asset

POST/assetsRegister new asset

The Asset Object

Attribute	Type	Description
asset_id	string	Unique identifier
name	string	Property name
type	string	apartment, villa, commercial
address	object	Location details
latest_proof	object	Most recent proof

Response200 OK

{
  "asset_id": "ast_marina_1205",
  "name": "Marina Tower Unit 1205",
  "type": "apartment",
  "address": {
    "building": "Marina Tower",
    "unit": "1205",
    "area": "Dubai Marina"
  },
  "latest_proof": {
    "proof_id": "prf_2x8K9mNqLr",
    "score": 87
  }
}

Webhooks

Receive real-time notifications when events occur. Configure webhook endpoints in your Dashboard.

Event Types

Event	Description
proof.created	New proof generated
proof.verified	Proof anchored on-chain
inspection.completed	Inspection finished
issue.detected	Critical issue found

Webhook Payload

{
  "id": "evt_1234567890",
  "type": "proof.created",
  "data": {
    "proof_id": "prf_2x8K9mNqLr",
    "asset_id": "ast_marina_1205",
    "condition_score": 87
  }
}

Verify signatures using X-Lucas-Signature header

SDKs & Libraries

Official client libraries for all major languages. All SDKs are open source.

JavaScript / TypeScript

npm install @lucas/sdk

Python

pip install lucas

Go

go get github.com/lucas/go

Ruby

gem install lucas

Usage Example

import Lucas from '@lucas/sdk';

const lucas = new Lucas({
  apiKey: process.env.LUCAS_API_KEY
});

// List all proofs for an asset
const proofs = await lucas.proofs.list({
  asset_id: 'ast_marina_1205'
});

// Request a new inspection
const inspection = await lucas.inspections.create({
  asset_id: 'ast_marina_1205',
  type: 'standard'
});