API Reference

Complete API reference for De. Query system.

Base URL

https://api.dedot.io/v1/queries

Authentication

All requests require authentication via Bearer token:

typescript

Authorization: Bearer YOUR_API_KEY
X-Workspace-ID: YOUR_WORKSPACE_ID

Discovery Queries

Discover Services

Find services matching basic criteria.

Endpoint: POST /discovery/discover

Request Body:

typescript

{
  serviceType: 'WAREHOUSE' | 'CARRIER' | 'HUB' | 'TERMINAL' | 'IOTSP'
  location?: {
    coordinates: [number, number]  // [lat, lng]
    maxDistance?: number           // km
  }
  filters?: Record<string, any>
  limit?: number                   // Default: 20
  offset?: number                  // Default: 0
}

Response:

typescript

{
  error: boolean
  status: string
  services: ServiceRegistryEntry[]
  total: number
  executionTimeMs: number
}

Example:

typescript

const result = await fetch('https://api.dedot.io/v1/realm/queries/discovery/discover', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'X-Workspace-ID': 'YOUR_WORKSPACE_ID',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    serviceType: 'WAREHOUSE',
    location: {
      coordinates: [40.7128, -74.0060],
      maxDistance: 50
    }
  })
})

Advanced Discovery

Multi-criteria search with capability matching.

Endpoint: POST /discovery/advanced

Request Body:

typescript

{
  serviceType: ServiceType
  location?: {
    coordinates: [number, number]
    maxDistance?: number
  }
  capabilities?: {
    // Flexible schema based on service type
    [key: string]: any
  }
  filters?: Record<string, any>
  performanceThresholds?: {
    onTimeDeliveryRate?: number
    orderAccuracy?: number
    overallScore?: number
  }
  limit?: number
  offset?: number
}

Response: Same as Discover Services

Example:

typescript

const result = await client.realm.queries.discovery.advancedDiscover({
  serviceType: 'WAREHOUSE',
  location: {
    coordinates: [40.7128, -74.0060],
    maxDistance: 100
  },
  capabilities: {
    environmental: {
      temperatureControlled: true,
      temperatureRange: { min: -20, max: 5 }
    },
    handling: {
      specialHandling: ['FRAGILE', 'HAZMAT']
    }
  },
  performanceThresholds: {
    onTimeDeliveryRate: 0.95,
    overallScore: 85
  }
})

Find Available Services

Find services with verified capacity.

Endpoint: POST /discovery/available

Request Body:

typescript

{
  criteria: QueryCriteria
  minCapacity?: number
  capacityType?: string  // e.g., 'STORAGE_SLOTS'
}

Response:

typescript

{
  error: boolean
  status: string
  services: Array<ServiceRegistryEntry & { capacity: Capacity }>
  total: number
  executionTimeMs: number
}

Get Service

Get specific service by composite ID.

Endpoint: GET /discovery/:compositeId

Parameters:

compositeId - Format: lsp:serviceId

Response:

typescript

{
  error: boolean
  status: string
  service: ServiceRegistryEntry
}

Count Services

Count services matching criteria.

Endpoint: POST /discovery/count

Request Body: Same as Discover Services

Response:

typescript

{
  error: boolean
  status: string
  count: number
}

Matching Queries

Match Order to Services

Intelligently match order to optimal service providers.

Endpoint: POST /matching/match

Request Body:

typescript

{
  serviceTypes: ServiceType[]
  delivery: {
    country?: string
    city?: string
    region?: string
    areaType?: 'URBAN' | 'SUBURBAN' | 'RURAL'
    coordinates?: [number, number]
  }
  items?: Array<{
    sku: string
    quantity: number
    weight?: number
    volume?: number
    requiresColdChain?: boolean
    requiresHazmatHandling?: boolean
    [key: string]: any
  }>
  requirements?: string[]
  strategy: 'BALANCED' | 'COST_OPTIMIZED' | 'SPEED_OPTIMIZED' | 'QUALITY_OPTIMIZED'
}

Response:

typescript

{
  error: boolean
  status: string
  recommendations: Array<{
    service: ServiceRegistryEntry
    serviceType: ServiceType
    scores: {
      capability: number      // 0-100
      proximity: number       // 0-100
      capacity: number        // 0-100
      performance: number     // 0-100
      cost: number           // 0-100
      overall: number        // 0-100
    }
    reasoning: string[]
    estimatedCost?: number
    estimatedDuration?: number
  }>
  totalCandidates: number
  strategy: string
}

Example:

typescript

