@taplid/client

@taplid/client

Official Node.js SDK for the hosted Taplid audit API.

Send a payload and get a trust decision (ALLOW / REVIEW / BLOCK), a 0-100 trust score and an audit trail.

• Docs: https://taplid.com/docs
• Audit page: https://taplid.com/audit

Install

npm install @taplid/client

SDK Example

import { Taplid } from '@taplid/client';

const taplid = new Taplid({
  apiKey: process.env.TAPLID_API_KEY ?? '',
});

const result = await taplid.audit({
  context: 'The number is 1.',
  prompt: 'What is the number?',
  response: 'The number is 2.',
  auditMode: 'standard'
});

console.log(result);

TypeScript autocomplete exposes the three SDK methods: taplid.audit(...), taplid.getAudit(...), and taplid.verifyAudit(...).

Retrieve an audit

Every completed hosted audit returns an auditId. Anyone with the ID can retrieve the persisted public result. No API key is required for retrieval.

import { Taplid } from '@taplid/client';

const taplid = new Taplid();

const audit = await taplid.getAudit(
  'AUD-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
);

console.log(audit);

Treat the audit ID like a share link. Retrieval is a public lookup. Hosted audit results include an attestation object, which is the cryptographic proof layer.

Verify an audit

Verify a persisted audit ID or signed attestation token. No API key is required.

Verify by audit ID:

import { Taplid } from '@taplid/client';

const taplid = new Taplid();

const verification = await taplid.verifyAudit({
  auditId: 'AUD-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
});

console.log(verification.status);

Verify by attestation token:

const verification = await taplid.verifyAudit({
  token: 'eyJhbGciOiJFUzI1NiIsImtpZCI6InRhcGxpZC1lczI1Ni0yMDI2LTA2IiwidHlwIjoiSldUIn0...',
});

console.log(verification.status);

Audit ID verification checks the persisted public result, signed fields, issuer, signature, and result hash. Token-only verification checks the signature and issuer, but cannot check the result hash without the persisted audit result.

Signed attestations

Hosted Taplid audit responses include an attestation object. It is an ES256-signed proof that Taplid issued the decision for the audited input and returned public result.

Public verification keys are available at:

https://api.taplid.com/.well-known/jwks.json

The attestation.token can be verified against the JWKS public key, by calling taplid.verifyAudit(...), or by posting an auditId or token to https://api.taplid.com/verify-audit. The signed payload includes the auditId, auditMode, decision, trustScore, inputHash, and resultHash.

HTTP API Example

You can call the API directly without the SDK using fetch or any HTTP client.

const payload = {
  context: 'The number is 1.',
  prompt: 'What is the number?',
  response: 'The number is 2.',
  auditMode: 'standard'
};

