Idemcore APIIdemcore API BetaBeta

An OpenAI-compatible chat API that returns a signed receipt with every answer. Anyone holding the receipt can check the signature and the run’s hash chain, and you can ask for the same answer to be replayed on a different engine build and compared.API chat tương thích OpenAI, mỗi câu trả lời đi kèm một receipt có chữ ký. Ai giữ receipt đều kiểm được chữ ký và chuỗi hash của lượt chạy, và bạn có thể yêu cầu phát lại cùng câu trả lời trên một bản build engine khác để so sánh.

OverviewTổng quan

• Base URLBase URL: https://api.idemcore.net
• Requests and responses are JSON (UTF-8). Send Content-Type: application/json on every POST. Maximum request body: 256 KB.Request và response là JSON (UTF-8). Gửi Content-Type: application/json với mọi POST. Kích thước body tối đa: 256 KB.
• Health check, no key needed: Kiểm tra tình trạng, không cần key: GET/health

AuthenticationXác thực

Send your API key as a Bearer token on every request except /health. Keys start with ick_ and are shown once, when we issue them. We store only a hash of the key, so we cannot show it again; if you lose it, ask for a new one.Gửi API key dưới dạng Bearer token với mọi request trừ /health. Key bắt đầu bằng ick_ và chỉ hiển thị một lần, lúc được cấp. Chúng tôi chỉ lưu hash của key nên không thể hiển thị lại; nếu làm mất, hãy yêu cầu key mới.

Authorization: Bearer ick_…

A key belongs to one organisation (tenant) and can only read that tenant’s receipts. By default a key has the scopes chat, receipts:read, receipts:verify and audit:export. Keep keys on your server: cross-origin browser calls are not enabled for other sites.Mỗi key thuộc về một tổ chức (tenant) và chỉ đọc được receipt của tenant đó. Mặc định key có các quyền chat, receipts:read, receipts:verify và audit:export. Hãy giữ key ở phía server: gọi trực tiếp từ trình duyệt của trang khác (cross-origin) không được bật.

Chat completionsChat completions

POST/v1/chat/completions Same request and response shape as the OpenAI Chat Completions API, plus an idemcore object in the response and an Idemcore-Receipt-Id header.Request và response có cùng cấu trúc với OpenAI Chat Completions API, kèm thêm đối tượng idemcore trong response và header Idemcore-Receipt-Id.

curl https://api.idemcore.net/v1/chat/completions \
  -H "Authorization: Bearer $IDEMCORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "messages": [{"role": "user", "content": "Name the three primary colours."}],
    "max_tokens": 64
  }'

{
  "id": "chatcmpl-3550cebf53dbc66a554977e8",
  "object": "chat.completion",
  "model": "MODEL_ID",
  "choices": [{ "index": 0, "finish_reason": "stop",
                "message": { "role": "assistant", "content": "Red, yellow and blue." } }],
  "usage": { "prompt_tokens": 38, "completion_tokens": 16, "total_tokens": 54 },
  "idemcore": {
    "receipt": { "receipt_version": "r1", "receipt_id": "rcpt_3550cebf53dbc66a554977e8", "...": "..." },
    "disclosure": { "salt": "q3J…", "output_token_ids": [785, 2326, 6028, "…"] }
  }
}
# response header:  Idemcore-Receipt-Id: rcpt_3550cebf53dbc66a554977e8

Request fieldsCác trường của request

Receipt objectĐối tượng receipt

A receipt is a small signed JSON object (format r1). It commits to which model and engine build produced the answer, which input and output were involved, and a digest of the run’s per-position hash log. It does not contain your prompt or the answer text.Receipt là một đối tượng JSON nhỏ có chữ ký (định dạng r1). Nó cam kết mô hình và bản build engine nào đã tạo ra câu trả lời, đầu vào và đầu ra nào liên quan, cùng một digest của log hash theo từng vị trí của lượt chạy. Receipt không chứa prompt hay nội dung câu trả lời của bạn.

{
  "receipt_version": "r1",
  "receipt_id": "rcpt_3550cebf53dbc66a554977e8",
  "issued_at": "2026-10-31T07:46:05.758Z",
  "tenant_id": "857588f4-…",
  "model_id": "MODEL_ID",
  "weights_hash": "9f923a5b…",            // SHA-256 of the model weights
  "kernel_version": "…",                  // engine identifier
  "engine_build": "b8faf4f5…",            // SHA-256 of the engine build
  "privacy": "hash_only",
  "prompt_hash": "3dff8f72…",             // salted commitment, not the prompt
  "params_hash": "d72a6d7e…",
  "seed": 0,
  "decoding": "greedy",
  "prompt_tokens": 38,
  "output_tokens": 16,
  "output_token_hash": "2b0654b1…",       // salted commitment, not the output
  "chain_digest": "3b1d1d9e…",            // digest of the per-position hash log
  "chain_fnv": "4a387c09…",               // compatibility digest
  "log_ref": "idemcore://logs/rcpt_3550cebf53dbc66a554977e8",
  "finish_reason": "stop",
  "key_id": "ed25519:…",
  "signature": "…"                        // Ed25519, base64url
}