const match = await client.realm.queries.matching.match({
  serviceTypes: ['WAREHOUSE'],
  delivery: {
    country: 'US',
    city: 'New York',
    coordinates: [40.7128, -74.0060]
  },
  items: [
    { sku: 'PROD-001', quantity: 10, requiresColdChain: true }
  ],
  requirements: ['SAME_DAY_DELIVERY', 'COLD_CHAIN'],
  strategy: 'BALANCED'
})

console.log('Best match:', match.recommendations[0])
console.log('Overall score:', match.recommendations[0].scores.overall)

Capacity Queries

Query Service Capacity

Get real-time capacity for a service.

Endpoint: POST /capacity/query

Request Body:

typescript

{
  lsp: string
  serviceId: string
  capacityType: string  // e.g., 'STORAGE_SLOTS', 'PALLET_POSITIONS'
}

Response:

typescript

{
  error: boolean
  status: string
  capacity: {
    type: string
    total: number
    used: number
    available: number
    reserved?: number
    utilizationRate: number  // 0-100
    unit: string
    lastUpdated: string
  }
}

Example:

typescript

const capacity = await client.realm.queries.capacity.query({
  lsp: 'lsp-001',
  serviceId: 'warehouse-123',
  capacityType: 'STORAGE_SLOTS'
})

console.log(`Available: ${capacity.available}/${capacity.total}`)
console.log(`Utilization: ${capacity.utilizationRate}%`)

Batch Query Capacities

Query multiple service capacities efficiently.

Endpoint: POST /capacity/batch

Request Body:

typescript

{
  queries: Array<{
    lsp: string
    serviceId: string
    capacityType: string
  }>
}

Response:

typescript

{
  error: boolean
  status: string
  capacities: Record<string, Capacity>  // Key: "lsp:serviceId"
  total: number
}

Example:

typescript

const result = await client.realm.queries.capacity.batchQuery({
  queries: [
    { lsp: 'lsp-001', serviceId: 'warehouse-123', capacityType: 'STORAGE_SLOTS' },
    { lsp: 'lsp-001', serviceId: 'warehouse-456', capacityType: 'STORAGE_SLOTS' },
    { lsp: 'lsp-002', serviceId: 'warehouse-789', capacityType: 'PALLET_POSITIONS' }
  ]
})

for (const [key, capacity] of Object.entries(result.capacities)) {
  console.log(`${key}: ${capacity.available} available`)
}

Query All Capacities

Get all capacity types for a service.

Endpoint: GET /capacity/:lsp/:serviceId/all

Response:

typescript

{
  error: boolean
  status: string
  capacities: Capacity[]
  total: number
}

Invalidate Cache

Manually invalidate capacity cache.

Endpoint: DELETE /capacity/:lsp/:serviceId/cache

Query Parameters:

capacityType (optional) - Specific capacity type to invalidate

Response:

typescript

{
  error: boolean
  status: string
  message: string
}

Get Cache Stats

Get capacity cache statistics.

Endpoint: GET /capacity/cache/stats

Response:

typescript

{
  error: boolean
  status: string
  size: number
  entries: Array<{
    key: string
    expiresIn: number  // seconds
  }>
}

Performance Queries

Sync Performance Data

Sync performance summary for a service.

Endpoint: POST /performance/sync

Request Body:

typescript

{
  lsp: string
  serviceId: string
  performance: {
    onTimeDeliveryRate: number       // 0-1
    orderAccuracy: number            // 0-1
    averageProcessingTime: number    // seconds
    damageRate: number               // 0-1
    customerSatisfaction?: number    // 0-5
    overallScore: number             // 0-100
  }
}

Response:

typescript

{
  error: boolean
  status: string
  message: string
}

Batch Sync Performance

Sync performance for multiple services.

Endpoint: POST /performance/sync/batch

Request Body:

typescript

{
  lsp: string
  services: Array<{
    serviceId: string
    performance: SPPerformanceSummary
  }>
}

Response:

typescript

{
  error: boolean
  status: string
  synced: number
  failed: number
}

Get Performance Data

Get current performance metrics for a service.

Endpoint: GET /performance/:lsp/:serviceId

Response:

typescript

{
  error: boolean
  status: string
  performance: {
    onTimeDeliveryRate: number
    orderAccuracy: number
    averageProcessingTime: number
    damageRate: number
    customerSatisfaction?: number
    overallScore: number
    lastUpdated: string
  }
}

Example:

typescript

const performance = await client.realm.queries.performance.get({
  lsp: 'lsp-001',
  serviceId: 'warehouse-123'
})

