v1 API reference: the public HTTP API: authentication, contacts, uploads, events and content # Authentication > Tokens, scopes, status codes and rate limits for the Erre OS v1 API. Every ErreOS API request carries a token. The token identifies the workspace it belongs to. There is no account id, workspace id or tenant parameter anywhere in the API, and you never need to look one up. ## Getting a token [Section titled “Getting a token”](#getting-a-token) Tokens are issued inside ErreOS, under **Settings**, then **API**, by a workspace owner or admin. If you are building a site for a client, ask them to mint one and send it to you; you cannot create one yourself. ## The two classes [Section titled “The two classes”](#the-two-classes) | | Publishable | Secret | | ---------------------- | --------------------------- | --------------------------- | | Prefix | `erre_pk_` | `erre_sk_` | | Safe in browser code? | **Yes** | **No, server only** | | Can it read data? | Never | Yes, if granted | | Restricted by site? | Yes, by an origin allowlist | No | | Can it be shown again? | Yes | No, copied once at creation | **A publishable token is meant to be visible.** It ships inside the JavaScript of a public web page, so treat it as public information. It is protected by being write-only and by only working from the sites its owner listed, not by being kept secret. **A secret token must never reach a browser.** It goes in server-side code, environment variables, or a backend service. Anyone holding it can act as the workspace. Pick publishable for a contact form on a website. Pick secret for a server, a build, or a serverless function: anything that reads content, and anything that posts on the site’s behalf. ## Sending it [Section titled “Sending it”](#sending-it) ```plaintext Authorization: Bearer erre_pk_your_token_here ``` Requests with a body must also send `Content-Type: application/json`. ## Permissions [Section titled “Permissions”](#permissions) A token carries a fixed set of scopes, chosen when it was created: | Scope | Grants | | ----------------- | ------------------------------------------------------------------------------- | | `contacts:write` | `POST /api/v1/contacts` | | `companies:write` | `POST /api/v1/companies` | | `files:write` | files sent with a contact (see [Uploads](/developers/api/uploads/)) | | `events:write` | `POST /api/v1/events` (see [Events](/developers/api/events/)) | | `content:read` | the four `/api/v1/content/...` routes (see [Content](/developers/api/content/)) | | `content:preview` | plus unpublished drafts, via `?preview=1` | **Scopes cannot be changed after a token is created.** If you need a different set, the workspace admin rolls the token (which issues a replacement and gives the old one a grace period) or issues a new one. A publishable token may only hold write scopes. If you need to read data, you need a secret token. `files:write` is only granted together with `contacts:write`, because the files arrive with the contact a form creates. ## Origin allowlisting [Section titled “Origin allowlisting”](#origin-allowlisting) A publishable token only works from the sites listed on it. The allowlist accepts three forms: | Entry | Matches | | --------------------- | -------------------------------------------- | | `https://example.com` | exactly that origin (a port may be included) | | `*.example.com` | any subdomain, at any depth | | `http://localhost:*` | localhost on any port, for development | Three rules worth knowing before you debug a `403`: * **A wildcard never matches the apex.** `*.example.com` does *not* match `https://example.com`. List the apex separately if you need both. * **An empty allowlist rejects everything.** A new token with no origins listed will refuse every request until origins are added. * **`https` is required** except for `localhost`. Requests with no `Origin` header at all are rejected for publishable tokens. Browsers always send one; a server-side caller does not, which is why a server-side integration needs a secret token instead. ## Status codes [Section titled “Status codes”](#status-codes) | Status | Code | What to do | | ------ | ---------------------- | -------------------------------------------------------------------------------------------------------------------- | | `201` | | Created. The response carries the new record’s `id`. | | `200` | | Already existed, because you sent a repeated `externalId`. Carries `deduplicated: true`. | | `304` | | Read endpoints only. Your `If-None-Match` still matches; there is no body. | | `400` | `invalid_json` | The body was not valid JSON. | | `400` | `invalid_content_type` | Send `Content-Type: application/json`. | | `400` | `unknown_field` | You sent a field this endpoint does not accept. See the note on `metadata` in [Contacts](/developers/api/contacts/). | | `400` | `name_required` | `name` is the one required field. | | `400` | `field_too_long` | A field exceeded its cap. The message names the field. | | `400` | `invalid_field` | A field was the wrong type, usually a number or object where a string was expected. | | `400` | `body_too_large` | The request body exceeded 32 KB. | | `401` | `unauthorized` | The token is missing, malformed, revoked or expired. Check you copied all of it. | | `403` | `forbidden_scope` | The token is valid but lacks the scope this endpoint needs. Check its permissions in Settings, then API. | | `403` | `forbidden_origin` | The site you are calling from is not on the token’s allowlist. Add it. | | `404` | `unknown_collection` | Read endpoints only. No collection with that key in this workspace. Check `?collection=` for a typo. | | `429` | `rate_limited` | Too many requests. Back off and retry. See below. | | `500` | `internal_error` | Something failed on our side. Retry. | Every error response has the same shape: ```json { "error": "forbidden_origin" } ``` Some also carry a `message` explaining the specific failure: ```json { "error": "unknown_field", "message": "\"service\" is not a field on this endpoint" } ``` **Note the asymmetry: success bodies have `"ok": true`, error bodies have no `ok` field at all.** Do not test `body.ok === false`. `ok` is `undefined` on every error. Use the HTTP status to decide success or failure (`res.ok` in `fetch`), then read `error` for the reason. Branch on `error`, not on `message`. The message is written for a developer reading a console and may change; the code will not. **A `403 forbidden_origin` deliberately carries no CORS headers.** In a browser this surfaces as a network/CORS failure rather than a readable `403`. That is what makes the allowlist meaningful. If your `fetch` fails with a CORS error and you have not added your site to the allowlist yet, that is why. ## Rate limits [Section titled “Rate limits”](#rate-limits) | Limit | Applies to | | --------------------------------------------------- | ----------------------------------------------------------------------- | | 10 requests/minute per token | every authenticated **write**, including ones that then fail validation | | 120 reads/minute per token (burst of 240) | the `/api/v1/content/...` routes | | 120 calls/minute per token (burst of 240) | the `/api/v1/uploads` routes | | 30 failed authentications/hour per IP (burst of 10) | wrong, missing or revoked tokens | The request limits are separate buckets on purpose: a nightly site build, or one visitor sending twenty photos, must not be able to throttle the same workspace’s contact form. A `429` carries a `Retry-After` header in seconds. Read it and wait. Do not retry immediately in a loop. **On the write endpoints, bursts are limited and daily volume is not.** There is no daily cap that rejects submissions. A busy day never causes a lead to be turned away. File uploads are the one exception: a token may reserve 2 GB of files a day, and past that a file is refused with `429` while contacts are still saved. [Uploads](/developers/api/uploads/#limits) has the reason and the other upload limits. Reads are counted per day per workspace, but that number rejects nothing today. It exists so we can answer “how much is this site reading” without a log grep. ## Rotation and revocation [Section titled “Rotation and revocation”](#rotation-and-revocation) A workspace admin can **roll** a token: this issues a replacement and puts the old one on a grace period of immediately, 24 hours, or 7 days. Both tokens work until the grace expires, so you can deploy the new one without downtime. **Revocation is immediate and permanent.** A revoked token cannot be restored. A replacement has to be issued and deployed. If your integration suddenly starts returning `401`, the token was almost certainly revoked or its grace period ran out. Ask the workspace admin. ## Hostnames [Section titled “Hostnames”](#hostnames) The API is served from: ```plaintext https://api.erreos.com ``` **The copy-paste snippet in Settings, then API, shows the host to use.** If this page and the snippet ever disagree, believe the snippet. Paths are versioned (`/api/v1/...`), so a future version will not change these routes. # Contacts and companies > Send a lead from a website form into the workspace CRM with POST /api/v1/contacts and POST /api/v1/companies. Post a lead straight from a website form into the workspace’s CRM. No backend of your own is required. It is designed to be called from browser JavaScript with a publishable token. Read [Authentication](/developers/api/authentication/) first for tokens, status codes and origin allowlisting. ## POST /api/v1/contacts [Section titled “POST /api/v1/contacts”](#post-apiv1contacts) Creates a contact. Requires the `contacts:write` scope. ```plaintext POST https://api.erreos.com/api/v1/contacts Authorization: Bearer erre_pk_... Content-Type: application/json ``` ### Fields [Section titled “Fields”](#fields) `name` is the only required field. Everything else is optional. Send what the form actually collected and omit the rest. | Field | Type | Max | Notes | | ------------- | ------- | ---------- | --------------------------------------------------------------------------------------------------------------- | | `name` | string | 200 | **Required.** | | `email` | string | 320 | | | `phone` | string | 40 | | | `address` | string | 500 | | | `source` | string | 100 | Where the lead came from, such as `"website"` or `"landing-page-q3"`. Your label, not a fixed vocabulary. | | `description` | string | 4000 | Free text. The visitor’s message. | | `externalId` | string | 200 | Your own id for this submission. See [externalId](#externalid-must-be-generated-once-per-form-fill). | | `metadata` | array | 20 entries | Everything else the form asked. See [Custom fields](#custom-fields-go-in-metadata). | | `uploads` | boolean | | `true` to send files with this contact. Needs the `files:write` scope. See [Uploads](/developers/api/uploads/). | Each `metadata` entry is `{ "label": string, "value": string }`. The label is capped at 64 and the value at 500. **Both must be strings.** Numbers, booleans, nested objects and `null` are rejected inside `metadata`; convert before sending. A **top-level** field set to `null` is treated as if you had omitted it, so `{ "name": "Jane", "email": null }` is accepted. Only `name` may not be empty. Request bodies are capped at 32 KB. ### Responses [Section titled “Responses”](#responses) Created: ```json { "ok": true, "id": "j57d8k2m4n6p8q0r2s4t6u8v" } ``` `201 Created` Already existed, because you sent an `externalId` that was seen before: ```json { "ok": true, "id": "j57d8k2m4n6p8q0r2s4t6u8v", "deduplicated": true } ``` `200 OK` **A deduplicated request changes nothing.** The existing contact is returned untouched. A second submission does not update the first. ### The snippet [Section titled “The snippet”](#the-snippet) The shortest thing that works, plus the one branch you must not omit: ```html ``` The same call with `curl`: ```bash curl -X POST https://api.erreos.com/api/v1/contacts \ -H "Authorization: Bearer erre_pk_..." \ -H "Content-Type: application/json" \ -d '{ "name": "Jane Doe", "phone": "+1 555 0100", "email": "jane@example.com", "description": "Looking for a quote on a back patio.", "metadata": [ { "label": "Service", "value": "permeable-pavers" }, { "label": "Budget", "value": "$10-25k" } ] }' ``` **Do not drop the `!res.ok` branch.** A form that posts and ignores the response looks like it works while silently losing every lead it fails to send. If you write nothing else, write that branch. ## Three things that catch people out [Section titled “Three things that catch people out”](#three-things-that-catch-people-out) ### Custom fields go in `metadata` [Section titled “Custom fields go in metadata”](#custom-fields-go-in-metadata) Unknown top-level keys are **rejected**, not ignored: ```json { "error": "unknown_field", "message": "\"service\" is not a field on this endpoint" } ``` That rejection is deliberate. Silently dropping a field would lose data permanently and invisibly. But it means this common shortcut fails: ```js // ✗ Rejected: sends every form input as a top-level key body: JSON.stringify(Object.fromEntries(new FormData(form))); ``` Map the known fields, and put everything else in `metadata`: ```js // ✓ const form = new FormData(e.target); body: JSON.stringify({ name: form.get('name'), email: form.get('email'), metadata: [ { label: 'Service', value: form.get('service') }, { label: 'How did you hear about us?', value: form.get('referrer') } ] }); ``` `metadata` is an **array, not an object**, because the order is preserved: it renders in the CRM in the order your form asked the questions. ### `externalId` must be generated once per form-fill [Section titled “externalId must be generated once per form-fill”](#externalid-must-be-generated-once-per-form-fill) Send an `externalId` and a repeat submission with the same value returns the original contact instead of creating a second one. This protects against a double-clicked submit button or a retry after a flaky connection. It only works if the id is stable across those retries: ```js // ✗ A new id on every attempt, so it dedupes nothing async function onSubmit(e) { const externalId = crypto.randomUUID(); await fetch(url, { /* ... */ }); } ``` ```js // ✓ One id per form-fill, reused by every retry of it let externalId = crypto.randomUUID(); async function onSubmit(e) { await fetch(url, { /* ... */ }); } function onFormReset() { externalId = crypto.randomUUID(); } ``` **Omitting `externalId` is fine.** Every submission then creates a new contact, which is the right behaviour for most forms. The same person legitimately enquiring twice should appear twice. ### Handle the rejection you will actually hit [Section titled “Handle the rejection you will actually hit”](#handle-the-rejection-you-will-actually-hit) Wiring up a new form, in order of likelihood: 1. **CORS error in the console, no status code.** Your site is not on the token’s origin allowlist. Add it in Settings, then API. Remember `*.example.com` does not cover `example.com`. 2. **`400 unknown_field`.** A form field went to the top level. Move it into `metadata`. 3. **`401 unauthorized`.** The token is truncated, revoked, or from a different workspace. Copy it again. 4. **`403 forbidden_scope`.** Real token, wrong permissions: it lacks `contacts:write`. ## POST /api/v1/companies [Section titled “POST /api/v1/companies”](#post-apiv1companies) Creates a company. Requires the `companies:write` scope, which is only available to **B2B workspaces**. If the workspace is B2C, this scope cannot be granted and the endpoint will answer `403 forbidden_scope`. | Field | Type | Max | Notes | | ------------ | ------ | --- | ---------------------------------- | | `name` | string | 200 | **Required.** | | `industry` | string | 100 | | | `website` | string | 500 | | | `address` | string | 500 | | | `source` | string | 100 | | | `externalId` | string | 200 | Same dedupe behaviour as contacts. | **Companies take no `email`, `phone` or `metadata` of their own.** A company’s contact details live on its *contacts*, the people you actually talk to. If your form collects both a company and a person, send **one** request with the person nested under `contact`; see below. The top-level field sets differ on purpose: posting a contact’s body to `/companies` fails immediately with `unknown_field` rather than quietly discarding half of it. Companies are created at the `lead` stage. ### Sending the company and the person together [Section titled “Sending the company and the person together”](#sending-the-company-and-the-person-together) Add a `contact` object. **Its fields are exactly the fields of `POST /api/v1/contacts`**: same names, same caps, same `metadata` rules, `name` still required. A body that works on one route works inside `contact` on the other. ```json { "name": "Acme Millwork", "industry": "General Contractor", "website": "acme.example", "externalId": "acme.example", "contact": { "name": "Jane Doe", "email": "jane@acme.example", "phone": "770-555-0134", "description": "Need 24 units repriced per-unit.", "externalId": "b3f1c9e2-5a77-4c31-9f0e-2d6a8b4e1c07" } } ``` This requires **both** `companies:write` and `contacts:write`. A key holding only `companies:write` can still post a plain company; sending `contact` without `contacts:write` answers `403 forbidden_scope`. Errors inside `contact` name their path, so you can tell which half was rejected: ```json { "error": "unknown_field", "message": "\"contact.role\" is not a field on this endpoint" } ``` **The contact becomes the company’s primary contact only if that company has no contacts yet.** Post a second person against the same company and they are added as an ordinary contact, and the existing primary is never changed. There is no `isPrimary` field; who the main point of contact is belongs to the workspace. #### The two `externalId`s [Section titled “The two externalIds”](#the-two-externalids) They are separate keys and they answer different questions. | Key | Identifies | Good value | | -------------------- | ------------------ | --------------------------------------------------------- | | `externalId` | **the company** | something stable, such as a domain or your own company id | | `contact.externalId` | **this form-fill** | a fresh `crypto.randomUUID()` per submission | * **`contact.externalId` is checked first.** If it has been seen before, the whole request is a no-op: no company is created, no contact is created, nothing is modified. This is what makes a retry safe. * **A company `externalId` that has been seen before reuses that company** and attaches the new person to it. * **Omit the company `externalId` and a new company is always created.** We never look a company up by its name, not exactly and not case-insensitively. Two submissions naming the same company produce two companies, and someone in the workspace merges them. This is deliberate: name-matching in a contract you have already shipped to a live page cannot be corrected later. If you have a stable company key, send it. It is the difference between a tidy CRM and one where every enquiry from the same customer forks another row. #### Responses [Section titled “Responses”](#responses-1) Both created (`201 Created`): ```json { "ok": true, "id": "", "contact": { "id": "" } } ``` Company already existed, person is new (**also `201 Created`**, because something was created): ```json { "ok": true, "id": "", "deduplicated": true, "contact": { "id": "" } } ``` Whole submission already seen (`200 OK`, nothing written): ```json { "ok": true, "id": null, "deduplicated": true, "contact": { "id": "", "deduplicated": true } } ``` ⚠️ **`id` can be `null` on that last response only.** Nothing was written, so the only company we can honestly name is whichever one that contact already belongs to, and it may belong to none. If you read `id` without checking, guard it. ## What the workspace type changes [Section titled “What the workspace type changes”](#what-the-workspace-type-changes) The workspace is either B2C or B2B, and that shapes the contact record, not the payload you send. **The fields above are identical either way.** * On a **B2C** workspace, the contact lands directly in the sales pipeline at the `new` stage. * On a **B2B** workspace, the contact lands without a stage and without a company attached. Someone in the workspace links it to the right company by hand. It is visible in the contacts list immediately. You do not need to know which type a workspace is to post to `/api/v1/contacts`. **If your form has a company field, post to `/api/v1/companies` with `contact` instead.** That connects the two for you. `/api/v1/contacts` is for forms that collect a person and nothing else; on a B2B workspace it will produce a contact with no company attached, which is correct when there was no company to attach, and merely untidy when there was. ## What happens after a successful post [Section titled “What happens after a successful post”](#what-happens-after-a-successful-post) The contact is saved, and the workspace is notified with an in-app activity entry plus an email to the addresses its admins configured. **Notification is not part of your request’s outcome.** If the response says `201`, the contact is saved, whether or not the email went out. Never retry a `201` on the assumption that a notification failed. # Content > Read a workspace's published website content: collections, entries and Markdown bodies. Read a workspace’s published website content: the collections it authored, their entries, and the Markdown body of any one of them. Read [Authentication](/developers/api/authentication/) first for tokens, status codes and rate limits. **Reads require a secret token (`erre_sk_`).** A publishable token may only hold write scopes, so there is no browser-safe way to call these endpoints, and there is not meant to be. See [Why a successful read has no CORS headers](#why-a-successful-read-has-no-cors-headers). The scope is `content:read` **on a workspace API key**. That string also names an MCP scope on a different credential for a different product surface, so if you are asking a workspace admin for access, ask for “`content:read` on a workspace API key in Settings, then API”. ## The routes [Section titled “The routes”](#the-routes) | Route | Returns | | --------------------------------- | -------------------------------------- | | `GET /api/v1/content/collections` | the schema of every collection | | `GET /api/v1/content/entries` | a page of entries, as JSON | | `GET /api/v1/content/entries.md` | one entry as Markdown with frontmatter | | `GET /api/v1/content/types.ts` | the schema as a TypeScript file | ```bash curl https://api.erreos.com/api/v1/content/entries?collection=blog \ -H "Authorization: Bearer erre_sk_..." ``` ## Types without a package [Section titled “Types without a package”](#types-without-a-package) Every route here is plain HTTPS, and [Generating types](#generating-types) gives you a TypeScript file for your schema. Together they type a `fetch` with no dependency: ```ts import type { ErreCollectionEntries } from './lib/erre'; // written by GET /types.ts async function list(collection: K) { const res = await fetch(`${API}/api/v1/content/entries?collection=${collection}`, { headers: { Authorization: `Bearer ${process.env.ERRE_API_KEY}` } }); if (!res.ok) throw new Error((await res.json()).error); return (await res.json()).entries as ErreCollectionEntries[K][]; } const posts = await list('blog'); posts[0]?.fields.categoria; // "guias" | "noticias" | undefined ``` A typed client, `@erreos/content`, is built and not yet on npm. When it is, it adds `listAll` (follows the cursor), errors as values, typed `filter` keys, and `npx erre-content types` to write the file above. ## GET /api/v1/content/entries [Section titled “GET /api/v1/content/entries”](#get-apiv1contententries) | Parameter | Values | Notes | | -------------- | ------------------------ | -------------------------------------------------------------- | | `collection` | a collection key | **Required.** The `key` from `/collections`. | | `slug` | an entry slug | Returns that one entry, or an empty array. Never empty. | | `sort` | `published_at`, `order` | Default `published_at`, newest first. `order` is ascending. | | `limit` | 1–100 (1–25 with a body) | Default 20. | | `cursor` | from `pagination.cursor` | Opaque. Do not construct one. | | `include` | `body` | Adds the Markdown body to each entry. | | `preview` | `1` | Serves drafts. Needs `content:read` **and** `content:preview`. | | `filter.` | a value | Up to three. See [Filtering](#filtering). | Any other parameter is a `400` that names it. `sort=title` is not offered. A parameter sent with an **empty value** is a `400` too, never a parameter we ignore: `?slug=` from a `?? ''` would otherwise return the whole collection and `?cursor=` would restart your walk at page one forever. `?slug=` matches the **published** slug: the one in the responses above, and the one your URLs were built from. An author renaming a draft does not move it; publishing does. Under `?preview=1`, `?slug=` matches the draft’s slug instead, which is the point of a preview. ### The response [Section titled “The response”](#the-response) ```json { "ok": true, "collection": { "key": "blog", "contractRevision": 12, "publishedCount": 42 }, "pagination": { "limit": 20, "hasMore": true, "cursor": "eyJ2IjoxLCJwIjoi..." }, "entries": [ { "id": "k57d8k2m4n6p8q0r2s4t6u8v", "collection": "blog", "slug": "como-cotizamos-una-cocina", "title": "Cómo cotizamos una cocina", "status": "published", "revision": 7, "order": 3, "publishedAt": "2026-09-14T15:04:05.000Z", "contractRevision": 12, "seo": { "title": "Cómo cotizamos una cocina a medida", "description": "Los tres números detrás de cada presupuesto.", "image": { "url": "https://.../og.jpg", "width": 1200, "height": 630 } }, "fields": { "resumen": "Los tres números detrás de una cotización.", "categoria": "guias", "autor": { "id": "k17c9...", "collection": "team", "slug": "ana-ruiz", "title": "Ana Ruiz", "fields": { "rol": "Directora" } } } } ] } ``` Everything we own is at the top level; everything the workspace authored is under `fields`. That is why a workspace can name a field `status` or `revision` without colliding with ours. **`title` and `slug` are top-level, never inside `fields`.** `entry.fields.title` reads `undefined` forever. There is no 404 and no error, just a blank heading on your live page. `/collections` marks every key with `location: "top"` or `"fields"` so a codegen cannot get this wrong. **An absent field has no key.** It is not `null`, not `""`, not a zero. That holds whether the field is required, retired, taken off the site, or a reference whose target was archived. So `if (!entry.fields.resumen)` is correct for every type and every kind of absence, and `=== null` is correct for none of them. **`seo` is the author’s meta tags**, top-level because every entry has one and no workspace declares it: `title`, `description` and `image` (the same shape as an `image` field), each optional. An entry with none written has no `seo` key, so read it as `entry.seo?.title ?? entry.title`. Values are untagged: `fields.resumen` is the string, not `{ type, value }`. You cannot tell `text` from `url` from `select` by looking at an entry. That is what `/collections` is for. | Type | On the wire | | ----------- | ------------------------------------------------------------ | | `text` | string | | `number` | number | | `boolean` | boolean | | `date` | `"YYYY-MM-DD"`, a calendar day with no timezone and no time | | `select` | the option’s **value**, never its label | | `tags` | array of strings | | `url` | string | | `image` | `{ url, alt?, width?, height? }` | | `gallery` | array of the above | | `file` | `{ url, name, mime, bytes }` | | `reference` | see [References](#a-reference-is-a-snapshot-not-a-live-view) | | `list` | array of row objects (see below) | `publishedAt` is the only ISO-8601 value in the payload. Everything else that looks like a date is a `date` field and is a calendar day. ### Image and file URLs are permanent, and public from the moment they upload [Section titled “Image and file URLs are permanent, and public from the moment they upload”](#image-and-file-urls-are-permanent-and-public-from-the-moment-they-upload) An `image`, `gallery` or `file` `url` is an absolute address on a public bucket. It does not expire, it carries no token, and it works for a crawler, a static build and a link unfurler. That is the point, since none of those can present a credential. The corollary is that **an image is fetchable by anyone holding its URL as soon as it uploads, weeks before its entry is published.** Nothing about a draft, an archive or a retired field changes that; what protects an unannounced photograph is that its URL has never been given out. Treat a preview build’s image URLs as published. A URL stops working thirty days after a publish replaces the image behind it. Copy the bytes if you need your own permanent copy; do not cache the URL and assume the object. ### A list is an array of rows, and every row must be probed [Section titled “A list is an array of rows, and every row must be probed”](#a-list-is-an-array-of-rows-and-every-row-must-be-probed) ```js // ✓ A list with no rows is omitted entirely, so the `?? []` is not optional. (entry.fields.hours ?? []).map((row) => `${row.day}: ${row.opens ?? 'closed'}`); ``` ```js // ✗ Throws on the first entry nobody filled the field in on. entry.fields.hours.map(...) ``` **Rows are ragged.** The absent-key rule applies inside a row exactly as it applies between entries: a row where nobody filled `closes` has no `closes` key. That is different from top-level raggedness and it catches people out. Check every key you read out of a row. ### Reading every entry [Section titled “Reading every entry”](#reading-every-entry) Follow `pagination.hasMore`. There is no offset and no cap. ```js const entries = []; let cursor; do { const url = new URL('https://api.erreos.com/api/v1/content/entries'); url.searchParams.set('collection', 'blog'); url.searchParams.set('limit', '100'); if (cursor) url.searchParams.set('cursor', cursor); const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.ERRE_TOKEN}` } }); if (!res.ok) throw new Error(`ErreOS ${res.status}: ${(await res.json()).error}`); const page = await res.json(); entries.push(...page.entries); cursor = page.pagination.cursor; } while (cursor); ``` **`collection.publishedCount` is advisory.** Draw a progress bar with it if you like; never loop on it. The loop condition is `hasMore`. A sitemap built against a count that drifted is a sitemap missing pages under a green build. A cursor is only valid for the query that produced it. Change `sort`, `slug`, `include`, `preview` or a filter mid-walk and the next request is `400 invalid_cursor` rather than a page from somewhere else. ### Filtering [Section titled “Filtering”](#filtering) `filter.=` keeps the entries whose field matches. Four field types can be filtered, and `/collections` marks each such field `filterable: true`: | Type | Matches when | | ----------- | ---------------------------------------------------------- | | `select` | the value equals one of the field’s option **values** | | `boolean` | the value is `true` or `false`, as sent | | `tags` | the entry has that tag | | `reference` | the target’s slug or id. A catalog reference matches by id | ```bash curl "https://api.erreos.com/api/v1/content/entries?collection=blog&filter.categoria=guias&filter.destacado=true" \ -H "Authorization: Bearer erre_sk_..." ``` * **At most three filters**, combined with AND. Each key once. * Filters read the **published** entry, the same values the response shows. Under `?preview=1` they read the draft. * **An absent field matches nothing**, `false` included: `filter.destacado=false` returns the entries where someone set it to false, not the ones nobody touched. * A reference matches the slug frozen when the referring entry was last published (see [References](#a-reference-is-a-snapshot-not-a-live-view)). A target renamed since then still matches by its id. * A key that names no field is `400 unknown_param`. A field that cannot be filtered (text, number, date, url, media, list), a select value that is not one of its options, a boolean that is not `true`/`false`, an empty value or a fourth filter is `400 invalid_param`. A select with no options yet cannot be filtered. * Filters compose with `sort`, `slug`, `limit` and `cursor`, and are part of the `ETag`. **A filtered page can be short, even empty, while `hasMore` is `true`.** Fields are not indexed, so a filtered request reads the collection in order and keeps what matches, and it stops after 500 entries (the most a collection can have live), so a published walk usually finishes in one request. Past that the page comes back with what it found and a cursor. Keep following `hasMore`, as for any walk. ## GET /api/v1/content/collections [Section titled “GET /api/v1/content/collections”](#get-apiv1contentcollections) Takes **no parameters at all**, including `preview`. A schema has no draft half. This is the contract document. Each collection carries `key`, `label`, `labelPlural`, `icon`, `bodyMode`, `seo`, `schemaRevision`, `contractRevision` and `fields[]`. Each row of `fields[]` carries `key`, `label`, `type`, `required`, `location`, and then `filterable`, `format`, `currency`, `unit`, `maxItems`, `options`, `refCollection`, `refTarget`, `refFields`, `itemFields`, `retired` and `replacedBy` where they apply. **`format` says how to draw a value, never what type it is.** The value under `entry.fields` keeps its `type`. A `text` field may carry `tel`, `email`, `multiline` or `color`. A `number` field may carry: | `format` | The value | Also on the row | | -------- | --------------------------------------------------------- | --------------------------------------------------------------- | | `money` | A number, in the currency’s major unit (`1200` is $1,200) | `currency`: an ISO 4217 code such as `"MXN"` | | `unit` | A number | `unit`: the suffix to print after it, such as `"m²"` or `"hrs"` | | `rating` | A whole number from 1 to 5, drawn as stars | nothing | A number field with no `format` is a plain number. **Assert on `contractRevision`, never on `schemaRevision`.** `contractRevision` moves when the emitted key set or its meaning moves: a key appears, a type appears, an option value appears or retires, field order changes, a field retires, a field stops being served. `schemaRevision` moves on every schema save, a relabel included, so asserting on it fails your 03:00 build because somebody fixed an accent in a Spanish label at 16:00. **The system rows use the frontmatter spelling.** `published_at` and `contract_revision` appear in `fields[]` under those names; the JSON envelope above spells the same two `publishedAt` and `contractRevision`. Only the `location: "fields"` rows describe keys under `entry.fields`, which is the half a codegen reads. A **retired collection** is omitted from this document while `/entries` keeps answering for it. That is the migration window, not a bug. A **retired field** is still listed, flagged `retired: true` with `replacedBy` where there is a successor. A `select` with no `options` and a `list` with no `itemFields` are legal: both keys are omitted while empty, because a field is created in one step and configured in the next. Code that reads them needs a `?? []`. ### Generating types [Section titled “Generating types”](#generating-types) `GET /api/v1/content/types.ts` serves this document as a TypeScript file. Same token, same scope, no parameters, and the same `ETag` and caching rules as `/collections`. Write it into your project and commit it: ```bash curl -sS https://api.erreos.com/api/v1/content/types.ts \ -H "Authorization: Bearer $ERRE_TOKEN" -o src/lib/erre.ts ``` Once `@erreos/content` is on npm, `npx erre-content types --out src/lib/erre.ts` writes the same file. The file has, per collection, a `Entry` (the envelope, with `collection` as a literal) and a `Fields` with **every property optional**: `required` means we will not let an author publish without it, not that the key is on every entry you read. Beyond that: * a `select` is the union of its option values, retired options included; * a `list` is an array of a `Row` interface; * a `reference` names its collection and types the keys it carries; * a `format` never changes the type: a `money` field is a `number`; * a retired field is still there, marked `@deprecated`, and a field taken off the website is not; * a `Filters` lists what `filter` accepts: a select’s option values, a boolean, one tag, a reference’s slug or id; * `ERRE_CONTRACT` holds every collection’s `contractRevision`; * `ErreCollectionEntries` and `ErreCollectionFilters` map each key to its types, and a `declare module "@erreos/content"` block types the client’s calls by collection key. Without the package installed the block does nothing. Names come from the collection key in PascalCase (`case_studies` becomes `CaseStudiesEntry`). Two keys that come out the same are numbered in order (`CaseStudies2Entry`). Assert `ERRE_CONTRACT` against the live `contractRevision` in your build and fail on a mismatch. The generated file can only ever grow: keys and types are immutable, and fields and options only append, so regenerating never removes a property and never changes one’s type. Two things that assertion cannot tell you: * A retired field keeps serving its last values. **“Still served” is not “still correct”.** * Taking a field off the website removes its key. That is the only operation in the system that narrows what you receive, and it is the whole reason `contractRevision` is asserted rather than merely logged. ## GET /api/v1/content/entries.md [Section titled “GET /api/v1/content/entries.md”](#get-apiv1contententriesmd) `?collection=` and `?slug=`, both required. Returns `200 text/markdown; charset=utf-8`: YAML frontmatter between `---` fences, one blank line, then the body byte for byte. ```plaintext --- id: "k57d8k2m4n6p8q0r2s4t6u8v" collection: "blog" slug: "como-cotizamos-una-cocina" title: "Cómo cotizamos una cocina" status: "published" revision: 7 published_at: "2026-09-14T15:04:05.000Z" order: 3 contract_revision: 12 seo: title: "Cómo cotizamos una cocina a medida" resumen: "Los tres números detrás de una cotización." --- Todo presupuesto de cocina se arma con tres números... ``` Every string is quoted and escaped; `number` and `boolean` are bare, so you can read them as a number and a boolean. **An unknown or unpublished slug returns `200` with an empty body**, not a `404`. Check for an empty string. A real document always opens with `---`. **Its errors are JSON, not Markdown**, so never branch your parser on the status code. Check `res.ok` first. The `.md` you download is a render, not the file we store. There is no importer: editing one and mailing it back does nothing. ## A reference is a snapshot, not a live view [Section titled “A reference is a snapshot, not a live view”](#a-reference-is-a-snapshot-not-a-live-view) **A reference carries the values the target had when the *referring* entry was last published. It is not a join and it does not update when the target changes.** Viajes Riviera runs Tours and Hoteles. Nine published tours reference `hotel-xcaret-mexico`. On Tuesday the hotel rebrands (new title, new slug) and is republished. That publish freezes the hotel’s own snapshot and touches nothing else. The nine tours keep serving `{"slug": "hotel-xcaret-mexico", "title": "Hotel Xcaret México"}` until each of them is republished, and their `revision` has not moved, which is correct: nobody edited a tour. Republishing the referring entry is what refreshes it. If a card shows an old name or links to a 404, that is the fix. A reference to a catalog item has a different shape (`{ id, target: "catalogItem", title, unit, kind }`) and never carries a price. The catalog is what a quote is built from; the website is not a second source of price. ## Bodies are Markdown, not HTML [Section titled “Bodies are Markdown, not HTML”](#bodies-are-markdown-not-html) A body is the bytes the author typed, unrendered, including any HTML they typed. **Pass it through your own Markdown renderer. Never `innerHTML`.** Nothing on our side sanitizes it, and anyone in the workspace who can edit content can publish. The consuming site owns that boundary. ## Caching [Section titled “Caching”](#caching) Published responses carry a weak `ETag` and `Cache-Control: private, max-age=60, stale-while-revalidate=300`. Send the tag back as `If-None-Match` and an unchanged response is a `304` with no body. ```bash curl -sS -D- -o/dev/null \ "https://api.erreos.com/api/v1/content/entries?collection=blog" \ -H "Authorization: Bearer erre_sk_..." \ -H 'If-None-Match: W/"12-40-1-9a3f1c02"' ``` The response is `private` because it required a secret token. A shared cache must never hold it. Responses also carry `Vary: Authorization`, and a tag is scoped to the workspace that minted it: the URL names no tenant, so a cache that keyed on the URL alone would serve one workspace’s content to another’s token. On `/entries`, a publish, an unpublish, an archive, a reorder and taking the collection’s entries off the site all move the tag. On `/collections`, any schema save does, including a relabel, since this document prints labels. `?preview=1` responses carry `Cache-Control: no-store` and **no `ETag`**. Do not cache a draft anywhere, including in a framework’s data cache. ## Previewing drafts [Section titled “Previewing drafts”](#previewing-drafts) `?preview=1` serves the draft of every entry, including never-published ones and the unsaved-since-publish state of published ones. It needs a **separate token** holding `content:read` **and** `content:preview`: every route on this reference checks `content:read` first, and `content:preview` is checked on top of it. A token holding `content:preview` alone is `403 forbidden_scope` on every request, preview or not. Scopes are fixed for a key’s life, so that mistake is a roll and not an edit. Separate, because a key that can read drafts can put unfinished work on a live site. One key holding both `content:read` and `content:preview` leaves a query parameter in a template as the only thing between a draft and the public. Give the preview context its own key and keep it out of the production build. ## Why a successful read has no CORS headers [Section titled “Why a successful read has no CORS headers”](#why-a-successful-read-has-no-cors-headers) A `200` from these routes carries no `Access-Control-Allow-Origin`, deliberately. A browser therefore cannot read one. That is the point. These endpoints need a secret token, and a secret token in a browser is the workspace’s entire content credential published in view-source. Withholding the header means that mistake fails on the machine of the person making it, instead of shipping. Call these from your server, your build, or a serverless function. Never call them from client-side JavaScript. A `401`, `403` or `429` does carry the header, so an origin-level failure is still readable while you are debugging. ## Status codes [Section titled “Status codes”](#status-codes) | Status | `error` | When | | ------ | -------------------- | ---------------------------------------------------------------------------------------- | | `200` | | a read, including an empty `entries` array | | `304` | | your `If-None-Match` still matches | | `400` | `unknown_param` | a parameter this endpoint does not take. The message names it | | `400` | `missing_param` | no `collection`, or `entries.md` with no `slug` | | `400` | `unknown_param` | a `filter.` that names no field | | `400` | `invalid_param` | a `limit`, `sort`, `include`, `preview`, empty `slug`, or a filter the field cannot take | | `400` | `invalid_cursor` | a cursor that did not decode, was empty, or came from another | | `401` | `unauthorized` | no token, wrong token, revoked, expired | | `403` | `forbidden_scope` | the token lacks `content:read` or `content:preview` | | `404` | `unknown_collection` | no collection with that key in this workspace | | `429` | `rate_limited` | back off; honour `Retry-After` | | `500` | `internal_error` | ours | **There is exactly one `404`, and it is for a collection key.** An unknown *slug* is a `200` with an empty array, because an entry’s absence is ordinary data. It was probably unpublished five minutes ago, and a build that throws on that wakes somebody for a correct state. A typo’d `?collection=` is the opposite: `200 []` for `?collection=blogs` would build green and ship empty. **Error bodies have no `ok` field at all**, so `body.ok === false` is `undefined` on every error. Branch on `error`, never on `message`. The message is written for a developer reading a console and may change. ## Rate limits [Section titled “Rate limits”](#rate-limits) 120 reads per minute per token, with a burst of 240. A server-rendered site never approaches it and a static build of a few hundred pages finishes well inside it. `include=body` plus keyset paging is what keeps that true. `limit=100` without a body, `limit=25` with one. If you hit it, the number is a starting estimate rather than a measured ceiling. Tell your Erre contact what your build does; that is the conversation that moves it. # Events and bookings > Put a booking or a meeting on the workspace Calendar with POST /api/v1/events. Put a booking on the workspace’s Calendar straight from a website, or a meeting from a server. No backend of your own is required: a publishable token can post from browser JavaScript. Read [Authentication](/developers/api/authentication/) first for tokens, status codes and origin allowlisting. ## POST /api/v1/events [Section titled “POST /api/v1/events”](#post-apiv1events) Creates an event. Requires the `events:write` scope. ```plaintext POST https://api.erreos.com/api/v1/events Authorization: Bearer erre_pk_... Content-Type: application/json ``` ### Fields [Section titled “Fields”](#fields) `startsAt` is required, and so is a `title` or a `name`. Everything else is optional. | Field | Type | Max | Notes | | ----------------- | ------- | ---- | ----------------------------------------------------------------------------------------------------------------- | | `startsAt` | string | | **Required.** ISO 8601 with an offset. See [Send the offset](#send-the-offset). | | `title` | string | 200 | What the event is called. With none, the customer’s `name` is used. | | `name` | string | 200 | The customer who booked. Required when you send `email` or `phone`. | | `email` | string | 320 | The customer’s. | | `phone` | string | 40 | The customer’s. | | `endsAt` | string | | ISO 8601 with an offset. Send this or `durationMinutes`, not both. | | `durationMinutes` | integer | | A whole number of minutes, 1 or more. With neither this nor `endsAt`, the event runs 60. | | `kind` | string | | `"booking"` (the default), `"meeting"` or `"other"`. | | `notes` | string | 5000 | Free text. Shown as the event’s description. | | `location` | string | 300 | An address, a room or a link. | | `assignee` | string | 320 | The email of the workspace member whose calendar it goes on. Secret tokens only. See [Who gets it](#who-gets-it). | | `externalId` | string | 200 | Your own id for this booking. See [Retries](#retries-need-an-externalid). | A field set to `null` is treated as if you had omitted it. A field this endpoint does not list is rejected with `unknown_field`. An event must end after it starts and can run for 7 days at most. Request bodies are capped at 32 KB. ### Responses [Section titled “Responses”](#responses) Created: ```json { "ok": true, "id": "k17d8k2m4n6p8q0r2s4t6u8v" } ``` `201 Created` Already existed, because you sent an `externalId` that was seen before: ```json { "ok": true, "id": "k17d8k2m4n6p8q0r2s4t6u8v", "deduplicated": true } ``` `200 OK` **A deduplicated request changes nothing.** The first event is returned as it is. A second post does not move or rename it. ### Errors of this endpoint [Section titled “Errors of this endpoint”](#errors-of-this-endpoint) All are `400`. The shared ones (`401`, `403`, `429`, `unknown_field`, `field_too_long`) are in [Authentication](/developers/api/authentication/). | Code | Meaning | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `invalid_time` | `startsAt` is missing, has no offset, is not a real date, ends before it starts or runs too long. Also `durationMinutes` that is not a whole number of 1 or more, or sent together with `endsAt`. | | `title_required` | Neither `title` nor `name` was sent. | | `name_required` | `email` or `phone` was sent with no `name`. | | `invalid_field` | A field has the wrong type, or `kind` is not one of the three. | | `unknown_assignee` | `assignee` is not the email of a member of this workspace. Nothing was written. | | `assignee_not_allowed` | `assignee` was sent with a publishable token. Nothing was written. | ### The snippet [Section titled “The snippet”](#the-snippet) ```html ``` The same call with `curl`, from a server. It names an `assignee`, so it uses a secret token: ```bash curl -X POST https://api.erreos.com/api/v1/events \ -H "Authorization: Bearer erre_sk_..." \ -H "Content-Type: application/json" \ -d '{ "name": "Jane Doe", "email": "jane@example.com", "phone": "+1 555 0100", "startsAt": "2026-11-20T10:00:00-06:00", "durationMinutes": 45, "notes": "First visit. Gate code 4411.", "assignee": "ana@yourbusiness.com" }' ``` **Do not drop the `!res.ok` branch.** A form that posts and ignores the response looks like it works while losing every booking it fails to send. ## Four things that catch people out [Section titled “Four things that catch people out”](#four-things-that-catch-people-out) ### Send the offset [Section titled “Send the offset”](#send-the-offset) `"2026-11-20T10:00:00"` is refused with `invalid_time`. With no offset it is ten o’clock in a zone the server would have to guess, and a booking that lands an hour off is worse than an error you see once. Send `Z` or an offset: `"2026-11-20T16:00:00Z"`, `"2026-11-20T10:00:00-06:00"`. A date that does not exist is refused the same way: `2026-02-31` and `T24:00` are errors, not 3 March and the next morning. In a browser, `new Date(localDateAndTime).toISOString()` reads the visitor’s own clock and gives you the instant. If your business takes bookings on its own clock whatever the visitor’s is, build the string with your business’s offset. ### The time is not checked [Section titled “The time is not checked”](#the-time-is-not-checked) This endpoint does not look at what is already on the calendar. Two bookings at ten are two events at ten. There is no availability endpoint: if your form offers slots, your form decides which are free. ### Who gets it [Section titled “Who gets it”](#who-gets-it) With an `assignee`, the event goes on that member’s calendar. The value is the email they are a member with, in any letter case. An address that is not a member’s is refused with `unknown_assignee` and nothing is saved. So is someone with an account who was asked to join and has not answered yet. **`assignee` needs a secret token.** A publishable token is visible in your page’s source, so it may not name a person: a request that sends `assignee` with one is refused with `assignee_not_allowed`. Post from the browser without it, or post from your server with a secret token. With no `assignee`, the event is on nobody’s calendar yet. The workspace’s owners and admins see it on theirs and put a person on it. ### Retries need an `externalId` [Section titled “Retries need an externalId”](#retries-need-an-externalid) Without one, a retried request makes a second event. Generate an id once per booking, not once per request, and send the same one on every attempt. The second attempt answers `200` with `"deduplicated": true` and the first event’s `id`. ## What happens after a successful post [Section titled “What happens after a successful post”](#what-happens-after-a-successful-post) The event appears on the Calendar at once, as a booking with the customer’s name, email and phone on it. No notification is sent and no contact is created: if you also want the person in the CRM, post them to [`/api/v1/contacts`](/developers/api/contacts/) as well. # Uploads > Let a website form send files with the contact it creates. Let a website form send files with the contact it creates: tax documents, photos of an ID, a signed PDF. The files land in the workspace on that contact. Like [contacts](/developers/api/contacts/), this is called from browser JavaScript with a publishable token, and needs no backend of your own. Read [Authentication](/developers/api/authentication/) first for tokens, status codes and origin allowlisting. ## Before you start [Section titled “Before you start”](#before-you-start) Two things have to be true: 1. **The token holds `files:write` as well as `contacts:write`.** A workspace admin chooses “Receive files with a contact” when creating the token in Settings, then API. Scopes cannot be added to an existing token, so an older token needs a replacement. 2. **Your site is on the token’s origin allowlist**, as for contacts. The bytes do not go to the API. They go straight to storage, on a different host, which accepts an upload from any site that holds a signed URL. If your site sends a Content-Security-Policy, its `connect-src` has to allow that host as well as the API’s, or the `PUT` is blocked by the browser. ## How it works [Section titled “How it works”](#how-it-works) 1. Post the contact with `"uploads": true`. The response carries an upload token. 2. For each file: reserve it, `PUT` the bytes to the URL you get back, confirm it. 3. Tell the API you are done. The upload token is good for one hour and belongs to that one contact. It is not a secret to guard like a password, but it is not the publishable token either: do not hard-code it, and do not reuse it for another visitor. ## 1. Open an upload session [Section titled “1. Open an upload session”](#1-open-an-upload-session) Add `uploads: true` to the body of [`POST /api/v1/contacts`](/developers/api/contacts/). ```json { "name": "Dana Ruiz", "email": "dana@example.com", "uploads": true } ``` `201 Created` ```json { "ok": true, "id": "j57d8k2m4n6p8q0r2s4t6u8v", "upload": { "token": "erre_up_Q2x...", "expiresAt": 1794000000000, "maxFiles": 20, "maxFileBytes": 26214400, "maxTotalBytes": 209715200 } } ``` `expiresAt` is a Unix time in milliseconds. Read the three limits from the response and check files against them before you reserve, so the visitor hears about a file that is too big before they wait for it. **The contact is saved even when uploads are not available.** In that case the status is still `201` and the body says so: ```json { "ok": true, "id": "j57d8k...", "upload": null, "uploadError": "rate_limited" } ``` | `uploadError` | Meaning | | --------------- | -------------------------------------------------------------------------------------------------------- | | `rate_limited` | Too many upload sessions were opened from this visitor’s network in the last hour. | | `session_ended` | You repeated an `externalId` whose upload session has expired or was completed. See [Retries](#retries). | Tell the visitor their details were received and ask them to send the files another way. Do not show an error for the whole form: the lead is already in the CRM. A token without `files:write` that sends `uploads: true` gets `403 forbidden_scope` and **nothing is saved**, not even the contact. ## 2. Send each file [Section titled “2. Send each file”](#2-send-each-file) ### Reserve [Section titled “Reserve”](#reserve) ```plaintext POST /api/v1/uploads Authorization: Bearer erre_pk_... Content-Type: application/json ``` | Field | Type | Notes | | ------------- | ------ | -------------------------------------------------------------------- | | `token` | string | **Required.** The upload token. | | `name` | string | **Required.** The file’s name, up to 200 characters. | | `size` | number | **Required.** The file’s exact size in bytes (`file.size`). | | `contentType` | string | The file’s MIME type (`file.type`). Empty is fine for unknown types. | `201 Created` ```json { "ok": true, "fileId": "k97c1...", "uploadUrl": "https://...", "headers": { "Content-Type": "application/pdf", "Content-Disposition": "attachment; filename=\"w2.pdf\"" }, "expiresInSeconds": 600 } ``` ### PUT the bytes [Section titled “PUT the bytes”](#put-the-bytes) `PUT` the file to `uploadUrl` within ten minutes, sending **exactly** the `headers` from the response and no `Authorization` header. The URL was signed for that size and those headers. A different file, a different `Content-Type` or a missing `Content-Disposition` is refused by storage with `403`. Send the `File` object itself as the body, not a `FormData`. ### Confirm [Section titled “Confirm”](#confirm) ```plaintext POST /api/v1/uploads/confirm { "token": "erre_up_...", "fileId": "k97c1..." } ``` `200 OK` with `{ "ok": true }`. **The file is saved from this moment.** A file you reserved and never confirmed is not in the workspace and is discarded within the hour. Confirming twice is harmless. ### If the PUT fails [Section titled “If the PUT fails”](#if-the-put-fails) ```plaintext POST /api/v1/uploads/remove { "token": "erre_up_...", "fileId": "k97c1..." } ``` This gives the file’s place back, so a retry does not count as a second file. You can only remove a file you have not confirmed. Once confirmed it belongs to the workspace, and `remove` answers `409 file_already_saved`. ## 3. Finish [Section titled “3. Finish”](#3-finish) ```plaintext POST /api/v1/uploads/complete { "token": "erre_up_..." } ``` `200 OK` ```json { "ok": true, "files": 3 } ``` `files` is how many were saved. The workspace is told about the files at this point, once, and the upload token stops working. If you never call it, the files are still saved and the workspace is told about ten minutes after the last one. ## The snippet [Section titled “The snippet”](#the-snippet) A form with name, email and a file input. It is longer than the contacts snippet because every branch here is one a visitor will reach. ```html

