API usage and setup guide

Endpoints

• - POST /certificates/batch queue up to 500 records; answers 202 with a batchId.
• - GET /certificates/batch/{batchId} status, counts and one result per record.

Example: queue a batch

curl -X POST "https://api.needine.com/certificates/batch" \
  -H "X-API-Key: ndi_xxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: nightly-2026-10-03" \
  -d '{
    "records": [
      {
        "certificateType": "ai_evaluation",
        "recordKind": "inference",
        "clientRecordId": "eval-0042",
        "signerName": "Maria Lopez",
        "issuingCompany": "Acme Learning",
        "inputEvidence": [{"sha256Hash": "b7c4...", "evidenceType": "input"}],
        "outputEvidence": [{"sha256Hash": "a99d...", "evidenceType": "output"}]
      }
    ]
  }'

HTTP/1.1 202 Accepted
{ "batchId": "5b2f0c1e-8a4d-4f7e-9c11-2d6a3e7b9f20", "status": "queued", "total": 1, "processed": 0, ... }

Example: GET /certificates/batch/{batchId} when the batch is done

{
  "batchId": "5b2f0c1e-8a4d-4f7e-9c11-2d6a3e7b9f20",
  "status": "done",
  "total": 3,
  "processed": 3,
  "succeeded": 2,
  "failed": 1,
  "results": [
    { "index": 0, "certificateId": "cert_9f1c..." },
    { "index": 1, "certificateId": "cert_4a7e...", "duplicate": true },
    { "index": 2, "error": "AI system version not found" }
  ],
  "errorMessage": null,
  "createdAt": "2026-10-03T22:00:00.000Z",
  "finishedAt": "2026-10-03T22:00:04.000Z"
}

TypeScript and Python SDKs

// TypeScript (@needine/sdk)
const records = evaluations.map((e) => ({
  certificateType: "ai_evaluation",
  recordKind: "inference",
  clientRecordId: e.id, // a retry never seals the same evaluation twice
  signerName: "Maria Lopez",
  issuingCompany: "Acme Learning",
  inputEvidence: [{ sha256Hash: e.inputHash, evidenceType: "input" }],
  outputEvidence: [{ sha256Hash: e.outputHash, evidenceType: "output" }],
}));
const batch = await client.sealRecords(records, { idempotencyKey: "nightly-2026-10-03" });
const done = await client.waitForRecordBatch(batch.batchId);
console.log(done.status, done.succeeded, done.failed);

# Python (needine-sdk)
batch = client.seal_records(records, idempotency_key="nightly-2026-10-03")
done = client.wait_for_record_batch(batch["batchId"])
print(done["status"], done["succeeded"], done["failed"])

Example: a minimal-disclosure record, then erasure

{
  "certificateType": "ai_evaluation",
  "recordKind": "inference",
  "disclosure": "minimal",
  "purpose": "Oral level assessment of a candidate",
  "metadata": { "candidateName": "Jane Doe" },
  "publicMetadata": { "level": "B2", "assessedAt": "2026-10-01" },
  "signerName": "Maria Lopez",
  "issuingCompany": "Acme Learning",
  "inputEvidence": [{ "sha256Hash": "b7c4...", "evidenceType": "input", "filename": "recording.webm" }],
  "outputEvidence": [{ "sha256Hash": "a99d...", "evidenceType": "output" }]
}

curl -X POST "https://api.needine.com/certificates/cert_xxx/erase-personal-data" \
  -H "X-API-Key: ndi_xxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"reason": "GDPR art. 17 request from the data subject"}'

Endpoints

• - GET /verification/{certificateId} public verification, no API key. Add /badge.svg for the embeddable badge or /qr.svg for the QR code.
• - GET /certificates/{certificateId}/export bundle for the owner (API key), with the private payload of minimal-disclosure records.
• - GET /certificates/{certificateId}/public-export public bundle, no API key.
• - GET /.well-known/needine-keys.json Needine's public signing keys.
• - GET /schemas/evidence-record-v2.json public JSON Schema of the signed record.