console.log('Performance Metrics:', {
  onTimeRate: `${performance.onTimeDeliveryRate * 100}%`,
  accuracy: `${performance.orderAccuracy * 100}%`,
  score: performance.overallScore
})

Pricing Queries

Get Pricing Rules

Get all pricing rules for a service.

Endpoint: GET /pricing/:lsp/:serviceId

Response:

typescript

{
  error: boolean
  status: string
  pricing: PricingRule[]
  total: number
}

Estimate Cost

Get cost estimate for an order.

Endpoint: POST /pricing/estimate

Request Body:

typescript

{
  lsp: string
  serviceId: string
  serviceType: ServiceType
  orderContext: {
    items?: Array<{
      sku: string
      quantity: number
    }>
    requirements?: string[]
    deliveryLocation?: {
      country?: string
      city?: string
      areaType?: string
    }
    strategy?: string
  }
}

Response:

typescript

{
  error: boolean
  status: string
  estimate: {
    totalCost: number
    currency: string
    breakdown: {
      baseRate: number
      surcharges: number
      taxes: number
      fees: number
    }
    appliedRules: string[]
  }
}

Example:

typescript

const estimate = await client.realm.queries.pricing.estimate({
  lsp: 'lsp-001',
  serviceId: 'warehouse-123',
  serviceType: 'WAREHOUSE',
  orderContext: {
    items: [
      { sku: 'PROD-001', quantity: 10 },
      { sku: 'PROD-002', quantity: 5 }
    ],
    requirements: ['SAME_DAY_DELIVERY'],
    deliveryLocation: {
      country: 'US',
      city: 'New York'
    }
  }
})

console.log(`Total: $${estimate.totalCost}`)
console.log('Breakdown:', estimate.breakdown)

Compare Pricing

Compare pricing across multiple services.

Endpoint: POST /pricing/compare

Request Body:

typescript

{
  services: Array<{
    lsp: string
    serviceId: string
    serviceType: ServiceType
  }>
  orderContext: {
    items?: Array<{ sku: string; quantity: number }>
    requirements?: string[]
    deliveryLocation?: {
      country?: string
      city?: string
    }
  }
}

Response:

typescript

{
  error: boolean
  status: string
  comparisons: Array<{
    lsp: string
    serviceId: string
    totalCost: number
    currency: string
    breakdown: {
      baseRate: number
      surcharges: number
      taxes: number
      fees: number
    }
  }>
  cheapest?: {
    lsp: string
    serviceId: string
    totalCost: number
  }
}

Example:

typescript

const comparison = await client.realm.queries.pricing.compare({
  services: [
    { lsp: 'lsp-001', serviceId: 'warehouse-123', serviceType: 'WAREHOUSE' },
    { lsp: 'lsp-002', serviceId: 'warehouse-456', serviceType: 'WAREHOUSE' },
    { lsp: 'lsp-003', serviceId: 'warehouse-789', serviceType: 'WAREHOUSE' }
  ],
  orderContext: {
    items: [{ sku: 'PROD-001', quantity: 10 }],
    requirements: ['SAME_DAY_DELIVERY']
  }
})

console.log('Cheapest option:', comparison.cheapest)

Invalidate Pricing Cache

Manually invalidate pricing cache.

Endpoint: DELETE /pricing/:lsp/:serviceId/cache

Response:

typescript

{
  error: boolean
  status: string
  message: string
}

Get Pricing Cache Stats

Get pricing cache statistics.

Endpoint: GET /pricing/cache/stats

Response:

typescript

{
  error: boolean
  status: string
  size: number
  entries: string[]
}

Type Definitions

ServiceRegistryEntry

typescript

interface ServiceRegistryEntry {
  compositeId: string
  lsp: string
  serviceId: string
  serviceType: SPType
  name: string
  description?: string
  
  location: {
    coordinates: [number, number]
    address: {
      street?: string
      city: string
      region?: string
      country: string
      postalCode?: string
    }
    timezone: string
  }
  
  capabilities: Record<string, any>
  
  coverage?: {
    geographic: Array<{
      type: 'COUNTRY' | 'REGION' | 'CITY'
      value: string
    }>
    serviceTypes: string[]
  }
  
  performance?: {
    onTimeDeliveryRate: number
    orderAccuracy: number
    overallScore: number
    lastUpdated: Date
  }
  
  status: 'ACTIVE' | 'INACTIVE' | 'MAINTENANCE'
  tags: string[]
  
  // Query results
  distance?: number
  proximityScore?: number
  score?: number
  
  created: Timestamp
  updated: Timestamp
  lastSynced: Timestamp
}

QueryCriteria

typescript