``` **The three status messages are not optional.** There are three different outcomes and a visitor who sent tax documents needs to know which one happened: nothing was saved, the contact was saved without files, or some files did not arrive. Files go one at a time on purpose. A phone on a weak connection finishes more of them that way than it does with five uploads competing. ## Limits [Section titled “Limits”](#limits) | Limit | Value | | ------------------------------ | ----------------------- | | Files per submission | 20 | | One file | 25 MB | | All files of one submission | 200 MB | | Upload token lifetime | 1 hour | | Signed upload URL lifetime | 10 minutes | | Upload sessions per network | 6 an hour, per token | | Upload calls | 120 a minute, per token | | Total reserved through a token | 2 GB a day | The limits in the contact response (`maxFiles`, `maxFileBytes`, `maxTotalBytes`) are the ones to code against. If these numbers change, the response changes with them and this table may lag. **The daily total is the one limit that turns visitors away.** It exists because a publishable token is public, and without it anyone who copied the token could fill the workspace’s storage. When it is spent, reserving a file answers `429` until the day rolls over. Contacts are still saved. If a site reaches it with real traffic, tell ErreOS. ## Errors on the upload routes [Section titled “Errors on the upload routes”](#errors-on-the-upload-routes) The codes in [Authentication](/developers/api/authentication/) apply here too. These are the ones specific to uploads: | Status | Code | What to do | | ------ | --------------------------- | ---------------------------------------------------------------------------------------------- | | `400` | `invalid_field` | `name`, `size`, `token` or `fileId` is missing or the wrong type. | | `400` | `unknown_field` | You sent a field this route does not accept. | | `404` | `unknown_file` | That `fileId` is not one this upload token reserved, or it was already removed. | | `409` | `too_many_files` | The submission already holds 20 files. | | `409` | `upload_allowance_exceeded` | This file would take the submission past 200 MB. | | `409` | `too_many_attempts` | The token reserved and removed too many times. Start a new submission. | | `409` | `file_already_saved` | `remove` only. The file was confirmed. | | `410` | `upload_session_ended` | The upload token is unknown, expired or completed. Stop sending. Confirmed files are saved. | | `413` | `file_too_large` | The file is over 25 MB. | | `429` | `rate_limited` | Too many calls, or the token’s daily total is spent. `Retry-After` says how long, in seconds. | | `507` | `storage_full` | The workspace’s storage is full. Nothing you can fix from the site; tell the visitor to email. | For a visitor, every one of these means the same thing: this file did not arrive. The snippet treats them alike for that reason. Log the code so you can tell them apart later. ## Retries [Section titled “Retries”](#retries) Send the same `externalId` again with `uploads: true` and you get the same contact and, if its hour is not over, **the same upload token**. That is what makes a retried submit safe: the form carries on where it stopped. Two consequences: * **Generate `externalId` with `crypto.randomUUID()`, once per form fill.** Do not use the visitor’s email or phone. Anyone who can guess an `externalId` can get its upload token while the hour lasts. * **A repeated `externalId` never opens a new session.** After the hour, or after `complete`, the answer is `"upload": null` with `"uploadError": "session_ended"`. To send more files later, the visitor fills the form again, which creates a new contact. ## What the workspace sees [Section titled “What the workspace sees”](#what-the-workspace-sees) The files are in the contact’s own folder in Files, and on the contact’s Files tab. Each one shows the contact as its sender. The people who are told about a new contact from the website are also told about its files: one notice per submission, naming the contact and how many files arrived. A submission that sent no file adds no second notice. Nothing is ever attached to a contact that already existed, even when the email matches. A typed email proves nothing about who typed it.