Offline checks with the SDKs (version 0.2.0 or later)

• - verifyBundle / verify_bundle: signed payload, Ed25519 signature and Merkle proofs, against the keys at /.well-known/needine-keys.json.
• - verifyBundleTimestamp / verify_bundle_timestamp: the RFC 3161 token.
• - verifyBundleQualification / verify_bundle_qualification: whether the authority was a qualified service in the EU trusted lists on the date of the stamp.

The signed record follows a public JSON Schema, https://api.needine.com/schemas/evidence-record-v2.json, also included in both SDKs (EVIDENCE_RECORD_V2_SCHEMA in TypeScript, evidence_record_schema() in Python).

Example (TypeScript)

import { verifyBundle, verifyBundleTimestamp, verifyBundleQualification } from "@needine/sdk";

const api = "https://api.needine.com";
const bundle = await (await fetch(`${api}/certificates/${certificateId}/public-export`)).json();
const { keys } = await (await fetch(`${api}/.well-known/needine-keys.json`)).json();

const record = verifyBundle(bundle, keys);             // payload, signature and Merkle proofs
const timestamp = await verifyBundleTimestamp(bundle); // RFC 3161 token
const tsa = await verifyBundleQualification(bundle);   // EU trusted lists
console.log(record.valid, timestamp.valid, tsa.status);

Example (Python)

import httpx
from needine import verify_bundle, verify_bundle_timestamp, verify_bundle_qualification

api = "https://api.needine.com"
bundle = httpx.get(f"{api}/certificates/{certificate_id}/public-export").json()
keys = httpx.get(f"{api}/.well-known/needine-keys.json").json()["keys"]

record = verify_bundle(bundle, keys)         # payload, signature and Merkle proofs
timestamp = verify_bundle_timestamp(bundle)  # RFC 3161 token
tsa = verify_bundle_qualification(bundle)    # EU trusted lists
print(record["valid"], timestamp["valid"], tsa["status"])

Model inventory endpoints

• - PUT /models/:id/gpai-classification set GPAI status and compute threshold.
• - PUT /models/:id/inventory update use case, department, responsible person, risk level.
• - GET /models/inventory/export export full model registry as CSV or JSON.

Model performance endpoints

• - POST /models/:modelId/performance record an evaluation (accuracy, precision, recall, F1, AUC).
• - GET /models/:modelId/performance list evaluation history (paginated).
• - GET /models/:modelId/performance/latest get the most recent evaluation.
• - GET /models/:modelId/performance/drift compare the latest two evaluations for metric drift.

Anchoring endpoints

• - POST /anchors/trigger trigger blockchain anchoring for pending certificates.
• - GET /anchors/:id/verify verify an anchor on-chain (returns Merkle root, tx hash, block number).

Anchor status: PENDING → SUBMITTED → CONFIRMED (or FAILED with automatic retries).

Fields of POST /certificates

• - disclosure: full (default) signs everything in clear; minimal keeps metadata, reportName and evidence filenames private and signs only a salted SHA-256 commitment to them.
• - publicMetadata: fields shown on public verification, signed in clear (max 4 KB). Never put personal data here.
• - aiSystemVersionId: AI system version that produced the result (POST /ai-systems/:id/versions). Signed into the payload.
• - supersedesCertificateId + supersessionReason (human_review, appeal, error_correction): the new certificate replaces an issued one, which becomes SUPERSEDED.

Endpoints

• - POST /certificates/:certificateId/erase-personal-data removes personal data (GDPR art. 17); signature and anchor keep verifying. ADMIN, scope certificates.erase.
• - GET /verification/:certificateId/qr.svg public QR code (SVG) of the verification page, to embed in your PDFs.
• - GET /.well-known/needine-keys.json Needine public signing keys, to verify signatures offline.
• - GET /organizations/current/usage?months=6 certificates issued per month and real anchoring fee (total and per certificate).
• - PATCH /organizations/current/verification-settings public presentation mode: certificate or integrity_seal. ADMIN.