interface QueryCriteria {
  serviceType: ServiceType
  location?: {
    coordinates: [number, number]
    maxDistance?: number
  }
  filters?: Record<string, any>
  limit?: number
  offset?: number
}

MatchRequest

typescript

interface MatchRequest {
  serviceTypes: ServiceType[]
  delivery: {
    country?: string
    city?: string
    region?: string
    areaType?: 'URBAN' | 'SUBURBAN' | 'RURAL'
    coordinates?: [number, number]
  }
  items?: Array<{
    sku: string
    quantity: number
    weight?: number
    volume?: number
    [key: string]: any
  }>
  requirements?: string[]
  strategy: MatchingStrategy
}

type MatchingStrategy = 
  | 'BALANCED'
  | 'COST_OPTIMIZED'
  | 'SPEED_OPTIMIZED'
  | 'QUALITY_OPTIMIZED'

MatchScore

typescript

interface MatchScore {
  capability: number    // 0-100
  proximity: number     // 0-100
  capacity: number      // 0-100
  performance: number   // 0-100
  cost: number         // 0-100
  overall: number      // Weighted average
}

Capacity

typescript

interface Capacity {
  type: string
  total: number
  used: number
  available: number
  reserved?: number
  utilizationRate: number  // 0-100
  unit: string
  lastUpdated: Date
}

Error Codes

Code	HTTP Status	Description	Action
`UNAUTHORIZED`	401	Invalid or expired API key	Check authentication credentials
`FORBIDDEN`	403	Insufficient permissions	Verify workspace access
`NOT_FOUND`	404	Service or resource not found	Check service ID and LSP
`VALIDATION_ERROR`	400	Invalid request parameters	Review request body
`NO_RESULTS`	200	Query returned no matches	Adjust filters or add fallback
`CAPACITY_UNAVAILABLE`	503	Cannot query capacity	Service may be down
`PRICING_UNAVAILABLE`	503	Cannot estimate cost	Pricing service unavailable
`RATE_LIMIT_EXCEEDED`	429	Too many requests	Implement rate limiting
`INTERNAL_ERROR`	500	Server error	Retry or contact support

Rate Limits

Discovery Queries: 500 requests/minute
Matching Queries: 200 requests/minute
Capacity Queries: 1,000 requests/minute (cached)
Performance Queries: 500 requests/minute
Pricing Queries: 500 requests/minute (cached)

SDK Usage

JavaScript/TypeScript

typescript

import { DeClient } from '@dedot/sdk'

const client = new DeClient({
  apiKey: 'your-api-key',
  workspace: 'your-workspace-id'
})

// Discovery
const services = await client.realm.queries.discovery.discover({...})

// Matching
const match = await client.realm.queries.matching.match({...})

// Capacity
const capacity = await client.realm.queries.capacity.query({...})

// Performance
const performance = await client.realm.queries.performance.get({...})

// Pricing
const estimate = await client.realm.queries.pricing.estimate({...})

API Reference ​

Base URL ​

Authentication ​

Discovery Queries ​

Discover Services ​

Advanced Discovery ​

Find Available Services ​

Get Service ​

Count Services ​

Matching Queries ​

Match Order to Services ​

Capacity Queries ​

Query Service Capacity ​

Batch Query Capacities ​

Query All Capacities ​

Invalidate Cache ​

Get Cache Stats ​

Performance Queries ​

Sync Performance Data ​

Batch Sync Performance ​

Get Performance Data ​

Pricing Queries ​

Get Pricing Rules ​

Estimate Cost ​

Compare Pricing ​

Invalidate Pricing Cache ​

Get Pricing Cache Stats ​

Type Definitions ​

ServiceRegistryEntry ​

QueryCriteria ​

MatchRequest ​

MatchScore ​

Capacity ​

Error Codes ​

Rate Limits ​

SDK Usage ​

JavaScript/TypeScript ​

Next Steps ​

API Reference

Base URL

Authentication

Discovery Queries

Discover Services

Advanced Discovery

Find Available Services

Get Service

Count Services

Matching Queries

Match Order to Services

Capacity Queries

Query Service Capacity

Batch Query Capacities

Query All Capacities

Invalidate Cache

Get Cache Stats

Performance Queries

Sync Performance Data

Batch Sync Performance

Get Performance Data

Pricing Queries

Get Pricing Rules

Estimate Cost

Compare Pricing

Invalidate Pricing Cache

Get Pricing Cache Stats

Type Definitions

ServiceRegistryEntry

QueryCriteria

MatchRequest

MatchScore

Capacity

Error Codes

Rate Limits

SDK Usage

JavaScript/TypeScript

Next Steps