This is the abridged developer documentation for Erre OS
# 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.
# Connect
> Connect Gmail, Stripe, Claude, ChatGPT and your website to Erre OS.
Each page here walks you through one connection: where to start, what the other service asks you to allow, and how to disconnect. | Connection | Who connects it | What you get | | -------------------------------------------------- | --------------------------- | --------------------------------------------------- | | [Gmail](/connect/gmail/) | Each member, for themselves | Email contacts from your own Gmail address. | | [Stripe](/connect/stripe/) | The workspace owner | Get paid online for invoices and quote deposits. | | [Claude and ChatGPT](/connect/claude-and-chatgpt/) | Each member, for themselves | Let an assistant read and draft in your workspaces. | | [CMS content key](/connect/cms-content-key/) | An owner or admin | Let your website read its content from the CMS. | | [Your website](/connect/website/) | An owner or admin | Edit your site’s words and photos from Erre OS. |
# Connect Claude and ChatGPT
> Let Claude or ChatGPT read and draft in your Erre OS workspaces through MCP.
Erre OS runs an MCP server. When you add it to Claude or ChatGPT as a connector, the assistant can look things up in your workspaces and make drafts for you: a contact, a task, a quote, a social post, a CMS entry. You sign in with your Erre OS account and choose what the assistant may do. There is no key to copy. Each member connects their own assistant, and it can act only where you can. The address to paste is:
```plaintext
https://api.erreos.com/mcp
```
## Connect [Section titled “Connect”](#connect) 1. In Claude or ChatGPT, add a custom connector and paste `https://api.erreos.com/mcp`. 2. Your browser opens Erre OS. Sign in if you need to. 3. Erre OS shows what the assistant wants to do, in every workspace you belong to. Turn off anything you do not want to allow, for example “Draft quotes, without sending them”. 4. Click **Allow**. ## What the assistant can do [Section titled “What the assistant can do”](#what-the-assistant-can-do) Each request names one workspace, and the assistant can only do what your role in that workspace allows. It can: * list your workspaces and their members * read and save companies, contacts and opportunities, add notes, log outreach, and import records * read social planners and draft posts, without sharing or publishing them * read and save catalog items, and read inventory * read projects and tasks, and create tasks * draft quotes from your templates, without sending them * read automations and create new ones, switched off * read CMS entries, save drafts and publish them The [MCP page](/developers/mcp/) lists the tools by name. ## Disconnect [Section titled “Disconnect”](#disconnect) Go to **Settings**, then **Personal**, then **Connected apps**. Each app shows when you connected it, when it was last active, and what it may do. Click **Disconnect**. The app stops working on its next request, in every workspace.
# Connect the CMS to your site
> Create a content key so your website can read its published content from the Erre OS CMS.
Your website reads its content from the [CMS](/products/cms/) with a secret key that can only read published content. You create the key once, put it in your site’s server environment, and the site starts reading. Only owners and admins can connect a site. ## Connect [Section titled “Connect”](#connect) 1. Open **CMS** and click **Website** in the top bar. It reads **Not connected** until a site has read from it. 2. Under **Create a key**, click **Create key**. Erre OS creates a secret key named “Website” with the **Read website content** permission. 3. Copy the key. It starts with `erre_sk_` and is shown only once. 4. Add it to your site’s environment as `ERRE_API_KEY`. Keep it on the server; never put it in browser code. 5. Under **Add it to your site**, pick **Astro**, **Next.js** or **fetch**, and click **Copy**. The snippet reads your first collection with the key from `ERRE_API_KEY`. 6. Deploy your site. The window shows **Waiting for your site…** until the site’s first request arrives, then **Connected**. Click **Done**. The [content API reference](/developers/api/content/) covers every route, filtering, caching and generated types. ## Manage the key [Section titled “Manage the key”](#manage-the-key) Keys live in **Settings**, then **Developers**, then **API**. From there you can: * **Roll** a key to get a replacement, and choose when the old one stops working. * **Revoke** a key. It stops on the very next request, and there is no undo. If you lose the key, create a new one. Erre OS cannot show a secret key again. To preview drafts on a staging site, create a key that also has **Read unpublished website drafts**. See [Previewing drafts](/developers/api/content/#previewing-drafts) in the content reference.
# Connect Gmail
> Send email to your contacts from your own Gmail address. Erre OS can send as you and cannot read your mail.
When you connect Gmail, the emails you send to contacts from Erre OS leave from your own Gmail address. Replies come back to your Gmail inbox. Each member connects their own Google account. Erre OS asks Google for one permission, to send email as you (`gmail.send`). It cannot read your inbox or the replies you get. ## Connect [Section titled “Connect”](#connect) 1. Go to **Settings**, then **Personal**, then **Email**. 2. Next to **Gmail is not connected**, click **Connect Gmail**. 3. Pick your Google account. Use the account with the same email address you sign in to Erre OS with. 4. On Google’s consent screen, allow Erre OS to send email for you. You come back to the same page, and it reads **Connected as** your address. You can also start from a contact. Click **Send email** on the contact, or select several contacts and click **Send email** in the bar that appears. If Gmail is not connected yet, the email window shows a **Connect Gmail** button, and your draft is still there when you come back. ## What you can send [Section titled “What you can send”](#what-you-can-send) * Each contact gets their own email. They do not see the other recipients. * Each email you send is logged on the contact’s **Outreach** tab. * You can send to up to 50 contacts at once, and up to 500 emails in 24 hours. * A subject can be up to 200 characters, and a message up to 10,000. ## If it does not connect [Section titled “If it does not connect”](#if-it-does-not-connect) If you see “Gmail was not connected”, either the Google account does not match your sign-in email, or you unticked the permission to send email. Try again with the matching account, and leave the permission ticked. If Google drops the connection later, the row reads **Gmail needs reconnecting**. Click **Reconnect Gmail**. ## Disconnect [Section titled “Disconnect”](#disconnect) Go to **Settings**, then **Personal**, then **Email**, and click **Disconnect**. This removes everything Erre OS can do with your Google account, including a connected Google Calendar. You stay signed in to Erre OS.
# Connect Stripe
> Get paid online for invoices and quote deposits through your workspace's own Stripe account.
Connecting Stripe lets your customers pay invoices and quote deposits online. The money goes to your workspace’s own Stripe account and then to your bank. Stripe charges its standard fees, and Erre takes nothing on top. Erre OS creates a new Stripe account for your workspace, and you get the full Stripe Dashboard for it. You cannot connect a Stripe account you already have. ## Before you start [Section titled “Before you start”](#before-you-start) * **Only the workspace owner can connect Stripe**, because Stripe verifies the owner’s identity. Other members see a note asking them to ask the owner. * **Set your country first.** A Stripe account’s country cannot change later. If it is missing, go to **Settings**, then **Company**, and set it. ## Connect [Section titled “Connect”](#connect) 1. Go to **Settings**, then **Administration**, then **Invoicing**. 2. In **Payments**, next to **Stripe**, click **Connect Stripe**. 3. Stripe opens in the same tab. Fill in your business and bank details there. 4. Stripe sends you back to **Invoicing**. When Stripe has what it needs, the row reads **Stripe account**, with **Charges on** and **Payouts on**. If you leave Stripe before you finish, the row reads **Finish on Stripe**. Click **Continue on Stripe** to pick up where you left off. If the link has expired, Erre OS makes a new one. ## After you connect [Section titled “After you connect”](#after-you-connect) * Click **Open Stripe Dashboard** to manage the account. You switch payment methods on or off there, not in Erre OS. * Under **Receipts**, open **Stripe email settings** and turn off Stripe’s customer emails, so your customers do not get two receipts. * If Stripe needs more from you, Erre OS shows “Stripe needs more details”. If Stripe rejects the account, it shows “Stripe rejected this account”. ## Disconnect [Section titled “Disconnect”](#disconnect) Erre OS has no disconnect button. The connection ends when you close the account in Stripe. If you connect again later, Erre OS creates a new Stripe account.
# Connect your website
> Give Erre OS access to your site's code on GitHub, so your team can edit the site's words and photos from Erre OS.
Connecting a website lets your team change its words and photos right on the page, from Erre OS. Each publish is saved to the site’s code on GitHub, and your host puts it live the way it already does. You need: * An owner or admin role in the workspace. * A site whose code is in a GitHub repository, and a host that builds it from a branch of that repository. * Access to install a GitHub app on the GitHub account or organization that owns the repository. ## Connect [Section titled “Connect”](#connect) 1. Open **Websites** in the sidebar. 2. Under **Give Erre OS access on GitHub**, click **Connect GitHub**. 3. GitHub asks where to install the Erre OS app. Pick the account that owns your site, then choose **Only select repositories** and pick your site’s repository. 4. GitHub sends you back to Erre OS. The first step now says **Connected as** and your GitHub account. 5. Under **Pick your website**, fill in: * **Repository**: your site’s repository. * **Branch**: the branch your host puts live. Usually `main`. * **Web address**: your site’s address, for example `example.com`. Leave it empty if this branch only builds previews. 6. Click **Connect website**. The editor opens on your site’s home page. It lists the site’s other pages from its sitemap. ## What Erre OS can reach [Section titled “What Erre OS can reach”](#what-erre-os-can-reach) The Erre OS app asks GitHub for three permissions on the repositories you chose: read and write the code, read deployments, and read the repository’s basic details. Erre OS uses them for one repository, the one you connected. Erre OS only changes two kinds of files: the site’s text files under `src/data/`, and photos that already exist under `public/` or `src/assets/`. Every publish is a normal commit on your branch, with a message naming who made the change. Nothing is force-pushed, so your developer’s own commits are never overwritten. To let Erre OS reach a different repository, click **Change which repositories** under the first step. ## Disconnect [Section titled “Disconnect”](#disconnect) 1. In the Websites editor, open the menu next to **View website**. It shows **Publishes to** and the repository. 2. Click **Disconnect website**, and confirm. That removes the site and the GitHub connection from your workspace. The Erre OS app stays installed on GitHub until you uninstall it there, under your account’s **Settings**, then **Applications**. ## Preparing a site [Section titled “Preparing a site”](#preparing-a-site) Your developer marks which words and photos can be changed, with a few attributes and one script. While Websites is in early access, the Erre OS team prepares your site with you. [Websites](/products/websites/) explains how editing and publishing work.
# For AI assistants
> How an AI assistant or a coding agent can read these docs as plain text.
These docs are written for people and for language models. If you are pointing an assistant or a coding agent at Erre OS, give it one of these. ## The llms.txt files [Section titled “The llms.txt files”](#the-llmstxt-files) | File | What is in it | | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | [`/llms.txt`](/llms.txt) | An index: what Erre OS is, and links to the files below. Start here. | | [`/llms-full.txt`](/llms-full.txt) | Every page in one file. | | [`/llms-small.txt`](/llms-small.txt) | Every page in one file, with notes, tips and extra whitespace removed, for a smaller context window. | | [`/_llms-txt/v1-api-reference.txt`](/_llms-txt/v1-api-reference.txt) | One section in one file. There is one each for products, connect, the v1 API reference and MCP, linked from `/llms.txt`. | They follow the [llms.txt](https://llmstxt.org/) convention, and the site rebuilds them on every deploy, so they never fall behind the pages. ## One page as Markdown [Section titled “One page as Markdown”](#one-page-as-markdown) Add `.md` to any page’s address to get its Markdown source, with no navigation or styling around it:
```plaintext
https://docs.erreos.com/developers/api/contacts/ the page
https://docs.erreos.com/developers/api/contacts.md the same page as Markdown
```
The home page is at [`/index.md`](/index.md). ## Which page to give it [Section titled “Which page to give it”](#which-page-to-give-it) * Building a contact form on a website: [Authentication](/developers/api/authentication/) and [Contacts](/developers/api/contacts/). * Reading CMS content into a site: [Content](/developers/api/content/). * Working in Erre OS from Claude or ChatGPT: [MCP server](/developers/mcp/). The v1 API reference is the source of truth for the HTTP API.
# MCP server
> How assistants and agents reach Erre OS over MCP, how they sign in, and which tools they get.
Erre OS serves an MCP server at `https://api.erreos.com/mcp`. Assistants such as Claude and ChatGPT use it to read and draft in a person’s workspaces. ## Signing in [Section titled “Signing in”](#signing-in) There are two ways in: * **OAuth, for people.** Claude, ChatGPT and other MCP clients that support OAuth 2.1 with dynamic client registration sign the person in to Erre OS and ask them what to allow. Access tokens start with `erre_oat_`. The person sees and revokes the app in **Settings**, then **Personal**, then **Connected apps**. [Connect Claude and ChatGPT](/connect/claude-and-chatgpt/) walks through it. * **A key, for agency agents.** An `erre_mk_` key is issued from the command line by the Erre team. [MCP: website content](/developers/mcp-cms/) shows how one is issued for the CMS tools. Either way, the caller acts as one person. Every tool takes a `workspace` argument, and a call can only do what that person’s role allows in that workspace. ## Tools [Section titled “Tools”](#tools) Call `list_workspaces` first. It returns the workspaces the person can reach and the areas each one has. | Area | Tools | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Workspace | `list_workspaces`, `list_members` | | CRM | `get_crm_schema`, `list_contacts`, `get_contact`, `list_companies`, `get_company`, `list_opportunities`, `get_opportunity`, `save_contact`, `save_company`, `save_opportunity`, `save_attribute`, `add_note`, `log_outreach`, `import_records`, `undo_import`, `list_views`, `save_view`, `delete_view` | | Social planner | `list_planners`, `list_planner_posts`, `get_planner_post`, `save_planner_post`, `prepare_post_upload`, `add_post_file`, `set_post_files` | | Catalog and inventory | `list_catalog_items`, `save_catalog_item`, `archive_catalog_item`, `list_inventory`, `inventory_summary` | | Projects and tasks | `list_projects`, `get_project`, `list_tasks`, `get_task`, `create_task` | | Quotes | `list_quote_templates`, `create_quote` | | Automations | `list_automations`, `get_automation`, `list_automation_step_types`, `create_automation` | | CMS | `list_site_collections`, `list_site_entries`, `get_site_entry`, `save_site_entry_draft`, `publish_site_entry` | Some limits hold for every caller: * `save_planner_post` only drafts. It never shares or publishes a post. * `create_quote` makes a draft. It never sends one. * `create_automation` saves the automation switched off. * `archive_catalog_item` archives. No tool deletes a catalog item. * `save_attribute` and `undo_import` need an admin. An import can be undone for 7 days. The CMS tools have their own page with the rules for reading and writing entries: [MCP: website content](/developers/mcp-cms/).
# MCP: website content (CMS)
> The five MCP tools that read and edit a workspace's website content.
Five tools on the [MCP server](/developers/mcp/) at `https://api.erreos.com/mcp` read and edit a workspace’s website content in the [CMS](/products/cms/). Call `list_workspaces` first and use a workspace whose `areas` include `site`. ## Access [Section titled “Access”](#access) A call needs all three: 1. A credential holding the tool’s scope: `cms:read` for the three reads, `cms:write` for the two writes. It is one of: * **An OAuth grant**, when a person connects Claude or ChatGPT and allows “See your website content” or “Edit and publish your website content” on the consent screen. See [Connect Claude and ChatGPT](/connect/claude-and-chatgpt/). * **An `erre_mk_` key**, issued from the command line by the Erre OS team for an agency agent. On that key, `content:read` and `content:write` are the social planner’s tools, not the CMS. 2. The person behind the credential has joined the workspace named by `workspace`. 3. Their role reaches the CMS: owners and admins always, anyone else through the CMS permission on their role. Writes also need the workspace’s plan to include the CMS. ## Tools [Section titled “Tools”](#tools) | Tool | Scope | Hint | Does | | ----------------------- | ----------- | --------------- | -------------------------------------------------------------------- | | `list_site_collections` | `cms:read` | read-only | collection keys, labels, fields (type, required, options, items) | | `list_site_entries` | `cms:read` | read-only | entries by status (default `published`), title search, cursor | | `get_site_entry` | `cms:read` | read-only | draft and live state by `id` or `slug`, body as Markdown, `revision` | | `save_site_entry_draft` | `cms:write` | not destructive | create a draft, or change one; never touches the live site | | `publish_site_entry` | `cms:write` | destructive | put the draft on the site, same rules as the Publish button | ## Rules worth knowing [Section titled “Rules worth knowing”](#rules-worth-knowing) * **Read before you write.** Changing an existing entry needs the `revision` from `get_site_entry`. If anyone saved or published since, the save is refused and the agent reads again. * **`fields` is a patch.** Only the keys sent change; `null` clears one. Values are tagged the way `get_site_entry` returns them, for example `{"type":"text","value":"…"}`. * **No media.** Image, file and gallery values can be kept or cleared, not pointed at a new URL. Uploads stay in Erre OS. * **Publish is the app’s publish.** A required field that is empty refuses it, and so does a slug another live entry serves. * A value that does not fit its field is refused. Most refusals come back as a sentence naming the field; one caught by the argument validator comes back as “Tool execution failed”, because the gateway hides validator detail.
# Erre OS docs
> Learn how Erre OS works, connect the tools you already use, and build on its API.
Products What each part of Erre OS does, from the CRM to the CMS. Start at the [products overview](/products/). Connect Send email from your Gmail, take payments through Stripe, and let Claude or ChatGPT work in your workspace. See [Connect](/connect/). Developers Post leads, bookings and files from your website, and read your CMS content. See the [v1 API](/developers/api/authentication/) and [MCP](/developers/mcp/). For AI assistants Every page is plain Markdown at its URL plus `.md`, and the whole site is in [`/llms-full.txt`](/llms-full.txt). See [For AI assistants](/developers/for-ai-assistants/).
# Products overview
> The parts of Erre OS, what each one is for, and where its guide lives.
Erre OS runs a small business from one workspace. Each part below is a module of that workspace. An admin switches modules on or off in **Settings**, and each member sees the ones their role allows. Each module gets its own guide over time. Until then, the pages here give you a short overview. | Module | What it is for | | ----------------------------------------------------- | ----------------------------------------------------------------------------- | | [CRM](/products/crm/) | Your companies, contacts and opportunities, and the outreach you log on them. | | [Quotes and invoices](/products/quotes-and-invoices/) | Send a quote as a link, then bill for it and get paid online. | | [Projects](/products/projects/) | Run accepted work through a workflow of steps and tasks. | | [Files](/products/files/) | Store, share and request files. | | [Forms](/products/forms/) | Build intake, satisfaction and review forms, and collect answers by link. | | [Social planner](/products/planner/) | Plan, review and approve social posts for each brand. | | [CMS](/products/cms/) | Write the content of your website and serve it to the site through the API. | | [Automations](/products/automations/) | Start steps on their own when something happens in the workspace. | | [Websites](/products/websites/) | Edit your website’s words and photos on the page, and publish them. | Every workspace also has **Home**, **Tasks** and **Notes**, and a workspace with more than one seat has **Messages** for team chat. Those guides are coming soon too.
# Automations
> Run steps on their own when something happens in your workspace.
An automation is a trigger followed by steps, drawn on a canvas. For example, when someone answers a [form](/products/forms/), an automation can create a contact and a company and send them a quote. Each automation has a draft and a live version. Your edits change the draft. The live version only changes when you click **Publish**. Owners and admins build automations. A full guide is coming soon.
# CMS
> Define your website's content, write it in Erre OS, and serve the published version to your site.
The CMS keeps the content of your website in your workspace. An admin defines **collections**, such as blog posts or team members, each with its own fields. You can start from a preset and change it. Then anyone with access writes **entries** in those collections. Your website reads the published entries through the [content API](/developers/api/content/). Drafts stay in Erre OS until you publish them. To connect a site, follow [Connect the CMS to your site](/connect/cms-content-key/). [Claude or ChatGPT](/connect/claude-and-chatgpt/) can also read entries and save drafts; see [MCP: website content](/developers/mcp-cms/). A full guide is coming soon.
# CRM
> Companies, contacts and opportunities, and the outreach you log on them.
The CRM holds the people and businesses you sell to. You find it under **Sales** in the sidebar. * **Contacts** are the people you talk to. Each contact keeps a log of outreach: a call, an email or a visit, with an outcome from a list your workspace edits. * **Companies** hold contacts and documents. They appear in workspaces set up for business customers (B2B). In a workspace that sells to people (B2C), the contact is the top record. * **Opportunities** are deals. The pipeline stage lives on the deal. Leads can arrive on their own. A form on your website can create a contact through the [contacts API](/developers/api/contacts/), and a [form](/products/forms/) or an [automation](/products/automations/) can create one too. If you [connect Gmail](/connect/gmail/), you can email a contact from their record and the email is logged on it. A full guide is coming soon.
# Files
> Store your workspace's files, share them by link, and ask clients to send theirs.
**Files** is the workspace’s storage. You can organize files in folders, preview them, download several at once as a zip, and upload large files. To send a file to someone outside the workspace, share it with a link. To get files from a client, send them a file request. A website form can also send files with the contact it creates. See [Uploads](/developers/api/uploads/) in the API reference. A full guide is coming soon.
# Forms
> Build intake, satisfaction and review forms with logic, and collect answers by link or by request.
You build a form in **Forms**, under **Marketing** in the sidebar. A form can show or skip questions based on earlier answers, jump ahead, and end on more than one screen. There are two ways to collect answers: * Share the form’s public link. Anyone with the link can answer. * Send it as a request tied to a company or a contact. This is the only way a respondent can upload files. An [automation](/products/automations/) can turn a response into a contact, a company or a quote. A full guide is coming soon.
# Social planner
> Plan social posts for each brand, and have reviewers approve them before they go out.
The **Social planner** is under **Marketing** in the sidebar. You keep one planner per brand, each with its own time zone, social accounts and people. A post moves through statuses from draft to published. You name its reviewers, and a planned post waits for their approval. You can share a planner with one linked workspace, for example an agency that plans your posts. [Claude or ChatGPT](/connect/claude-and-chatgpt/) can draft posts in a planner for you. They never share or publish one. A full guide is coming soon.
# Projects
> Run accepted work through a workflow of steps, with tasks assigned by role.
A project usually starts from an accepted [quote](/products/quotes-and-invoices/). You can also start one without a quote. Each project follows a workflow of steps that you set up. A step’s tasks go to project roles, such as “Installer”, so the right person gets them on each project. A project can also have a page for your client, shared by link. A full guide is coming soon.
# Quotes and invoices
> Send a quote as a link, then bill for it and get paid online through your own Stripe account.
You find both under **Sales** in the sidebar. **Quotes.** You send a quote to a lead as a link. The lead opens it, then accepts or rejects it without signing in. Erre OS keeps a copy of the quote exactly as it was when it was accepted. A quote can ask for a deposit, and you can start a new quote from a template. Lines can come from your **Catalog** of products and services. **Invoices.** You make an invoice from an accepted quote, on its own, or on a recurring schedule. Your customer pays from a link, and autopay can charge a saved card or bank account. To take payments online, the workspace owner [connects Stripe](/connect/stripe/). The money goes to your own Stripe account, and Erre OS takes no fee on top. A full guide is coming soon.
# Websites
> Edit your website's words and photos on the page, and publish them to your site.
Websites shows your own site inside Erre OS and lets your team change its words and photos right on the page. When you publish, Erre OS saves the changes to the site’s code on GitHub, and your host puts them live the way it already does. There is no separate CMS to keep in sync and no copy of the site to maintain. Owners and admins can use it. To set it up, see [Connect your website](/connect/website/). ## Edit [Section titled “Edit”](#edit) 1. Open **Websites** in the sidebar. Your site opens on its home page. 2. To go to another page, use the page menu above the site. Pages are grouped by language when the site has more than one. Links inside the site work too. 3. Click any words to change them, or a photo to replace it. Dashed outlines show changes you haven’t published. They stay in your browser until you publish or discard them. ## Publish [Section titled “Publish”](#publish) 1. Click **Publish** at the top. The button counts your changes, for example **Publish 3 changes**. 2. Check the list. **Undo** drops one change, and **Discard all** drops every one. 3. Click **Publish** in the list. The top bar then follows your host: * **is updating** while it builds. * **Live on** and your address when the change is up. Click it to open the site. * **Update failed** if the build did not finish. Your site stays as it was, and your developer can see why in the host’s logs. ## When someone else changed the same thing [Section titled “When someone else changed the same thing”](#when-someone-else-changed-the-same-thing) If a teammate or your developer changed the same words since you opened the page, Erre OS does not overwrite their change. It names the field so you can look at it again, and the rest of your changes stay as drafts. Changes to different fields never get in each other’s way, even when they land at the same moment.