Docs page

Docs · FAQ

API FAQ

21 questions. Short answers about keys, limits, idempotency, verification and errors. Product and pricing questions are on the site FAQ.

Error reference Site FAQ

Getting started

What is the Invoance API?

A REST API at https://api.invoance.com. You send an event, a document hash, an AI exchange or an audit event. Invoance hashes it with SHA-256, signs it with your organization's Ed25519 key and appends it to a ledger. Public proof endpoints let anyone check a record without an account.

How do I create an API key?

Open Settings in the dashboard and create a key. It is shown once; the server stores only its SHA-256. A key looks like invoance_live_<8 characters>_<43 characters>. Set it as INVOANCE_API_KEY or pass it to the SDK client.

Authentication

What do I need to start?

An API key and one SDK, or plain HTTP. Every endpoint is documented with a REST sample. Install the SDK, set the key and send your first record.

Install

npm install invoance
pip install invoance
go get github.com/Invoance/invoance-go
cargo add invoance
gem install invoance
composer require invoance/invoance
dotnet add package Invoance
# Java: com.invoance:invoance on Maven Central

SDKs

Which SDKs are available?

Eight: Node, Python, Go, Java, Ruby, Rust, .NET and PHP. Every SDK checks an AI attestation signature and an audit event signature offline.

Is there a sandbox?

No. The Developer plan is free, and its records are real records signed with your key. Use a separate API key for staging so you can revoke it on its own.

Pricing

Authentication

How does authentication work?

Send the key as a Bearer token in the Authorization header, or in the X-API-Key header. Authorization is read first when both are present. A missing, malformed, unknown or revoked key returns 401. A key belongs to one organization and cannot read another organization's records.

Authentication

What scopes does a key have?

read and write cover events, documents, AI attestations and traces. audit:read and audit:write cover the audit log API and are a separate set. write passes every read check, and audit:write passes every audit:read check. A key without the needed scope gets 403 insufficient_scope.

Can I have more than one key?

Yes. Create one per environment or service and revoke any of them on its own. Every key in the organization shares one rate limit budget.

Can I restrict a key to certain IP addresses?

Yes. Add IP rules to the key in the dashboard. A request from any other address gets 403 ip_not_allowed.

Sending records

What can I send?

Five record types, one endpoint each. Events go to POST /v1/events, document hashes to POST /v1/document/anchor, AI attestations to POST /v1/ai/attestations and audit events to POST /v1/audit/events. POST /v1/traces opens a trace that groups events, documents and attestations into one sealed bundle.

All endpoints

What are the size limits?

Event payload: 64 KB serialized; event_type 1 to 128 characters. Document anchor: document_hash 64 hex characters; metadata up to 8 KB; original_bytes_b64 up to 5 MB decoded, with the anchor route's body limit sized to fit it. AI attestation: 1 MB canonical JSON; subject up to 8 KB and 20 extra keys. Trace: label up to 255 characters; metadata up to 16 KB; events listed on GET /v1/traces/{trace_id} up to 200 per call, default 50. Audit event: 64 KB body; action up to 128 characters; up to 20 targets; metadata up to 50 keys with keys up to 40 and values up to 500 characters; Idempotency-Key up to 255 characters. An event or audit event over its limit gets 400 payload_too_large; an AI attestation, or a document anchor body over about 8 MB, gets 413 payload_too_large.

Does the API support idempotency?

Yes. Send an Idempotency-Key header: optional on events, document anchors and AI attestations, required on audit events. For 24 hours a retry with the same key and the same request gets the original response. The same key with a different request gets 409 idempotency_key_reuse_mismatch. A retry while the first request is still running gets 202 with status processing. When you omit the key on an audit event, the SDKs derive one from the body.

Can I change or delete a record?

No. There is no endpoint that edits a signed record, and the ledger tables reject deletes. After the plan's retention window an event, document or AI attestation is sealed: get returns 410 retention_expired, verify still works. An open trace with no events can be deleted.

Verification

How do I verify a record?

Recompute the SHA-256 of what you hold and compare it with the recorded hash. Then check the Ed25519 signature against the organization's public key. Events, documents, AI attestations and public traces have proof endpoints under /v1/proof that need no key. Audit events are verified with a key that has audit:read.

Open the verifier

Where is my organization's public key?

At https://api.invoance.com/keys/{your-domain} once your domain is verified, and in the dashboard. The endpoint sits at the API root, not under /v1, and returns the key base64url encoded without padding. The proof endpoints return the same 32 bytes hex encoded.

Can I verify offline?

Yes. Every SDK checks an attestation signature from the get response with no call to Invoance, and does the same for an audit event, pinning the key from GET /keys/{domain} when you pass it. Any Ed25519 library can do the same with the signed bytes, the signature and the key.

Verification guide

Does the proof endpoint show my data?

No. It returns the issuer, timestamps, the hashes, the public key and the signature, plus the event type or, for an attestation, the model provider, name and version and the subject ids. Payloads, prompts, outputs, actors and metadata are not returned.

Rate limits and errors

What are the rate limits?

Requests per second are limited per tenant, so every key under a tenant shares one budget: the plan's rate_limit_per_sec (developer 10, builder 50, growth 200, compliance 500, enterprise 500), or the organization's override when one is set, with a minute budget of 60 times that figure; 10 per second is the fallback when no plan row is found. A limited request gets 429 rate_limited with Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining headers.

What does an error response look like?

A JSON object with two fields. error is a stable code you can match on. message is text for people and may change. A 429 rate_limited also carries retry_after, plan_tier, limit_per_sec, upgrade_url.

Error

{
  "error": "invalid_api_key",
  "message": "The API key is invalid or does not exist. Double-check the key and try again."
}

Error reference

What happens when I reach my monthly quota?

Writes and verify calls return 429 quota_exceeded with the two-field shape and no Retry-After; the message names /dashboard/plans/upgrade. Get and list calls keep working. A paid subscription that is past due returns 402 payment_required on writes until the payment method is updated.

Where is the full list of error codes?

On the Errors page, grouped the way the backend groups them, with the HTTP status for each code and when it is returned.

Every error code

npm install invoance pip install invoance go get github.com/Invoance/invoance-go cargo add invoance gem install invoance composer require invoance/invoance dotnet add package Invoance # Java: com.invoance:invoance on Maven Central