# API reference: which path to use, and how to authenticate immut gives a file permanent, independently verifiable proof of when it existed. This page is the orientation. Every endpoint has its own page, generated from the contract, so it can never fall behind the code. **Base URL:** `https://backend.immut.io/api/v1` **Browse every endpoint:** grouped by resource in the sidebar under Endpoint reference. **Reading this as a model?** Fetch [llms-full.txt](https://www.immut.io/llms-full.txt). Every endpoint, with parameters, responses and a working example, in one file. ## Which path should I use? There are four doors into immut. They do the same job. | Door | Use it when | Start here | |---|---|---| | Agent skill | You want something to scan your files and decide what matters | [Agent playbook](/docs/agents) | | MCP connector | Your host speaks MCP and you want tools, not code | [MCP connector](/docs/mcp) | | REST API | You are writing the integration yourself | This page | | Hash-only | You want proof without sending the file | `POST /proofs` | Most people should start with the skill or the connector. Write against the REST API when neither fits. ## How do I authenticate? Send an API key as a bearer token on every call. ```bash curl "https://backend.immut.io/api/v1/workspaces" \ -H "Authorization: Bearer imut_live_your_key" ``` Create the key in the immut app under Organization Settings, then AI Agents. Keys carry scopes, and each endpoint page names the scope it needs. If a call returns `SCOPE_NOT_PERMITTED`, that call is out of bounds for the key. Do not ask anyone to widen it. Browser code needs the CORS mirror at `https://backend.immut.io/api/public/v1`. Same routes, same auth. ## What is the shortest path to a first proof? Three calls. You need a workspace id before you can store anything. ```bash # 1. Find your workspace curl "https://backend.immut.io/api/v1/workspaces" \ -H "Authorization: Bearer $IMMUT_API_KEY" # 2. Store a file and create proof curl -X POST "https://backend.immut.io/api/v1/documents" \ -H "Authorization: Bearer $IMMUT_API_KEY" \ -F "file=@/path/to/contract.pdf" \ -F "workspace=" # 3. Verify it, with no key at all curl "https://backend.immut.io/api/public/verify/" ``` Step three is the point of the product. Anyone can run it, including a court, an acquirer, or an auditor. It needs no account and no permission from you. ## Should I upload the file or only its fingerprint? Upload it when you want immut to hold the file. Send a fingerprint when you do not. `POST /documents` takes the file itself. This is what the public skill uses, and it is what most people want, because immut can then produce the certificate and re-verify later. `POST /proofs` takes a `hash` and a `workspace`. The bytes never leave your machine. You get the same permanent proof, but immut cannot show you the file afterwards, because it never had it. That is a real tradeoff, not a lesser mode. ## How do I add a new version of something? `POST /documents/{id}/version`. Each version gets its own proof and its own timestamp. Be precise about what this proves. Each proof shows that version's content existed by the time immut received it. It does not show when the edit was made, so never date the change itself. A chain of versions is still usually worth more in diligence than a single file, because it shows the shape of the work over time. ## What about errors and limits? Read the `code`, not the message. Almost nothing is worth retrying. The two exceptions, the upload allowance response, and the rate limits are all on the [Errors page](/docs/errors). ## Where is the machine-readable contract? Three forms, all generated from the same source. | Form | URL | |---|---| | OpenAPI 3.1 | [/docs/openapi.json](/docs/openapi.json) | | Everything in one file | [llms-full.txt](https://www.immut.io/llms-full.txt) | | Bootstrap, no auth needed | `https://backend.immut.io/api/v1/docs` | Any page on this site is also available as raw markdown. Add `.md` to the URL.