const response = await fetch('https://api.taplid.com/review', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.TAPLID_API_KEY}`,
  },
  body: JSON.stringify(payload),
});

const result = await response.json();
console.log(result);

Request Payload

Field	Type	Description
context	string	Policy, rules, or background context for the audit.
prompt	string	The user prompt that produced the response.
response	string	The AI-generated output to audit.
auditMode	string	Optional. 'artifact' (default) for code reviews, PRs, implementation plans, long answers, and structured outputs. 'standard' for factual, policy, refund, pricing, and entitlement issues.

Only response is required; context, prompt, and auditMode are optional. For file-based input, use @taplid/cli. The hosted SDK/API path accepts inline text only.

File format handling (CLI resolution)

Taplid treats context, prompt, and response file inputs as raw UTF-8 text. Supported examples include .txt, .md, .json, .log, .ndjson, .yaml, and .yml. These files are not parsed by type. Taplid reads the file contents as plain text and uses the resolved text value. This behavior is consistent across the audit page, CLI file-location flags, environment file-location variables, and request-payload file-location fields.

@taplid/client does not resolve files directly. When using the SDK, pass resolved inline text values for context, prompt, and response.

Response Shape

{
  "auditId": "AUD-XXX",
  "auditMode": "standard",
  "decision": "BLOCK",
  "trustScore": 20,
  "summary": "This answer conflicts with the provided context.",
  "issues": [
    {
      "message": "Contradicts the provided context.",
      "reason": "The context states one thing; the response says the opposite."
    }
  ],
  "nextStep": "Do not use this yet. Adjust the answer to match the provided context, then re-run the check.",
  "repairActions": [
    {
      "action": "Rewrite the answer so it aligns with the provided context.",
      "priority": "critical",
      "target": "response"
    }
  ],
  "claims": [
    {
      "text": "The number is 2.",
      "status": "contradicted",
      "evidence": [
        "Response value: 2",
        "Context value: 1"
      ]
    }
  ],
  "diagnosis": {
    "action": "revise_answer",
    "confidence": "high",
    "severity": "error",
    "nextSteps": [
      "Verify the answer is consistent with the provided context before re-running."
    ],
    "explanation": "The answer contradicts the provided context. Revise the answer to align with the source material before re-running the audit."
  },
  "claimStats": {
    "total": 1,
    "supported": 0,
    "unsupported": 0,
    "contradicted": 1,
    "evaluated": 1
  },
  "evidenceCoverage": 1,
  "metadata": {
    "auditDurationMs": 1,
    "claimsDetected": 1,
    "engine": "taplid",
    "version": "1"
  },
  "meta": {
    "policy": {
      "profileId": "balanced",
      "passThreshold": 80,
      "reviewThreshold": 60
    }
  },
  "requestId": "aud_XXX",
  "attestation": {
    "alg": "ES256",
    "kid": "taplid-es256-2026-06",
    "typ": "JWT",
    "issuer": "https://api.taplid.com",
    "issuedAt": "2026-06-12T21:28:52.000Z",
    "inputHash": "91f5884c9a9be6152e6d75534df82dada5965e7905bc80eca95df02970c6f3b1",
    "resultHash": "f95e77eb3224d987fa0baf35b5ee4c4e04029960cdcd6fd16c9171ffad929a7e",
    "token": "eyJhbGciOiJFUzI1NiIsImtpZCI6InRhcGxpZC1lczI1Ni0yMDI2LTA2IiwidHlwIjoiSldUIn0..."
  }
}

Response Fields

The response may include more fields than listed here. These are the primary fields.

• auditId - unique identifier for this audit run; anyone with this ID can retrieve the persisted public result
• auditMode - the effective mode that actually ran ('artifact' or 'standard')
• decision - ALLOW, REVIEW, or BLOCK
• trustScore - 0 to 100 public trust signal
• summary - short explanation for the verdict
• issues - concrete problems found in the response
• nextStep - practical guidance for what to do next
• repairActions - prioritized steps to fix the response (priority: critical / high / medium / low)
• claims - individual claims extracted and verified against the context, each with status and evidence
• diagnosis - structured diagnosis (action, confidence, severity, nextSteps, explanation)
• claimStats - counts across the claims array (total / supported / unsupported / contradicted / evaluated)
• evidenceCoverage - 0 to 1 fraction of claims grounded against the supplied context
• metadata - engine metadata (auditDurationMs, claimsDetected, engine, version)
• meta.policy - profileId plus passThreshold / reviewThreshold actually applied to this run
• requestId - server-assigned request id for support and tracing
• attestation - ES256 signed proof that Taplid issued this decision for the audited input and returned public result

Related

• Taplid Audit - run audits in the browser
• Taplid CLI - run, retrieve, and verify audits locally or in CI
• Taplid MCP - expose Taplid audit, retrieval, and verification tools to MCP-capable AI clients
• Taplid CLI eval - CI threshold gate via npx @taplid/cli eval request.json --api-key tap_live_... --pass-threshold 80 (exits non-zero when below)
• Full docs

ESM only - @taplid/client is ESM-only. If your project is CommonJS you may see ERR_PACKAGE_PATH_NOT_EXPORTED. Use ESM config: package.json => "type": "module", and tsconfig.json => "module": "NodeNext" with "moduleResolution": "NodeNext". If you need to stay on CommonJS, use the HTTP API example above instead of the SDK import.