Skip to main content
SkillNexus Logo

SkillNexus API Reference

Complete developer manual covering authentication, all endpoints, request/response examples, and practical use cases.

1. Authentication & Base URL

All API requests are made to https://legal-api.skillnexus.uk. You must include your API key (prefixed with sknx_) in the x-api-key header.

Required headers:

  • x-api-key: sknx_your_secret_key_here
  • Content-Type: application/json (for POST/PUT requests)
Security: Never expose your API key in client‑side code. Always perform requests from a secure backend.

2. Available Endpoints & Use Cases

Below is the complete list of legal AI endpoints. Each card shows the method, path, a description, a use case (when to use it), and a request/response example.

POST /api/search

Description: Perform a keyword‑based search across legal documents, statutes, and case law. Falls back to D1 SQL if Typesense is unavailable.

Use Case: Quick statutory lookup, precedent retrieval, or citation search when you need exact‑term matches.

Request Payload:

{
  "query": "intellectual property infringement damages",
  "filters": { "jurisdiction": "US" },
  "limit": 10
}

Response (excerpt):

{
  "results": [
    {
      "id": "doc_123",
      "title": "Apple v. Samsung (2018)",
      "jurisdiction": "US",
      "citation": "Civil Action 12‑CV‑0630",
      "score": 0.92
    }
  ],
  "total": 42,
  "limit": 10
}

POST /api/search/hybrid

Description: Combines vector embedding (semantic) and keyword search using Reciprocal Rank Fusion (RRF).

Use Case: Concept‑based discovery – find documents that are semantically related even if they don’t share exact keywords (e.g., "fair use" vs "copyright exemption").

Request Payload:

{
  "query": "cross‑border data transfer compliance",
  "filters": { "jurisdiction": ["UK", "DE"] },
  "limit": 20
}

Response (excerpt):

{
  "results": [
    {
      "id": "doc_456",
      "title": "Schrems II Judgment",
      "jurisdiction": "EU",
      "rrfScore": 0.876
    }
  ],
  "isHybrid": true
}

POST /api/compare

Description: Cross‑jurisdictional legal comparison – fetches relevant precedents from multiple jurisdictions for a given query.

Use Case: Multi‑national M&A due diligence, treaty compliance, or harmonising legal advice across borders.

Request Payload:

{
  "jurisdictions": ["NG", "UK", "US"],
  "query": "data protection breach penalties"
}

Response (excerpt):

{
  "results": {
    "NG": [ { "title": "NDPR Regs", "holding": "…" } ],
    "UK": [ { "title": "UK GDPR", "holding": "…" } ],
    "US": [ { "title": "CCPA", "holding": "…" } ]
  }
}

POST /api/rag/summarize

Description: Generates an executive summary from a legal document or a set of text chunks using AI (BART + Llama fallback).

Use Case: Quickly grasp the essence of a 50‑page judgment or statute – ideal for busy counsel and compliance teams.

Request Payload:

{
  "documentId": "doc_789",
  "chunkIds": ["chunk_1", "chunk_5", "chunk_9"]
}

Response:

{
  "summary": "The court held that …",
  "aiCreditsRemaining": 198
}

POST /api/defense/build

Description: Constructs a structured legal defence strategy based on charges, facts, and relevant precedents. Optionally enhanced with AI synthesis.

Use Case: Litigation preparation – generate a first‑cut defence outline for a criminal or regulatory case.

Request Payload:

{
  "caseTitle": "R v. Adebayo",
  "charges": "Money laundering under Section 18",
  "facts": "Defendant operated a bureau de change…",
  "jurisdiction": "NG"
}

Response (excerpt):

{
  "defenseStrategy": {
    "primaryTheory": "Lack of mens rea…",
    "supportingPrecedents": [ … ],
    "aiSynthesis": { … }
  }
}

POST /api/monitoring/trigger

Description: Manually start a regulatory compliance scan across all active jurisdictions. Checks for changes and generates alerts.

Use Case: On‑demand compliance audit – e.g., before a board meeting or after a new legislation is passed.

Request:

No payload required (admin‑only endpoint).

Response:

{ "status": "success", "message": "Monitoring cycle dispatched." }

GET /api/monitoring/alerts

Description: Retrieve the 50 most recent compliance alerts with severity and affected sectors.

Use Case: Stay updated on regulatory changes – integrate with your internal dashboard or Slack notifications.

Response (excerpt):

{
  "data": [
    {
      "title": "New AML Guidelines",
      "severity": "high",
      "affected_sectors": ["Financial Services"],
      "created_at": "2026-08-11T10:00:00Z"
    }
  ]
}

GET /api/billing

Description: Returns the authenticated user’s current subscription tier, pay‑as‑you‑go credit balance, and regional pricing.

Use Case: Check remaining AI credits before making a heavy summarisation request, or display plan information in your UI.

Response (excerpt):

{
  "subscription": { "plan_tier": "pro", "status": "active" },
  "api_credits": { "balance": 243 },
  "regional_pricing": { "currency": "USD", "plans": { … } }
}

3. Node.js Integration Example

Below is a complete example showing how to call the hybrid search endpoint from a secure backend (using environment variables for the API key).

import fetch from 'node-fetch';

const API_BASE = 'https://legal-api.skillnexus.uk';
const API_KEY = process.env.SKNX_API_KEY;

async function searchLegal(query, jurisdiction = 'GENERAL', limit = 10) {
  const response = await fetch(`${API_BASE}/api/search/hybrid`, {
    method: 'POST',
    headers: {
      'x-api-key': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ query, jurisdiction, limit })
  });

  if (response.status === 402) {
    throw new Error('Insufficient API credits. Please top up.');
  }

  if (!response.ok) {
    const err = await response.json();
    throw new Error(`API Error: ${err.error || response.statusText}`);
  }

  return response.json();
}

// Usage
const results = await searchLegal('cross-border tax compliance', 'INTL');
console.log(results);