• Commitments (prompt_hash, output_token_hash, params_hash) and the chain digest are SHA-256 based. The signature is Ed25519 over the canonical JSON of the receipt without signature.Các cam kết (prompt_hash, output_token_hash, params_hash) và chain digest dựa trên SHA-256. Chữ ký là Ed25519 trên JSON chuẩn hóa của receipt khi bỏ trường signature.
• finish_reason (stop or length) and request_id are optional. Any field not listed in the spec makes a receipt invalid.finish_reason (stop hoặc length) và request_id là tùy chọn. Trường nào không có trong đặc tả sẽ làm receipt không hợp lệ.
• Receipts contain no floating-point numbers and are safe to store, forward or publish.Receipt không chứa số thực dấu phẩy động và có thể lưu, chuyển tiếp hoặc công khai an toàn.

Privacy modesChế độ riêng tư

Set "idemcore": {{"privacy": "full"}} on a request to opt in, or ask us to change your organisation’s default.Gửi "idemcore": {{"privacy": "full"}} trong request để chọn chế độ này, hoặc yêu cầu chúng tôi đổi mặc định cho tổ chức của bạn.

Verify a receiptKiểm chứng receipt

POST/v1/receipts/verify Body: receipt (required), optional log_text (a hash log you hold; otherwise the stored log is used when the receipt is yours), and optional disclosure with salt plus messages and/or output_token_ids.Body: receipt (bắt buộc), tùy chọn log_text (log hash bạn đang giữ; nếu không gửi, hệ thống dùng log đã lưu khi receipt thuộc về bạn), và tùy chọn disclosure gồm salt cùng messages và/hoặc output_token_ids.

curl https://api.idemcore.net/v1/receipts/verify \
  -H "Authorization: Bearer $IDEMCORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "receipt": { "receipt_version": "r1", "receipt_id": "rcpt_…", "...": "..." },
  "disclosure": {
    "messages": [{"role": "user", "content": "Name the three primary colours."}],
    "salt": "q3J…",
    "output_token_ids": [785, 2326, 6028]
  }
}
JSON

{
  "ok": true,
  "levels": {
    "L1": { "level": "L1", "ok": true, "errors": [] },
    "L2": { "level": "L2", "ok": true, "errors": [], "log_source": "stored" },
    "disclosure": { "level": "disclosure", "ok": true, "errors": [] }
  }
}

ok is true only if every level that ran passed. Each level lists its errors when it fails.ok chỉ đúng khi mọi mức đã chạy đều đạt. Mức nào không đạt sẽ liệt kê errors.

Verification levelsCác mức kiểm chứng

Replay (L3)Phát lại (L3)

POST/v1/receipts/replay Re-runs one of your receipts on a different engine build and compares the chain digest. For hash_only receipts send receipt_id, messages and salt (and the output_token_ids from the disclosure); the disclosure is checked first. For full receipts receipt_id is enough. Replay is slower than verify and shares the chat rate limit.Chạy lại một receipt của bạn trên bản build engine khác và so sánh chain digest. Với receipt hash_only, gửi receipt_id, messages và salt (cùng output_token_ids từ disclosure); disclosure được kiểm trước. Với receipt full, chỉ cần receipt_id. Phát lại chậm hơn kiểm chứng và dùng chung giới hạn tần suất với chat.

curl https://api.idemcore.net/v1/receipts/replay \
  -H "Authorization: Bearer $IDEMCORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "receipt_id": "rcpt_3550cebf53dbc66a554977e8",
    "messages": [{"role": "user", "content": "Name the three primary colours."}],
    "salt": "q3J…",
    "output_token_ids": [785, 2326, 6028]
  }'

{
  "ok": true,
  "level": "L3",
  "errors": [],
  "mode": "…",
  "replay_build": "alt",
  "replay_engine_build": "…",
  "receipt_engine_build": "b8faf4f5…",
  "chain_digest_expected": "3b1d1d9e…",
  "chain_digest_replayed": "3b1d1d9e…"
}

Audit exportXuất log kiểm toán

GET/v1/audit/export Returns NDJSON: a header line, your receipts, your audit events and one signed root per day. Every issuance, verification, replay, export and key creation is appended to a hash-chained, append-only event log. Each daily root is a Merkle root over that day’s events, signed with Ed25519. Parameters since and until are dates (YYYY-MM-DD, UTC), at most 31 days apart; by default the window runs from yesterday to tomorrow. The same parameters work as a JSON body with POST.Trả về NDJSON: một dòng header, các receipt, các sự kiện kiểm toán và mỗi ngày một gốc có chữ ký. Mọi lần cấp receipt, kiểm chứng, phát lại, xuất log và tạo key đều được ghi thêm vào một log sự kiện nối chuỗi hash, chỉ ghi thêm (append-only). Mỗi gốc theo ngày là Merkle root của các sự kiện trong ngày đó, ký bằng Ed25519. Tham số since và until là ngày (YYYY-MM-DD, UTC), cách nhau tối đa 31 ngày; mặc định từ hôm qua tới ngày mai. Có thể gửi cùng tham số dưới dạng JSON body bằng POST.

