Submit an Item
How to timestamp data by submitting an item on the web form, JSON:API, GraphQL, console WebSocket, CLI, or an MCP agent, with every claims field (name, hash and hash type, description, URL, location, timestamp, metadata), hash mode versus plan-gated claims-only mode, and the limits that apply.
Overview
Submitting an item is how you timestamp something with Truestamp. You describe the data in a small structured object called the claims, Truestamp reduces those claims to a cryptographic fingerprint the moment they arrive (see the item’s composite fingerprint), and from there the item advances toward a portable proof that the data was submitted within a provable submission window (see the proof lifecycle). Your file itself is never uploaded: in the usual mode you submit a hash of the data, so the content stays with you.
At that same instant Truestamp notes which public records already existed, the item’s witnesses, and folds them into the same fingerprint. The block then at the head of Truestamp’s internal chain is always among them, and the newest observation from each public randomness source that has one rides along too. Which witnesses your item names is fixed at submission and can never be chosen afterward; the entropy witnesses open the submitted-after edge of your submission window, and the head block fixes where your item sits in the ledger.
There are two submission modes. In hash mode you supply the hash of an external file together with the algorithm that produced it, and that hash is the data being timestamped. In claims-only mode you omit the hash entirely and the claims content itself (a description, freeform metadata, or both) becomes the data of record; this mode is size-gated by the team owner’s plan.
You can submit an item from six surfaces: the web form, the JSON:API, the GraphQL API, the console WebSocket, the command-line client, and an MCP-connected LLM agent. Every surface lands on the same create pipeline, so the resulting items and their fingerprints are identical no matter which path produced them.
Before you begin
- You must be signed in or hold a credential. Every submission surface is authenticated. The web form needs a signed-in session; the JSON:API, GraphQL, and console surfaces take an API key or an OAuth 2.1 access token; the MCP endpoint is OAuth-only.
- Know which team the item will live in. An item belongs to exactly one team, and you need write access to that team (a viewer role cannot submit). On the web form the item goes into your currently selected team. On the APIs you can name a team explicitly; if you do not, the request falls back to your default team preference or your personal team.
- Pick your mode. For a file or any content you can hash, use hash mode:
hashandhash_typeare co-required, so supply both or neither. To timestamp short self-contained content directly, use claims-only mode: the claims must then include either a description of at least 32 code points or non-empty metadata (a name-only submission is rejected), and the total encoded claims size must fit the team owner’s plan budget, from 256 bytes on Free up to 16 KB on Enterprise (see plans and entitlements). - Know your allowance. Each submission counts against the monthly item allowance of the team’s billing owner, and that allowance is pooled across every team that owner owns, whoever submitted the item. When the allowance is exhausted, submissions are refused until it resets or the plan is upgraded.
The claims fields
The claims object is the data you are timestamping plus your own statements about it. Only name is always required.
| Field | Required | Rules |
|---|---|---|
name |
yes | 1 to 64 code points; letters, marks, numbers, spaces, and common punctuation in any language |
hash |
with hash_type |
lowercase hexadecimal, 32 to 128 characters; length must match the chosen algorithm’s output |
hash_type |
with hash |
one of md5, sha1, sha224, sha256, sha384, sha512, sha3_224, sha3_256, sha3_384, sha3_512, blake2s, blake2b |
description |
no | 1 to 256 code points; the characters a name may hold, plus square brackets |
url |
no | HTTPS only, up to 256 code points, must point at a public host (addresses on private or internal networks are rejected) |
location |
no | an object with latitude (-90 to 90) and longitude (-180 to 180), both required together |
timestamp |
no | a claimed timestamp, your own statement, as a flexible ISO 8601 value (2026, 2026-07, 2026-07-15, or a full datetime) naming a real date. Truestamp checks only that it is a well-formed date: it does not confirm it, nothing checks whether it is past or future, and it is never part of the submission window. It is kept and shown exactly as you wrote it |
metadata |
no | a freeform JSON object of your own fields, nested up to 10 levels; its size is capped by the team owner’s plan (none on Free, 1 KB Starter, 4 KB Pro, 16 KB Enterprise) |
nonce |
no | 1 to 32 bytes of lowercase hexadecimal; it makes identical submissions hash differently and counts against no budget |
Things to know about how claims are handled:
-
Claims are your statement. Truestamp commits them exactly as submitted and attests only that they were submitted, not that they are true. The item page and the verify page show them that way, under “Claims”, with the claimed timestamp labelled “Claimed timestamp” and never shown beside the submission window. A claims string that holds a code point that would not show as itself (a bidi control such as U+202E, a zero-width character, or anything else the rules below refuse, which an item or proof from before those rules may hold, and a few invisible characters the rules accept, such as the Hangul filler U+3164) shows that code point by its number, such as
U+202E. A value shown on its own, such as the name, sits apart from the text around it so it cannot reorder the page, and the copy buttons copy each value exactly as submitted. The claims card’s canonical view showsclaims_jcsitself, under “Claims, exactly as submitted”. -
The rules and their codes are on the API docs page. The API documentation lists every claims rule and every error code, and is the reference for writing a client.
-
Claims are kept in canonical form and hashed exactly. Truestamp stores the claims in canonical form (the JSON Canonicalization Scheme, which changes only member order, whitespace, escapes, and number spelling), hashes those exact bytes, and returns them as
claims_jcsbesideclaims_hash. On every surface, the web form included, nothing in your claims is changed: claims that break a rule are refused, and each error names the member and the fix. That covers text that is not in Unicode normalization form C, text that begins or ends with whitespace or holds an invisible control character, an empty optional string, anullanywhere, a member Truestamp does not recognize, a number sent as a string, and any number canonical form would change. The web form leaves a field you leave blank out of the claims, shows each error at its field as you type, and offers a Fix button where the fix is mechanical; it changes nothing until you press it. -
Numbers are kept as 64-bit floating-point numbers; send any other number as a string. Canonical form holds each number as a 64-bit floating-point number (a double), which keeps about 15 to 17 significant digits, so a number is refused whenever what canonical form would store has a different value from what you wrote:
claims_number_range: a whole number whose nearest 64-bit floating-point value is beyond 2^53 - 1 and below 10^21 in magnitude (such as9007199254740992, or1e20, which canonical form writes as 21 digits), a number no double holds (1e400), and a number too close to zero to hold at all (1e-400, which would be read as 0);claims_number_precision: a number whose canonical form has a different value.3.14159265358979323846would be stored as3.141592653589793,1000000000000000000001as1e+21, and999999999999999999999, whose nearest double is 10^21, also as1e+21. A number too close to zero for a double to hold exactly, such as3e-324, would be stored as5e-324, and the message says so. The error says what the number would be stored as, and when the number is at most 40 characters, shows it as you wrote it and gives the string to send instead ("3.14159265358979323846"), which keeps every digit.- A change of spelling alone is accepted:
1E2is kept as100,2.50as2.5,-0and0e-400as0, and1e21or1000000000000000000000as1e+21. A whole number of 10^21 or more is accepted only when canonical form keeps its exact value, which a double alone does not settle: 2^70 (1180591620717411303424) is a double, but canonical form writes it1.1805916207174113e+21, so it is refused.
-
Claims nest at most 32 levels deep. The claims object itself counts as the first level, and the limit covers every member, including ones Truestamp does not recognize. Deeper claims are refused before anything else about them is checked.
metadatahas its own, tighter limit of 10 levels. -
Claims are immutable. Once submitted they can never be edited, because changing them would change the fingerprint. What you can change later is the item’s team, its visibility, and its tags; none of those are part of any hash.
-
Your
timestampis a claim, not the guarantee. It is recorded verbatim as your own statement about the data. The provable timing is the submission window: Truestamp proves when the claims were submitted, never when the underlying data was originally created. -
locationgets a map. A location claim is displayed on the item and public verification pages as an interactive map with a reverse-geocoded place name and links to external map services. -
Separate from the claims, a submission may also carry a visibility (
private,team, orpublic; see item visibility) and tags. The APIs accept tags at submission time, and tags can be added or removed on the item afterward.
Steps
On the web
- Sign in and open
https://www.truestamp.com/items/new. - For hash mode, drag a file onto the drop zone or click it to pick one. The file is hashed locally in your browser and is never uploaded; only the resulting hash, the filename, and the algorithm are sent. Files up to 10 GB are supported, with a progress bar for large files and a Cancel button beside it that stops the hash and returns the drop zone. The filename fills the name field if you have not typed one. If you already have a hash, paste it instead and pick its algorithm from the grid (SHA-256 is the default).
- For claims-only mode, skip the hash and write a description of at least 32 characters or add at least one metadata entry.
- Fill in any optional fields: description, URL, a claimed timestamp, latitude and longitude. A field left blank is left out of the claims. The claimed timestamp is your own statement: Truestamp checks only that it is a well-formed date, does not confirm it, and never makes it part of the submission window. The description is a single line, since claims text holds no line break. A coordinate is taken as the number you type, digit for digit, and a comma works as the decimal separator (
48,8566); leading zeros (045,007.5) are dropped, which changes the spelling, not the value, while.5,+45and45.are refused. If your plan includes a metadata allowance you can add up to 8 metadata key/value pairs (keys are letters and numbers only, values up to 128 characters). An entry the claims leave out says why at the entry (a key that is not letters and numbers, a key already used by an entry above it, a key with no value, or a value with no key), and Create stays disabled until it is fixed or removed. Each field takes far more characters than its rule allows, so a long paste is cut short in your browser and still shows why it is too long. - Fix anything the form flags. As you type, the form reads your claims with the same rules and the same reader as the GraphQL API, the console and MCP, and shows each problem at its field with the same
codethose APIs return and a message in your language. Where the fix is mechanical, a Fix button applies it and shows the result in the field: whitespace at either end removed, text normalized to Unicode normalization form C, an invisible or control character removed, a character a name or description may not hold removed, a hash written in lowercase, or a coordinate replaced by the number canonical form would store. Nothing is changed until you press it. A coordinate out of range for canonical JSON (1e20,9007199254740993,1e400) is flagged at its field, where the APIs report it for the claims as a whole. The claims as a whole are limited to 65,536 bytes of JSON, as on every surface. - Check the claims to commit. The form adds a nonce of 32 random bytes by default and shows it: it makes identical claims hash differently, and keeps anyone from confirming redacted claims by guessing them. You can remove it, and add a new one. Once the claims break no rule, the form shows the exact
claims_jcsandclaims_hashthe create commits. The nonce, the hash type, the visibility and the set of metadata entries change only through their buttons, and the server keeps the choice you made last: a keystroke or a submit your browser sent just before a click’s answer came back cannot undo the click. If the page reconnects, the form restores the nonce (or its removal), the hash type, the visibility and the metadata entries from what your browser still shows, so the claims it shows are the ones you had. Keep the claims, nonce included, to restore or re-check the item later. - Choose the visibility. On the Free plan the form always submits with Public visibility and the Private and Team buttons are locked behind an upgrade prompt; on paid plans all three are selectable and Team is preselected. The lock belongs to this form alone: once the item exists you can change its visibility from its page on any plan, and API submissions default to Private on every plan.
- Select Create Item. The button is enabled once the claims break no rule and no metadata entry says why it is left out. The item holds the claims whose preview was on screen when you pressed Create Item, at the visibility the form showed. A submit whose claims or visibility changed since, as an edit, or a hash type, nonce, visibility or metadata removal chosen just before pressing Enter or Create Item can, creates nothing: the form shows the new preview with the choices made last, and asks you to check them and press Create Item again, which then commits them. A submit that carries a metadata entry the form refuses, as pressing Enter in a metadata field before leaving it can, creates nothing either: the form shows the entry’s error and the claims without it. Otherwise you are taken to the new item’s page.
Via the JSON:API
Send a JSON:API create request to the items collection:
curl -X POST https://www.truestamp.com/api/json/items \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/vnd.api+json" \
-d '{
"data": {
"type": "item",
"attributes": {
"claims": {
"name": "quarterly-report.pdf",
"hash": "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9",
"hash_type": "sha256"
},
"visibility": "team",
"tags": ["finance", "q3"]
}
}
}'
Select the team with a tenant header or query parameter carrying the team id; without one the request falls back to your default team preference or your personal team. When visibility is omitted it defaults to private. See the JSON:API surface for authentication, tenancy, and pagination conventions.
A successful create returns the item with claims_jcs, the exact canonical bytes of your claims, and claims_hash. Claims that break a rule are refused with status 422 and one error object per broken rule, each with a stable code (such as claims_empty or claims_not_nfc), a detail naming the fix, and a source.pointer at the member it concerns, under /data/attributes/claims. Send claims as a JSON object: an object sent as a string is refused with claims_not_object.
Via GraphQL
The GraphQL API exposes the same operation as the createItem mutation. It takes the claims as claimsJson, a required string holding the claims as a JSON text of at most 65,536 bytes, with their own member names (hash_type, not hashType), alongside optional visibility, tags and teamId. The text is read as sent, never trimmed or rewritten; an empty text, or one of only whitespace, is refused as a missing argument.
mutation CreateItem($input: CreateItemInput!) {
createItem(input: $input) {
result { id claimsJcs claimsHash }
errors { code message fields vars }
}
}
with the variables:
{"input": {"claimsJson": "{\"name\": \"quarterly-report.pdf\", \"hash\": \"b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9\", \"hash_type\": \"sha256\"}", "visibility": "team"}}
A successful create returns claimsJcs, the exact canonical bytes of your claims, and claimsHash. Claims that break a rule are refused with one entry in errors per broken rule, each with the same stable code as the JSON:API, a message naming the fix, and vars.pointer, a JSON pointer to the member it concerns within your claims ("" for the claims as a whole). A member name repeated in one object, and a number out of range (one no double holds, or a whole number beyond +-(2^53-1) as canonical form writes it, such as 1e20 or 9007199254740992), are refused with the pointer "", since they are found as the text is read; the message still names the reason. A claims text that is not UTF-8 is refused with 400 before GraphQL runs when it comes in a JSON body (in an application/graphql document it fails to parse, with no code), and a raw NUL character gets an argument error with no code. See the GraphQL surface.
On the console WebSocket
On an authenticated console connection, send an items.create command with claims_json, a string holding your claims as a JSON text of at most 65,536 bytes, and an optional watch flag that auto-subscribes you to the new item’s lifecycle events so you can watch it advance in real time. The claims are committed exactly as sent, under the same rules as the other APIs. They travel as a text because the console’s frames are read by a JSON decoder that keeps the first of two repeated member names and drops the other, where the claims rules refuse the repeat.
[null, "1", "console:lobby", "items.create", {
"claims_json": "{\"name\": \"server-log-2026-07-15\", \"hash\": \"b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9\", \"hash_type\": \"sha256\"}",
"watch": true
}]
Leave hash and hash_type out of the claims to submit in claims-only mode. The payload takes no other member: one such as name, description, hash or hash_type is refused with a message saying to send claims_json, and no hash type is assumed for a hash sent without one. A successful create replies with the item, watched, claims_jcs and claims_hash. Claims that break a rule are refused with the code invalid and claims_reasons, one entry per broken rule, each with its stable code, a message naming the fix, and a pointer into your claims ("" for a repeated member name or a number out of range, as over GraphQL). OAuth-authenticated connections need the console:write scope for this command; API-key connections are not scope-limited. See the console WebSocket for the wire format and stream catalog.
From the terminal
The Truestamp CLI submits items with truestamp items create. Given a file, it computes the file’s SHA-256 locally, as the web form’s drop zone does, and submits that hash, so the file never leaves your machine. The claim flags (--name, --description, --data-hash with --hash-type, and the rest) build the claims, or --claims and --claims-stdin send a claims text you wrote, exactly as given; the server checks every rule and names each one broken.
Through an MCP agent
An LLM agent connected to the MCP server submits items through a confirm-before-write flow: it first calls a preview operation that computes exactly what the create would produce (the resolved team, the claims as they would be stored with their claims_jcs and claims_hash, the effective visibility) without persisting anything, shows you the result, and only submits after you approve. Both take the claims as claims_json, the JSON text in a string of at most 65,536 bytes, committed exactly as sent under the same rules as the other APIs. The agent writes it as a Lua long-bracket string ([==[{"name":"Report", ...}]==]), which Lua keeps as written, where a quoted Lua string would have its backslash escapes rewritten first. When anything would be refused, the preview says so: claims_reasons has one entry per broken claims rule with its code, message and pointer, and reasons gives the text of any other error, such as a bad tag; claims that break no rule are still returned beside such an error. The submit refuses each broken rule as its own error with the same code and message and the pointer in vars.pointer. The agent can pick the team by id or by name, or let it default. Submitting requires the mcp:write OAuth scope. Two platform switches sit above that: the agent endpoint as a whole can be taken offline, in which case an agent cannot connect to it at all, and agent-driven item creation can be switched off on its own, which refuses submissions while leaving the agent’s reads working.
Verify
- Open the item’s page (you are taken there automatically after a web submission, and every API response returns the item’s id). Check that the claims render exactly as you intended: the name, the hash and algorithm, and the location map if you claimed one.
- Watch the state. A fresh item starts in the
createdstate and advances toprocessingand thencommittedas blocks are built on a regular cadence; the exact timing is not a fixed guarantee. See the item lifecycle for what each state means. - Once the item is committed and its block has at least one public blockchain commitment, generate the proof and check it end to end with verify a proof. If you kept your original file, re-hash it and confirm the hash matches the one in the claims.
- Programmatic checks work too: fetch the item by id over the JSON:API or GraphQL, or use a console
items.watchsubscription (orwatch: trueat create time) to receive its lifecycle events as they happen.
Troubleshooting
- “You have reached your plan’s monthly item limit.” The team billing owner’s monthly allowance, counted across all the teams they own, is exhausted. It resets with the calendar month in UTC, or the owner can upgrade.
- “You must have write access to the team.” Your role in the selected team is read-only. Switch to a team where you can write, or ask for a write-capable role.
- A name-only submission is rejected. In claims-only mode the claims must include a description of at least 32 code points or non-empty metadata; add one, or supply an external hash instead.
- Claims content exceeds the plan limit. A claims-only submission is bigger than the team owner’s plan budget. Provide an external hash (hash mode has no claims byte budget) or upgrade the team owner’s plan.
- “claims exceed maximum nesting depth of 32 levels” (
claims_too_deepover the JSON:API and GraphQL, which say the claims nest more than 32 levels deep). Some part of the claims object is nested more than 32 levels deep. Flatten it; custom structure belongs inmetadata, which allows 10 levels. - A number is refused with
claims_number_precision. It has more digits than canonical form keeps (about 15 to 17 significant digits), so it would be stored as a different number; the message shows which. Send it as a string to keep every digit, or send the number the message shows. - Metadata is refused. Custom metadata requires a plan with a metadata allowance; the Free plan has none, and each paid tier caps its size.
- “Hash length doesn’t match selected algorithm.” The pasted hash’s length disagrees with the chosen algorithm (for example, a 64-character hash is SHA-256 sized, not SHA-512). Fix the hash or the algorithm; the hash must be lowercase hexadecimal.
- The timestamp is rejected. Your
timestampclaim must be a flexible ISO 8601 value naming a real date. Whether it is past or future is never checked. - The URL is rejected. Only HTTPS URLs are accepted, and the URL must resolve to a public host; loopback, private, and other internal network addresses are refused.
- A rate-limit error. Two caps per minute protect the ingestion pipeline: one on your own account’s submissions and one platform-wide, shared across all users. Both apply however you submit, including through the API, the console and the MCP server. A refusal says how long to wait; wait that long and retry.