Xinsere API

Overview

Every file you send through the API is fragmented, encrypted with independent per-fragment keys, and distributed across storage. Reading access is enforced by an on-chain permission record, not a database flag, so a grant or revoke is a timestamped, independently verifiable event rather than an editable row.

Read and plan a full integration here without an account. You can build before you license: a sandbox key gives you the real API against an isolated test workspace, no contract and no card. Production keys and the interactive try-it-now reference are issued with your plan (see next steps below).

Authentication

Your organization is issued an API key from the admin console. Send it as a bearer token on every request:

# every request
Authorization: Bearer xin_your_key_here

The key is your organization's service identity. Its party_id owns everything stored under it and is the party recorded in every grant.

curl -H "Authorization: Bearer $XINSERE_KEY" \
  https://api.xinsere.com/v1/ping

Returns your party_id and the current inline upload cap (max_inline_bytes); read it rather than hardcoding a size limit.

Store a file

curl -X POST https://api.xinsere.com/v1/files \
  -H "Authorization: Bearer $XINSERE_KEY" \
  -F "file=@contract.pdf" \
  -F "path=productions/show-x"   # optional folder path

The response returns the file's id and the sha256 of your original bytes. Use the id in every later call.

Retrieve a file

Two ways to get bytes back, depending on where you want reassembly to happen:

Delete a file

Moves the file to trash. It's recoverable for 30 days, then erased automatically. Add ?permanent=true to erase immediately: fragments and keys are destroyed and any outstanding grants are revoked on-chain in the same operation.

Grant & revoke access

Permissions are written to an on-chain contract: immutable, timestamped, and independently checkable by anyone you give the record to, without asking Xinsere.

curl -X POST https://api.xinsere.com/v1/files/{id}/grants \
  -H "Authorization: Bearer $XINSERE_KEY" \
  -F "party_id=<grantee uuid>"

The response includes a transaction reference you can hand to an auditor as proof of the grant.

Revokes access. The revoke is its own on-chain event, so the full grant history, including everything that was later revoked, survives for audit.

Lists current shares on a file along with each one's transaction reference.

Resolves another organization's party_id from its slug, so a machine-to-machine grant never needs a human to copy a uuid by hand.

Verify

curl "https://api.xinsere.com/v1/files/{id}/verify?party_id=<uuid>" \
  -H "Authorization: Bearer $XINSERE_KEY"

Answers "does this party currently have access, and since when," read straight from the ledger, without touching the file's content.

Signer health and remaining transaction budget. Costs nothing to call; check it before a grant on a workflow you can't afford to have fail mid-run.

Scopes

Keys are scoped when they're issued in the admin console. A key with only files:read can't grant access to anything, even if it can read the file itself.

Errors

Every error, including validation failures, returns one shape:

{ "error": "human-readable message [error_code]" }

Validation errors add an errors array with field-level detail. The HTTP status carries the primary signal:

Codes worth branching on: chain_grant_failed, chain_revoke_failed, chain_status_unavailable.

Plan limits

API usage draws from the same monthly file, share, and storage allowance as your plan's web app, listed on the pricing page. There's no separate API quota to track.

Agent & MCP access

For AI agents that need to store and share files with the same guarantees, Xinsere ships an MCP server, Botverse Secure, exposing the permission model as callable tools instead of raw HTTP:

Works with Claude, LangChain, CrewAI, n8n, and any MCP-compatible agent runtime.