curl "https://api.idemcore.net/v1/audit/export?since=2026-10-01&until=2026-10-31" \
  -H "Authorization: Bearer $IDEMCORE_API_KEY" \
  -o idemcore-audit.ndjson

{"type":"header","format":"idemcore-audit-export/r1","since":"2026-10-01","until":"2026-10-31","receipts":42,"events":97,"chain_check":"ok",…}
{"type":"receipt","receipt":{…}}
{"type":"event","event":{"seq":1,"event_type":"receipt.issued","receipt_id":"rcpt_…","prev_hash":"000…","event_hash":"…",…}}
{"type":"root","root":{"day":"2026-10-30","merkle_root":"…","signature":"…",…}}

Other endpointsEndpoint khác

• GET/v1/receipts/{id} returns {{"receipt": …}} for a receipt id (rcpt_ + 24 hex) owned by your organisation; /log returns its hash log.trả về {{"receipt": …}} cho một receipt id (rcpt_ + 24 ký tự hex) thuộc tổ chức của bạn; /log trả về log hash của nó.
• GET/v1/models lists model ids in OpenAI format.liệt kê model id theo định dạng OpenAI.
• GET/v1/keys returns the receipt-signing public keys as Ed25519 JWKs with their kid, so you can check signatures offline.trả về các khóa công khai ký receipt dưới dạng JWK Ed25519 kèm kid, để bạn kiểm chữ ký ngoại tuyến.

Python and JavaScriptPython và JavaScript

Python (requests)

import os, requests

API = "https://api.idemcore.net"
H = {"Authorization": f"Bearer {os.environ['IDEMCORE_API_KEY']}"}

r = requests.post(f"{API}/v1/chat/completions", headers=H, timeout=60, json={
    "model": "MODEL_ID",
    "messages": [{"role": "user", "content": "Name the three primary colours."}],
    "max_tokens": 64,
})
r.raise_for_status()
res = r.json()
print(res["choices"][0]["message"]["content"])

receipt = res["idemcore"]["receipt"]          # safe to store and share
disclosure = res["idemcore"]["disclosure"]    # keep private: salt + output token ids

v = requests.post(f"{API}/v1/receipts/verify", headers=H, timeout=30,
                  json={"receipt": receipt}).json()
print(v["ok"], {name: lvl["ok"] for name, lvl in v["levels"].items()})

Python (OpenAI SDK, compatibility mode)Python (OpenAI SDK, chế độ tương thích) BetaBeta

from openai import OpenAI   # OpenAI-compatible client, pointed at Idemcore

client = OpenAI(base_url="https://api.idemcore.net/v1",
                api_key=os.environ["IDEMCORE_API_KEY"])
resp = client.chat.completions.create(
    model="MODEL_ID",
    messages=[{"role": "user", "content": "Name the three primary colours."}],
    temperature=0, max_tokens=64,
)
receipt = resp.model_extra["idemcore"]["receipt"]

JavaScript (fetch)

// Node 18+ or any runtime with fetch. Call from your server: browser CORS is limited.
const API = "https://api.idemcore.net";
const H = { "Authorization": `Bearer ${process.env.IDEMCORE_API_KEY}`,
            "Content-Type": "application/json" };

const res = await fetch(`${API}/v1/chat/completions`, {
  method: "POST", headers: H,
  body: JSON.stringify({
    model: "MODEL_ID",
    messages: [{ role: "user", content: "Name the three primary colours." }],
    max_tokens: 64,
  }),
}).then((r) => r.json());

const { receipt, disclosure } = res.idemcore;
const check = await fetch(`${API}/v1/receipts/verify`, {
  method: "POST", headers: H, body: JSON.stringify({ receipt }),
}).then((r) => r.json());
console.log(check.ok, check.levels);

ErrorsLỗi

Errors use one shape, with deliberately generic messages:Lỗi có chung một cấu trúc, với thông báo cố ý ở mức chung chung:

{ "error": { "type": "invalid_request_error",
             "message": "only greedy decoding (temperature 0) is supported in this preview" } }

Rate limitsGiới hạn tần suất

Beta limits; pilots can ask for higher ones. A 429 means wait and retry with backoff.Đây là giới hạn trong giai đoạn beta; khách thí điểm có thể yêu cầu nâng. Lỗi 429 nghĩa là hãy chờ rồi thử lại với backoff.

SDK, MCP plugin and browser extensionSDK, MCP plugin và tiện ích trình duyệt

Questions about the API: Câu hỏi về API: [email protected]. Security reports: Báo cáo bảo mật: [email protected].