Test mode

ck_test_... keys call the same API, with the same routes, option validation and response format, but instead of analysing the document with AI they return a deterministic result chosen by the file name. Use them for development, CI and demos without spending credits.

Test vs liveCopy Anchor Link

The checks you ask for (holder, min_age_years, max_age_days, expected_amount…) are evaluated on the simulated data exactly as in live, so you can test error cases too.

How the result is chosenCopy Anchor Link

1. The file name is taken without extension, lowercased.
2. If it matches a scenario exactly (dni_valid, dni_expired, nie, passport, medical_certificate, sexual_offences_certificate, payment_receipt, invoice, blurry), that one is used.
3. Otherwise keywords are searched in this order: blur/borros, expired/caducad, nie/tie, passport/pasaporte, medical/medico/médico, sexual/delitos/penales, receipt/justificante/transfer, invoice/factura, dni. The first one found wins: dni_blurry.jpg gives the blurry scenario, and dni_expired_2.png, dni_expired.
4. If none matches, the document is generic.

The content must be a real JPEG, PNG, WEBP, HEIC or PDF file: the type is detected from the first bytes, not from the extension. Any photo or PDF will do. You don't need one file per scenario: the name that counts is the one you send in the request (the multipart filename), so you can reuse the same file with different names.

ScenariosCopy Anchor Link

There are no scenarios for US types or the rest of the catalogue: a driver's license or a W-9 in test mode returns generic and, with expect, review. To see those types, use a live key (the month's 150 free credits are enough).

Messages with relative dates, such as "Emitido hace 28 días (máximo 365)." ("Issued 28 days ago (maximum 365)."), depend on the day you run the test.

Response examplesCopy Anchor Link

Forcing error casesCopy Anchor Link

Besides dni_expired and blurry, you can trigger other outcomes by combining a file with options:

Messages in another languageCopy Anchor Link

language changes the language of reasons[].message, checks messages and document.label. For example, dni_valid.jpg with {"expect":"es_dni","checks":{"holder":{"full_name":"Juan Pérez"},"min_age_years":18},"language":"en"}:

{
  "expected": ["es_dni"],
  "match": true,
  "status": "invalid",
  "reasons": [
    { "code": "type_match", "severity": "info", "message": "The document is Spanish ID card (DNI)." },
    { "code": "not_expired", "severity": "info", "message": "Valid until 12/03/2031." },
    { "code": "age", "severity": "info", "message": "The holder is 36 years old." },
    { "code": "holder", "severity": "error", "message": "Holder mismatch: full_name is “MARÍA GARCÍA LÓPEZ”, expected “Juan Pérez”." }
  ]
}

Codes don't change with the language: always code against code and severity.

Automated testsCopy Anchor Link

Recommendations so your tests don't break:

• Use a ck_test_ key dedicated to CI, in its own environment variable (for example CONSTAIA_TEST_API_KEY), and check it starts with ck_test_ before running anything.
• Assert only on verdict.status, the code and severity of verdict.reasons, and warnings. Don't compare messages (they depend on the language and, in some cases, on the date), nor id, timestamps or size_bytes.
• Keep a single small JPEG and a single small PDF in the repository and send them with different names.

import { beforeAll, describe, expect, it } from "vitest";
import { Constaia, type Analysis } from "@constaia/sdk";
import { fromPath } from "@constaia/sdk/node";

const apiKey = process.env.CONSTAIA_TEST_API_KEY ?? "";
const constaia = new Constaia({ apiKey });

// Same real file, different name: the name picks the scenario.
const jpeg = (name: string) => fromPath("test/fixtures/sample.jpg", name);

const codes = (a: Analysis, severity?: string): string[] =>
  (a.verdict?.reasons ?? []).filter((r) => !severity || r.severity === severity).map((r) => r.code);

describe("ID card validation", () => {
  beforeAll(() => {
    if (!apiKey.startsWith("ck_test_")) throw new Error("CONSTAIA_TEST_API_KEY must be a ck_test_ key");
  });

  it("accepts a valid ID card", async () => {
    const analysis = await constaia.analyze(await jpeg("dni_valid.jpg"), { expect: "es_dni" });
    expect(analysis.verdict?.status).toBe("valid");
    expect(codes(analysis)).toContain("type_match");
    expect(analysis.warnings).toEqual([]);
  });

  it("rejects an expired ID card", async () => {
    const analysis = await constaia.analyze(await jpeg("dni_expired.jpg"), { expect: "es_dni" });
    expect(analysis.verdict?.status).toBe("invalid");
    expect(codes(analysis, "error")).toContain("not_expired");
  });

  it("sends a blurry photo to review", async () => {
    const analysis = await constaia.analyze(await jpeg("blurry.jpg"), { expect: "es_dni" });
    expect(analysis.verdict?.status).toBe("review");
    expect(analysis.warnings).toEqual(expect.arrayContaining(["blurry", "low_quality"]));
    expect(codes(analysis, "warning")).toContain("low_quality");
  });

  it("rejects a passport when an ID card is expected", async () => {
    const analysis = await constaia.analyze(await jpeg("passport.jpg"), { expect: "es_dni" });
    expect(analysis.verdict?.status).toBe("invalid");
    expect(codes(analysis, "error")).toContain("type_mismatch");
  });
});

If you run many tests in parallel, remember test mode has the same requests-per-second limit as your tier (2 req/s on the free plan): the SDKs retry 429s honouring Retry-After, but you should limit concurrency. See Rate limits.

Webhooks in test modeCopy Anchor Link

Each webhook endpoint has the mode of the key it was created with (mode: "test" or "live") and only receives events of that mode. To test webhooks during development:

1. Create the endpoint with your ck_test_ key (POST /v1/webhook-endpoints) pointing at a public HTTPS URL (for example, a tunnel to your machine).
2. Run analyses with async: true or batches with the test key: you will receive analysis.completed, analysis.review_required (with blurry.jpg), batch.completed…
3. From the dashboard you can also send a test event (type: "test") and see the last 100 deliveries.

credits.low only exists in live mode. For unit tests of your receiver without network, generate signed headers with signWebhook (JavaScript SDK), Webhook::headers (PHP SDK) or constaia.webhooks.sign (Python SDK). See Webhooks.

When you go liveCopy Anchor Link

Live keys never get simulated results. If the environment has no real AI providers available, ck_live_ calls fail with 503 live_mode_unavailable (APIError in the JavaScript SDK). Keep using the test key meanwhile. The steps to go live are in the quickstart.

Next stepsCopy Anchor Link