# BriefGate — full documentation (auto-generated, do not edit by hand) This file concatenates every English docs page verbatim — for an agent that wants the whole corpus in one fetch instead of crawling each page. For a short curated overview instead, see https://briefgate.dev/llms.txt. Regenerated on every docs build from the same Markdown source as the pages themselves, so it cannot go stale independently of them. --- ## What is BriefGate? URL: https://briefgate.dev/docs/what-is-briefgate # What is BriefGate? BriefGate is a client intake platform. It asks a client for the files, information, structured answers and credentials a project needs, and hands the answers back to whoever is running the project — from the dashboard in your browser, or through an AI coding agent over MCP or REST. ## The problem A project — built by hand or by an AI coding agent — can move fast right up until it needs something from the client. Not because the work is hard. Because the logo is in someone's Dropbox, the opening hours are in someone's head, and the WordPress password is in an email nobody wants to forward. There is no good way to ask a non-technical client for any of it, no way to chase them when they forget, and no way to tell whether what came back is usable. That gap is the whole product. Everything below exists to close it. ## Two ways in Every intake ends up in the same place regardless of how it started: a portal the client fills in, a chase engine that follows up automatically, and typed results at the end. What differs is who defines the intake and reads the results. ### From the dashboard — no code Sign in at [https://app.briefgate.dev/app](https://app.briefgate.dev/app) and run the whole thing by hand: - **Start an intake from scratch**, from an **onboarding sample** (website, branding, or campaign brief), or from a **template** — seven built-in public templates ship on every plan, including Free (a website, an e-shop, a logo and brand brief, a mobile app, a restaurant website, an advisor's site and a club site; all Czech-language, built for Radim's own agency work); Solo plans and up can save their own. - **Send the portal link** — BriefGate emails the client; you never write the chasing emails yourself. - **Track progress** on the intake's detail page as items come in. - **Request a revision** on anything a client submitted that isn't right (Solo plan and up) — they get your note and a re-opened field for just that item. - **Organize with folders** once you're running more than a handful of intakes at once. - **Download everything as one ZIP** once the intake is done — a PDF and Markdown summary plus every uploaded file, no need to open each item by hand (see [ZIP download](./zip.md)). - **Add teammates** — Agency plans ship with 3 seats and can buy more; other plans get 1. This path never touches MCP or the REST API. It is the whole product for an account that never writes a line of code against BriefGate. ### From an AI coding agent **1. The agent declares what it needs.** Through the MCP tool `define_intake`, or `POST /v1/intakes` over REST. Each item has a key the agent will read it back by, a label the client will read, a type, and optional constraints: ```json { "project_name": "Bella Cucina website", "client": { "email": "owner@bellacucina.cz", "name": "Marek", "language": "cs" }, "items": [ { "key": "logo", "type": "image", "label": "Company logo", "constraints": { "formats": ["svg", "png"], "min_width": 512 } }, { "key": "opening_hours", "type": "structured", "label": "Opening hours", "schema": { "type": "object", "properties": { "mon_fri": { "type": "string" }, "sat": { "type": "string" } } } }, { "key": "wp_admin", "type": "secret", "label": "WordPress admin access" } ] } ``` **2. The agent gets typed data back.** A webhook fires, or the agent calls `get_intake_results`: ```json { "intake_id": "in_01J9Z8X", "status": "completed", "progress": { "submitted": 3, "total": 3 }, "missing": [], "results": { "logo": { "url": "https://…", "filename": "logo.svg", "checksum_sha256": "…" }, "opening_hours": { "mon_fri": "11:00–22:00", "sat": "12:00–23:00" }, "wp_admin": { "value": "…", "one_time": true } } } ``` File URLs with checksums. Structured objects, validated against the schema the agent declared. Secrets released once, to an API key carrying the right scope, with the reveal written to an audit log. And `missing`, naming anything still outstanding, so the agent can decide whether it has enough to keep going. **3. The agent continues building.** Every MCP tool has a REST equivalent, so a custom agent loop in any language works too. Creating custom templates and inviting teammates are dashboard-only actions — an agent authenticated with just an API key cannot do either. ## What happens in between, either way **The client gets a portal, not a form to figure out.** An email with a magic link. One click opens a branded page in their own language, listing what is still needed and what is already done. No account, no password, no registration. The session lasts 14 days, so they can start on a phone and finish on a laptop. The portal never mentions agents, MCP, or APIs, and it looks the same whether the intake was defined by hand in the dashboard or by an agent. As far as the client is concerned, someone building their project needs six things from them. **BriefGate chases them.** On a schedule you or the agent chose, respecting quiet hours. Each reminder asks only for what is still missing, the reminders stop once everything required is in, and they stop for good if the address turns out to be undeliverable. After the last reminder the intake is marked stalled and handed back, rather than nagging forever. ## Who it is for - **People running intake from the dashboard** — freelancers and agency staff who want a portal, reminders and encrypted secret storage without writing any code. - **AI coding agents** — Claude Code, Cursor, Codex, Windsurf, or any MCP-compatible client, plus any custom agent loop over the REST API. - **Web agencies** running several client projects at once, where chasing is a systemic cost rather than an annoyance. - **Freelance developers** who would rather not be the person sending the fourth "just following up on the logo" email. - **Anyone** whose delivery stalls waiting on assets, content or credentials. ## How it differs from a form builder A form builder is designed for a human to build a form and a human to read the answers. BriefGate supports that workflow too, but adds a second one: an agent can declare the requirement and consume the result without a human in the loop at either end. That second workflow is why the items are typed, why the API response is typed JSON rather than a spreadsheet export, why there is a `missing` array, why repeated calls are idempotent, and why webhooks exist. The client-facing half stays the same either way: the client sees a page asking for six things, and nothing about how it got there. BriefGate also collects credentials, which a form builder should not be asked to do. A `secret` item is encrypted on the server on receipt and released exactly once — to your agent's API call, to you when you click Reveal in the dashboard, or in a ZIP you explicitly ask to include it — see [Security](./security.md). ## What it does not do It is not a CRM, a project manager, an invoicing tool or a contract system. It does one thing: get the missing information from a client to whoever needs it. Anything else on that list would make it worse at that. ## Start here - [Quickstart](./quickstart.md) — a working intake in five minutes - [MCP tools](./mcp.md) — every tool, argument and response - [REST API](./rest-api.md) — the same surface without MCP - [Client portal](./portal.md) — what your client actually sees - [Security](./security.md) — including what BriefGate is not --- ## Quickstart — 5 minutes to your first intake URL: https://briefgate.dev/docs/quickstart # Quickstart — 5 minutes to your first intake This guide walks you through installing BriefGate, connecting it to your coding agent, and sending your first client intake. --- ## Prerequisites - **Node.js 18 or later** — needed for the local package (Options 1 and 2 below). The hosted endpoint needs nothing installed. - **An MCP-capable agent** — Claude Code, Cursor, claude.ai, or any client that speaks the Model Context Protocol. - **A BriefGate account** — sign up at [https://app.briefgate.dev/app](https://app.briefgate.dev/app). You don't need an API key up front: Options 0 and 1 below sign you in without one. --- ## 1. Connect BriefGate to your agent Four ways to connect, all producing the same 13 tools. The first two need no API key to copy or paste. Already signed in? The dashboard's **AI agents** page ([app.briefgate.dev/app/agents](https://app.briefgate.dev/app/agents)) shows the setup for each client below with a copy button. **Option 0 — hosted endpoint, OAuth (recommended for Claude Code and claude.ai):** ```bash claude mcp add --transport http briefgate https://mcp.briefgate.dev/mcp ``` Then start Claude Code, run `/mcp`, pick **briefgate** and choose **Authenticate**. Your browser opens the dashboard, where you sign in and approve access — nothing to install, nothing to paste. Until you do this, the server shows as needing authentication and its tools stay unavailable. In claude.ai, use **Settings > Connectors > Add custom connector** with the same URL. Any MCP client that speaks Streamable HTTP and OAuth 2.1 connects the same way. **Option 1 — local package, device login (recommended for the Claude Code CLI when you'd rather not do a browser OAuth redirect, or for scripting a terminal agent):** ```bash claude mcp add briefgate -- npx -y @briefgate/mcp npx -y @briefgate/mcp login ``` `login` prints a short code and opens the dashboard in your browser; approve it there. The API key it receives is stored in `~/.briefgate/credentials.json` (directory mode `0700`, file mode `0600`) and used automatically from then on — no environment variable to set. Run `npx -y @briefgate/mcp logout` to remove it; this also revokes the key on the server. **Option 2 — local package, API key (for CI, scripts, or if you'd rather manage the key yourself):** ```bash claude mcp add briefgate -- npx -y @briefgate/mcp --api-key bg_live_xxxxx ``` Or add manually to `~/.claude.json` (the `mcpServers` key holds this for every project; for a config shared with your team, use `.mcp.json` in the project root instead): ```json { "mcpServers": { "briefgate": { "command": "npx", "args": ["-y", "@briefgate/mcp"], "env": { "BRIEFGATE_API_KEY": "bg_live_xxxxx" } } } } ``` `BRIEFGATE_API_KEY`, if set, always takes precedence over a stored login credential. **Option 3 — hosted endpoint, API key (for CI or a client that cannot do an OAuth redirect):** ```bash claude mcp add --transport http briefgate https://mcp.briefgate.dev/mcp \ --header "Authorization: Bearer bg_live_xxxxx" ``` For Options 2 and 3, get a key from the dashboard at [https://app.briefgate.dev/app](https://app.briefgate.dev/app). To try things out during development without emailing a real client, create the intake with `"send": false` — it stays a draft — then check `GET /v1/intakes/preview` (or the dashboard preview) to see the exact subject line and sender name before anything goes out, and call `POST /v1/intakes/:id/send` when you're ready. Restart your agent after changing its MCP config. --- ## 2. Your first intake The example below creates an intake for a restaurant website project. Paste this into your agent's context (or call the `define_intake` MCP tool directly): ```json { "project_name": "Bella Napoli — Website", "client": { "email": "owner@bellanapoli.com", "name": "Marco Esposito", "language": "en" }, "items": [ { "key": "logo", "label": "Restaurant logo", "help": "Upload your logo in SVG or PNG format with a transparent background. Minimum 512px on the shortest side.", "type": "image", "required": true, "constraints": { "formats": ["svg", "png"], "min_width": 512, "transparent_background": true } }, { "key": "hero_copy", "label": "Hero section tagline", "help": "A short paragraph (up to 400 characters) that captures the spirit of the restaurant. This appears above the fold on the homepage.", "type": "longtext", "required": true, "constraints": { "max_chars": 400 } }, { "key": "opening_hours", "label": "Opening hours", "help": "Your regular opening hours. Use a simple format like '12:00-22:00' or 'Closed'.", "type": "structured", "required": true, "schema": { "type": "object", "required": ["mon_fri", "sat", "sun"], "properties": { "mon_fri": { "type": "string", "example": "12:00-22:00" }, "sat": { "type": "string", "example": "12:00-23:00" }, "sun": { "type": "string", "example": "13:00-21:00" } } } }, { "key": "photos", "label": "Food and interior photos", "help": "Upload between 5 and 15 photos of your food, interior, and ambience. JPG, PNG, or HEIC.", "type": "file_list", "required": true, "constraints": { "formats": ["jpg", "png", "heic"], "min_count": 5, "max_count": 15 } } ], "chase_schedule": "default" } ``` The tool returns: ```json { "intake_id": "in_8f3kQmR2", "portal_url": "https://p.briefgate.dev/8f3kqmr2", "status": "sent", "items": [ { "key": "logo", "status": "pending" }, { "key": "hero_copy", "status": "pending" }, { "key": "opening_hours", "status": "pending" }, { "key": "photos", "status": "pending" } ], "follow_up": { "recommended": "schedule", "reason": "No webhook endpoint is registered on this account. Register one if you run a service that can receive HTTPS; otherwise check on a schedule.", "webhook": { "active_endpoints": 0, "events": ["intake.completed", "item.submitted"], "register_with": "manage_webhook" }, "schedule": { "check_with": "get_intake_status", "every_hours": 24, "until": "2026-04-08T00:00:00.000Z" } } } ``` BriefGate immediately emails the client a personal link to `portal_url`, carrying a one-time sign-in token that the API never returns — so `portal_url` on its own does not open the portal. The intake status becomes `sent`. `follow_up` tells you how to learn the intake is done: register a webhook with `manage_webhook`, or poll `get_intake_status` every `follow_up.schedule.every_hours` hours until `follow_up.schedule.until`. --- ## 3. What happens next 1. The client receives an email with a link to their personal intake portal. 2. They upload or fill in each item directly in the browser — no account required. 3. As they submit items, BriefGate fires **webhooks** to your endpoint (configure them in the dashboard under **Settings > Webhooks**). 4. If the client does not complete the intake, the chase engine sends automatic follow-up emails on the schedule you specified. 5. When all required items are submitted, the intake status transitions to `completed` and a final webhook fires. --- ## 4. Check status **Via MCP (in your agent):** ``` Call: get_intake_status Args: { "intake_id": "in_8f3kQmR2" } ``` **Via REST:** ```bash curl https://api.briefgate.dev/v1/intakes/in_8f3kQmR2/status \ -H "Authorization: Bearer bg_live_xxxxx" ``` Both return the completion percentage, per-item statuses, and a timeline of chase emails sent so far. --- ## 5. Get results when complete **Via MCP:** ``` Call: get_intake_results Args: { "intake_id": "in_8f3kQmR2" } ``` **Via REST:** ```bash curl https://api.briefgate.dev/v1/intakes/in_8f3kQmR2/results \ -H "Authorization: Bearer bg_live_xxxxx" ``` The response contains typed, ready-to-use data: - **Text and longtext items** return plain strings. - **Image and file items** return signed URLs (valid for 24 hours), dimensions, MIME type, and checksum. - **Secret items** return the decrypted plaintext in a `value` field on the first call only (`first_reveal: true`). Store it immediately — subsequent calls omit the value. - **Structured items** return a validated JSON object matching the schema you declared. --- ## Next steps | Topic | Document | |---|---| | Full reference for all 13 MCP tools | [mcp.md](./mcp.md) | | All 12 item types and their constraints | [item-types.md](./item-types.md) | | REST API, webhooks, and authentication | [rest-api.md](./rest-api.md) | --- ## Dashboard Quickstart: Client Intake Without Code URL: https://briefgate.dev/docs/dashboard-quickstart # Dashboard Quickstart — collect client materials without code This guide is for agencies and freelancers who want to run BriefGate entirely from the browser — no MCP, no API key, nothing to install. In about ten minutes you'll create an account, send a real intake to a client, and see how review, reminders, and delivery work from the dashboard. --- ## 1. Create your account Go to [https://app.briefgate.dev/app](https://app.briefgate.dev/app) and switch to the **Sign up** tab. You need an email, a password, and **your name**. On a paid plan, clients see it as the sender of their intake ("*{name} via BriefGate*"), so use the name or business name you want them to recognize. On the **Free** plan, clients see a built-in sender identity instead ("Your developer", localized, plus your login email) — your own name is not shown until you upgrade; see [Custom branding](./billing.md#custom-branding). **Account / agency name** is optional and only used internally. You can also **Continue with Google** instead of setting a password. New accounts confirm their email with a six-digit code before the dashboard opens. If you signed up with a password, set up **two-factor authentication** under Settings > Security while you're there — it's optional but free on every plan. The first time you land on the Intakes page, a banner offers **"Send your first intake in 3 minutes"**. It walks you through picking a sample project (website, branding, or a marketing campaign), sends a real intake to your own inbox, and lets you fill it in yourself so you see exactly what a client sees. It's a fast way to get oriented, but it's optional — the steps below work the same whether you start from that guide or go straight to a real client. --- ## 2. Set up your branding (optional) Under **Settings > Branding** you can upload a **logo**, pick an **accent color**, set a **sender name**, and add an **e-mail signature** image (a business card works well) that appears at the bottom of every e-mail a client gets from you. Custom branding is a **Solo plan and up** feature — on the Free plan, the portal and e-mails carry BriefGate's own look and a "Powered by BriefGate" notice at the bottom of the portal. This step is optional and can wait — an intake sent before you set any of this up still works, it just looks like a generic BriefGate request instead of one from you. --- ## 3. Create the request Click **New intake** on the Intakes page. There are three ways to fill it in: **From scratch.** Fill in **Project** (project name, an optional due date, and a folder if you're organizing several intakes), then **Client** (their email, name, language, and how often they get reminded — see [Reminders](#4-send-it-and-let-reminders-do-the-work) below), then add items under **What you need**. Each item gets a **Label** the client reads, a **Type** (Short text, Long text, File, Several files, Image, URL, Yes/No, Colours, Credentials (encrypted), Choice, Structured…), whether it's **Required**, and **Who** answers it — most items go to the **Client**, but you can mark one for **Me** if it's a note to yourself that should never be shown to the client or chased (it shows up later under "My tasks" on the intake page). **From a sample.** The onboarding guide from step 1 is available any time — the same three sample projects (website, branding, campaign) are meant for trying the product on yourself, not for a real client. **From a template.** Click **Start from a template** to pre-fill the items from a saved list instead of typing them one by one. Seven public templates, all Czech-language, ship on every plan including Free: websites for a restaurant, an advisor and a club, a general website, an e-shop, a logo and brand identity, and a mobile app. Once you've built an intake you like, **Save as template** (next to Send) turns it into a reusable one for next time; creating your own templates needs the **Solo plan and up**. See [Templates](./templates.md) for the full list of built-in items. Before sending, **What your client will see** previews the exact subject line and sender name the invitation e-mail will carry. --- ## 4. Send it and let reminders do the work Toggle **Email the client now** to send immediately, or leave it off to **Save as draft** and send later from the intake page — useful while you're still adding items. Sending fires the invitation e-mail with the client's portal link. Under **Reminders**, pick a cadence: **Default** (2, 5, 9 days after the invite, then weekly), **Gentle** (3 and 8 days, then every 2 weeks, never on weekends), **Aggressive** (1, 3, 5 days, then every 2 days), **Custom** (your own interval), or **None**. The chase engine sends these automatically and stops the moment the client submits everything — you never write a follow-up e-mail yourself. **On the Free plan, only Default and None are available**; the other cadences need Solo and up. See [Chase engine](./chase.md) for the full schedule reference, quiet hours, and how to change the cadence after sending. --- ## 5. Review what comes back Open the intake's detail page to see every item's status as it arrives. There's no manual "Approve" button — a submitted item **auto-approves automatically** after a set number of hours (72 by default; change it under Settings > Defaults or per intake under Advanced) if you never act on it. Instead, your options while reviewing are: - **Request revision** — send the client back to a specific field with a note explaining what's wrong ("This logo is too small…"). Requires the **Solo plan and up**; on Free this button shows "Revisions require the Solo plan" instead. - **Waive** — mark an item as not needed, with an optional reason, when the client genuinely won't be providing it. - **Received outside BriefGate** — mark an item as delivered when the client sent it another way (e-mail, a call), so the intake can still complete. --- ## 6. Download everything as a ZIP Once you have what you need, **Download everything (ZIP)** on the intake page bundles every file plus a PDF and Markdown summary into one download — no opening items one by one. Files still going through the antivirus scan are left out until they clear. **Secrets (passwords, credentials) are excluded by default** and stay available for a one-time reveal in the dashboard; including them in the PDF spends that one-time reveal. See [ZIP download](./zip.md) for the full details. --- ## What the client sees The client never sees a dashboard, MCP, or an API — just an e-mail with a **magic link**. One click opens their personal portal: no account, no password, no registration. They see your branding (on paid plans), a progress bar, and the items still outstanding. The portal is available in **six languages** — English, Czech, Slovak, Polish, German, and Spanish — set per intake or defaulted for your account. --- ## Limits on the Free plan - **1 active intake** at a time, **10 items** per intake. - **Up to 10 invitation emails per UTC day** (on top of the 30-per-hour cap every plan has). Past it, new intakes are created as drafts — send them after midnight UTC, or upgrade. - Reminder cadence: **Default or None only** — Gentle, Aggressive, and Custom are Solo and up. - **No revision requests** — you can still waive an item or mark it received outside BriefGate. - **No custom branding** — logo, accent color, sender name, and e-mail wording stay BriefGate's own. Clients see a built-in sender identity ("Your developer" plus your login e-mail) instead of your name, and the portal shows a "Powered by BriefGate" notice. - **No custom templates** — the seven public templates are available, but you can't save your own. - **1 seat** — team invites need the Agency plan (3 seats included). --- ## Next steps | Topic | Document | |---|---| | Reminder schedules, quiet hours, and custom cadences | [Chase engine](./chase.md) | | Downloading everything as a ZIP | [ZIP download](./zip.md) | | Built-in and custom templates | [Templates](./templates.md) | | What the client sees, magic links, and languages | [Client portal](./portal.md) | | How one agency replaced Slack nagging with automatic reminders | [Case study: automated reminders](./case-study-automated-client-reminders.md) | | Running BriefGate from an AI coding agent instead | [Quickstart (MCP/REST)](./quickstart.md) | --- ## MCP Tools Reference URL: https://briefgate.dev/docs/mcp # MCP Tools Reference BriefGate ships as an MCP server so coding agents can orchestrate client intake without leaving their context. All 13 tools map 1:1 to REST endpoints under `https://api.briefgate.dev/v1/`. Connect it without pasting a key — hosted OAuth or local device login — or with an API key for CI and scripts; see [quickstart.md](./quickstart.md) for all four options. `login` and `logout` are two additional local-only helpers available when you run the package via `npx` — see below. --- ## When should an agent use BriefGate **Triggers.** Reach for these tools when a task is blocked on something only a human outside the current conversation can provide: files (logo, product photos, documents), copy, brand assets, structured answers, or credentials/logins — and that person may take hours or days to respond, so something needs to chase them on a schedule instead of you polling by hand. **When not to.** Skip it when the information is already available — in the repo, earlier in the conversation, or in an earlier BriefGate intake — or when the person you're talking to right now can just answer directly. BriefGate's portal and reminders are built for people who are not in this conversation. **Flow.** 1. Call `define_intake` with the typed items you need (see the item types table linked from each tool below). 2. Poll `get_intake_status`. An item staying `pending`, or the intake staying `sent` or `in_progress`, is the normal state while BriefGate chases the client on the configured schedule — it is not an error or a sign the call failed. Use `follow_up` on the `define_intake` response, or a registered webhook, instead of tight polling. 3. Once items are submitted, call `get_intake_results` to get typed values back. Its `missing` array names anything still outstanding — check it before assuming the intake is done. 4. If a submitted value is wrong or incomplete, call `request_revision` with a note explaining what to fix, instead of asking the client again yourself outside BriefGate. 5. `secret` items (passwords, API keys) come back through `get_intake_results` **once**: the plaintext `value` is present only on the first successful read (`first_reveal: true`) and absent on every call after. Store it immediately. Secrets are encrypted server-side on arrival (libsodium sealed box) — not end-to-end, not zero-knowledge — see [security.md](./security.md). --- ## define_intake Creates a new intake and immediately sends the client an email with their portal link. **Parameters** | Parameter | Type | Required | Description | |---|---|---|---| | `project_name` | string | Yes | Human-readable project title shown in the portal and all emails. | | `client.email` | string | Yes | Client's email address. | | `client.name` | string | Yes | Client's display name. Every invite and reminder email opens by addressing the client by name. | | `client.language` | string | No | Portal and email language: `cs`, `sk`, `pl`, `de`, `es`, `en`. Omit it and the account's default language applies, falling back to English. | | `client.timezone` | string | No | IANA timezone (e.g. `Europe/Prague`) used for quiet-hours scheduling. | | `client.phone` | string | No | E.164 phone number (e.g. `+420601123456`). | | `client.also_notify` | array | No | Up to 4 extra `{ email, name }` people who get the same portal link and reminders as the primary client (e.g. two directors of one company). Each gets their own email; nobody sees the rest. | | `email_copy` | object | No | Your own `invite_subject`, `invite_intro`, `reminder_subject`, `reminder_intro`, overriding the built-in translation for this intake. Placeholders: `{sender}`, `{project}`, `{client}`, `{count}`, `{minutes}`, `{due}` — an unknown one is rejected, not rendered literally. No links allowed in any line, on any plan (`422` otherwise). Part of [custom branding](./billing.md#custom-branding) (Solo plan and up) — accepted and stored on Free, but not used until the account upgrades. | | `items` | array | Yes | Ordered list of item definitions. See [item-types.md](./item-types.md). | | `items[].assignee` | string | No | `client` (default) or `owner`. An `owner` item is your own to-do — invisible to the client, never chased, and it never holds the intake open. See [item-types.md](./item-types.md#who-owes-the-item-assignee). | | `branding` | object | No | Per-intake override of account branding: `logo_url`, `accent_color` (hex, e.g. `#1B2A4A`), `sender_name`, `reply_to`. `logo_url`, `accent_color` and `sender_name` are [custom branding](./billing.md#custom-branding) (Solo plan and up) — accepted and stored on Free, but not used until the account upgrades; `reply_to` is not gated. `sender_name` may not contain a link (web address, bare domain, or email address) on any plan. | | `template` | string | No | Template slug to pre-populate items (e.g. `"restaurant-website"`). | | `chase_schedule` | string | No | One of `default`, `gentle`, `aggressive`, `custom`, `off` (default: `default`). `default`=T+2d,T+5d,T+9d,weekly. `gentle`=T+3d,T+8d,biweekly. `aggressive`=T+1d,T+3d,T+5d,every-other-day. `custom`=every `chase_interval` `chase_interval_unit`. `off`=no auto reminders. | | `chase_interval` | integer | No | Reminder interval for `chase_schedule: "custom"`. Omit it and custom reminds every 3 days. Rejected with any other schedule. | | `chase_interval_unit` | string | No | `minutes`, `hours` or `days` (default `days`). Minimum 5 minutes, maximum 90 days. | | `respect_quiet_hours` | boolean | No | Keep reminders inside the client's 08:00–19:00 window (default `true`). | | `max_reminders` | integer \| string | No | Reminders before the intake stalls and hands back to you (1–1000, default 3, or `"unlimited"` to remove the cap). | | `chase_at_time` | string | No | Local time of day for the reminder, `HH:MM`. Requires `chase_schedule: "custom"` with a whole-day interval, and outranks quiet hours. | | `due_date` | string | No | ISO 8601 date. Shown in the portal and email subject. | | `auto_approve_hours` | integer | No | Hours after submission before an item is auto-approved without your review (default `72`). Set to `0` to require explicit approval. | | `send` | boolean | No | Set to `false` to create a draft without emailing the client. Call `POST /v1/intakes/:id/send` to send later. Default: `true`. | | `retention` | object | No | `{ mode: "days"\|"on_delivery", days?: number, anonymize?: boolean }`. Default: purge 90 days after `intake.completed`. Use `mode: "on_delivery"` for intakes containing credentials — contents are removed ~24 h after you call `get_intake_results`. | | `folder_id` | string | No | Put this intake in an existing folder from `list_folders` instead of leaving it unfiled. Folders group intakes by client or project — reuse one for a returning client rather than creating a duplicate with `create_folder`. | **Example — restaurant website project** ```json { "project_name": "Bella Napoli — Website", "client": { "email": "owner@bellanapoli.com", "name": "Marco Esposito", "language": "en" }, "items": [ { "key": "logo", "label": "Restaurant logo", "help": "SVG or PNG with transparent background, minimum 512px.", "type": "image", "required": true, "constraints": { "formats": ["svg", "png"], "min_width": 512, "transparent_background": true } }, { "key": "brand_colors", "label": "Brand colors", "help": "Pick the primary and secondary brand colors.", "type": "color_list", "required": true }, { "key": "hero_copy", "label": "Hero tagline", "type": "longtext", "required": true, "constraints": { "max_chars": 400 } }, { "key": "has_existing_site", "label": "Do you have an existing website?", "type": "boolean", "required": true }, { "key": "existing_site_url", "label": "Existing website URL", "help": "Only required if you answered Yes above.", "type": "url", "required": false }, { "key": "platform", "label": "Preferred platform", "type": "select", "required": true, "options": [ { "value": "wordpress", "label": "WordPress" }, { "value": "webflow", "label": "Webflow" }, { "value": "custom", "label": "Custom / I'm not sure" } ] }, { "key": "cms_password", "label": "Admin credentials", "help": "Existing CMS admin login (if migrating). Stored encrypted, one-time reveal.", "type": "secret", "required": false }, { "key": "opening_hours", "label": "Opening hours", "type": "structured", "required": true, "schema": { "type": "object", "required": ["mon_fri", "sat", "sun"], "properties": { "mon_fri": { "type": "string" }, "sat": { "type": "string" }, "sun": { "type": "string" } } } } ], "chase_schedule": "default" } ``` **Response** ```json { "intake_id": "in_8f3kQmR2", "portal_url": "https://p.briefgate.dev/8f3kqmr2", "status": "sent", "items": [ { "key": "logo", "status": "pending" }, { "key": "brand_colors","status": "pending" } ], "follow_up": { "recommended": "schedule", "reason": "No active webhook endpoints are registered on this account.", "webhook": { "active_endpoints": 0, "events": ["item.submitted", "intake.completed"], "register_with": "manage_webhook" }, "schedule": { "check_with": "get_intake_status", "every_hours": 24, "until": "2024-03-29T10:22:00Z" } } } ``` `follow_up` tells you how to learn about progress on this intake without polling blindly. `recommended` is `"webhook"` when you already have an active webhook endpoint covering the relevant events, or `"schedule"` — as above — when you don't. On `"schedule"`, poll `get_intake_status` every `follow_up.schedule.every_hours` hours until `follow_up.schedule.until`; on `"webhook"`, register one with `manage_webhook` (or rely on the endpoints already listed under `follow_up.webhook`) instead of polling. **If an invitation limit is hit**, `define_intake` still creates the intake — it just does not email the client. The response carries `"invitation_sent": false`, `"status": "draft"`, and a `note` explaining which limit and what to do: ```json { "intake_id": "in_8f3kQmR2", "portal_url": "https://p.briefgate.dev/8f3kqmr2", "status": "draft", "items": [ ... ], "follow_up": { ... }, "invitation_sent": false, "note": "Daily invitation limit of the free plan reached — the intake was created as a draft. Send it with POST /v1/intakes/{id}/send after midnight UTC, or upgrade to remove the daily limit." } ``` This happens for two different limits: the account-wide **30 invitations per hour** (every plan), and the **Free plan's 10 invitations per UTC day** (`invites_per_day` in `GET https://api.briefgate.dev/pricing.json` — `null` on Solo, Studio, and Agency, which have no daily cap). Either way, nothing was sent to the client; call `POST /v1/intakes/:id/send` once the limit resets, or check `invitation_sent` before telling whoever you're working for that the client has been contacted. --- ## get_intake_status Returns a lightweight snapshot of the intake's current state: which items are complete, which are pending, and the full chase history. Prefer this over `get_intake_results` when you only need to check progress. `progress.total` counts what the intake is waiting on: an item the owner has waived, and an optional item the client has not touched, both leave the denominator. That keeps `percent` at 100 exactly when `status` turns `completed`. **Parameters** | Parameter | Type | Required | Description | |---|---|---|---| | `intake_id` | string | Yes | The `intake_id` returned by `define_intake`. | **Response** ```json { "status": "in_progress", "due_date": "2024-04-01", "client_last_seen": "2024-03-16T14:05:33Z", "progress": { "submitted": 5, "total": 8, "outstanding": 3, "percent": 62 }, "items": [ { "key": "logo", "status": "approved", "submitted_at": "2024-03-16T10:00:00Z", "label": "Restaurant logo" }, { "key": "brand_colors", "status": "approved", "submitted_at": "2024-03-16T10:05:00Z", "label": "Brand colors" }, { "key": "hero_copy", "status": "needs_revision", "submitted_at": "2024-03-16T10:10:00Z", "label": "Hero tagline" }, { "key": "has_existing_site","status": "approved", "submitted_at": "2024-03-16T10:15:00Z", "label": "Do you have an existing website?" }, { "key": "existing_site_url","status": "approved", "submitted_at": "2024-03-16T10:15:00Z", "label": "Existing website URL" }, { "key": "platform", "status": "approved", "submitted_at": "2024-03-16T10:20:00Z", "label": "Preferred platform" }, { "key": "cms_password", "status": "pending", "submitted_at": null, "label": "Admin credentials" }, { "key": "opening_hours", "status": "pending", "submitted_at": null, "label": "Opening hours" } ], "chases": [ { "channel": "email", "sent_at": "2024-03-17T09:00:00Z", "status": "sent", "attempt_no": 1 }, { "channel": "email", "sent_at": "2024-03-20T09:00:00Z", "status": "sent", "attempt_no": 2 }, { "channel": "email", "sent_at": null, "status": "scheduled", "attempt_no": 3 } ] } ``` **Item statuses** | Status | Meaning | |---|---| | `pending` | Not yet submitted by client. | | `submitted` | Uploaded or filled in; awaiting agent review or auto-approval. | | `needs_revision` | Agent requested a revision via `request_revision`. | | `approved` | Accepted (explicitly or via 72-hour auto-approval). | | `waived` | The owner waived the item — it will never be submitted and does not count toward `progress.total`. | --- ## get_intake_results Returns the typed content of all approved (or all submitted) items. Use this once the intake is complete, or incrementally as items are approved using `only_new: true`. **Parameters** | Parameter | Type | Required | Description | |---|---|---|---| | `intake_id` | string | Yes | The intake to retrieve results from. | | `only_new` | boolean | No | If `true`, returns only items approved since the last call. Useful for streaming incremental processing. | | `include_pending` | boolean | No | If `true`, also returns items that are `submitted` but not yet approved. | **Response** ```json { "intake_id": "in_8f3kQmR2", "status": "completed", "progress": { "submitted": 8, "total": 8, "outstanding": 0, "percent": 100 }, "missing": [], "results": { "logo": { "url": "https://files.briefgate.dev/in_8f3kQmR2/logo.png?token=sig_abc&expires=1710615600", "filename": "bella-napoli-logo.png", "mime": "image/png", "width": 1024, "height": 512, "size": 48210, "checksum_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b8" }, "brand_colors": ["#1B2A4A", "#E8E2D9", "#C8382E"], "hero_copy": "Since 1987, handcrafted Neapolitan pizza in the heart of the city. Come hungry, leave happy.", "has_existing_site": true, "existing_site_url": "https://old.bellanapoli.com", "platform": "wordpress", "cms_password": { "value": "admin:s3cr3tP@ssw0rd", "one_time": true, "first_reveal": true, "expires_at": "2024-04-15T10:22:00Z" }, "opening_hours": { "mon_fri": "12:00-22:00", "sat": "12:00-23:00", "sun": "13:00-21:00" } }, "meta": { "logo": { "type": "image", "status": "approved", "submitted_at": "2024-03-16T10:00:00Z" }, "cms_password": { "type": "secret", "status": "approved", "submitted_at": "2024-03-16T10:15:00Z" } } } ``` `missing` lists the keys of required client items still `pending` or `needs_revision` — useful to check before assuming the intake is complete. `meta` carries one entry per item returned in `results`: its `type`, `status`, `submitted_at`, and (for a decision item) `decided_by`. **Notes on specific types:** - **Images and files** — `url` is a signed URL with 24-hour validity. Fetch it promptly or re-request results to get a fresh URL. - **Secrets** — the `value` field contains the decrypted plaintext on the **first call only** (`first_reveal: true`). On all subsequent calls `value` is absent. Store the secret immediately. Auto-expire after 30 days. Requires the `secrets:read` or `admin` scope on the API key. --- ## request_revision Marks an item as `needs_revision` and sends the client an email notification explaining what needs to be fixed. The item returns to `pending` on the client's side, and the cycle restarts. **Parameters** | Parameter | Type | Required | Description | |---|---|---|---| | `intake_id` | string | Yes | The intake containing the item. | | `item_key` | string | Yes | The `key` of the item to revise (e.g. `"logo"`). | | `note` | string | Yes | Human-readable explanation sent to the client. Be specific. | **Example** ```json { "intake_id": "in_8f3kQmR2", "item_key": "logo", "note": "The logo appears to be exported at 320px. Please re-export at a minimum of 512px on the shortest side, ideally as an SVG vector file." } ``` **Response** ```json { "intake_id": "in_8f3kQmR2", "item_key": "logo", "status": "needs_revision", "client_notified": true } ``` The client receives an email with your note. Their portal highlights the flagged item. When they resubmit, the item transitions back to `submitted` and the 72-hour auto-approval timer resets. --- ## send_chase Manually triggers a chase message outside the automatic schedule. Use this to send a personal nudge before a deadline. **Parameters** | Parameter | Type | Required | Description | |---|---|---|---| | `intake_id` | string | Yes | The intake to chase. | | `channel` | string | No | `"email"`. Defaults to `"email"`. | **Example** ```json { "intake_id": "in_8f3kQmR2", "channel": "email" } ``` **Response** ```json { "intake_id": "in_8f3kQmR2", "channel": "email", "sent_at": "2024-03-22T08:15:00Z" } ``` **When to use this tool** - The deadline is tomorrow and the client has not responded to the automatic emails. - You want to send a personal nudge outside the automatic schedule. --- ## list_intakes Returns a paginated list of intakes, optionally filtered by status or client email. Useful for building dashboards or checking which projects need attention. **Parameters** | Parameter | Type | Required | Description | |---|---|---|---| | `status` | string | No | Filter by intake status: `draft`, `sent`, `in_progress`, `completed`, `archived`. | | `client_email` | string | No | Filter to intakes belonging to a specific client. | | `folder_id` | string | No | Filter by folder, using an id from `list_folders`. Pass the literal string `"none"` to see only intakes that are not in any folder. | | `q` | string | No | Free-text search: matches a substring of project name, client name, or client email. | | `limit` | integer | No | Number of results per page (default 20, max 100). | | `offset` | integer | No | Pagination offset (default 0). | **Response** ```json { "intakes": [ { "intake_id": "in_8f3kQmR2", "project_name": "Bella Napoli — Website", "status": "in_progress", "client": { "email": "owner@bellanapoli.com", "name": "Marco Esposito" }, "portal_url": "https://p.briefgate.dev/8f3kqmr2", "created_at": "2024-03-15T10:22:00Z", "progress": { "submitted": 3, "total": 7 } }, { "intake_id": "in_4p2nWxY7", "project_name": "Green Leaf Cafe — Rebrand", "status": "completed", "client": { "email": "ops@greenleafcafe.com", "name": "Priya Nair" }, "portal_url": "https://p.briefgate.dev/4p2nwxy7", "created_at": "2024-03-10T09:00:00Z", "progress": { "submitted": 5, "total": 5 } } ], "total": 47, "limit": 20, "offset": 0 } ``` Each intake in the array uses the same snake_case field shape as the single-intake object described elsewhere in these docs, plus a per-intake `progress` summary showing how many items have been submitted out of the total. --- ## add_items Appends new items to an existing intake that has already been sent. The client receives a notification that new items have been added. Use this when scope expands after the initial intake is live. **Parameters** | Parameter | Type | Required | Description | |---|---|---|---| | `intake_id` | string | Yes | The intake to extend. | | `items` | array | Yes | Array of item definitions in the same format used in `define_intake`. | **Example — adding a favicon request after the initial intake was sent** ```json { "intake_id": "in_8f3kQmR2", "items": [ { "key": "favicon", "label": "Favicon", "help": "A square icon at least 32x32px, ideally 512x512px. Used in browser tabs and bookmarks.", "type": "image", "required": true, "constraints": { "formats": ["png", "svg"], "min_width": 32, "min_height": 32 } } ] } ``` **Response** ```json { "intake_id": "in_8f3kQmR2", "items_added": [ { "key": "favicon", "status": "pending" } ] } ``` The client's portal immediately shows the new item. --- ## update_item Changes the definition of an existing item on an intake — for example, tightening a constraint, editing the label or help text, or making an item required after the fact. The item's `key` cannot be changed; if you need a different key, use `add_items` to add a new item and leave the old one in place or discard it. **Parameters** | Parameter | Type | Required | Description | |---|---|---|---| | `intake_id` | string | Yes | The intake containing the item. | | `item_key` | string | Yes | The `key` of the item to update. | | `type` | string | No | New item type. See [item-types.md](./item-types.md). | | `label` | string | No | New label shown to the client. | | `help` | string | No | New help text. | | `required` | boolean | No | Whether the item is required. | | `constraints` | object | No | New constraints object, replacing the previous one. | | `options` | array | No | New `{value, label}` options array, for `select`/`multiselect` items. | | `pattern` | string | No | New regular expression, for `text` items. | | `discard_submitted_value` | boolean | No | See "Conflicts with an existing answer" below. Default `false`. | At least one field besides `intake_id` and `item_key` must be given. Neither `schema` nor `owner_note` can be set through this tool — the call is rejected if you pass either. `assignee` also cannot be changed by this tool — remove and re-add the item with `add_items` if it needs to move between `client` and `owner`. **Example — widening an image constraint after the client complained** ```json { "intake_id": "in_8f3kQmR2", "item_key": "logo", "constraints": { "formats": ["svg", "png", "jpg"], "min_width": 256 } } ``` **Response** ```json { "item": { "key": "logo", "type": "image", "assignee": "client", "label": "Restaurant logo", "help": "SVG or PNG with transparent background, minimum 512px.", "required": true, "status": "pending", "value": null, "constraints": { "formats": ["svg", "png", "jpg"], "min_width": 256 }, "options": null, "pattern": null, "submitted_at": null, "approved_at": null, "revision_note": null, "revision_count": 0, "waiver": null, "client_note": null, "owner_note": null } } ``` **Conflicts with an existing answer** If the client has already submitted a value for the item, and your change would invalidate that value under the new definition (e.g. narrowing `max_chars` below the submitted text's length, or removing an option the client already selected), the call fails with `409` and error code `item_answer_would_be_discarded` instead of silently dropping the client's answer: ```json { "error": { "code": "item_answer_would_be_discarded", "message": "Changing constraints on \"logo\" would invalidate the client's submitted value." } } ``` Pass `discard_submitted_value: true` to proceed anyway. In that case the item resets to `pending` and the response includes `"discarded_submitted_value": true` alongside `item`. --- ## update_intake Edits an intake that is already `sent` — the alternative used to be deleting it and calling `define_intake` again, which re-sends the invitation and hands the client a second link. Works on an intake in any status except `archived`; changing the chase cadence on a `sent` or `in_progress` intake re-plans the schedule from now, cancelling whatever reminder was still pending under the old settings. **The client's e-mail address cannot be changed with this tool** — it is what the portal link and magic token are bound to. Use `manage_recipients` to add, remove, or reinstate an address instead. **Parameters** | Parameter | Type | Required | Description | |---|---|---|---| | `intake_id` | string | Yes | The intake to edit. | | `project_name` | string | No | | | `due_date` | string \| null | No | `YYYY-MM-DD`. `null` clears it. | | `chase_schedule` | string | No | `default`, `gentle`, `aggressive`, `custom`, `off`. | | `chase_interval` | integer | No | Only meaningful with `chase_schedule: "custom"`. Pair with `chase_interval_unit`. | | `chase_interval_unit` | string | No | `minutes`, `hours`, or `days` (default `days`). | | `chase_at_time` | string \| null | No | `HH:MM` local time. Needs an interval measured in whole days. `null` clears it. | | `max_reminders` | integer \| `"unlimited"` | No | Raising this past the number of reminders already sent un-stalls an intake that had run out and resumes chasing. | | `respect_quiet_hours` | boolean | No | | | `client.name` | string | No | | | `client.phone` | string \| null | No | E.164, e.g. `+420601123456`. `null` clears it. | | `client.language` | string | No | `cs`, `sk`, `pl`, `de`, `es`, `en`. | | `client.timezone` | string | No | IANA timezone, e.g. `Europe/Prague`. Feeds `respect_quiet_hours` and `chase_at_time` — changing it also re-plans the schedule. | | `folder_id` | string \| null | No | Move this intake to a different folder, using an id from `list_folders`. `null` removes it from any folder. It never touches the chase schedule. | No `client.email` — see above. At least one field besides `intake_id` is required. Omitting a field leaves it untouched; `null` is only accepted where the table above says so. **Example — switching a stalled intake to a faster, uncapped cadence** ```json { "intake_id": "in_8f3kQmR2", "chase_schedule": "custom", "chase_interval": 6, "chase_interval_unit": "hours", "max_reminders": "unlimited" } ``` **Example — correcting the client's name and timezone** ```json { "intake_id": "in_8f3kQmR2", "client": { "name": "Marco Esposito", "timezone": "Europe/Rome" } } ``` **Response** is `{ "intake": { ... } }`, the same object `get_intake_status`'s sibling read tools return. **Errors** | Code | Meaning | |---|---| | `intake_archived` (409) | The intake is archived and cannot be edited. | | 400 | No field besides `intake_id` was given. | | 422 | A field's value is invalid — e.g. `chase_at_time` against an interval that isn't a whole number of days. | --- ## manage_recipients Adds, removes, or reinstates one of the people an intake is addressed to. An intake can have up to five recipients sharing one portal link — a primary client plus four others (two directors of the same company, for instance). Wraps `POST`/`DELETE /v1/intakes/:id/recipients` and the reinstate endpoint; see [rest-api.md](./rest-api.md#post-v1intakesidrecipients) for the underlying REST contract. **Parameters** | Parameter | Type | Required | Description | |---|---|---|---| | `intake_id` | string | Yes | | | `action` | string | Yes | `add`, `remove`, or `reinstate`. | | `email` | string | Yes | The address to add, remove, or reinstate. | | `name` | string | No | Only used with `action: "add"`. | **`add`** — includes the address in the same portal link and future reminders as the primary client. Sends nothing by itself; use `send_chase` to reach the new person immediately. **`remove`** — drops an additional address. The primary client cannot be removed this way — use `update_intake` to change other fields, or `define_intake` to start over. **`reinstate`** — for a bounce that was wrong: the person did get the e-mail, or the mailbox has since been fixed. Clears the bounce flag on an address that a delivery failure had silenced. If nobody was left to chase before this call, automatic reminders resume. **Example** ```json { "intake_id": "in_8f3kQmR2", "action": "reinstate", "email": "owner@bellanapoli.com" } ``` **Response** ```json { "email": "owner@bellanapoli.com", "bounced_at": null, "still_chasing": true } ``` (`add` and `remove` return the shapes documented for their underlying REST endpoints instead — `also_notify` for `add`, an empty body for `remove`.) **Errors** | Code | Meaning | |---|---| | `recipient_exists` (409) | `add`: that address is already on the intake. | | 400 (`recipient_limit`) | `add`: the intake already has five recipients. | | `recipient_is_primary` (400) | `remove`: that address is the primary client. | | 404 | `remove`/`reinstate`: no such recipient on the intake. | | `recipient_not_bounced` (409) | `reinstate`: that address has never bounced. | --- ## manage_webhook Creates, lists, or deletes webhook endpoints for your account. Webhooks let you react to intake events (an item submitted, an intake completed, a reminder bouncing, and so on) without polling. See [webhooks.md](./webhooks.md) for delivery, signature verification, and retry behavior. **Parameters** | Parameter | Type | Required | Description | |---|---|---|---| | `action` | string | Yes | `"create"`, `"list"`, or `"delete"`. | | `url` | string | For `create` | HTTPS endpoint that receives the webhook POSTs. | | `events` | array | For `create` | Subset of `item.submitted`, `intake.completed`, `client.viewed`, `chase.bounced`, `intake.stalled`, `intake.overdue`. | | `format` | string | No | `"raw"` (default, signed BriefGate envelope), `"slack"`, or `"discord"`. | | `webhook_id` | string | For `delete` | The endpoint to remove. | `url` and `events` are both required for `action: "create"`. **Example — registering an endpoint** ```json { "action": "create", "url": "https://yourapp.com/webhooks/briefgate", "events": ["item.submitted", "intake.completed", "intake.stalled"] } ``` **Response (create)** ```json { "id": "whe_a1b2c3d4e5f6", "url": "https://yourapp.com/webhooks/briefgate", "events": ["item.submitted", "intake.completed", "intake.stalled"], "format": "raw", "active": true, "created_at": "2024-03-22T08:15:00Z", "secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } ``` `secret` is shown exactly once, at creation — store it immediately, since you need it to verify signatures and it is never returned again (including by `action: "list"`). **Response (list)** ```json { "webhooks": [ { "id": "whe_a1b2c3d4e5f6", "url": "https://yourapp.com/webhooks/briefgate", "events": ["item.submitted", "intake.completed", "intake.stalled"], "format": "raw", "active": true, "created_at": "2024-03-22T08:15:00Z" } ] } ``` `url` is masked in the list response for `slack`/`discord` format endpoints, and shown in full for `raw` format. **Response (delete)** `action: "delete"` returns no body (`204 No Content` at the REST layer). --- ## list_folders Lists the folders in your account, used to group intakes by client or project. Call this before `create_folder` or before setting `folder_id` on `define_intake`, `update_intake`, or `list_intakes` — reuse an existing folder for a returning client instead of creating a duplicate. **Parameters** None. **Response** ```json { "folders": [ { "id": "fld_a1b2c3d4", "name": "Bella Napoli", "sort_order": 0, "intake_count": 3, "created_at": "2024-03-10T09:00:00Z" } ] } ``` --- ## create_folder Creates a new folder to group intakes, e.g. one per client. Call `list_folders` first and reuse a matching folder — only create one when none of the existing folders fits. **Parameters** | Parameter | Type | Required | Description | |---|---|---|---| | `name` | string | Yes | Folder name, e.g. the client's or project's name. Must be unique in your account. | **Response** ```json { "id": "fld_a1b2c3d4", "name": "Bella Napoli", "sort_order": 0, "intake_count": 0, "created_at": "2024-03-22T08:15:00Z" } ``` **Errors** | Code | Meaning | |---|---| | `folder_exists` (409) | A folder with this name already exists — use `list_folders` to find it instead. | --- ## login Signs in without pasting an API key — the local-package equivalent of Option 1 in [quickstart.md](./quickstart.md). Not available when connected through the hosted endpoint (`mcp.briefgate.dev`); there, connecting the client already triggers OAuth. Takes no arguments. This is a **two-phase** tool because approval can take minutes, longer than a single tool call should block for: 1. The first call starts a device-authorization flow and returns immediately with a short code and a URL. Tell the client's user to open the URL and approve the code; a browser is also opened automatically where possible. 2. Call `login` again — any time, or once the user says they've approved it — to check progress. While it's still waiting, the response says so; once approved, that same call reports success and the key is saved to `~/.briefgate/credentials.json`. No restart needed — the very next tool call is signed in. Has no effect, and says so instead of running the flow, if an API key is already configured via `--api-key` or `BRIEFGATE_API_KEY` — those always take priority over a locally stored one. **Parameters:** none. --- ## logout Removes the API key `login` stored locally for this BriefGate server, and best-effort revokes it on the server too (a `DELETE /v1/keys/current` call using that same key). Not available when connected through the hosted endpoint. Takes no arguments. If the revoke call fails (no network, API unreachable), the local copy is still removed; the response says so and points at the BriefGate dashboard to revoke it there instead. **Parameters:** none. --- ## Idempotency Network errors can cause `define_intake` to be called twice, which would send the client two emails and create two intakes. The MCP package automatically derives a stable idempotency key from the `project_name`, `client.email`, and a hash of the `items` array — retrying with identical arguments returns the original response without creating a second intake. When calling the REST API directly, pass an `Idempotency-Key` header: ```bash curl -X POST https://api.briefgate.dev/v1/intakes \ -H "Authorization: Bearer bg_live_xxxxx" \ -H "Idempotency-Key: bella-napoli-2024-01" \ -H "Content-Type: application/json" \ -d '{ ... }' ``` If the key was seen before, BriefGate returns the original response unchanged (HTTP 200, not 201). Keys expire after 24 hours. --- ## Trying it without emailing a client Pass `"send": false` to `define_intake` to create the intake as a draft without emailing the client — see the `send` parameter above. Nothing goes out until you call `POST /v1/intakes/:id/send` over REST; there is no MCP tool for sending a draft later. While it's still a draft, `GET /v1/intakes/preview` shows the exact subject line and sender name the client will get, using the account's current branding — it's session-only, so check it from the dashboard rather than from the agent. On a plan without custom branding, that preview shows the built-in sender identity ("Your developer", etc.) rather than anything set in `branding.sender_name`, so you can confirm whether a name you set will actually be used before the client sees it. --- ## Tool call example in Claude Code When Claude Code invokes a BriefGate tool, the underlying MCP call looks like this: ```json { "type": "tool_use", "id": "toolu_01XyzAbc", "name": "mcp__briefgate__define_intake", "input": { "project_name": "Bella Napoli — Website", "client": { "email": "owner@bellanapoli.com", "name": "Marco Esposito", "language": "en" }, "items": [ { "key": "logo", "label": "Restaurant logo", "type": "image", "required": true, "constraints": { "formats": ["svg", "png"], "min_width": 512 } } ], "chase_schedule": "default" } } ``` The tool name is prefixed with `mcp__` and the MCP server name (`mcp__briefgate__`). Claude Code handles the JSON serialization and transport automatically — you just describe what you need in natural language and the agent constructs the call. --- ## REST API Reference URL: https://briefgate.dev/docs/rest-api # REST API Reference All MCP tools map 1:1 to REST endpoints. Use the REST API directly for CI/CD pipelines, non-MCP integrations, webhook handlers, server-side automation, or any HTTP client. **Base URL:** `https://api.briefgate.dev` All requests and responses use JSON (`Content-Type: application/json`). All timestamps are ISO 8601 in UTC. --- ## Authentication Include your API key in every request as a Bearer token: ``` Authorization: Bearer bg_live_xxxxx ``` **Manage API keys** ``` POST /v1/keys Create a new key GET /v1/keys List all keys DELETE /v1/keys/:id Revoke a key DELETE /v1/keys/current Revoke the key making the request (what the MCP package's logout calls) ``` Create a key: ```bash curl -X POST https://api.briefgate.dev/v1/keys \ -H "Authorization: Bearer bg_live_xxxxx" \ -H "Content-Type: application/json" \ -d '{ "name": "CI/CD pipeline", "mode": "live", "scopes": ["intakes:read", "intakes:write"] }' ``` **Key modes.** `mode` is `live` (default) or `test`. A test key (`bg_test_…`) only sees the intakes it created, and those intakes never email or text a client — invitations and reminders are recorded as `skipped`, everything else (portal, webhooks, results) behaves normally. Use it for CI and for trying things out; there is no separate inbox, check the intake in the dashboard instead. Available scopes: `admin`, `intakes:read`, `intakes:write`, `secrets:read`. The `admin` scope includes all others. Key management itself is session-only: `POST /v1/keys`, `GET /v1/keys` and `DELETE /v1/keys/:id` all require a signed-in dashboard user — an API key cannot create or list other keys. `DELETE /v1/keys/current` is the one exception, since it revokes the very key making the request. --- ## Error format All errors return a JSON body: ```json { "error": "not_found", "message": "Intake in_8f3k not found or does not belong to this account.", "request_id": "req_abc123" } ``` Some errors carry extra fields: a stable `reason` slug and machine-readable `params`, or — for a request that failed field validation — a `details` array of `{ path, message }` pairs, one per offending field: ```json { "error": "unprocessable", "message": "items.0.constraints: min_count must not exceed max_count", "reason": "validation_failed", "params": { "field": "items.0.constraints" }, "details": [ { "path": "items.0.constraints", "message": "min_count must not exceed max_count" } ], "request_id": "req_abc123" } ``` Include `request_id` when contacting support. **Error codes** | HTTP status | `error` value | Meaning | |---|---|---| | 400 | `invalid_request` | Malformed JSON body, or a request that is well-formed but invalid given the resource's current state (e.g. revoking an already-revoked key). Check `message` for details. | | 401 | `unauthorized` | Missing or invalid API key. | | 403 | `forbidden` | Key does not have the required scope for this operation. | | 404 | `not_found` | Resource does not exist or belongs to a different account. | | 409 | `conflict` | A resource with the same identifier already exists (e.g. duplicate `idempotency_key` within the expiry window). Returns the existing resource. | | 410 | `gone` | A one-time value has expired and been purged — e.g. a submitted `secret` past its reveal window. Re-reading an already-revealed secret is not this case: it returns HTTP 200 with `already_revealed: true` instead. | | 413 | `payload_too_large` | Reserved for future use — no endpoint returns it for an oversized request body. An oversized uploaded file is rejected as `422 unprocessable` with a `file.too_large` issue instead. | | 413 | `download_too_large` | The intake exceeds the size limit for a ZIP download (`GET /v1/intakes/:id/download`) — see [Download Everything as a ZIP](./zip.md#size-limit) for fetching a large intake's items individually instead. | | 422 | `unprocessable` | Request failed validation: a missing or malformed required field, a value outside its allowed range, or one that is structurally valid but semantically invalid (e.g. `min_count` greater than `max_count`). This is also what a missing required field returns, not 400 — see `details` for which field. | | 429 | `rate_limited` | Too many requests. Honour the `Retry-After` header (seconds) before retrying. | | 402 | `quota_exceeded` | Monthly intake or file-storage quota reached. | | 402 | `plan_required` | Feature is not available on the current plan. | | 500 | `internal_error` | Unexpected server error. Safe to retry with exponential backoff. | | 503 | `service_unavailable` | The database is temporarily unreachable. Honour `Retry-After` (seconds) and retry. | --- ## Intakes ### POST /v1/intakes Create a new intake and send the client their portal link. **Request headers** | Header | Description | |---|---| | `Idempotency-Key` | Optional. A unique string (UUID recommended). If an intake was already created with this key, the original is returned (HTTP 200) instead of creating a duplicate. | **Key request fields** | Field | Type | Required | Description | |---|---|---|---| | `project_name` | string | Yes | Human-readable project title. | | `client.email` | string | Yes | Client email address. | | `client.name` | string | Yes | Client display name — every invitation opens by addressing them, so this cannot be blank. | | `client.language` | string | No | `cs`, `sk`, `pl`, `de`, `es`, `en`. Omitted, it falls back to the account's `default_language`, then English. | | `client.phone` | string | No | E.164 format, e.g. `+420601123456`. Reserved for SMS chases (`chase_schedule` channel `sms`, see [Chase schedules](#post-v1intakesidchase)). | | `client.timezone` | string | No | IANA timezone, e.g. `Europe/Prague`. Anchors `respect_quiet_hours` and `chase_at_time` to the client's local clock. Default `Europe/Prague`. | | `client.also_notify` | array | No | Up to 4 more people (`{ email, name? }`) who get the same portal link and reminders as the primary client. Add or remove them after creation with `POST`/`DELETE /v1/intakes/:id/recipients` (see [Recipients](#post-v1intakesidrecipients)). | | `email_copy` | object | No | Overrides the subject and intro lines for this intake. No links allowed in any line, on any plan (`422` otherwise). Part of [custom branding](./billing.md#custom-branding) — accepted and stored on Free, but not used until the account upgrades. See [chase.md](./chase.md#writing-your-own-subject-and-intro). | | `branding` | object | No | Per-intake override of account branding: `logo_url`, `accent_color` (hex), `sender_name`, `reply_to`. `logo_url`, `accent_color`, and `sender_name` are part of [custom branding](./billing.md#custom-branding) — accepted and stored on Free, but not used until the account upgrades; `reply_to` is not gated. `sender_name` is rejected with `422` if it contains a link (web address, bare domain, or email address), on any plan. | | `client_brief` | string | No | Information and context for the client — shown at the top of the portal, before the requested items, as "Information from <your name>". Max 5000 characters; trimmed; an empty string is stored as `null`. Attach files with `POST /v1/intakes/:id/brief/files` once the intake exists — see [Client brief](#post-v1intakesidbrieffiles). | | `items` | array | Yes | Item definitions. See [item-types.md](./item-types.md). Still required (min. 1) even when `template` is set. | | `template` | string | No | Slug of a saved template ([templates.md](./templates.md)). Template items merge with `items` by key. Every other field the template's `settings` sets applies as a default — only where this request itself leaves that field unset. | | `chase_schedule` | string | No | `default`, `gentle`, `aggressive`, `custom`, or `off`. | | `chase_interval` | integer | No | How often to remind, only with `chase_schedule: "custom"`. Pair with `chase_interval_unit`. Default: every 3 days. Sending it with any other schedule returns 422. | | `chase_interval_unit` | string | No | `minutes`, `hours` or `days` (default `days`). The interval must work out to at least 5 minutes and at most 90 days. | | `respect_quiet_hours` | boolean | No | Hold reminders to the client's 08:00–19:00 window. Default `true`. | | `max_reminders` | integer \| string | No | Reminders before the intake is marked stalled (1–1000, default 3, or `"unlimited"`). | | `chase_at_time` | string | No | Local time of day for the reminder, `HH:MM`. Requires `chase_schedule: "custom"` with a whole-day interval. | | `due_date` | string | No | ISO 8601 date shown to the client. | | `send` | boolean | No | Set to `false` to create a draft without sending. Call `POST /v1/intakes/:id/send` to send later. Default: `true`. | | `retention` | object | No | How long to keep data after completion. `{ mode: "days"\|"on_delivery", days?: number, anonymize?: boolean }`. Default: purge 90 days after `intake.completed`. Use `mode: "on_delivery"` for intakes with credentials — contents are removed ~24 h after you collect results. | | `folder_id` | string | No | File the intake under this folder — an id from [GET /v1/folders](#folders). Omitted means Unfiled. Must name a folder on your own account, or `400 invalid_request` (reason `validation_error`). | **Chase schedules** | Schedule | Reminders | |---|---| | `default` | T+2 days, T+5 days, T+9 days, then weekly | | `gentle` | T+3 days, T+8 days, then bi-weekly (also skips weekends, moving to Monday 08:00) | | `aggressive` | T+1 day, T+3 days, T+5 days, then every other day | | `custom` | Every `chase_interval` `chase_interval_unit` (default every 3 days), starting one interval after the invite | | `off` | No automatic reminders | **Response** (HTTP 201) ```json { "intake_id": "in_8f3kQmR2", "portal_url": "https://p.briefgate.dev/8f3kqmr2", "status": "sent", "items": [ { "key": "logo", "status": "pending" }, { "key": "hero_copy", "status": "pending" } ], "follow_up": { "recommended": "schedule", "reason": "No active webhook endpoints are registered on this account.", "webhook": { "active_endpoints": 0, "events": ["item.submitted", "intake.completed"], "register_with": "manage_webhook" }, "schedule": { "check_with": "get_intake_status", "every_hours": 24, "until": "2024-03-29T10:22:00Z" } } } ``` `follow_up` is always present and tells you how to learn about progress without polling blindly. `recommended` is `"webhook"` when an active endpoint already covers the relevant events, or `"schedule"` when it does not — in that case, poll `GET /v1/intakes/:id/status` every `follow_up.schedule.every_hours` hours until `follow_up.schedule.until`, or register a webhook (`POST /v1/webhooks`, see [Webhooks](#webhooks)) instead. **If an invitation limit is hit**, the intake is still created, as a draft, instead of the request failing. `status` is `"draft"` rather than `"sent"`, and the response adds `invitation_sent: false` plus a `note` explaining which limit and what to do next: ```json { "intake_id": "in_8f3kQmR2", "portal_url": "https://p.briefgate.dev/8f3kqmr2", "status": "draft", "items": [ ... ], "follow_up": { ... }, "invitation_sent": false, "note": "Daily invitation limit of the free plan reached — the intake was created as a draft. Send it with POST /v1/intakes/{id}/send after midnight UTC, or upgrade to remove the daily limit." } ``` Two different limits can trigger this: the account-wide 30-invitations-per-hour cap (every plan), or the Free plan's 10-invitations-per-UTC-day cap (`invites_per_day` in `GET /pricing.json`; `null` — no daily limit — on Solo, Studio, and Agency). Send the draft later with [POST /v1/intakes/:id/send](#post-v1intakesidsend) once the limit resets. **Complete curl example** ```bash curl -X POST https://api.briefgate.dev/v1/intakes \ -H "Authorization: Bearer bg_live_xxxxx" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: bella-napoli-website-2024" \ -d '{ "project_name": "Bella Napoli — Website", "client": { "email": "owner@bellanapoli.com", "name": "Marco Esposito", "language": "en" }, "items": [ { "key": "logo", "label": "Restaurant logo", "help": "SVG or PNG, transparent background, minimum 512px.", "type": "image", "required": true, "constraints": { "formats": ["svg", "png"], "min_width": 512, "transparent_background": true } }, { "key": "hero_copy", "label": "Hero section tagline", "type": "longtext", "required": true, "constraints": { "max_chars": 400 } }, { "key": "opening_hours", "label": "Opening hours", "type": "structured", "required": true, "schema": { "type": "object", "required": ["mon_fri", "sat", "sun"], "properties": { "mon_fri": { "type": "string" }, "sat": { "type": "string" }, "sun": { "type": "string" } } } }, { "key": "photos", "label": "Food and interior photos", "type": "file_list", "required": true, "constraints": { "formats": ["jpg", "png", "heic"], "min_count": 5, "max_count": 15 } } ], "chase_schedule": "default", "due_date": "2024-04-01" }' ``` --- ### GET /v1/intakes List intakes with optional filters. **Query parameters** | Parameter | Description | |---|---| | `status` | Filter by status: `draft`, `sent`, `in_progress`, `completed`, `archived`. | | `client_email` | Filter to a specific client. | | `folder_id` | Filter to one folder — an id from [GET /v1/folders](#folders), or the literal `none` for intakes with no folder. | | `q` | Case-insensitive substring search across `project_name`, `client.name` and `client.email` (1–100 chars). Combines with the other filters. | | `limit` | Results per page (default 20, max 100). | | `offset` | Pagination offset (default 0). | **Response** ```json { "intakes": [ { "intake_id": "in_8f3kQmR2", "project_name": "Bella Napoli — Website", "status": "in_progress", "client": { "email": "owner@bellanapoli.com", "name": "Marco Esposito" }, "portal_url": "https://p.briefgate.dev/8f3kqmr2", "created_at": "2024-03-15T10:22:00Z", "progress": { "submitted": 3, "total": 7 } } ], "total": 47, "limit": 20, "offset": 0 } ``` > **Note:** Each intake object matches the same snake_case shape used everywhere else in this API, plus a per-intake `progress` summary — see [GET /v1/intakes/:id](#get-v1intakesid) and [GET /v1/intakes/:id/status](#get-v1intakesidstatus) for the full field reference. --- ### GET /v1/intakes/:id Retrieve the full intake definition including all item definitions and metadata. **Response** ```json { "intake": { "intake_id": "in_8f3kQmR2", "project_name": "Bella Napoli — Website", "status": "in_progress", "mode": "live", "portal_url": "https://p.briefgate.dev/8f3kqmr2", "client": { "email": "owner@bellanapoli.com", "name": "Marco Esposito", "phone": null, "language": "en", "timezone": "Europe/Rome", "also_notify": [ { "email": "chef@bellanapoli.com", "name": "Giulia", "bounced_at": null } ], "client_bounced_at": null }, "branding": null, "folder_id": null, "chase_schedule": "default", "chase_interval_minutes": null, "respect_quiet_hours": true, "max_reminders": 3, "chase_at_time": null, "due_date": "2024-04-01", "retention": { "mode": "days", "days": 90, "anonymize": true }, "created_at": "2024-03-15T10:22:00Z", "sent_at": "2024-03-15T10:22:05Z", "completed_at": null, "delivered_at": null, "anonymized_at": null, "client_last_seen": "2024-03-16T14:05:33Z", "stalled_at": null, "purge_at": null, "client_note": null, "owner_note": null, "client_brief": null, "brief_files": [] }, "items": [ { "key": "hero_copy", "type": "longtext", "assignee": "client", "label": "Hero section tagline", "help": null, "required": true, "status": "approved", "value": "Real Napoli-style pizza, right in your neighbourhood.", "constraints": { "max_chars": 400 }, "options": null, "pattern": null, "submitted_at": "2024-03-16T11:00:00Z", "approved_at": "2024-03-16T11:05:00Z", "revision_note": null, "revision_count": 0, "waiver": { "state": "none", "reason": null, "requested_by": null, "requested_at": null, "decided_at": null }, "client_note": null, "owner_note": null } ], "progress": { "submitted": 2, "total": 4, "outstanding": 2, "percent": 50 }, "owner_tasks": { "done": 0, "total": 0 } } ``` `chase_interval_minutes` is the normalised value of `chase_interval`/`chase_interval_unit`; it is `null` unless `chase_schedule` is `"custom"`. A `file`, `file_list` or `image` item additionally carries a `files` array (`id`, `filename`, `mime`, `size`, `width`/`height`, `av_status`, `checksum_sha256`) instead of a meaningful `value` — no signed URL is minted here; download one via `GET /v1/intakes/:id/items/:key/files/:fileId` (below) or `GET /v1/intakes/:id/results`. An owner-assigned `select`/`multiselect` (a "decision") additionally carries a `decision` object: `{ decided_by: "agent"|"owner", value, proposed_value, proposed_rationale }`. `brief_files` — the attachments on `client_brief` — is present on this detail response only, not on `GET /v1/intakes` (a query per row on every list page would run for every intake, most of which have none). Each entry is `{ id, filename, mime, size, av_status, created_at }`, same servability rule as an item file (`av_status` gates whether a download will actually work). See [Client brief](#post-v1intakesidbrieffiles) below for managing the text and the files. --- ### PATCH /v1/intakes/:id Edits an existing intake instead of deleting it and creating a new one — which used to be the only option, and re-sent the invitation to the client. Every field is optional, but at least one is required (`400 invalid_request` otherwise). `null` clears `owner_note`, `client_brief`, `due_date` and `chase_at_time`; omitting a field always leaves it untouched. | Field | Type | Notes | |---|---|---| | `owner_note` | string \| null | Never shown to the client. | | `client_brief` | string \| null | Information for the client, shown at the top of the portal — see `client_brief` under [POST /v1/intakes](#post-v1intakes). `null` clears it; an empty string is also stored as `null`. | | `project_name` | string | | | `due_date` | string \| null | `YYYY-MM-DD`. | | `chase_schedule` | string | `default`, `gentle`, `aggressive`, `custom`, `off`. | | `chase_interval` / `chase_interval_unit` | integer / string | Same rules as `POST /v1/intakes` — only meaningful with `chase_schedule: "custom"`. | | `chase_at_time` | string \| null | `HH:MM`, needs a whole-day interval. | | `max_reminders` | integer \| `"unlimited"` | | | `respect_quiet_hours` | boolean | | | `client.name`, `.phone`, `.language`, `.timezone` | | **No `client.email`.** The portal link and magic token are bound to the primary address — changing it here would strand the client's existing link. Add, remove or reinstate addresses with the [recipients endpoints](#post-v1intakesidrecipients) instead. | | `folder_id` | string \| null | Move the intake to this folder, or `null` to move it to Unfiled. Must name a folder on your own account (`400 invalid_request`, reason `validation_error`, otherwise). Never touches `status`, chases, or anything else. | **Cadence changes on a live intake.** On a `sent`, `in_progress`, or stalled intake, changing any of `chase_schedule`, `chase_interval`, `chase_interval_unit`, `chase_at_time`, `max_reminders`, `respect_quiet_hours`, `client.timezone` or `due_date` cancels every still-scheduled reminder and re-plans under the new settings. Reminders already sent still count toward `max_reminders` — attempt numbering is not reset. **Un-stalling.** An intake that ran out of `max_reminders` stops chasing and sets `stalled_at` (see [Reminder cap](./chase.md#reminder-cap)). Raising `max_reminders` (or setting it to `"unlimited"`) past the number of reminders already sent clears `stalled_at` and resumes automatic chasing. Changing other fields on a still-stalled intake updates the stored settings but does not resume chasing by itself. Returns `409 conflict` (reason `intake_archived`) on an archived intake. **Request** ```json { "chase_schedule": "custom", "chase_interval": 6, "chase_interval_unit": "hours", "max_reminders": 12 } ``` **Response** is `{ "intake": { ... } }`, the same shape as `GET /v1/intakes/:id`'s `intake` object. --- ### GET /v1/intakes/:id/items/:key/files/:fileId Downloads or previews one file a client uploaded. Responds with an HTTP 302 redirect to a signed URL (24-hour validity) rather than JSON — use it directly as an ``/``. Returns `422 unprocessable` if the file is still pending its antivirus scan or was flagged as infected. --- ### POST /v1/intakes/:id/brief/files Attaches a file to the client brief — the paragraphs and documents you hand to the client, shown at the top of the portal before the requested items (see `client_brief` under [POST /v1/intakes](#post-v1intakes)). `multipart/form-data` with one field, `file`. Goes through the same pipeline as a client's own upload: the real content type is sniffed rather than trusted, HEIC is converted to JPEG, and the antivirus scan runs before the file is stored — an infected upload is refused outright (`422 unprocessable`), not stored and hidden. A brief holds at most 10 files; uploading an 11th returns `422 unprocessable`. Counts against the same storage quota as everything else on the account. Refused with `409 conflict` (reason `intake_archived`) on an archived intake. **Response** (HTTP 201) ```json { "file": { "id": "bff_9k2mQ7xR", "filename": "contract-offer.pdf", "mime": "application/pdf", "size": 184320, "av_status": "clean", "created_at": "2024-03-15T10:20:00Z" } } ``` --- ### DELETE /v1/intakes/:id/brief/files/:fileId Removes one brief attachment and releases its bytes from the storage quota. Returns `204 No Content`. Refused with `409 conflict` (reason `intake_archived`) on an archived intake. --- ### GET /v1/intakes/:id/brief/files/:fileId/url Downloads or previews one brief attachment. Same convention as `GET /v1/intakes/:id/items/:key/files/:fileId` above: an HTTP 302 redirect to a signed URL, and `422 unprocessable` while the file is still pending its antivirus scan or once it has been flagged as infected. --- ### GET /v1/intakes/:id/status Lightweight status endpoint. Returns item statuses, chase history, and progress without transferring file content or signed URLs. `progress.total` counts what the intake is waiting on: an item the owner has waived, and an optional item the client has not touched, both leave the denominator. That keeps `percent` at 100 exactly when `status` turns `completed`. **Response** ```json { "status": "in_progress", "due_date": "2024-04-01", "client_last_seen": "2024-03-16T14:05:33Z", "progress": { "submitted": 2, "total": 4, "outstanding": 2, "percent": 50 }, "items": [ { "key": "logo", "status": "approved", "submitted_at": "2024-03-16T10:00:00Z", "label": "Restaurant logo", "assignee": "client", "required": true }, { "key": "hero_copy", "status": "needs_revision", "submitted_at": "2024-03-16T11:00:00Z", "label": "Hero section tagline", "assignee": "client", "required": true }, { "key": "opening_hours", "status": "pending", "submitted_at": null, "label": "Opening hours", "assignee": "client", "required": true }, { "key": "photos", "status": "submitted", "submitted_at": "2024-03-16T12:00:00Z", "label": "Food and interior photos", "assignee": "client", "required": true } ], "chases": [ { "id": "chs_a1", "channel": "email", "kind": "invite", "scheduled_at": "2024-03-15T10:22:00Z", "sent_at": "2024-03-15T10:22:05Z", "status": "sent", "attempt_no": 1, "missing_items_count": null, "error": null }, { "id": "chs_a2", "channel": "email", "kind": "reminder", "scheduled_at": "2024-03-17T09:00:00Z", "sent_at": "2024-03-17T09:00:00Z", "status": "sent", "attempt_no": 2, "missing_items_count": 2, "error": null }, { "id": "chs_a3", "channel": "email", "kind": "reminder", "scheduled_at": "2024-03-20T09:00:00Z", "sent_at": null, "status": "scheduled", "attempt_no": 3, "missing_items_count": null, "error": null } ] } ``` `items[].assignee` (`client`/`owner`) and `.required` are always present; an owner-assigned decision item additionally carries the same `decision` object described under `GET /v1/intakes/:id`. `chases[].kind` is one of `invite`, `reminder`, `revision`, `manual`; `.status` is one of `scheduled`, `sent`, `failed`, `bounced`, `complained`, `cancelled`, `skipped`. `scheduled_at` is when the *next* pending reminder is due — poll it instead of guessing from `chase_schedule`. --- ### GET /v1/intakes/:id/results Returns typed results for approved items. File and image items include signed URLs (24-hour validity). **API key only** — unlike every other intake endpoint, this one does not accept a dashboard session. It reveals secrets and advances the per-key `only_new` cursor, both of which only make sense for an agent's own API key; the dashboard uses `GET /v1/intakes/:id` and `POST /v1/intakes/:id/items/:key/reveal` instead. **Query parameters** | Parameter | Type | Description | |---|---|---| | `only_new` | boolean | Only return items approved since the last call to this endpoint (tracked per API key). | | `include_pending` | boolean | Also include items in `submitted` status (not yet approved). | | `exclude_secrets` | boolean | Leave `secret` items out **without revealing them** — `meta` reports `secret_unavailable: true` and the one-time reveal stays available. Use it from integrations that log every response (Zapier, Make, n8n). | **Response** ```json { "intake_id": "in_8f3kQmR2", "status": "in_progress", "progress": { "submitted": 2, "total": 4, "outstanding": 2, "percent": 50 }, "missing": ["opening_hours"], "results": { "logo": { "url": "https://...", "filename": "logo.svg", "mime": "image/svg+xml", "size": 4821, "checksum_sha256": "..." }, "hero_copy": "Real Napoli-style pizza, right in your neighbourhood." }, "meta": { "logo": { "type": "image", "status": "approved", "submitted_at": "2024-03-16T10:00:00Z" }, "hero_copy": { "type": "longtext", "status": "approved", "submitted_at": "2024-03-16T11:00:00Z" } } } ``` `results` holds one entry per included item, keyed by `key`, shaped per its `type` — a `secret` reveals its value here exactly once (see below) and every subsequent read reports it in `meta` instead as `{ secret_unavailable: true, reason, revealed_at }`. `missing` lists the keys of required client items still outstanding. Reading a `secret` item requires the `secrets:read` scope (or `admin`); without it the item is omitted from `results` and `meta` reports `{ secret_unavailable: true, reason: "Scope 'secrets:read' or 'admin' required." }` instead. A `file`/`file_list` item not yet servable (pending antivirus scan, or infected) is likewise left out of its file list and `meta[key].files_pending` counts how many. --- ### POST /v1/intakes/:id/items/:key/reveal Reveals one `secret` item's value. **Session only** — the dashboard's way to read a credential; an API key must use `GET /v1/intakes/:id/results` with the `secrets:read` scope instead, and only the account **owner** may call it (a non-owner team member gets `403 forbidden`, reason `secrets_owner_only`). Like `/results`, the value is released exactly once. **Response** (first reveal) ```json { "key": "admin_password", "value": "hunter2", "first_reveal": true, "expires_at": "2024-03-23T10:00:00Z" } ``` **Response** (already revealed — HTTP 200, not an error) ```json { "key": "admin_password", "value": null, "already_revealed": true, "revealed_at": "2024-03-16T10:05:00Z", "message": "This credential was already revealed. Secrets are shown once and cannot be shown again." } ``` --- ### POST /v1/intakes/:id/items Add items to an existing intake. The client is notified by email. **Request body** ```json { "items": [ { "key": "favicon", "label": "Favicon", "type": "image", "required": true, "constraints": { "formats": ["png","svg"], "min_width": 32 } } ] } ``` **Response** ```json { "intake_id": "in_8f3kQmR2", "items_added": [ { "key": "favicon", "status": "pending" } ] } ``` --- ### PATCH /v1/intakes/:id/items/:key Changes one item on an intake that is already with the client — its type, label, hint, whether it is required, and which formats it accepts. Also carries `owner_note`. Reach for this when the field turns out to be the wrong shape: you asked for an image and the client only has their logo as a PDF, or what you asked for as text is really a file. Widening the formats or switching the type unblocks the client without adding a duplicate item and waiving the original. `key` cannot be changed — results come back under it. Add a new item instead. If the client has already answered and the change would make that answer invalid, the call fails with `409 item_answer_would_be_discarded` and nothing is touched. Repeat it with `discard_submitted_value: true` to clear the answer and ask again. A change that leaves the answer valid — a new label, a wider limit — never discards anything. **Request** ```json { "type": "file", "label": "Logo", "constraints": { "formats": ["svg", "png", "pdf"] } } ``` ### POST /v1/intakes/:id/revision Request a revision on a specific item. Only valid when the item's status is `submitted` or `approved` (otherwise `409 conflict`). Requires the `revisions` feature — not available on the Free plan (`402 plan_required` otherwise). **Request body** ```json { "item_key": "logo", "note": "The logo appears blurry at 320px. Please re-export at minimum 512px, ideally as SVG." } ``` **Response** ```json { "intake_id": "in_8f3kQmR2", "item_key": "logo", "status": "needs_revision", "client_notified": true } ``` --- ### POST /v1/intakes/:id/items/:key/done Tick off one of your own tasks — an item created with `"assignee": "owner"`. **Request body** ```json { "done": true } ``` `done` is optional and defaults to `true`. Send `false` to re-open the task. **Response** ```json { "key": "call_client", "done": true, "status": "approved" } ``` Only owner items are accepted. A client item returns `400` — that answer belongs to the client and is given in the portal. Ticking a task off never completes or delivers an intake: owner tasks are deliberately outside the client's progress. --- ### POST /v1/intakes/:id/items/:key/received-outside Mark a client item as received outside BriefGate — the client e-mailed the file, handed it over on a call, or sent it through another channel. From now on the item counts as complete, so the intake can finish even though nothing came through the portal. If it was the last outstanding item, the intake completes exactly as if the client had clicked "Send assets": `intake.completed` fires and the optional thank-you e-mail goes out. **Request body** ```json { "note": "Sent as an e-mail attachment on 5 Sept" } ``` `note` is optional — a short reminder of where the material actually is. It is shown next to the item in the dashboard and never to the client. **Response** ```json { "key": "logo", "status": "approved", "received_outside": true, "intake_status": "completed" } ``` Only client items are accepted; an owner task returns `400` — tick those off with `/done`. An item that is already approved or waived returns `409` (revert the waiver first), and so does an archived intake. Every item in `GET /v1/intakes/:id` and in the results carries `received_outside` and `received_outside_note`, so an agent reading the results knows the material exists but is not stored in BriefGate. --- ### DELETE /v1/intakes/:id/items/:key/received-outside Undo the mark. The item goes back to waiting for the client and the progress counter drops accordingly; an intake that had completed because of the mark is reopened, the same way reverting a waiver reopens it. Returns `404` if the item was never marked. --- ### POST /v1/intakes/:id/items/:key/answer Settles a **decision** — an owner-assigned `select`/`multiselect` item, optionally carrying the agent's own `proposed` answer (see `items[].proposed` under [POST /v1/intakes](#post-v1intakes)). `value` is validated against the item's own `options`, same as a client submission. **Session only, deliberately.** An API key cannot call this: it is what the AGENT holds, and accepting it here would let an agent confirm its own proposal and have the result recorded as `decided_by: "owner"` — exactly what separating a proposal from an answer exists to prevent. Non-decision items return `400 invalid_request`. **Request** ```json { "value": "29" } ``` **Response** ```json { "key": "attendee_count", "value": "29", "status": "approved", "decided_by": "owner" } ``` --- ### POST /v1/intakes/:id/items/:key/waive The owner closes an item outright ("we're not going to have this"). Only the owner can waive directly — a client can only *propose* a waiver in the portal, which the owner then accepts or rejects with the endpoint below. **Request** ```json { "reason": "Client doesn't have a logo yet; using a text wordmark instead." } ``` `reason` is optional. **Response** is `{ "item": { ... } }`, the same item shape as `GET /v1/intakes/:id`. --- ### POST /v1/intakes/:id/items/:key/waive/decision The owner accepts or rejects a waiver the client proposed. Returns `409 conflict` if the item has no waiver proposal pending. **Request** ```json { "accept": true, "note": "Confirmed with the client by phone." } ``` Accepting moves the item to `waived`; rejecting leaves its status unchanged but clears the pending-waiver flag, so it is chased again like any other outstanding item. `note` is for the audit log only. **Response** is `{ "item": { ... } }`. --- ### DELETE /v1/intakes/:id/items/:key/waive Reverts a waiver back to `pending`, discarding whatever value, submission and revision note the item had — the client has to be asked again either way. If the intake had reached `completed`, it reopens to `in_progress` and chases are rescheduled. **Response** is `{ "item": { ... } }`. --- ### POST /v1/intakes/:id/recipients Adds another person to an intake that has already gone out. They get the same portal link and future reminders as the primary client; no mail is sent by this call itself — send one with `POST /v1/intakes/:id/send` or `.../chase`. At most 4 additional recipients (5 total including the primary client); `409 conflict` (reason `recipient_exists`) if the address is already on the intake. **Request** ```json { "email": "chef@bellanapoli.com", "name": "Giulia" } ``` **Response** (HTTP 201) ```json { "intake_id": "in_8f3kQmR2", "also_notify": [ { "email": "chef@bellanapoli.com", "name": "Giulia", "bounced_at": null } ] } ``` --- ### DELETE /v1/intakes/:id/recipients/:email Removes an additional recipient (URL-encode the address). The primary client cannot be removed this way — use `PATCH /v1/intakes/:id` to change it, or `POST /v1/intakes` to start over — and returns `400 invalid_request` (reason `recipient_is_primary`) if attempted. Returns HTTP 204 on success, `404 not_found` if the address isn't on the intake. --- ### POST /v1/intakes/:id/recipients/:email/reinstate Clears the bounce flag on one address (URL-encode it), primary or additional — for a bounce that was a false positive, or a mailbox the client has since fixed and asked to be re-added to. If the intake had nobody left to chase before this call (every address had bounced) and the intake is `sent` or `in_progress`, automatic chasing resumes. Returns `404 not_found` (reason `recipient_not_found`) if the address isn't on the intake, `409 conflict` (reason `recipient_not_bounced`) if it never bounced. **Response** (HTTP 200) ```json { "email": "owner@bellanapoli.com", "bounced_at": null, "still_chasing": true } ``` `still_chasing` reports whether this address will actually receive further automatic reminders — `false` if the intake is `completed`, `archived`, stalled, or `chase_schedule` is `"off"`. --- ### GET /v1/intakes/preview **Session only.** Renders what the client will actually see in their inbox — subject line and sender name — before anything is sent, using the account's current branding. Useful for catching a missing sender name or wrong language before a real client sees it. **Query parameters:** `language` (defaults to the account's `default_language`), `project_name` (defaults to a localized placeholder). **Response** ```json { "language": "en", "from_name": "Marco @ Bella Napoli via BriefGate", "subject": "Marco @ Bella Napoli needs assets — Website", "sender_name": "Marco @ Bella Napoli", "sender_label": "Marco @ Bella Napoli", "custom_sender_name": true, "using_fallback_sender_name": false } ``` `custom_sender_name` says whether the plan lets the account name itself. When it is `false` (Free — no [custom branding](./billing.md#custom-branding)), `sender_name` is the built-in, localized one ("Your developer", "Váš dodavatel", …), `from_name` reads `"Your developer via BriefGate"`, and `sender_label` is what the client sees inside the email and on the portal: the built-in name with the account owner's login address, e.g. `"Your developer (jan@firma.cz)"`. `using_fallback_sender_name: true` means a paid account has not set a name of its own, so the same built-in name is standing in until one is set. --- ### POST /v1/intakes/:id/chase Manually trigger a chase message outside the automatic schedule. **Request body** ```json { "channel": "email" } ``` `channel` is optional: `"email"` (default) or `"sms"`. SMS requires the `sms` feature (not available on Free) and a positive SMS credit balance — `402 plan_required` or `402 quota_exceeded` (reason `sms_credits`) otherwise. Rate limited to 1 manual chase per intake per hour and 20 per account per hour (`429 rate_limited`, reason `manual_chase_intake`/`manual_chase_account`), independent of channel. --- ### POST /v1/intakes/:id/send Send a draft intake to the client. Only valid when `status` is `draft` (`409 conflict` otherwise). Rate limited to 30 invitations per account per hour (`429 rate_limited`, reason `intake_invites`) — the same limit `POST /v1/intakes` counts against when it sends immediately. On a plan with a daily invitation cap (Free: 10 per UTC day; `invites_per_day` in `GET /pricing.json` — `null` means no daily limit), this also checks that cap, after the hourly one: `429 rate_limited` with reason `intake_invites_daily` if the day's invitations are already used up, naming the plan's limit and how long until it resets. Retry after midnight UTC, or upgrade to remove the daily limit. Unlike `POST /v1/intakes` (which creates the intake as a draft instead of failing when a limit is hit, since there is nothing to roll back), this endpoint is called against an intake that already exists, so it simply returns the error — the intake stays a draft. --- ### POST /v1/intakes/:id/archive Closes an intake without deleting it. Works from any status (`draft`, `sent`, `in_progress`, `completed`); `409 conflict` (reason `intake_archived`) if it is already archived. Empty request body. Side effects: - Cancels every pending or scheduled chase reminder. - Blocks further activity: `PATCH /v1/intakes/:id`, adding/updating items, waivers, and manual chases all return `409 conflict` (reason `intake_archived`), the same error an archived intake already returned from those endpoints. - On the client portal, the magic link keeps resolving — the client still sees everything they already submitted, with `status: "archived"` — but item submissions, file uploads, notes, waivers, and completion are all refused with the same `409`/`intake_archived`. - Fires an `intake.archived` webhook (see [Webhooks](./webhooks.md#events)) and an `intake.archived` audit log entry. Nothing is deleted: the row, its items, files, and history stay exactly as they were, and `GET /v1/intakes/:id` keeps returning it. Returns `{ intake }` — the same single intake object `PATCH /v1/intakes/:id` returns, not the fuller `GET /v1/intakes/:id` bundle (no `items`/`progress`/`owner_tasks`) — reflecting the new `archived` status. This is the reversible counterpart to `DELETE /v1/intakes/:id` below, which is permanent — there is currently no "unarchive". --- ### GET /v1/intakes/:id/download/preflight Reports what a ZIP download (below) would contain, without generating it — the byte count, whether it exceeds the size limit, and how many secrets are available to include. See [Download Everything as a ZIP](./zip.md) for the ZIP's contents and the secrets tradeoff. **Response** ```json { "files": 6, "bytes": 18420531, "skipped_files": 1, "secrets": { "total": 2, "unrevealed": 1, "already_revealed": 1 }, "too_large": false, "max_bytes": 524288000, "filename": "podklady-bella-napoli-website-in_8f3kQmR2.zip" } ``` `skipped_files` counts uploads still pending the antivirus scan — left out of the ZIP and listed by name in `podklady.pdf`/`podklady.md` instead. `secrets.unrevealed` is how many secret items would still be available for a one-time reveal if left out of the download; `secrets.already_revealed` were shown earlier and always render as `already revealed on ` regardless of `include_secrets`. `too_large` mirrors the `413` the download call below would return. --- ### GET /v1/intakes/:id/download Downloads every submitted item as one ZIP: `podklady.pdf` and `podklady.md` (the same content — one for reading, one for machines) covering every item's label, type, status, submitted value, decisions, and waiver reasons, plus one subfolder per item that has files, holding the client's uploads exactly as submitted. **Query parameters** | Parameter | Type | Description | |---|---|---| | `include_secrets` | boolean | Reveal and include secret item values in `podklady.pdf`. Default `false`. Never affects `podklady.md`, which never carries secret values. | Accepts a dashboard session or an API key with the `intakes:read` scope (or `admin`), same as reading the intake. `include_secrets=true` additionally requires the account **owner's** own session, or a key with `secrets:read`/`admin`; any other caller gets `403 forbidden`, reason `secrets_owner_only`. Including secrets consumes each unrevealed one's one-time reveal, exactly like [GET /v1/intakes/:id/results](#get-v1intakesidresults) or [POST /v1/intakes/:id/items/:key/reveal](#post-v1intakesiditemskeyreveal) — see [Secrets vault](./secrets.md). A secret already revealed earlier renders as `already revealed on ` instead of its value either way. Returns `application/zip` with `Content-Disposition: attachment; filename="podklady--.zip"`. Refused with `413 download_too_large` above the size limit reported by the preflight endpoint's `max_bytes`. Logged as an `intake.downloaded` audit event. --- ### DELETE /v1/intakes/:id Permanently delete an intake and all associated uploaded files. This action is irreversible. Returns HTTP 204 on success. --- ## Clients The address book of people this account has sent intakes to. There is no clients table — it's a view over [intakes](#intakes), grouped case-insensitively by email, so it already knows about every client from before this endpoint existed and can never drift from what was really sent. The price of that is the same as any view: a mistyped address becomes its own entry, and disappears only when the intakes carrying it are deleted. ``` GET /v1/clients List clients derived from past intakes ``` ### GET /v1/clients List clients, most active first. **Query parameters** | Parameter | Description | |---|---| | `q` | Case-insensitive substring search across the client's name and email (1–100 chars). | | `limit` | Results per page (default 20, max 100). | | `offset` | Pagination offset (default 0). | **Response** ```json { "clients": [ { "email": "jan@firma.cz", "name": "Jan Novák", "language": "cs", "phone": null, "timezone": "Europe/Prague", "folder_id": "fld_a1b2c3", "last_intake_id": "int_x9y8z7", "last_intake_at": "2026-09-18T10:00:00.000Z", "intake_count": 3 } ], "total": 1, "limit": 20, "offset": 0 } ``` `name`, `phone` and `folder_id` can be `null` when the most recent intake never set them. `name`, `language`, `phone`, `timezone` and `folder_id` come from that client's **most recent** intake; `intake_count` and `last_intake_at`/`last_intake_id` are computed over all of that client's intakes. Results are ordered by `intake_count` descending, then `last_intake_at` descending. > **Note:** Accepts a dashboard session or an API key with the `intakes:read` scope, same as [GET /v1/intakes](#get-v1intakes) — an API key sees only clients from intakes in its own mode (test/live). --- ## Folders A single level of organisation for intakes, shared by everyone on the account — not per-user, and not visible to the client: the portal never learns an intake has a folder. Use `folder_id` on [POST /v1/intakes](#post-v1intakes) and [PATCH /v1/intakes/:id](#patch-v1intakesid) to file an intake, and `folder_id`/`q` on [GET /v1/intakes](#get-v1intakes) to filter or search the list. ``` GET /v1/folders List all folders POST /v1/folders Create a folder PATCH /v1/folders/:id Rename or reorder a folder DELETE /v1/folders/:id Delete a folder ``` ### GET /v1/folders List every folder on the account, ordered by `sort_order` then `name`. **Response** ```json { "folders": [ { "id": "fld_9k2mQxR7", "name": "Website projects", "sort_order": 0, "intake_count": 4, "created_at": "2024-03-01T09:00:00Z" }, { "id": "fld_2wq8LpN3", "name": "Archived clients", "sort_order": 1, "intake_count": 0, "created_at": "2024-03-10T14:30:00Z" } ] } ``` `intake_count` counts intakes currently filed there that still exist and are not part of a deleted account. --- ### POST /v1/folders Create a new folder. **Request** ```json { "name": "Website projects" } ``` `name` is trimmed and 1–80 characters. Folder names are unique per account, case-insensitively — a duplicate returns `409 conflict` (reason `folder_exists`). **Response** (HTTP 201) is the folder object, the same shape as one entry in `GET /v1/folders`. --- ### PATCH /v1/folders/:id Rename a folder, change its `sort_order`, or both. Every field is optional, but at least one is required (`400 invalid_request` otherwise). ```json { "name": "Website projects 2024" } ``` Renaming to a name already used by another folder on the account returns `409 conflict` (reason `folder_exists`). **Response** is the updated folder object. --- ### DELETE /v1/folders/:id Delete a folder. Every intake filed in it moves to Unfiled (`folder_id` becomes `null`) — the intakes themselves, and their files, are untouched. Returns HTTP 204 on success. --- ## Templates Save an intake definition as a reusable template to avoid re-specifying items — and every other create-intake setting — for recurring project types. See [templates.md](./templates.md) for the full field reference and the settings-as-defaults rule. ``` GET /v1/templates List all templates POST /v1/templates Create a template from an item definition array, plus optional settings ``` **Create a template** `POST /v1/templates` requires a logged-in dashboard **session**, not an API key — there is currently no way to create a template as an agent. `name` and `items` are required; `description`, `language`, and `settings` are optional. ```bash curl -X POST https://api.briefgate.dev/v1/templates \ -H "Cookie: bg_session=..." \ -H "Content-Type: application/json" \ -d '{ "name": "Restaurant Website", "items": [...], "settings": { "chase_schedule": "custom", "chase_interval": 5, "chase_interval_unit": "days", "due_in_days": 14 } }' ``` Use the template slug in `define_intake` (or `POST /v1/intakes`) with `"template": "web-restaurant"` instead of specifying `items` manually — `items` is still required in the request even then (see the known gap noted in [templates.md](./templates.md)). Any setting the template carries applies as a default: it fills in only the fields the create-intake request itself leaves unset, and `due_in_days` becomes a real `due_date` at creation time. --- ## Webhooks BriefGate fires webhooks on intake state changes. Every payload carries `event`, `intake_id` and `timestamp`, plus the fields belonging to that event. Every route below needs the `admin` scope on an API key (an endpoint receives every event on the whole account) — `intakes:read`/`intakes:write` are not enough. A dashboard session may read the roster, but only the account **owner** may register, remove, test or retry (`403 forbidden` for any other member). ``` GET /v1/webhooks List configured endpoints POST /v1/webhooks Register a new endpoint DELETE /v1/webhooks/:id Remove an endpoint GET /v1/webhooks/:id/deliveries Delivery history (last 100 attempts) POST /v1/webhooks/:id/test Send a test event to the endpoint POST /v1/webhooks/:id/deliveries/:deliveryId/retry Retry one delivery by hand ``` **Register a webhook** ```bash curl -X POST https://api.briefgate.dev/v1/webhooks \ -H "Authorization: Bearer bg_live_xxxxx" \ -H "Content-Type: application/json" \ -d '{ "url": "https://yourapp.com/webhooks/briefgate", "events": ["intake.completed", "item.submitted"] }' ``` The signing secret is generated by BriefGate and returned once in the response — you do not supply it. Add `"format": "slack"` or `"format": "discord"` to deliver into a chat channel instead of your own server. BriefGate signs each webhook request with an HMAC-SHA256 signature in the `X-BriefGate-Signature` header. Verify it using your `secret` before processing the payload. **Events** | Event | Fired when | |---|---| | `item.submitted` | Client uploaded or filled in an item. | | `intake.completed` | All required items have been submitted. | | `client.viewed` | Client opened their portal. | | `chase.bounced` | A reminder hard-bounced or was reported as spam. | | `intake.stalled` | The intake used up its reminder allowance without being completed. | | `intake.overdue` | The due date passed with required items still outstanding (fires once per intake). | | `intake.archived` | The intake was archived via `POST /v1/intakes/:id/archive`. | These seven are the only accepted values; anything else is rejected when you register the endpoint. See [webhooks.md](./webhooks.md) for the payloads. **Retry a delivery** If an endpoint didn't return 2xx, BriefGate already retried it on the automatic schedule (immediate, then +1m, +5m, +30m, +2h, +6h — 6 attempts total) before marking it `failed`. This re-queues that same delivery by hand, through the same path as any other send — SSRF re-check, a freshly computed signature, logged like any other attempt. It does not reset `attempts`: a delivery that already used all 6 keeps climbing from there, so this buys exactly one more try, not a fresh ladder — fix the endpoint first if you want more than that. ```bash curl -X POST https://api.briefgate.dev/v1/webhooks/whe_2f9k/deliveries/whd_9f8e7d6c5b4a/retry \ -H "Authorization: Bearer bg_live_xxxxx" ``` ```json { "delivery": { "id": "whd_9f8e7d6c5b4a", "event": "intake.completed", "status": "pending", "attempts": 6, "response_code": 500, "error": null, "next_retry_at": "2026-07-18T09:12:00Z", "created_at": "2026-07-18T09:11:00Z", "delivered_at": null } } ``` `404 not_found` if the endpoint or the delivery doesn't exist on this account. `409 conflict` (reason `already_delivered`) if that delivery already succeeded — sending it again would duplicate the event downstream. `409 conflict` (reason `endpoint_inactive`) if the endpoint has since been switched off — turn it back on first. --- ## Account and billing ``` GET /v1/account Account info and current tier PATCH /v1/account Update account settings (name, branding, default language, retention_days, portal_link_ttl_days, etc.) POST /v1/account/logo Upload the logo shown in the portal and e-mails (multipart `file`; dashboard session only) DELETE /v1/account/logo Remove the logo POST /v1/account/signature Upload the e-mail signature image (business card) rendered at the bottom of every e-mail your clients get (multipart `file`, PNG/JPEG/WebP; dashboard session only) DELETE /v1/account/signature Remove the signature image GET /v1/usage Current period usage against plan limits GET /v1/audit Paginated audit log of API and user actions (session only, account owner only) POST /v1/billing/checkout Create a Stripe Checkout session to upgrade POST /v1/billing/portal Create a Stripe Customer Portal session to manage subscription ``` **Branding fields on `PATCH /v1/account`:** `brand_logo_url` (a pasted URL — `POST /v1/account/logo` is the upload path), `brand_accent_color` (hex), `brand_sender_name`, and `email_copy` (same shape as on `define_intake`, see [chase.md](./chase.md#writing-your-own-subject-and-intro)) are all part of [custom branding](./billing.md#custom-branding). Setting any of them to a new, non-null value on a Free account is refused with `402 plan_required` (reason `custom_branding`, `message`: "Custom branding (sender name, email wording, logo and accent colour) requires the Solo plan or higher; this account is on free."); clearing one back to `null` is always allowed on any plan, since removing branding never needs one. `brand_sender_name` is rejected with `422` (same `NO_LINKS` message as the per-intake `branding.sender_name`) if it contains a link. **Usage response** ```json { "period": "2024-03", "intakes": { "used": 12, "limit": 50 }, "storage_bytes": { "used": 524288000, "limit": 5368709120 } } ``` **Team seats.** A seat is a person who signs in to the dashboard — clients never take one, since they only ever open the link they were emailed. Every route below is **dashboard session only**; no API key can call any of them, not even one with the `admin` scope — except accepting an invite, which instead proves itself with the invite token and needs no session at all. Any signed-in member may read the roster; inviting, cancelling an invite, and removing a member are **owner-only** (`403 forbidden` for anyone else). ``` GET /v1/team List members and pending invites POST /v1/team/invites Invite an email into a seat (owner-only) DELETE /v1/team/invites/:id Cancel a pending invite (owner-only) POST /v1/team/invites/accept Accept an invite — no session; the token is the proof DELETE /v1/team/members/:id Remove a member (owner-only) ``` ### GET /v1/team Lists current members plus invites that are still pending and unexpired. **Response** ```json { "members": [ { "id": "usr_9f3kqmr2", "email": "marco@bellanapoli.com", "name": "Marco Esposito", "role": "owner", "created_at": "2026-01-10T09:00:00Z", "last_login_at": "2026-09-04T08:12:00Z" } ], "invites": [ { "id": "tin_7h2jvw4x", "email": "giulia@bellanapoli.com", "role": "member", "created_at": "2026-09-01T10:00:00Z", "expires_at": "2026-09-08T10:00:00Z" } ] } ``` --- ### POST /v1/team/invites Invites an email address into a purchased seat. Every invite grants the `member` role — there's no flow for inviting a second owner. **Request body** | Field | Type | Required | Description | |---|---|---|---| | `email` | string | Yes | Address to invite. Lowercased; max 320 characters. | **Response** (HTTP 201) ```json { "id": "tin_7h2jvw4x", "email": "giulia@bellanapoli.com", "role": "member", "created_at": "2026-09-05T10:00:00Z", "expires_at": "2026-09-12T10:00:00Z" } ``` The invite is emailed with a link valid for 7 days. Inviting the same address again replaces the earlier invite — only the newest link ever works. `402 quota_exceeded` (reason `seats`) once members plus pending invites already fill the plan's seat count — cancel a pending invite, remove a member, or buy an extra seat. `400 invalid_request` if that address already belongs to a member on this account. `429 rate_limited` (reason `team_invites`) past 20 invitations per account per hour. --- ### DELETE /v1/team/invites/:id Cancels a pending invite. `404 not_found` if it doesn't exist on this account. `400 invalid_request` if it was already accepted — there's nothing left to cancel. Returns `{ "ok": true, "id": "tin_7h2jvw4x" }`. --- ### POST /v1/team/invites/accept No authentication — the invite token is the proof, the same way a password-reset link works. Creates the `member` user, signs them in, and sets the session cookie. **Request body** | Field | Type | Required | Description | |---|---|---|---| | `token` | string | Yes | The token from the invite email's link. | | `name` | string | Yes | The new member's display name. | | `password` | string | Yes | At least 12 characters. | **Response** (HTTP 201) ```json { "user": { "id": "usr_2k9fjbrt", "email": "giulia@bellanapoli.com", "name": "Giulia", "role": "member" }, "account": { "id": "acc_8j3nq2mv", "name": "Bella Napoli", "tier": "agency" } } ``` `401 unauthorized` ("That invitation link is not valid or has expired.") for a token that's unknown, already accepted, or expired — deliberately one answer for all three, same as password reset. `400 invalid_request` ("An account with this email already exists.") if the invited address already has a user elsewhere. `402 quota_exceeded` (reason `seats`) if the seat filled up between the invite being sent and accepted — the quota is re-checked here, not just when the invite was created. --- ### DELETE /v1/team/members/:id Removes a member: soft-deletes the user and ends every one of their sessions immediately. `400 invalid_request` if `:id` is your own user id ("You cannot remove your own account this way.") or names the account owner ("The account owner cannot be removed."). `404 not_found` if it doesn't match an existing member on this account. Returns `{ "ok": true, "id": "usr_2k9fjbrt" }`. --- ## Public endpoints These endpoints require no authentication and are designed for programmatic consumption. | Endpoint | Description | |---|---| | `GET /pricing.json` | Machine-readable pricing tiers, limits, and feature flags. Intended for agents to decide which plan to recommend or to check quota before creating intakes. | | `GET /v1/openapi.json` | OpenAPI 3.1 specification for the entire API. Import into Postman, generate an SDK, or pass to an agent for full API introspection. | | `GET /healthz` | Liveness probe. Returns HTTP 200 with `{"status":"ok"}` when the API process is running. | | `GET /readyz` | Readiness probe. Returns HTTP 200 only when the API process and all downstream dependencies (database, object storage, email provider) are healthy. Returns HTTP 503 during deployments or outages. | --- ## BriefGate for n8n URL: https://briefgate.dev/docs/n8n # BriefGate for n8n `n8n-nodes-briefgate` is a community node for [n8n](https://n8n.io/) that wraps BriefGate's client intake — create an intake, chase-and-wait, and read typed results — as workflow nodes, an AI Agent tool, and a trigger for BriefGate's webhook events. It is a **verified** n8n community node: on n8n Cloud you add it straight from the canvas, and on self-hosted n8n you can install it the same way or by package name — see [Installation](#installation) below. --- ## Installation ### Installing on n8n Cloud 1. Make sure **Verified Community Nodes** is enabled in your instance's Admin Panel (the owner or an admin can switch it on). 2. On the workflow canvas, open the nodes panel, search for **BriefGate**, and drag the node into your workflow. If the node doesn't show up in search yet, restart the instance from the Admin Panel — n8n Cloud picks up newly verified nodes on restart. ### Installing on self-hosted n8n Verified nodes also appear in the canvas search on self-hosted n8n, as long as verified community nodes are enabled on your instance. You can install by package name instead: 1. Go to **Settings → Community Nodes**. 2. Select **Install**. 3. Enter `n8n-nodes-briefgate`. 4. Agree to the risk notice (n8n shows it for any package installed by name) and select **Install**. Or from the command line, if you manage your n8n instance's dependencies directly: ```bash npm install n8n-nodes-briefgate ``` Both nodes and the credential type appear after n8n restarts (Docker/npm installs) or immediately (the Community Nodes panel installs without a restart). **Self-hosted and data residency.** Running n8n yourself already keeps your workflow logic and credentials on infrastructure you control. BriefGate's hosted API pairs with that: per its [GDPR documentation](./gdpr.md), all data is processed exclusively in the EU — application hosting in Germany, file storage in Cloudflare R2 under the EU jurisdiction restriction. Worth knowing if residency is part of why you self-host n8n; it isn't a reason to pick BriefGate on its own. --- ## Credential: BriefGate API Both nodes authenticate with a BriefGate **API key**. 1. In the BriefGate dashboard, open **API Keys** and create one. Use a `bg_test_…` key while you build the workflow — it behaves normally but never emails or texts a real client; switch to `bg_live_…` when you're ready to go live. 2. In n8n, create a new **BriefGate API** credential and paste the key into **API Key**. Leave **Base URL** at `https://api.briefgate.dev` unless you're pointed at a staging or self-hosted BriefGate deployment. 3. The **BriefGate Trigger** node specifically needs a key with the **`admin`** scope — registering a webhook subscribes to events across the whole account, so `intakes:read`/`intakes:write` aren't enough. See [API key scopes](./rest-api.md#authentication). --- ## Operations (BriefGate node) The **BriefGate** node has one **Operation** field with five choices: | Operation | What it does | Key fields | |---|---|---| | **Create Intake** | Starts a new intake and emails the client their portal link | Project Name, Client Email, Client Name, Items (fixed fields or raw JSON), Additional Fields (chase schedule, due date, retention, folder, idempotency key…) | | **Get Many** | Lists intakes with optional filters | Filters: Status, Client Email, Folder ID, Search; Return All / Limit | | **Get Results** | Typed values for approved (optionally also submitted-but-unapproved) items | Intake ID; Options: Only New, Include Pending | | **Get Status** | Item statuses, chase history and progress for one intake | Intake ID | | **Send Reminder** | Manually triggers a chase message outside the automatic schedule | Intake ID, Channel (Email/SMS) | ### Example — Create Intake Items can be built with the **Items** fixed-collection field (Key, Label, Type, Required, Assignee, Help Text, and an optional Advanced (JSON) field for constraints/options/schema), or switch **Specify Items** to **Using JSON** and paste an array directly: ```json [ { "key": "logo", "label": "Company logo", "type": "image", "required": true }, { "key": "colors", "label": "Brand colors", "type": "color_list", "required": false } ] ``` Set **Project Name** to `Bella Napoli — Website`, **Client Email**/**Client Name** to the client's details, and under **Additional Fields** set **Chase Schedule** to `Default` and **Due Date** to `2026-12-01`. Running the node emails the client their portal link and returns the created intake, including its `id` — pass that downstream as `intakeId` for Get Status / Get Results / Send Reminder. ### Example — Get Results Set **Intake ID** to `{{$json.id}}` (from an earlier Create Intake or Trigger node) and, under **Options**, enable **Include Pending** if you want submitted-but-not-yet-approved items in the response too. The node returns typed values per item key, signed file URLs for file/image items, and a `missing` array naming anything still outstanding. ### Example — Get Many Leave **Filters** empty to list every intake, or set **Status** to `In Progress` and **Search** to a client name to narrow it down. Turn on **Return All** to page through every match instead of stopping at **Limit**. --- ## Using BriefGate as an AI Agent tool The BriefGate node is usable as a tool: connect it to the **Tool** input of an **AI Agent** node the same way you'd attach any other n8n tool node. The agent sees it as **BriefGate** with all five operations available, and decides for itself — from its system prompt and the conversation — when to call `Create Intake`, check `Get Status`, or pull `Get Results`. This is the same use case BriefGate's [MCP server](./mcp.md) covers for Claude Code and other MCP clients, just wired through n8n's own Agent instead. A typical setup: an AI Agent node with a chat trigger, the BriefGate node attached as a tool (with a BriefGate API credential), and a system prompt telling the agent when a task is blocked on something only a human client can provide (see [BriefGate's own guidance on this](./mcp.md#when-should-an-agent-use-briefgate) — the same reasoning applies whether the agent runs in n8n or in an MCP client). --- ## BriefGate Trigger — webhook events The **BriefGate Trigger** node starts your workflow when one of these events fires on your account: - `intake.completed` — every required item has been submitted - `item.submitted` — the client submitted or filled in one item - `client.viewed` — the client opened their portal - `chase.bounced` — a reminder hard-bounced or was reported as spam - `intake.stalled` — the intake used up its reminder allowance - `intake.overdue` — the due date passed with required items outstanding Pick one or more in the **Events** field (multi-select). Activating the workflow registers a webhook endpoint on your BriefGate account pointing at n8n's webhook URL; deactivating the workflow removes it again — there's nothing to clean up by hand on either side. Every delivery is verified against BriefGate's `X-BriefGate-Signature` header (HMAC-SHA256, 5-minute replay window) before your workflow sees it. See [webhooks.md](./webhooks.md) for the full payload shape of each event. --- ## Example workflows **New client, one click.** A form (Typeform, or an n8n Form trigger), a CRM webhook (deal marked won), or a plain **Webhook** node feeds **BriefGate: Create Intake** the project name, client email, and client name, plus the items your team always asks for at kickoff — `logo` (Image), `hero_copy` (Long Text), `wp_admin` (Secret), for example. Running the node emails the client their portal link immediately and returns the intake's `id`, which every workflow below needs as `intakeId`. If the trigger is a webhook, set **Additional Fields → Idempotency Key** to something stable from the source event (a CRM deal ID, say): CRMs and form providers retry deliveries, and without one a retried webhook creates a second intake for the same client — reusing the same key returns the original intake instead. **Files land in your own storage automatically.** **BriefGate Trigger** (`Intake Completed`) → **BriefGate: Get Results** → one node per file. *Get Results* returns typed values keyed by item: a file or image item comes back as `{ url, filename, mime, size, checksum_sha256 }` with a 24-hour signed URL, and a text item as the plain value — reference the keys you defined yourself (`results.logo.url`, `results.hero_copy`) rather than looping over an unknown shape. Feed a file's signed URL into an **HTTP Request** node set to return binary data, then write it with **Write Binary File**, a **Google Drive** node, or an S3/MinIO node. A `secret` item (an admin login, an API key) needs an API key with the `secrets:read` or `admin` scope to read, and its value comes back exactly once — store it the moment this workflow runs, since every call after that reports `secret_unavailable: true` instead. Keep this workflow instant rather than batching it: the signed URL only lasts 24 hours. **Ask who still owes you something.** Two ways to get this, depending on whether you want it pushed to you or pulled on demand. Pushed: a **Schedule Trigger** (e.g. weekdays at 08:00) → **Get Many** (Status: `In Progress`, Return All: on) → loop with **Get Status** on each → a **Filter** keeping `progress.outstanding > 0` → post the list to Slack or email. *Get Status* is the lightweight endpoint for this step — item statuses, chase history, and an outstanding count, without pulling file content, which is what makes calling it once per intake on a schedule reasonable rather than expensive. Pulled: wire the **BriefGate** node into an **AI Agent** node's Tool input (see [above](#using-briefgate-as-an-ai-agent-tool)) and just ask it — "which clients still owe me materials?" — and let the agent call `Get Many` and `Get Status` itself. **An overdue intake gets a deliberate nudge.** `intake.overdue` fires once, the first time a periodic sweep notices an intake passed its due date with a required item still outstanding — independent of the automatic reminder schedule, and meant to tell *you*, not the client. **BriefGate Trigger** (`Intake Overdue`) → **BriefGate: Send Reminder** (Channel: `Email` or `SMS`, the latter needing the `sms` feature and a positive credit balance) turns that into an actual message going out. `intake.stalled` pairs with the same pattern — it fires once the reminder allowance is exhausted and the chase engine has cancelled the rest, handing the intake back to you — so add it alongside `Intake Overdue` in the trigger's **Events** field to escalate there too. Every event payload above carries `intake_id`, and every one except `chase.bounced` also carries `project_name` — none carries the client's own email address, deliberately, since a workflow's execution log has a wider audience than the intake itself. `chase.bounced` is the exception, since its whole point is naming which `recipient` address failed. For anything else about the client, call *Get Status* or *Get Results* rather than expecting the trigger payload to carry it. Full field lists for all six events are in [webhooks.md](./webhooks.md). Five ready-to-import templates built on these ideas are on [GitHub](https://github.com/sekera-radim/n8n-nodes-briefgate/tree/main/templates). --- ## Resources - [npm: n8n-nodes-briefgate](https://www.npmjs.com/package/n8n-nodes-briefgate) - [GitHub: sekera-radim/n8n-nodes-briefgate](https://github.com/sekera-radim/n8n-nodes-briefgate) (source, README, workflow templates) - [n8n community nodes documentation](https://docs.n8n.io/integrations/community-nodes/) - [BriefGate REST API reference](./rest-api.md) - [BriefGate webhooks reference](./webhooks.md) - [Item types and their constraints](./item-types.md) - [How the automatic reminders work](./chase.md) - [BriefGate MCP tools](./mcp.md) — the equivalent integration for MCP-capable AI assistants (Claude Code, Cursor, etc.) --- ## BriefGate for Zapier URL: https://briefgate.dev/docs/zapier # BriefGate for Zapier The BriefGate Zapier integration connects client intake to the apps you already run on Zapier — start an intake when a deal closes in your CRM, send the finished files to Google Drive, post in Slack when a client opens their portal. It is a **private beta**: the integration is not listed in Zapier's app directory yet. Anyone can use it today through the invite link below; it becomes public once it passes Zapier's review. **[Join the BriefGate Zapier beta →](https://zapier.com/developer/public-invite/246461/bf6cf6f634d011065659aba77f0ab803/)** --- ## Connecting your account 1. Open the invite link above while signed in to Zapier and accept the invitation. BriefGate then shows up in the app picker of the Zap editor. 2. In the BriefGate dashboard, open **API Keys** and create a key. - Actions and searches need the `intakes:read` and `intakes:write` scopes. - The triggers need the **`admin`** scope, because a trigger registers a webhook on your account. See [API key scopes](./rest-api.md#authentication). - A `bg_test_…` key never emails or texts a real client, so it is the safest choice while you build a Zap. Switch to a `bg_live_…` key when the Zap goes live. 3. In Zapier, add a BriefGate step, choose **Sign in**, and paste the key. Scopes are set per key, so one key per Zap is fine but not required — add a second, narrower key with just `intakes:read` and `intakes:write` if you want an actions-only Zap to run on something less powerful than an `admin`-scoped one. --- ## Triggers All four triggers are instant: turning the Zap on registers a webhook on your BriefGate account, and turning it off removes it again. Every delivery is checked against BriefGate's `X-BriefGate-Signature` header before the Zap runs. Payloads are described in [webhooks](./webhooks.md). | Trigger | Fires when | |---|---| | **Intake Completed** | Every required item on an intake has been submitted. | | **Item Submitted** | The client submits or fills in one item. | | **Client Viewed Portal** | The client opens their portal for the first time. Refreshing the page does not fire it again. | | **Intake Overdue** | The due date passes with required items still outstanding. Fires once per intake. | ## Actions | Action | What it does | |---|---| | **Create Intake** | Starts a new intake and emails the client their portal link. Set **Send Immediately** to false to keep it as a draft. | | **Send Reminder** | Sends a chase message outside the automatic schedule, by email or SMS (SMS needs the SMS feature and credit). Limited to one manual reminder per intake per hour; fails with "Nothing to chase" when the intake is already completed. | ## Searches | Search | What it returns | |---|---| | **Find Intake** | One intake by ID: status, due date, progress, item statuses and chase history. | | **Get Intake Results** | Typed values for approved items (optionally also submitted ones), signed file URLs, and the list of items still missing. | **Secrets are never returned to Zapier.** Zapier keeps every step's output in your Zap history, and a `secret` item (a password or API key the client entered) can be revealed only once. Get Intake Results therefore always sends `exclude_secrets=true`: secret items are left out without being revealed, with `meta` reporting `secret_unavailable: true`, and you read them in the BriefGate dashboard instead — where the one-time reveal is spent deliberately, not logged into a Zap run you can't un-log. The value itself is encrypted on the server with a libsodium sealed box before it's ever written to the database, so it's never plaintext, and never "end-to-end" or "zero-knowledge" — BriefGate itself holds the decryption key. --- ## Example Zaps ### Deal won → intake sent Trigger: your CRM (Pipedrive, HubSpot, Copper, …) on Deal Won / Stage Changed → Action: BriefGate **Create Intake**. Map **Project Name**, **Client Email**, and **Client Name** from the deal, and **Items** from the set you always ask for at kickoff — each item takes a Key, Label, Type (`text`, `longtext`, `file`, `image`, `file_list`, `url`, `boolean`, `select`, `multiselect`, `color_list`, `structured`, or `secret`), and whether it's Required. Set **Due Date** from the deal's close date plus your standard turnaround, and **Chase Schedule** to `default` (Free plan) or `gentle`/`aggressive` on Solo and up. Set **Send Immediately** to false if you'd rather review the intake before it emails the client — it's created as a draft, and you send it later from the dashboard; Create Intake and Send Reminder are the only two actions today. A few Free-plan limits worth knowing before testing this: Create Intake fails once you already have an active intake, and an intake with more than ten items is rejected — both show up as a `plan_required` or validation error in the Zap's run history. Free also sends at most 10 invitations per UTC day: a Create Intake run past that still succeeds, but the intake is left as an unsent draft and the response says so (`invitation_sent: false`, with a `note`). ### Completed intake → files in Drive Trigger: BriefGate **Intake Completed** (carries `intake_id`, `project_name`, `timestamp` — no file content yet, just the signal to collect) → Search: BriefGate **Get Intake Results** → Action: Google Drive **Upload File**. A single **file** or **image** item comes back from Get Intake Results as one object with a signed `url` (valid 24 hours), `filename`, `mime`, `size`, and `checksum_sha256` — map its Url field straight into the Drive step's File field and Zapier downloads it automatically before uploading. A **file_list** item comes back as an array of the same shape, so one Drive step can't consume it directly: insert **Looping by Zapier** between the search and the Drive step and put the upload inside the loop, one iteration per file. Because the signed URL only lasts 24 hours, keep this Zap instant rather than adding a Delay step in front of the upload. ### Client opened the portal → heads-up in Slack Trigger: BriefGate **Client Viewed Portal** → Action: Slack **Send Channel Message**. Fires once, the first time the client opens their link — refreshing the page doesn't fire it again — with `intake_id`, `project_name`, and `slug`. It deliberately carries neither the portal link nor the client's email, so a simple message template is `{{project_name}} — client just opened their intake portal ({{intake_id}})`. Chain in a **Find Intake** search on the same `intake_id` first if the team wants progress or a due date in the message too. ### Overdue intake → one more nudge Trigger: BriefGate **Intake Overdue** → Action: BriefGate **Send Reminder**. Fires once per intake, the first time a periodic sweep notices the due date has passed with required items still outstanding — it carries `intake_id`, `project_name`, `due_date`, and `outstanding_items`, independent of the automatic reminder schedule and meant to tell *you*, not the client. Map Send Reminder's Intake field from the trigger's `intake_id` and choose Email (default) or SMS (needs the SMS feature and credit). It's capped at one manual reminder per intake per hour and returns "Nothing to chase" if the intake was already completed by the time the Zap runs — worth a Filter step if you chain more steps after it. A caution that applies to all four Zaps: Create Intake's response includes `portal_url`, but the magic sign-in token that actually authenticates the client is never returned by the API — it only ever goes out in the invitation email. Don't build a step that tries to construct a working client link from `portal_url` alone; there isn't one to construct. --- ## Resources - [Join the Zapier beta](https://zapier.com/developer/public-invite/246461/bf6cf6f634d011065659aba77f0ab803/) - [BriefGate REST API reference](./rest-api.md) - [BriefGate webhooks reference](./webhooks.md) - [BriefGate for n8n](./n8n.md), the same building blocks for self-hosted workflow automation --- ## Item Types URL: https://briefgate.dev/docs/item-types # Item Types BriefGate items are typed. The agent declares what it needs; the client portal validates input in real time; `get_intake_results` returns data the agent can use directly without further parsing or type coercion. Each item definition requires at minimum a `key` (unique within the intake), a `label` (shown to the client), and a `type`. Most types accept optional `constraints` that the portal enforces before the client can submit. ## Who owes the item: `assignee` Every item also has an `assignee`, which defaults to `"client"` — the thing the intake was created to collect. Set `"assignee": "owner"` to put one of *your own* to-dos on the intake instead: "call the client", "register the domain", "book the photographer". An owner item - never appears in the client portal, - is never mentioned in a reminder, - never counts toward the progress the client is shown, - and never holds the intake open — the intake completes when the *client* is done. You tick it off in the dashboard, or with `POST /v1/intakes/:id/items/:key/done`. Use `type: "boolean"` for a plain tick-off task. Because an owner item never reaches the portal, it cannot use the types that are submitted there: `file`, `file_list`, `image` and `secret` are rejected with `assignee: "owner"`. ```json { "key": "call_client", "label": "Call the client about the launch date", "type": "boolean", "assignee": "owner" } ``` --- ### text A single-line text input. Use for short, structured strings such as tracking IDs, account names, or codes. **Constraints** (inside `constraints` object) | Field | Type | Description | |---|---|---| | `min_chars` | integer | Minimum character count. | | `max_chars` | integer | Maximum character count. Defaults to 2000 if not set. | **Top-level item fields** | Field | Type | Description | |---|---|---| | `pattern` | string | ECMAScript regular expression the value must match. Placed directly on the item definition, not inside `constraints`. | **Example — Google Analytics tracking ID** ```json { "key": "ga4_id", "label": "Google Analytics 4 Measurement ID", "help": "Found in GA4 > Admin > Data Streams. Format: G-XXXXXXXXXX", "type": "text", "required": true, "pattern": "^G-[A-Z0-9]+" } ``` **Returned by `get_intake_results`** ```json "ga4_id": "G-K4M9X3R2B1" ``` --- ### longtext A multi-paragraph textarea. Use for copy blocks, bios, mission statements, and any text where the client needs room to write. **Constraints** | Field | Type | Description | |---|---|---| | `min_chars` | integer | Minimum character count. | | `max_chars` | integer | Maximum character count. Defaults to 20000 if not set. | **Example — hero section copy** ```json { "key": "hero_copy", "label": "Homepage hero text", "help": "A short paragraph (up to 400 characters) that captures the spirit of the restaurant. Appears above the fold.", "type": "longtext", "required": true, "constraints": { "max_chars": 400 } } ``` **Returned by `get_intake_results`** ```json "hero_copy": "Since 1987, handcrafted Neapolitan pizza in the heart of the city. Come hungry, leave happy." ``` --- ### file A single file upload. Use for documents, PDFs, spreadsheets, fonts, or any non-image binary. **Constraints** | Field | Type | Description | |---|---|---| | `formats` | string[] | Allowed file extensions without the leading dot, e.g. `["pdf","docx"]`. Case-insensitive. | | `max_bytes` | integer | Maximum file size in bytes. Default is 52,428,800 (50 MB). | **Example — signed contract** ```json { "key": "signed_contract", "label": "Signed project contract", "help": "Upload the signed PDF you received by email.", "type": "file", "required": true, "constraints": { "formats": ["pdf"], "max_bytes": 10485760 } } ``` **Returned by `get_intake_results`** ```json "signed_contract": { "filename": "bella-napoli-contract-signed.pdf", "url": "https://files.briefgate.dev/in_8f3kQmR2/signed_contract.pdf?token=sig_abc&expires=1710615600", "mime": "application/pdf", "size": 283492, "checksum_sha256": "a3f2e1..." } ``` The `url` is a signed URL valid for 24 hours. Fetch the file promptly or call `get_intake_results` again to obtain a fresh URL. --- ### file_list Multiple file uploads collected as a group. Use for photo galleries, asset packs, or any situation where you need several files of the same category. **Constraints** | Field | Type | Description | |---|---|---| | `formats` | string[] | Allowed file extensions. | | `max_bytes` | integer | Maximum size per individual file. | | `min_count` | integer | Minimum number of files required. | | `max_count` | integer | Maximum number of files accepted. | **Example — restaurant photos** ```json { "key": "photos", "label": "Food and interior photos", "help": "Upload between 5 and 15 photos of your food, interior, and ambience.", "type": "file_list", "required": true, "constraints": { "formats": ["jpg", "png", "heic"], "min_count": 5, "max_count": 15 } } ``` **Returned by `get_intake_results`** ```json "photos": [ { "filename": "interior-01.jpg", "url": "https://files.briefgate.dev/in_8f3kQmR2/photos/interior-01.jpg?token=...", "mime": "image/jpeg", "size": 3204812, "checksum_sha256": "b4c1d2..." }, { "filename": "pizza-margherita.jpg", "url": "https://files.briefgate.dev/in_8f3kQmR2/photos/pizza-margherita.jpg?token=...", "mime": "image/jpeg", "size": 2917034, "checksum_sha256": "f9e3a1..." } ] ``` --- ### image An image upload with optional dimension and format constraints. Use instead of `file` when you need to enforce resolution or require transparency. **Constraints** | Field | Type | Description | |---|---|---| | `formats` | string[] | Allowed file extensions, e.g. `["svg","png"]`. No default — if omitted, any image file is accepted. | | `min_width` | integer | Minimum image width in pixels. Ignored for `svg` uploads, which have no fixed pixel size. | | `max_width` | integer | Maximum image width in pixels. Ignored for `svg` uploads. | | `min_height` | integer | Minimum image height in pixels. Ignored for `svg` uploads. | | `max_height` | integer | Maximum image height in pixels. Ignored for `svg` uploads. | | `max_bytes` | integer | Maximum file size in bytes. Cannot exceed the account's upload size limit (default 52,428,800 / 50 MB) even if set higher. | | `transparent_background` | boolean | If `true`, the portal warns the client if the image has no alpha channel. | **Example — logo** ```json { "key": "logo", "label": "Company logo", "help": "SVG or PNG with a transparent background. Minimum 512px on the shortest side.", "type": "image", "required": true, "constraints": { "formats": ["svg", "png"], "min_width": 512, "transparent_background": true } } ``` **Returned by `get_intake_results`** ```json "logo": { "filename": "logo-transparent.png", "url": "https://files.briefgate.dev/in_8f3kQmR2/logo-transparent.png?token=...", "mime": "image/png", "width": 1024, "height": 512, "size": 48210 } ``` --- ### color_list A color picker that collects one or more hex color values. The portal provides a visual color picker with hex input. The portal always validates that values are valid hex codes; every other constraint is optional. **Constraints** (inside `constraints` object) | Field | Type | Description | |---|---|---| | `min_count` | integer | Minimum number of colors required. | | `max_count` | integer | Maximum number of colors accepted. Defaults to 12 if not set. | **Example — brand palette** ```json { "key": "brand_colors", "label": "Brand colors", "help": "Select your primary and secondary brand colors. Add as many as you use.", "type": "color_list", "required": true } ``` **Returned by `get_intake_results`** ```json "brand_colors": ["#1B2A4A", "#E8E2D9", "#C8382E"] ``` --- ### select A dropdown or radio group where the client picks exactly one option from a list you define. Useful when you need a constrained vocabulary. **Required fields** | Field | Type | Description | |---|---|---| | `options` | array | Array of `{value, label}` objects. `value` is what gets stored; `label` is what the client sees. | **Example — website platform** ```json { "key": "platform", "label": "Preferred website platform", "type": "select", "required": true, "options": [ { "value": "wordpress", "label": "WordPress" }, { "value": "webflow", "label": "Webflow" }, { "value": "shopify", "label": "Shopify" }, { "value": "custom", "label": "Custom / I'm not sure" } ] } ``` **Returned by `get_intake_results`** ```json "platform": "wordpress" ``` The result is always the `value` string, never the `label`. --- ### multiselect A checkbox group where the client picks any number of options from a list you define. Useful when the client may need to select more than one option, or none at all. **Required fields** | Field | Type | Description | |---|---|---| | `options` | array | Array of `{value, label}` objects. `value` is what gets stored; `label` is what the client sees. | **Constraints** (inside `constraints` object) | Field | Type | Description | |---|---|---| | `min_count` | integer | Minimum number of options that must be selected. | | `max_count` | integer | Maximum number of options that may be selected. | **Example — services needed** ```json { "key": "services_needed", "label": "Which services do you need?", "type": "multiselect", "required": true, "constraints": { "min_count": 1, "max_count": 3 }, "options": [ { "value": "design", "label": "Design" }, { "value": "copywriting","label": "Copywriting" }, { "value": "seo", "label": "SEO" }, { "value": "hosting", "label": "Hosting" } ] } ``` **Returned by `get_intake_results`** ```json "services_needed": ["design", "seo"] ``` The result is always an array of `value` strings, never the `label`, even when only one option is selected. --- ### boolean A yes/no toggle. The portal renders it as a pair of clearly labelled buttons or a checkbox, depending on the portal theme. **Example — existing website check** ```json { "key": "has_existing_site", "label": "Do you have an existing website?", "type": "boolean", "required": true } ``` **Returned by `get_intake_results`** ```json "has_existing_site": true ``` --- ### url A URL input with built-in http/https validation. Optionally constrain to a specific domain or path pattern. **Top-level item fields** | Field | Type | Description | |---|---|---| | `pattern` | string | ECMAScript regular expression the URL must match. Placed directly on the item definition, not inside `constraints`. Use to restrict to a specific domain. | **Example — existing website URL** ```json { "key": "existing_site_url", "label": "Existing website address", "help": "The full URL including https://", "type": "url", "required": false } ``` **Returned by `get_intake_results`** ```json "existing_site_url": "https://old.bellanapoli.com" ``` --- ### secret An encrypted credential input. The portal shows a password-style field with a lock icon and explicit messaging that the value is stored securely. The value travels over HTTPS and is sealed on the server with a libsodium sealed box before it is stored; it is never logged, indexed, or included in webhook payloads. Secrets auto-expire after 30 days and can be revealed only once — with a short grace window (below) for a caller that never got the response. **Example — CMS admin login** ```json { "key": "cms_credentials", "label": "WordPress admin credentials", "help": "Your current admin username and password. Stored encrypted and only accessible to your project team.", "type": "secret", "required": false } ``` **Returned by `get_intake_results`** On the **first** call, the decrypted plaintext is returned directly: ```json "cms_credentials": { "value": "username:password", "one_time": true, "first_reveal": true, "expires_at": "2024-04-15T10:22:00Z" } ``` A call from the same API key within 5 minutes of the first reveal gets the same value again (a retry window for a response that never arrived). After that window, or from a different key, `results.cms_credentials` is `null` instead, and a companion `meta.cms_credentials` entry explains why: ```json "cms_credentials": null ``` ```json "meta": { "cms_credentials": { "secret_unavailable": true, "reason": "Already revealed — secrets are one-time and cannot be shown again.", "revealed_at": "2024-04-15T09:10:00Z" } } ``` Store the plaintext before proceeding — you cannot rely on retrieving it again. Requires the `secrets:read` or `admin` scope on the API key. --- ### structured A JSON value matching a JSON Schema you define. The portal renders a dynamic form from the schema (simple flat schemas) or provides a JSON editor (complex or nested schemas). The submitted value is validated against the schema server-side before the item is accepted. **Required fields** | Field | Type | Description | |---|---|---| | `schema` | object | A valid JSON Schema object, draft-07 (Ajv's default). Omit `"$schema"` or set it to the draft-07 meta-schema URI; a schema that declares `"$schema": ".../2020-12/schema"` fails to compile. | **Example — opening hours** ```json { "key": "opening_hours", "label": "Opening hours", "help": "Your regular weekly schedule. Use a simple time range like '12:00-22:00' or the word 'Closed'.", "type": "structured", "required": true, "schema": { "type": "object", "required": ["mon_fri", "sat", "sun"], "properties": { "mon_fri": { "type": "string", "title": "Monday to Friday", "example": "12:00-22:00" }, "sat": { "type": "string", "title": "Saturday", "example": "12:00-23:00" }, "sun": { "type": "string", "title": "Sunday", "example": "Closed" } } } } ``` **Returned by `get_intake_results`** ```json "opening_hours": { "mon_fri": "12:00-22:00", "sat": "12:00-23:00", "sun": "13:00-21:00" } ``` The returned object is guaranteed to conform to the declared schema. --- ## Combining types: restaurant website example The following `items` array covers the major item types in a realistic project: ```json [ { "key": "logo", "label": "Restaurant logo", "type": "image", "required": true, "constraints": { "formats": ["svg","png"], "min_width": 512, "transparent_background": true } }, { "key": "brand_colors", "label": "Brand colors", "type": "color_list", "required": true }, { "key": "hero_copy", "label": "Hero section tagline", "type": "longtext", "required": true, "constraints": { "max_chars": 400 } }, { "key": "ga4_id", "label": "Google Analytics 4 ID", "type": "text", "required": false, "pattern": "^G-[A-Z0-9]+" }, { "key": "has_existing_site", "label": "Do you have an existing website?", "type": "boolean", "required": true }, { "key": "existing_site_url", "label": "Existing website URL", "type": "url", "required": false }, { "key": "platform", "label": "Preferred platform", "type": "select", "required": true, "options": [ { "value": "wordpress", "label": "WordPress" }, { "value": "webflow", "label": "Webflow" }, { "value": "custom", "label": "Custom / I'm not sure" } ] }, { "key": "cms_credentials", "label": "Existing CMS credentials", "type": "secret", "required": false }, { "key": "menu_pdf", "label": "Menu (PDF)", "type": "file", "required": true, "constraints": { "formats": ["pdf"], "max_bytes": 10485760 } }, { "key": "photos", "label": "Food and interior photos", "type": "file_list", "required": true, "constraints": { "formats": ["jpg","png","heic"], "min_count": 5, "max_count": 15 } }, { "key": "opening_hours", "label": "Opening hours", "type": "structured", "required": true, "schema": { "type": "object", "required": ["mon_fri","sat","sun"], "properties": { "mon_fri": { "type": "string" }, "sat": { "type": "string" }, "sun": { "type": "string" } } } } ] ``` --- ## Validation Validation is server-side and happens at upload time, before the item is marked `submitted`. The client receives immediate inline feedback in the portal if a file fails a constraint (wrong format, too small, below minimum count, pattern mismatch). They cannot submit an invalid item. The agent's item definition — `type`, `constraints`, and `schema` — is the single source of truth. BriefGate does not infer constraints from file content or other heuristics. If you need to tighten constraints after an intake is live, use `add_items` to add a replacement item with a new `key`, then use `request_revision` to direct the client to the new field. --- ## Client Portal URL: https://briefgate.dev/docs/portal # Client Portal **Try it yourself.** [Open a demo portal](https://api.briefgate.dev/v1/demo) — no account, no sign-up. It is a real intake on the real portal, so what you see is exactly what your client sees. It deletes itself within a day. ## Overview When you call `define_intake`, BriefGate generates a unique branded portal URL (e.g. `https://p.briefgate.dev/8f3k`) and emails it to your client with a magic link. The client does not need to create an account. They click the link, land directly in their portal, and start submitting assets. On paid plans, the portal shows your branding — not BriefGate's. From the client's perspective, this is a tool you built for them. On the Free plan, the portal shows a built-in sender identity instead — see [What the client sees](#what-the-client-sees) below. Once the client starts submitting, review what came in from the intake detail page in the dashboard, or pull everything at once as a ZIP — see [Download Everything as a ZIP](./zip.md). ## Magic link flow 1. Client receives an email with a magic link containing a token 2. Client clicks the link; the browser sends `POST /portal/:slug/redeem` to exchange the token for a session cookie 3. The cookie grants access to that specific intake only (not other intakes), and is valid for **14 days** 4. If the client loses the email, trigger a re-send: `POST /v1/intakes/:id/send` (or use `send_chase` from MCP) The magic link is not single-use, and it's also not one-per-email: an intake has **one stable link** for its whole life, and every email about it — the invitation, each reminder, a manual chase — carries that same link. It stays valid for the account's **portal link validity** setting (`portal_link_ttl_days`, default 30 days, configurable 1–365 in the dashboard), counted from the **most recent email sent** for that intake, so every send extends the window instead of replacing the link. The token itself is derived server-side from the intake and a server secret, and only its hash is stored — never the token, never in plaintext. The practical consequence: whoever holds the link holds access to that intake for as long as the intake keeps getting emails (or until `portal_link_ttl_days` passes since the last one). Treat a forwarded invitation email the way you would treat a forwarded document. Deleting or anonymising an intake stops its link from working, regardless of the TTL. ## What the client sees - Your branding: logo, accent color, sender name (on paid plans — see [Custom branding](./billing.md#custom-branding)); the same logo and an optional e-mail signature image (a business card works well) appear in every e-mail the client gets from you - Project name and a headline naming your business ("Radim needs your assets") — the client's own name is not shown in a greeting - A progress bar ("5 of 8 complete") - All items listed with their labels, help text, and current status - A "Send assets" button that marks the intake complete and fires the `intake.completed` webhook On the **Free** plan, the portal (and every e-mail) shows a built-in sender identity instead of your logo, accent color, or a name you chose: "Your developer" (English), "Váš dodavatel" (Czech), localized to the client's language, with your account's verified login email shown next to it, e.g. "Your developer (jan@firma.cz)". A logo or color set for a specific intake via `branding` on `define_intake` is stored but not shown while the account is on Free — only a paid plan's own branding, or the built-in identity, ever reaches the portal. "Powered by BriefGate" is also shown at the bottom of the portal on Free. Both are removed on Solo, Studio, and Agency plans. Custom portal domain (e.g. `intake.yourcompany.com`) is available on Studio and Agency — see [Custom Domains](./custom-domains.md) for setup. ## Client brief Sometimes the information needs to flow the other way first — a contract offer to sign, a scope document, a few paragraphs of context before the client fills anything in. Set `client_brief` on `define_intake` (or `PATCH /v1/intakes/:id` afterwards) and attach files with `POST /v1/intakes/:id/brief/files`; both are documented under [POST /v1/intakes](./rest-api.md#post-v1intakes) and [Client brief](./rest-api.md#post-v1intakesidbrieffiles) in the REST API reference. When either is set, it appears above the requested items as "Information from <your name>" — the same sender name the invitation e-mail signs with. Attachments go through the identical pipeline a client's own upload does: real content-type sniffing, HEIC-to-JPEG conversion, and an antivirus scan before the file is ever shown as downloadable. A file still being scanned, or one the scanner flagged, shows in the portal without a working link until it clears — the client is never handed a file BriefGate has not vetted. The invitation and reminder e-mails add one line pointing the client at the portal when a brief is present, but never attach the files themselves — email attachments bypass the antivirus/quota accounting this whole product is built around, so the client always has to open the portal to see them. ## Thank-you e-mail The moment an intake completes — whether the client clicked "Send assets" or you marked the last item as received outside BriefGate — the client gets one short thank-you e-mail in the intake's language, confirming that everything arrived and you can continue. It is on by default, sent once per intake and never for intakes created with a test-mode key. Switch it off with **Send a thank-you e-mail to the client when everything has arrived** in Settings (or `send_client_thank_you: false` on `PATCH /v1/account`) if you prefer to close the loop yourself; the `intake.completed` webhook and your own notification are unaffected. ## Item interactions Each item type renders a specific UI: - **text / longtext** — standard input or textarea with live character count - **file / image** — drag-and-drop upload area or camera/gallery picker on mobile, progress bar during upload - **file_list** — an "Add files" picker (camera/gallery on mobile), progress bar during upload; unlike file/image there is no drag-and-drop area - **color_list** — a color swatch plus a hex text input per entry (there is no separate singular `color` item type — only `color_list`) - **select** — dropdown - **boolean** — a Yes/No button pair - **url** — URL input with format validation on blur - **secret** — masked input with lock icon; the value is sent over HTTPS and encrypted server-side (public-key sealed box) before being stored — it is not encrypted in the browser, and it is never sent back once saved - **structured** — a simple form auto-generated from JSON Schema; key/value pairs for objects, repeated rows for arrays All items autosave on every field change. If the client closes the browser mid-way through, their progress is saved and they can return via the same portal link without re-entering anything. ## Mobile-first The portal is designed for clients submitting from a phone. Key mobile behaviors: - File inputs trigger the camera or photo gallery on iOS and Android - **HEIC images** from iPhone cameras are converted to JPEG server-side automatically — clients do not need to convert files themselves - Progress is preserved across page reloads and browser restarts - Uploads show a live progress bar; there is no chunked or resumable upload, so a dropped connection mid-upload needs a retry (files already saved are kept) ## In-portal validation Clients see validation errors in two layers, before and after anything is sent: - **In the browser, before any request is sent** — basic checks run instantly as the client picks a file or leaves a field, e.g. "Please enter a valid URL (https://...)" or "Image too small — we need at least 512px wide". - **On the server, on submit/upload** — BriefGate independently re-validates every value and file it receives and returns a detailed message if something still doesn't pass, e.g. "This image is only 200px wide; we need at least 512px." or "This file is 28 MB; the limit is 20 MB." The browser-side check is a courtesy that catches the obvious cases before the client hits Send assets, reducing revision cycles; the server-side check is authoritative and cannot be bypassed by a client that skips the browser check. ## Languages The portal UI is available in: | Code | Language | |---|---| | `en` | English | | `cs` | Czech | | `sk` | Slovak | | `pl` | Polish | | `de` | German | | `es` | Spanish | Omit `client.language` and the account's `default_language` applies; with neither set, the portal falls back to English. Set at `define_intake` time via `client.language`. All labels, help text, buttons, and system messages are shown in the chosen language. The item `label` and `help` fields you define are shown as-is — translate them yourself when using a non-English language. Additional languages are planned. Contact support to request one. ## Revision flow When the agent calls `request_revision(intake_id, item_key, note)`, the portal flags that item with a banner showing your note: > "This logo is too small. Please upload at least 512px wide. The SVG version would be ideal if you have it." The item's status changes to `needs_revision`. The client receives an email notification, clicks back to the portal, and re-uploads or re-enters the item. When they submit, `item.submitted` fires again and the item status returns to `submitted`. On Free plan, revision requests are not available (`plan_required` error). Available on Solo, Studio, and Agency. ## "Powered by BriefGate" On the Free plan, a small "Powered by BriefGate" notice appears at the bottom of the portal, and again on the "Done!" screen once the client submits everything. Both link to `https://briefgate.dev`. Right next to each one is a second, smaller line — "Collecting files from your own clients? Try BriefGate →" — pointed at other people running an intake of their own, not at your client. Client-facing emails (invite, reminder, revision request, completion notice) carry the same line in their footer. Both notices are removed entirely on Solo, Studio, and Agency plans — there is no separate toggle for the referral line; it disappears together with the branding it sits next to. On Studio and Agency, you can also configure a custom portal domain so the URL itself shows your brand (e.g. `intake.yourcompany.com` instead of `p.briefgate.dev/8f3k`) — see [Custom Domains](./custom-domains.md). --- ## Chase Engine URL: https://briefgate.dev/docs/chase # Chase Engine ## Overview The chase engine automatically sends reminder emails to clients who have not completed their intake. You configure the cadence when you call `define_intake`; BriefGate handles timing, deduplication, and quiet hours from that point on. The agent never has to babysit email threads or remember to follow up. When a client submits all required items, the chase engine stops automatically. ## Schedules | Schedule | Reminders | Cadence | |---|---|---| | gentle | T+3d, T+8d, then every 14 days | For sensitive client relationships | | default | T+2d, T+5d, T+9d, then weekly | Recommended for most projects | | aggressive | T+1d, T+3d, T+5d, then every other day | For hard deadlines | | custom | Every `chase_interval` `chase_interval_unit` (default every 3 days) | When no preset fits | | off | None | Manual only | Set the schedule when creating the intake: ```json { "project_name": "Bella Cucina Website", "client": {"email": "owner@bellacucina.cz"}, "items": [...], "chase_schedule": "default" } ``` The cadence can be changed after the intake is sent — see [Changing the schedule later](#changing-the-schedule-later). **Solo, Studio, and Agency plans** have access to all schedules. **Free plan** has access to `default` and `off` only. ## Custom interval When none of the presets fits, set `chase_schedule` to `custom` and give the interval as a number plus a unit: ```json { "project_name": "Bella Cucina Website", "client": {"email": "owner@bellacucina.cz"}, "items": [...], "chase_schedule": "custom", "chase_interval": 5, "chase_interval_unit": "minutes" } ``` `chase_interval_unit` is one of `minutes`, `hours`, `days`, and defaults to `days`. The first reminder lands one interval after the invite and one every interval after that — `5` `days` gives T+5d, T+10d, T+15d, and so on. **Bounds: at least 5 minutes, at most 90 days.** Anything shorter than five minutes runs into mail-provider rate limits and reads as spam to the recipient, so the API rejects it. Both fields are optional. `chase_schedule: "custom"` on its own reminds **every 3 days**. Sending either alongside a preset schedule is rejected with a 422, because the presets have fixed cadences and silently ignoring the field would leave you believing you had changed one. Unlike `gentle`, a custom cadence does not skip weekends. ### A fixed time of day A cadence measured in whole days can be pinned to a local time instead of drifting with whenever the invite happened to go out: ```json { "chase_schedule": "custom", "chase_interval": 1, "chase_interval_unit": "days", "chase_at_time": "07:00" } ``` That reminds the client every morning at 07:00 in `client.timezone`, DST included. - The value is a 24-hour local time, `HH:MM`. - It needs an interval measured in whole days. A sub-daily cadence cannot also land at one fixed time, so the API rejects the combination with a 422. - **It outranks quiet hours.** Naming 07:00 means 07:00 — the reminder is not pushed to 08:00 just because the default quiet window opens then. - Like every send, it carries a few seconds of jitter so a fleet of intakes does not hit the mail provider on the same second. ## Reminder cap An intake stops chasing after `max_reminders` reminders (default **3**), marks itself stalled, and fires the `intake.stalled` webhook so you can step in. A rapid cadence would burn through three attempts in minutes, so raise the cap when you shorten the interval: ```json { "chase_schedule": "custom", "chase_interval": 30, "chase_interval_unit": "minutes", "max_reminders": 12 } ``` The maximum is 1000. Passing `"max_reminders": "unlimited"` removes the cap entirely — worth it only for a genuinely open-ended chase, because an intake ignored a hundred times is unlikely to be rescued by another email and the sending domain's reputation pays for every one of them. ## Changing the schedule later `PATCH /v1/intakes/:id` can change `chase_schedule`, `chase_interval`, `chase_interval_unit`, `chase_at_time`, `max_reminders` and `respect_quiet_hours` after the intake has already gone out — no need to delete it and start over, which would re-send the invitation and hand the client a second link. ```json { "chase_schedule": "custom", "chase_interval": 6, "chase_interval_unit": "hours", "max_reminders": 12 } ``` Changing any of those fields — or `client.timezone` or `due_date`, both of which the cadence math reads — cancels every reminder still `scheduled` and re-plans from the new settings. Reminders already sent are not undone and still count toward `max_reminders`: lowering the cap after three of five reminders have gone out leaves two attempts, not five. If the intake has already stalled (see [Reminder cap](#reminder-cap) above), changing the cadence alone does not resume chasing — a stalled intake stays stalled until `max_reminders` is raised past the number already sent, or set to `"unlimited"`. That is also the escape hatch: an intake that stalled with `max_reminders: 3` picks up automatic reminders again the moment you `PATCH` it to `5` or `"unlimited"`. ## Quiet hours The chase engine respects client working hours to avoid sending reminders at inconvenient times. - Reminders are held if the client's local time is outside **8:00–19:00**. - Set `respect_quiet_hours: false` on the intake to send around the clock. Worth doing for a deliberately rapid cadence, which would otherwise sit idle overnight. - With quiet hours on, a sub-daily cadence counts only the time the window is open: a 30-minute interval running out at 18:50 resumes at 08:05 the next morning rather than dropping every overdue reminder onto 08:00 at once. - Client timezone is set via `client.timezone` in `define_intake` (e.g. `"Europe/Prague"`). Defaults to UTC if not set. - The **gentle schedule** never sends on weekends. - Every other schedule, custom cadences included, sends on weekends too. If a scheduled send falls in a quiet window, it is held until the next allowed time — it is not skipped. ## What the reminder email contains Each reminder is tailored to what is still missing: - Only the items the client has not yet submitted (not already-submitted ones) - A progress summary ("3 of 8 items remaining, approximately 6 minutes") - A direct link to the portal (the intake's one stable magic link, its validity extended by this send — no login required) - Your name and branding — on paid plans, the "Powered by BriefGate" footer is removed The email is written from your perspective, not BriefGate's. Clients see a professional reminder from you, not from a third-party tool. On the shared sending domain, the From name still reads "Your Name via BriefGate" — that's true on every plan, including paid ones. The only way to remove "BriefGate" from the From line entirely is the Studio or Agency plan with a verified custom sending domain (below). On the **Free plan**, "Your Name" is not a name you chose — a custom sender name is part of [custom branding](./billing.md#custom-branding), which Free does not have. Instead, clients see a built-in identity: "Your developer" (English), "Váš dodavatel" (Czech), localized to the client's language, with your account's verified login email shown next to it, e.g. "Your developer (jan@firma.cz)". The From line reads "Your developer via BriefGate". ## Custom sending domain (Studio and Agency) On the Studio or Agency plan, configure your own sending domain (e.g. `intake@yourcompany.com`) so clients see your domain in the From field and your name alone, with no "via BriefGate". The account settings page shows the DNS records to add and checks them automatically. See [Custom Domains](./custom-domains.md) for the full setup guide. Until a custom domain is configured, emails are sent from `intake@briefgate.dev`, with your name in front of it ("Your Name via BriefGate"). ## Manual chase Send a reminder immediately, outside the schedule: Via MCP: ``` send_chase(intake_id: "int_01J3K...", channel: "email") ``` Via REST: ``` POST /v1/intakes/:id/chase ``` ```json { "channel": "email" } ``` `channel` defaults to `email`; `sms` is also accepted on plans with SMS enabled. This does not reset the schedule — scheduled reminders continue as planned after the manual one. It does, however, count toward `max_reminders`: a manual send is one of the reminders that can trip the reminder cap and stall the intake, same as a scheduled one. Manual chase is rate-limited: at most 1 per intake per hour, and 20 per account per hour. ## Escalation flow When email delivery consistently fails, the chase engine signals the agent: 1. Client email hard-bounces (or keeps bouncing temporarily with no delivery) → `chase.bounced` webhook fires, BriefGate stops sending to that address 2. The intake runs out its reminder allowance without being completed → `intake.stalled` webhook fires with the `missing_items` list 3. Agent receives `intake.stalled` and can escalate by other means (notify a human, update project status, etc.) The `missing_items` array in `intake.stalled` tells you exactly which items are still outstanding, so you can relay that to whoever handles escalation. ## More than one person at the client Some material belongs to a company rather than to a person, and either of two directors could send it. An intake can be addressed to up to five people who share one portal link: ```json { "client": { "email": "first@bellacucina.cz", "name": "Marek", "also_notify": [{ "email": "second@bellacucina.cz", "name": "Jana" }] } } ``` Everyone on the list gets the invitation, every reminder, and the same link. Whoever opens it first can supply everything; the others see what is already done rather than being asked for it again. Each of them gets their own message. Nobody's address appears in anyone else's copy, each is greeted by their own name, and each carries its own bounce state — so one dead address stops mail to that person and to nobody else. Add or remove someone later with `POST /v1/intakes/:id/recipients` and `DELETE /v1/intakes/:id/recipients/:email`. Adding sends nothing by itself: the new person is included from the next reminder onward, or you can send one now with `send_chase`. The primary client cannot be removed this way — it is the address the intake was created for. ## Bounce handling Not every bounce means the address is dead, so BriefGate reads what the mail provider reported before it acts: | What Resend reported | What BriefGate does | |---|---| | Spam complaint | Retires the address, stops chasing it | | Permanent bounce (mailbox does not exist, domain rejects) | Retires the address, stops chasing it | | Bounce **after** a confirmed delivery of the same message | Keeps the address, schedule untouched | | Temporary bounce (mailbox full, greylisting) with no delivery | Keeps the address; the third undelivered one in a row retires it | The "bounce after delivery" case is common and easy to misread: the client's server accepts the message, then a forwarding rule or a quarantine gateway behind it sends a delivery failure seconds later. The person has the email in their inbox. Treating that as a dead address would silently cancel every reminder on the intake. Whenever an address is retired, BriefGate: 1. Fires the `chase.bounced` webhook 2. Marks that email address as bounced on this intake 3. Stops all future chase emails to that address (to protect your sender reputation) Only that address stops. On an intake addressed to several people, the others go on being reminded — the webhook payload carries `recipient` and `still_chasing` so you can tell which of the two happened. The webhook also fires for a bounce that did **not** retire the address (`still_chasing: true`, plus `bounce_type` and `delivered_before`), so you can see a flaky mailbox before it becomes a dead one. A bounced **primary** address cannot be corrected on an existing intake — there is no endpoint for changing `client.email` after creation. Either add a working address with `POST /v1/intakes/:id/recipients`, or create a new intake for the items they still owe you and let the old one be archived. ## Language Every email is written in the client's language, chosen in this order: 1. `client.language` on the intake 2. `default_language` on the account (`PATCH /v1/account`) 3. English Supported: `cs`, `sk`, `pl`, `de`, `es`, `en`. The subject, the body, the button and the date format all follow it — including plural agreement, which differs between languages that look similar. Polish treats 22 as "few" and 25 as "many"; Czech treats both as "many". Set `default_language` once if you work in one market. Without it, an intake that forgets `client.language` sends that client an English email and nobody finds out. ## Writing your own subject and intro `email_copy` replaces the built-in lines, on the account (as a default, via `PATCH /v1/account`) or on a single intake (overriding it, field by field, via `define_intake`/`POST /v1/intakes`). `invite_subject`/`invite_intro` customize the first invitation email; `reminder_subject`/`reminder_intro` customize the chase emails themselves — set the reminder pair if it's the reminders you want to change: ```json { "email_copy": { "invite_subject": "{sender} needs {count} things for {project}", "invite_intro": "Hi {client}, for {project} we still need a few things — it takes about {minutes} minutes.", "reminder_subject": "Reminder: {sender} still needs {count} things for {project}", "reminder_intro": "Hi {client}, just a nudge — {project} is still waiting on a few things ({minutes} minutes or so)." } } ``` Placeholders: `{sender}`, `{project}`, `{client}`, `{count}`, `{minutes}`, `{due}`. Anything else is **rejected with a 422** rather than rendered literally — a client reading `{proejct}` is a mistake nobody notices until after they have read it. **Links are never allowed in any of the four lines, on any plan.** A web address, a bare domain (`example.com`, `tr.ee/abc`), or an email address is rejected with a `422` ("Links and web or e-mail addresses are not allowed here — the portal button is the only link in the email"). The only link BriefGate ever puts in one of these emails is the portal button itself. If a line is rejected for looking like a domain when it isn't one ("J.Novak"), add a space after the full stop. **`email_copy` is part of [custom branding](./billing.md#custom-branding)** — Solo plan and up. Setting it on the account with `PATCH /v1/account` on a Free account is refused with `402 plan_required` (reason `custom_branding`). Setting it per intake on Free is **not** refused — the value is accepted and stored — but it is not used while the account stays on Free; the built-in lines go out instead, and the stored value takes effect automatically on upgrade. The layout, the button and the footer stay as they are. Values are escaped where the line lands inside HTML, so a project name is never able to inject markup — and the same escaping means any HTML typed into one of these lines shows up to the client as literal text, not as rendered markup. --- ## Custom Domains URL: https://briefgate.dev/docs/custom-domains # Custom Domains Custom domains are a **Studio or Agency plan** feature. They replace BriefGate's shared domains with your own in the two places a client sees them: the email a reminder comes from, and the URL the portal opens at. The two domains are independent — set up one, both, or neither. ## What you get - **Sending domain.** Client emails go out as `Name ` instead of `intake@briefgate.dev` shown as "Name via BriefGate". Once the domain is verified, "via BriefGate" disappears from the From line entirely. - **Portal domain.** Clients open `intake.yourcompany.com` instead of `p.briefgate.dev`. It's a CNAME to the BriefGate portal host, and a TLS certificate is issued automatically the first time someone visits. Reply-to is independent of either domain: replies always go to your account's reply-to address or your own email, regardless of which domain the invite was sent from. Until the sending domain is verified, mail keeps going out from `intake@briefgate.dev` and nothing breaks while DNS propagates — there's no window where email stops working. ## Before you start - You need the **Studio or Agency plan**. - You need access to the DNS settings for the domain you want to use — either directly, or someone who can add records for you. - Decide which domain to use. Your **main domain** is fine: the records BriefGate asks for live on `send.` and `resend._domainkey.`, so your existing mailbox, MX and SPF on the domain itself are never touched. Use a subdomain such as `intake.yourcompany.com` only if you prefer to keep intake mail visibly separate. ## Sending domain, step by step 1. In the dashboard, open **Settings → Custom domains** and add your sending domain. 2. BriefGate registers the domain with its email provider and shows you the DNS records it needs — normally these three: - A **DKIM** TXT record, at `resend._domainkey.` - An **SPF** TXT record, at `send.` (not at the domain itself) - An **MX** record, at `send.`, used for bounces Depending on the region and routing the email provider assigns your domain, it can add a fourth record — typically a **CNAME**, also on the `send.` subdomain. Always add exactly the records shown on your **Settings → Custom domains** screen rather than assuming a fixed count; the dashboard reflects whatever the provider currently asks for. If a CNAME is among them and your DNS provider proxies traffic (for example Cloudflare's orange cloud), turn proxying **off** for that record — set it to "DNS only" — the same as for the portal domain's CNAME below, otherwise it won't resolve to the target the provider expects. 3. Add each record at your DNS provider, using the exact name and value BriefGate shows — copy them rather than retyping. 4. BriefGate rechecks automatically every 10 minutes for up to 7 days after you add the domain. If you don't want to wait, click **Verify** to check immediately. 5. Each record shows its own status — verified, pending, or failed — so a typo in one record doesn't hide behind the others. Once every record shown verifies, new emails switch to the custom domain automatically. Nothing else changes on your intakes. ### Sender address By default mail goes out as `intake@`. You can change the part before the `@` under **Settings → Custom domains → Sender address**, for example to `hello` or `podklady`: 1–32 lowercase letters, digits, dots or dashes, starting and ending with a letter or digit. The dashboard previews the full address clients will see. Over the API the same setting is `sending_local_part` on `PATCH /v1/account`; `GET /v1/account/domains` returns the resulting `from_address`. Replies still go to the Reply-To address from your intake or account settings, not to this mailbox. ## Portal domain, step by step 1. In **Settings → Custom domains**, add your portal domain. 2. Create a CNAME record pointing your domain at the CNAME target shown in Settings. 3. If your DNS provider proxies traffic (for example Cloudflare's orange cloud), turn proxying **off** for this record — set it to "DNS only". A proxied CNAME serves the provider's page instead of the portal, and certificate issuance fails. 4. BriefGate rechecks automatically every 10 minutes for up to 7 days, the same as the sending domain. 5. Once the CNAME resolves, a TLS certificate is issued automatically on the first visit to the domain — there's nothing further to configure. ## Provider guides Menu names may differ slightly between provider versions — look for "DNS", "DNS management", or "Zone editor". **Cloudflare** 1. Log in and select the domain. 2. Go to **DNS → Records**. 3. Click **Add record**, choose the record type (TXT, MX, or CNAME). 4. Enter the name and value from BriefGate's setup screen. 5. For any **CNAME** record — the portal domain's, or a sending-domain CNAME if BriefGate's setup screen shows one — set the proxy status to **DNS only** (grey cloud, not orange). TXT and MX records are unaffected by proxying. 6. Save. **Wedos** 1. Log in to the WEDOS customer administration. 2. Open **DNS hosting** and select the domain. 3. Add a new record with the type, name, and value BriefGate shows. 4. Save the record and allow a few minutes for propagation. **Active24** 1. Log in and open **Domains → DNS records** for the domain. 2. Click to add a new record and pick the correct type. 3. Enter the name and value exactly as shown in Settings. 4. Save changes. **Forpsi** 1. Log in to the Forpsi client zone. 2. Open **DNS administration** for the domain. 3. Add a record with the type, name, and value from BriefGate. 4. Confirm and save. **GoDaddy** 1. Log in and go to **My Products → DNS** for the domain. 2. Click **Add** under Records. 3. Select the record type and enter the name and value. 4. Save — GoDaddy usually applies changes within a few minutes. **Namecheap** 1. Log in and go to **Domain List → Manage** for the domain. 2. Open the **Advanced DNS** tab. 3. Click **Add New Record**, choose the type. 4. Enter the host and value from BriefGate's setup screen. 5. Save all changes. ## Troubleshooting - **Record not found after an hour.** DNS changes can take up to 24 hours to propagate, though most providers apply them in minutes. If it's been longer than that, check for a duplicated domain name — a common mistake is a record named `intake.yourcompany.com.yourcompany.com` because the provider already appends the root domain to whatever you type in the name field. - **TXT value looks wrong.** Don't wrap the value in quotation marks unless your provider's interface requires them for every TXT record — check what an existing TXT record on the same domain looks like if you're unsure. - **Portal domain won't verify.** Confirm the CNAME record isn't proxied (Cloudflare's orange cloud, or an equivalent on another provider) — a proxied record blocks certificate issuance. - **Sending domain won't verify and one of the records is a CNAME.** Same cause as above: confirm that record isn't proxied either. - **Status shows "failed".** Click **Verify** again after fixing the record; failure doesn't stop the 7-day automatic rechecking, so a corrected record still verifies on its own if you'd rather not click anything. - **Removing a domain.** Remove it from **Settings → Custom domains** at any time. Sending and the portal fall back to the shared BriefGate domains immediately — no client-facing downtime. ## FAQ **Does this change my normal company email?** No. Only mail sent through BriefGate uses the sending domain you configure, and we recommend a dedicated subdomain specifically so your existing mailbox and SPF record are untouched. **Do I need a DMARC record?** No — it's optional. BriefGate's setup only requires the records shown on the Custom domains screen (SPF, DKIM, the bounce MX record, and sometimes a CNAME). Adding DMARC on your domain is a good practice generally, but it isn't part of custom domain verification. --- ## Secrets Vault URL: https://briefgate.dev/docs/secrets # Secrets Vault ## Overview The `secret` item type lets you collect credentials — passwords, API keys, hosting logins, third-party service tokens — from clients with encryption at rest. The decrypted plaintext can be revealed exactly **once**, through either of two paths: your agent calling `get_intake_results` (MCP or `GET /v1/intakes/:id/results`), or the account owner clicking **Reveal** on the item in the dashboard (`POST /v1/intakes/:id/items/:key/reveal`). Both draw on the same one-time reveal — whichever happens first gets the plaintext, and the other side gets back a note that it was already revealed. Secrets vault is available on **Solo, Studio, and Agency** plans. Attempting to include a secret item on a Free plan returns `plan_required`. ## Why secrets are different Regular items (text, file, color, URL) store their submitted values in plaintext in the database. That is appropriate for non-sensitive content. Secret items work differently: 1. The client fills in a masked input field on the portal 2. The value travels over HTTPS and is encrypted on arrival using a **libsodium sealed box** with BriefGate's public key, before anything is written to the database; it is never stored in plaintext 3. Only the ciphertext is stored in the database — the plaintext exists in server memory just long enough to be sealed, and again only during the one-time reveal; it is never written to disk or logs 4. The private key exists only in the server environment (never in the database) 5. Even a complete database dump cannot reveal secret values The private key is a 32-byte libsodium keypair secret held in the server environment. ## Declaring a secret item Include it in `items[]` when calling `define_intake`: ```json { "key": "wp_admin", "type": "secret", "label": "WordPress admin credentials", "help": "Your username and password. Encrypted at rest, revealed only once to your developer." } ``` On the portal, the client sees: - A masked password input, with a show/hide toggle - A lock icon - The note: "Encrypted — shown once to your provider only." There is no way to recover the value through the portal after submission. ## One-time reveal flow **Step 1.** There are three ways to trigger the reveal: - An agent calls `get_intake_results` (MCP, or `GET /v1/intakes/:id/results` with an API key that has the `secrets:read` or `admin` scope). This reveals **every** secret item on the intake in one call. - The account owner clicks **Reveal** on a single credential in the dashboard, which calls `POST /v1/intakes/:id/items/:key/reveal` (dashboard session only, owner role required). This reveals **one** item. - The account owner (or a `secrets:read`/`admin` API key) downloads the intake's ZIP with `include_secrets=true` (`GET /v1/intakes/:id/download`). This reveals **every** unrevealed secret item and includes the values in `podklady.pdf` — see [Download Everything as a ZIP](./zip.md). All three draw on the same one-time reveal recorded on the secret itself: whichever happens first gets the plaintext, and the others are told it was already revealed. The dashboard's own confirmation dialog says this outright before the owner clicks Reveal: "Credentials are shown once. After this it cannot be retrieved again — by you, or by an agent using an API key." On the **first call, via either path**, the response includes the decrypted plaintext. Via `get_intake_results` / `GET /v1/intakes/:id/results`, the item's entry in `results` looks like: ```json { "wp_admin": { "value": "admin:MyPassword123", "one_time": true, "first_reveal": true, "expires_at": "2026-08-15T10:00:00Z" } } ``` Via the dashboard's `POST /v1/intakes/:id/items/:key/reveal`, the response is: ```json { "key": "wp_admin", "value": "admin:MyPassword123", "first_reveal": true, "expires_at": "2026-08-15T10:00:00Z" } ``` **Step 2.** Store the value in your own secrets manager. This is your only chance, from either path. That is meant literally: the value is gone the moment it has been read, no matter which endpoint read it. There is one narrow allowance — the **same caller** (the same API key, or the same owner's dashboard session) may repeat its own call within **five minutes** and get the same value back, so a connection dropped between our response and your process does not destroy the credential. The retry window is tracked per caller identity, so an API key and a dashboard reveal never share it with each other — if the agent revealed it via the API, the owner clicking Reveal five seconds later still gets "already revealed," and vice versa. Any other caller, or the same caller later, gets nothing. On a subsequent `get_intake_results` call, the item drops out of `results` entirely (its value is `null`) and `meta` explains why: ```json { "wp_admin": { "secret_unavailable": true, "reason": "Already revealed — secrets are one-time and cannot be shown again.", "revealed_at": "2026-07-16T09:14:02Z" } } ``` A subsequent dashboard reveal instead gets: ```json { "key": "wp_admin", "value": null, "already_revealed": true, "revealed_at": "2026-07-16T09:14:02Z", "message": "This credential was already revealed. Secrets are shown once and cannot be shown again." } ``` If you lost the value, the way back is the same as if it had expired: ask the client for it again with `request_revision`. If the secret expires (30 days after submission, configurable per deployment via `SECRETS_TTL_DAYS`) before anyone collects it: Call `request_revision(intake_id, "wp_admin", "Credentials expired before we could retrieve them. Please resubmit.")` to ask the client to enter them again. The API key used with `get_intake_results` needs the `secrets:read` or `admin` scope to reveal secret values. Without it, `GET /v1/intakes/:id/results` still succeeds — every other item comes back normally — but each secret item is dropped from `results` and `meta` marks it `secret_unavailable: true, reason: "Scope 'secrets:read' or 'admin' required."` instead. ## Audit trail Every reveal is logged with: - Actor — the API key that called `get_intake_results` (`actor_type: "api_key"`) or the dashboard owner who clicked Reveal (`actor_type: "user"`) - IP address of the caller - Timestamp - `intake_id` and `item_key`, nested under `meta` View the audit log (dashboard session only, account owner — an API key cannot call this endpoint): ``` GET /v1/audit?action=secret.revealed ``` There is no server-side filter for a single intake — `intake_id` is not a supported query parameter. Each entry's `meta.intake_id` and `meta.item_key` tell you which item it was, so filter client-side if you need just one intake's history. This log is append-only and cannot be deleted. ## Auto-expiry Secrets expire **30 days** after the client submits the item. An expired secret has `value: null` and cannot be retrieved. Use `request_revision` to ask the client to resubmit. ## Best practices for agents **Store immediately.** When `get_intake_results` returns a secret with `first_reveal: true`, store the value before the call returns. It is never available again through the API. **Store in a secrets manager.** After revealing, put the value in your secrets manager (1Password, Vault, AWS Secrets Manager, etc.). Do not write it to a file, log it, or include it in a commit. **Never log the revealed value.** Even at debug level. If your logger captures variables, mask secrets before passing them to any logging function. **Rotate after use.** Once you have finished using a credential (e.g., after deploying the site), inform the client that they can rotate it. The captured credential was valid at collection time; rotating it limits exposure if the value was ever stored unsafely. ## Availability | Plan | Secrets vault | |---|---| | Free | Not available — `plan_required` error | | Solo | Available | | Studio | Available | | Agency | Available | --- ## Download Everything as a ZIP URL: https://briefgate.dev/docs/zip # Download Everything as a ZIP From an intake's detail page in the dashboard, or `GET /v1/intakes/:id/download`, download everything a client submitted as one ZIP file — no need to open each item individually. ## What's in the ZIP ``` podklady-bella-napoli-website-in_8f3kQmR2.zip ├── podklady.pdf ├── podklady.md ├── Logo/ │ └── bella-napoli-logo.png └── Food and interior photos/ ├── photo-1.jpg ├── photo-2.jpg └── photo-3.jpg ``` `podklady.pdf` is a readable summary of every item — label, type, status, the submitted value, decisions, and waived items with their reason — for a human who wants one document instead of opening the dashboard. `podklady.md` carries the same content in Markdown, for a script or another agent to parse. Every uploaded file sits in its own item's subfolder, exactly as the client uploaded it — no re-encoding, no format conversion. A file still going through the antivirus scan is left out of the ZIP and listed as pending in both `podklady.pdf` and `podklady.md` — download again once the scan clears. The dashboard says so before anything downloads: if the check is still running for any file, it asks whether to come back in a few minutes for a complete ZIP or download without those files now. ## Secrets are opt-in per download By default, `secret` items are left out entirely, so they stay available for a one-time reveal in the dashboard. Choosing to include them — in `podklady.pdf` only; `podklady.md` never carries secret values — reveals every secret item that hasn't been shown yet, and that reveal is final: it consumes the same one-time reveal as `get_intake_results` or the dashboard's Reveal button, and downloading again without secrets does not give it back. A secret already revealed earlier is shown as `already revealed on ` regardless of what you choose this time. See [Secrets vault](./secrets.md) for the one-time reveal itself. Only the account owner's own session, or an API key with the `secrets:read` or `admin` scope, may choose to include secrets — anyone else gets `403 forbidden` (reason `secrets_owner_only`) if they try. ## Size limit An intake above 2 GB is refused for ZIP download (`413 download_too_large`). There's no bundled alternative for an intake that large — fetch each item's signed URL individually with `get_intake_results` / [GET /v1/intakes/:id/results](./rest-api.md#get-v1intakesidresults) instead. ## API **Check before downloading** ```bash curl https://api.briefgate.dev/v1/intakes/in_8f3kQmR2/download/preflight \ -H "Authorization: Bearer bg_live_xxxxx" ``` ```json { "files": 6, "bytes": 18420531, "skipped_files": 1, "secrets": { "total": 2, "unrevealed": 1, "already_revealed": 1 }, "too_large": false, "max_bytes": 524288000, "filename": "podklady-bella-napoli-website-in_8f3kQmR2.zip" } ``` `skipped_files` is how many uploads are still pending the antivirus scan and would be left out. `secrets.unrevealed` is how many secret items are still available for a one-time reveal if `include_secrets` is left off; `secrets.already_revealed` show as already-revealed text either way. `too_large` mirrors the `413` the download call below would return. **Download the ZIP** ```bash curl "https://api.briefgate.dev/v1/intakes/in_8f3kQmR2/download?include_secrets=false" \ -H "Authorization: Bearer bg_live_xxxxx" \ -o podklady.zip ``` Returns `application/zip` with `Content-Disposition: attachment; filename="podklady-bella-napoli-website-in_8f3kQmR2.zip"`. `include_secrets` defaults to `false`; set it to `true` to reveal and include secret values in `podklady.pdf` — owner session or a `secrets:read`/`admin` key only, see [Secrets are opt-in per download](#secrets-are-opt-in-per-download) above. Logged as an `intake.downloaded` audit event either way. ## Troubleshooting - **"Download refused, intake too large."** ZIP download tops out at 2 GB (`413 download_too_large`). Check `GET /v1/intakes/:id/download/preflight` for the exact size, then fetch large items individually through `get_intake_results` instead. --- ## Intake Templates URL: https://briefgate.dev/docs/templates # Intake Templates ## Overview Templates let you save item sets and reuse them across projects. Instead of defining items from scratch each time, point `define_intake` at a template and the items are filled in automatically. You can still override or extend template items for a specific project. Templates are especially useful in agency settings where you run the same type of project repeatedly — restaurant websites, advisor pages, e-commerce stores — and want a consistent, tested item set. ## Built-in templates Seven public templates are available on all plans, including Free. They are always present and cannot be deleted. All seven are Czech-language templates (`language: "cs"`) — their item labels and help text are in Czech, since they were built for Radim's own agency work. The four newer templates (`web-cs`, `eshop-cs`, `logo-brand-cs`, `mobile-app-cs`) each have exactly 10 items, so a single intake built from one of them fits inside the Free plan's 10-items-per-intake limit without trimming anything. ### `restaurant-web-cs` For restaurant and cafe website projects. | Item key | Type | Notes | |---|---|---| | `logo` | image | SVG/PNG/JPEG, min. 512px wide, required | | `hero_copy` | longtext | Short intro text (max 400 chars), required | | `about` | longtext | Restaurant story, atmosphere, specialties (100–2000 chars), required | | `opening_hours` | structured | Object with `mon_fri`, `saturday`, `sunday` fields, required | | `gallery` | file_list | Interior/food/exterior photos, 5–15 files, min. 1200px wide, required | | `menu_pdf` | file | PDF menu — optional | | `brand_colors` | color_list | Up to 5 brand colors — optional | | `ga4_id` | text | Google Analytics measurement ID, pattern `^G-[A-Z0-9]+$` — optional | ### `advisor-web-cs` For financial advisors, coaches, consultants, and similar professional profile pages. | Item key | Type | Notes | |---|---|---| | `logo` | image | SVG/PNG, min. 512px wide — optional | | `portrait` | image | Professional headshot, min. 800×800px, required | | `hero_copy` | longtext | One-line headline (max 200 chars), required | | `bio` | longtext | About the advisor (150–3000 chars), required | | `services` | structured | Up to 6 services, each with `name` + `description`, required | | `brand_colors` | color_list | Up to 3 brand colors — optional | | `contact` | structured | Object with `phone`, `email` (required), `address` (optional) | | `ga4_id` | text | Google Analytics measurement ID — optional | ### `club-web-cs` For sports clubs and other associations — not an e-commerce template; see `eshop-cs` below for that. | Item key | Type | Notes | |---|---|---| | `logo` | image | SVG/PNG/JPEG, min. 512px wide, required | | `hero_copy` | longtext | Motto or one-line intro (max 200 chars), required | | `about` | longtext | Club history and focus (100–2500 chars), required | | `founding_year` | text | 4-digit year, pattern `^\d{4}$` — optional | | `activities` | longtext | What the club does, meetup schedule (80–2000 chars), required | | `gallery` | file_list | Event photos, 3–12 files, min. 1024px wide — optional | | `contact` | structured | Object with `email` (required), `phone`, `address` (optional) | | `social_urls` | structured | Object with `facebook`, `instagram`, `youtube` URLs — optional | ### `web-cs` For general business presentation websites. | Item key | Type | Notes | |---|---|---| | `logo` | image | SVG/PNG/JPEG, min. 512px wide, required | | `hero_copy` | longtext | Headline and intro text for the home page (max 400 chars), required | | `about` | longtext | About the business / what it does (100–2500 chars), required | | `subpages_copy` | longtext | Text for other subpages — services, contact… (max 5000 chars) — optional | | `photos` | file_list | 5–15 photos, min. 1200px wide — optional | | `brand_colors` | color_list | Up to 5 brand colors — optional | | `contact` | structured | Object with `company_name`, `address`, `phone` (required), `ico` (optional) | | `pricing` | longtext | Pricing or service packages, if they should be public (max 3000 chars) — optional | | `access_note` | longtext | Note on existing domain/hosting/admin access (max 1000 chars) — optional | | `ga4_id` | text | Google Analytics measurement ID, pattern `^G-[A-Z0-9]+$` — optional | ### `eshop-cs` For e-commerce stores. | Item key | Type | Notes | |---|---|---| | `logo` | image | SVG/PNG/JPEG, min. 512px wide, required | | `hero_copy` | longtext | Headline and intro text for the home page (max 400 chars), required | | `product_catalog` | longtext | Product and category list (50–5000 chars), required | | `product_photos` | file_list | 5–50 product photos, min. 1000px wide — optional | | `brand_colors` | color_list | Up to 5 brand colors — optional | | `prices_vat` | select | `with_vat` or `without_vat`, required | | `payment_methods` | multiselect | Card, bank transfer, cash on delivery, Apple/Google Pay — required | | `shipping` | longtext | Carriers and shipping price structure (max 2000 chars), required | | `invoice_details` | structured | Object with `company_name`, `ico`, `email` (required), `dic` (optional) | | `legal_terms` | longtext | Terms of service and right of withdrawal (max 5000 chars) — optional | ### `logo-brand-cs` For logo and visual identity briefs. | Item key | Type | Notes | |---|---|---| | `positioning` | select | `budget`, `mid`, or `premium` price-quality positioning, required | | `one_liner` | longtext | One sentence on the association the logo should evoke (max 200 chars), required | | `brand_words` | text | Three words for how the brand should feel (max 100 chars), required | | `competitors` | longtext | 2–3 competitors and an opinion on their logos (max 1000 chars) — optional | | `slogan` | text | Existing slogan, if it should be worked into the logo (max 150 chars) — optional | | `existing_logo` | image | Current logo file, if one exists — optional | | `moodboard` | file_list | 3–15 moodboard/reference images — optional | | `deliverable_formats` | multiselect | Vector (AI/SVG), print PDF, PNG, favicon — required | | `approver` | text | Who has final sign-off on approval (max 150 chars), required | | `revision_rounds` | text | How many initial directions and revision rounds are included (max 100 chars) — optional | ### `mobile-app-cs` For mobile app projects. | Item key | Type | Notes | |---|---|---| | `app_name` | text | App name, checked as available in both stores (max 100 chars), required | | `languages` | multiselect | Czech, English, German, Slovak — required | | `app_icon` | image | SVG/PNG, min. 512px wide, required | | `screenshots` | file_list | 3–10 screenshots or material to prepare them — optional | | `store_description` | longtext | Short and long store listing description (max 4000 chars), required | | `user_data` | longtext | What user data the app collects and why (max 2000 chars), required | | `integrations` | longtext | External services/APIs to integrate — maps, payments, booking… (max 2000 chars) — optional | | `store_accounts_note` | longtext | Client's own Apple Developer Program / Google Play Console account (max 1000 chars) — optional | | `privacy_url` | url | Privacy policy URL, if one already exists — optional | | `release_constraints` | longtext | Minimum OS version, supported devices, fixed release date (max 1000 chars) — optional | ## Using a template in define_intake Pass the template slug in the `template` field: ```json { "project_name": "Bella Cucina Restaurant Website", "client": { "email": "owner@bellacucina.cz", "name": "Marco" }, "template": "restaurant-web-cs", "branding": { "sender_name": "Radim" } } ``` `branding.sender_name` here is [custom branding](./billing.md#custom-branding) — Solo plan and up. It's accepted and stored on any plan, but only shown to the client once the account is on a paid plan; on Free the client sees the built-in sender identity instead. This creates an intake with all `restaurant-web-cs` items pre-populated. `items` is optional here — with `template` set, `POST /v1/intakes` no longer requires it; omitting it (or sending `"items": []`) means "every item comes from the template." Without `template`, `items` is still required and non-empty, with the same `422` as before. ### Overriding and extending Provide an `items` array alongside `template` to override specific items or add new ones. Items in your `items` array are merged with the template: - If `key` matches a template item, your definition overrides the template's - If `key` is new, it is appended after the template items Every entry in `items` — including one that only means to tweak a template item — must still be a complete item definition (`key`, `type`, and `label` are all required by the API; there is no partial-patch shorthand that lets you send just the field you want to change): ```json { "template": "restaurant-web-cs", "items": [ { "key": "menu_pdf", "type": "file", "label": "Jídelní lístek (PDF)", "required": false, "help": "Only needed if you want a downloadable menu link. Skip if menu is managed online." }, { "key": "allergen_info", "type": "file", "label": "Allergen information document", "required": false } ] } ``` ## Creating custom templates Custom templates require the Solo plan or above ($29/mo) — on Free, `POST /v1/templates` fails with a `plan_required` error, and Free accounts can only use the three built-in public templates above. `POST /v1/templates` also requires a logged-in dashboard session; an agent authenticated with only an API key cannot create a custom template through this endpoint — create it from the dashboard instead (or ask a teammate with dashboard access to). From the dashboard, the quickest way is **Save as template** next to the Send button when you finish building an intake. It stores the item definitions and the language only — never the client's name, e-mail or project name — so the same template is safe to reuse for the next client. Through the API there is no way to copy an existing intake: `POST /v1/templates` only accepts a template built from scratch, described below. ``` POST /v1/templates ``` ```json { "name": "SaaS Landing Page", "description": "Standard intake for SaaS product landing page projects", "language": "en", "items": [ {"key": "logo", "type": "image", "label": "Product logo"}, {"key": "hero_headline", "type": "text", "label": "Hero headline", "constraints": {"max_chars": 80}}, {"key": "hero_subline", "type": "text", "label": "Hero subline", "constraints": {"max_chars": 160}}, {"key": "stripe_keys", "type": "secret", "label": "Stripe API keys"} ] } ``` There is no `slug` field to set — the slug is derived automatically from `name` (lowercased, non-alphanumeric characters replaced with hyphens). `language` accepts `cs`, `en`, or `de` — not the full six-language portal list. Constraints such as `max_chars` must be nested under `constraints`, the same as in `define_intake`'s `items` — a top-level `max_chars` on the item is rejected. ## Template settings A template can also store every other create-intake setting besides items — chase cadence, retention, branding, and which folder new intakes land in. `POST /v1/templates` accepts an optional `settings` object with these fields, all optional: | Field | Same as on `define_intake` | Notes | |---|---|---| | `due_in_days` | — | Integer, 0–365. There is no `due_date` field here: a template cannot hold an absolute date, only an offset from the day the intake is created. | | `chase_schedule` | `chase_schedule` | | | `chase_interval` / `chase_interval_unit` | same | Only with `chase_schedule: "custom"` — same rule as `define_intake`. | | `respect_quiet_hours` | same | | | `max_reminders` | same | | | `chase_at_time` | same | | | `email_copy` | same | [Custom branding](./billing.md#custom-branding) — Solo plan and up; stored but not used on Free. | | `auto_approve_hours` | same | | | `retention` | same | | | `branding` | same | `logo_url`/`accent_color`/`sender_name` are [custom branding](./billing.md#custom-branding) — Solo plan and up; stored but not used on Free. | | `folder_id` | same | Still checked against the caller's own account when the intake is created — a template built under one account cannot silently file an intake into another account's folder. | | `client_brief` | `client_brief` | Text only — a template has no intake to attach files to. See [Client brief](./rest-api.md#post-v1intakesidbrieffiles). | ```json { "name": "SaaS Landing Page", "language": "en", "items": [ {"key": "logo", "type": "image", "label": "Product logo"} ], "settings": { "due_in_days": 14, "chase_schedule": "custom", "chase_interval": 5, "chase_interval_unit": "days", "retention": {"mode": "on_delivery", "anonymize": false} } } ``` **Settings are defaults, not overrides.** When an intake is created with `template` set, each setting field applies only if the create-intake request itself leaves that field unset. Anything the request sets explicitly — even a value that happens to match what a template also sets — always wins, field by field; nothing is merged inside a single field (an `email_copy` sent on the request replaces the template's `email_copy` object whole, it does not merge subject/intro lines individually). `due_in_days` is resolved to a real `due_date` at the moment the intake is created (creation day + N), unless the request already supplies its own `due_date`. A template that omits `settings` entirely — including the three built-in public templates — changes nothing beyond items; `GET`/`POST /v1/templates` then reports `settings` as `null`. `settings` is API-only for now: the dashboard's **Save as template** button (above) still stores items and language only. ## Listing templates ``` GET /v1/templates ``` Returns public templates and your own custom templates together, as `{ "templates": [...] }`. There is currently no `?public=true` (or any other) filter on this endpoint — a query string has no effect; filter the result client-side if you only want the public ones (`accountId` is `null` on those). The response is the template row as stored, not a summarized view — in particular `items` is the full array of item definitions (not a count), `settings` is either the full settings object described above or `null`, and there is no field tracking which user created a template, only which account owns it. Note that this endpoint's field names are the raw camelCase database columns (`accountId`, `isPublic`, `createdAt`, …), unlike the rest of the API, which returns snake_case. ## Agency: team-shared templates On Agency plans, templates created by any seat member are visible to all seats in the account. There is no separate sharing step — templates are team-scoped by default. This lets you build a library of standard intake checklists once and use them across all projects, regardless of which team member creates the intake. To keep templates organized, use consistent slug naming: ``` restaurant-web-v2 advisor-web-minimal webapp-onboarding ``` Custom templates require Solo, Studio, or Agency (Free cannot create any). On Solo and Studio, custom templates are scoped to the account's single seat; on Agency they are shared across all seats, as above. --- ## Webhooks URL: https://briefgate.dev/docs/webhooks # Webhooks ## Overview BriefGate sends signed POST requests to your endpoint when intake events happen. Webhooks are the best way to react to client activity in real time — more efficient than polling `get_intake_status` in a loop, and they work while your agent is idle or sleeping between tasks. Each request is signed so you can verify it came from BriefGate and was not tampered with. ## Registering an endpoint ``` POST /v1/webhooks ``` ```json { "url": "https://yourapp.com/webhooks/briefgate", "events": ["item.submitted", "intake.completed"] } ``` You can subscribe to any subset of the seven available events. To subscribe to all events, pass all seven event names. ```bash curl -X POST https://api.briefgate.dev/v1/webhooks \ -H "Authorization: Bearer bg_live_xxxxx" \ -H "Content-Type: application/json" \ -d '{"url":"https://yourapp.com/webhooks/briefgate","events":["item.submitted","intake.completed","intake.stalled"]}' ``` Response: ```json { "id": "whe_a1b2c3d4e5f6", "url": "https://yourapp.com/webhooks/briefgate", "events": ["item.submitted", "intake.completed", "intake.stalled"], "format": "raw", "active": true, "created_at": "2026-07-18T09:11:00Z", "secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } ``` The `secret` is shown exactly once. Store it securely — you need it to verify signatures. The optional `format` field decides what shape the request body takes. It defaults to `raw`, the signed BriefGate envelope described below. Set it to `slack` or `discord` to post a ready-made chat message instead — see [Slack and Discord](#slack-and-discord). ## Managing endpoints List every endpoint registered on the account: ``` GET /v1/webhooks ``` ```json { "webhooks": [ { "id": "whe_a1b2c3d4e5f6", "url": "https://yourapp.com/webhooks/briefgate", "events": ["item.submitted", "intake.completed", "intake.stalled"], "format": "raw", "active": true, "created_at": "2026-07-18T09:11:00Z" } ] } ``` The `secret` is never returned here — only at creation. For a `slack` or `discord` endpoint, `url` comes back as only the origin (see [What a chat notification does not contain](#what-a-chat-notification-does-not-contain)). Remove an endpoint: ``` DELETE /v1/webhooks/:id ``` Returns `204 No Content`. Nothing more is sent to it afterwards, and there is no way to reactivate it — register a new one. Creating an endpoint, deleting one, retrying a delivery and sending a test event are all restricted to the account owner. Any signed-in team member can list endpoints and view delivery history, but changing them takes the owner role. An API key is the account's own credential, so this restriction applies only to browser sessions. ## Signature verification Every webhook request includes the header: ``` X-BriefGate-Signature: t=1721131200,v1=abc123... ``` - `t` — Unix timestamp of the request - `v1` — HMAC-SHA256(webhook_secret, `${t}.${rawBody}`) as hex Two more headers travel alongside it, though neither is part of the signature: `X-BriefGate-Event` carries the event name, so you can route before parsing JSON, and `User-Agent: BriefGate-Webhook/1.0` identifies the request as ours. To verify: 1. Extract `t` and `v1` from the header. 2. Reject the request if `|now - t| > 300 seconds` (prevents replay attacks). 3. Compute `HMAC-SHA256(secret, "${t}.${rawBody}")` where `rawBody` is the raw request body string. 4. Compare with `timingSafeEqual` — never use `===` for signature comparison. Complete Node.js verification function: ```javascript import { createHmac, timingSafeEqual } from 'crypto'; function verifyWebhook(rawBody, secret, signatureHeader) { const parts = Object.fromEntries( signatureHeader.split(',').map(p => p.split('=', 2)) ); const t = parts['t']; const v1 = parts['v1']; if (!t || !v1) throw new Error('Missing signature components'); if (Math.abs(Date.now() / 1000 - Number(t)) > 300) { throw new Error('Timestamp out of tolerance window'); } const expected = createHmac('sha256', secret) .update(`${t}.${rawBody}`) .digest('hex'); if (!timingSafeEqual(Buffer.from(v1), Buffer.from(expected))) { throw new Error('Signature mismatch'); } } ``` Call `verifyWebhook` before doing anything with the payload. If it throws, return HTTP 400 and discard the request. ## Events ### item.submitted Fires when a client submits a single item in their portal. ```json { "event": "item.submitted", "intake_id": "in_01J3K...", "project_name": "Bella Cucina Website", "item_key": "logo", "item_label": "Company logo", "item_type": "image", "file_count": 1, "timestamp": 1784212920 } ``` `file_count` is present only on file, image and file_list items. `timestamp` is Unix seconds and is the value the signature is computed over. The client's email address is deliberately not included — a chat channel usually has more readers than the intake does. ### intake.completed Fires when all required items have been submitted (optional items do not block completion). ```json { "event": "intake.completed", "intake_id": "in_01J3K...", "project_name": "Bella Cucina Website", "timestamp": 1784372060 } ``` Call `get_intake_results` to collect the answers themselves. ### client.viewed Fires when the client opens their portal. ```json { "event": "client.viewed", "intake_id": "in_01J3K...", "slug": "8f3kqmr2", "project_name": "Bella Cucina Website" } ``` No IP address is sent. Views are deduplicated server-side, so a client refreshing the page does not fire the event repeatedly. ### chase.bounced Fires when the mail provider reports a bounce or a spam complaint for a reminder email. Whether BriefGate stops sending to the address depends on what was reported — see `still_chasing` below and [Bounce handling](chase.md#bounce-handling). ```json { "event": "chase.bounced", "intake_id": "in_01J3K...", "chase_id": "chs_01J4M...", "provider_message_id": "01J4M8Z...", "event_type": "bounced", "recipient": "owner@bellacucina.cz", "still_chasing": true, "bounce_type": "Transient", "delivered_before": true, "timestamp": 1784361600 } ``` `event_type` is what the mail provider reported — `bounced` or `complained`. `recipient` is the address that bounced. `still_chasing` tells you whether the intake still has other recipients being chased (`true`) or this was the last one, so future reminders for this intake are now cancelled (`false`). `bounce_type` is the provider's classification (`Permanent`, `Transient`, `Undetermined`, or `null` for a complaint). `delivered_before` is `true` when the provider had already confirmed delivery of that very message — a late delivery-status notification from behind the recipient's server, not a dead address. A permanent bounce or a complaint always retires the address; a bounce after delivery never does; a temporary bounce with no delivery retires it on the third one in a row. ### intake.stalled Fires when the intake has used up its reminder allowance — `max_reminders` reminders have been sent (default 3) without the client completing it. The chase engine cancels the remaining reminders and hands the intake back to you. ```json { "event": "intake.stalled", "intake_id": "in_01J3K...", "project_name": "Bella Cucina Website", "missing_items": ["logo", "hero_copy", "wp_admin"], "timestamp": 1784707200 } ``` `missing_items` lists the required items still waiting on the client, by key. When you receive `intake.stalled`, consider reaching out to the client by other means. ### intake.overdue Fires once, the first time a periodic sweep notices an intake has passed its due date with at least one required item still outstanding. It cannot fire twice for the same intake. ```json { "event": "intake.overdue", "intake_id": "in_01J3K...", "project_name": "Bella Cucina Website", "due_date": "2026-07-01T00:00:00.000Z", "outstanding_items": 3, "timestamp": 1784707200 } ``` `outstanding_items` counts required items that are still `pending` or `needs_revision` — waived items don't count. This fires independently of the automatic reminder schedule and independently of whether owner-notification email is enabled for the account; it is the one event meant to tell you, the developer, rather than remind the client. ### intake.archived Fires when [POST /v1/intakes/:id/archive](./rest-api.md#post-v1intakesidarchive) closes an intake — from any status, including one that was never sent. ```json { "event": "intake.archived", "intake_id": "in_01J3K...", "project_name": "Bella Cucina Website", "timestamp": 1784707200 } ``` The intake and everything on it (items, files, chase history) still exist — this is not a deletion event, and there is no corresponding `intake.deleted` webhook for `DELETE /v1/intakes/:id` today. ## Slack and Discord You do not have to run a server to receive BriefGate events. Point a webhook at a Slack or Discord incoming webhook and the notification arrives in the channel your team already watches. This is the same delivery path as any other webhook — same events, same retries, same delivery log. Only the request body changes, because Slack and Discord accept their own message shape and answer anything else with a 400. ### Slack Create an incoming webhook in Slack (**Your apps → your app → Incoming Webhooks → Add New Webhook to Workspace**), pick the channel, and copy the URL. Then: ```bash curl -X POST https://api.briefgate.dev/v1/webhooks \ -H "Authorization: Bearer bg_live_xxxxx" \ -H "Content-Type: application/json" \ -d '{ "url": "https://hooks.slack.com/services/T0000/B0000/xxxxxxxx", "events": ["intake.completed", "intake.stalled", "chase.bounced"], "format": "slack" }' ``` The channel receives plain sentences: ``` The client submitted "logo" for Bella Cucina Website. Intake: in_01J3K... ``` The sentence never names the client — `item.submitted` payloads deliberately omit the client's email (see above), so the chat formatter falls back to "The client" whenever no `client_email` is present, which for this event is always. A Slack incoming webhook always posts to the channel it was created for, under the name and icon configured on the Slack app. That is Slack's rule, not ours: an incoming webhook cannot override the channel, the username or the icon, and it cannot send a direct message. If you want each developer notified privately, give each of them their own webhook created against a DM, or subscribe a channel per project. ### Discord Open **Channel settings → Integrations → Webhooks → New Webhook**, copy the URL, and register it with `"format": "discord"`. ```bash curl -X POST https://api.briefgate.dev/v1/webhooks \ -H "Authorization: Bearer bg_live_xxxxx" \ -H "Content-Type: application/json" \ -d '{ "url": "https://discord.com/api/webhooks/123456/xxxxxxxx", "events": ["intake.completed"], "format": "discord" }' ``` Mentions in the message are inert: a project or client name containing `@everyone` is delivered as text and pings nobody. ### What a chat notification does not contain The portal link is never included. It is a bearer link into your client's portal, and a channel usually has more readers than the intake does. Each notification carries the intake id, which is enough to look the intake up through the API and gives away nothing. For the same reason, `GET /v1/webhooks` returns only the origin of a Slack or Discord URL (`https://hooks.slack.com/…`). The path of such a URL is the credential — anyone holding it can post into the channel — so it is treated like the signing secret and not shown again. A `raw` URL points at your own server and is returned in full. Requests to Slack and Discord are still signed with `X-BriefGate-Signature`. Neither service checks it; it costs nothing and keeps one code path for every format. ### Choosing between them A chat notification is for a human who wants to know. The `raw` format is for an agent that will act — it carries the full payload, it is verifiable, and it is what `intake.completed` should trigger if the next step is code. Registering both is normal: one endpoint per format, subscribed to the events that matter to each. ## Retries If your endpoint does not return HTTP 2xx, BriefGate retries with exponential backoff: | Attempt | Delay after previous | |---|---| | 1 (immediate) | — | | 2 | 1 minute | | 3 | 5 minutes | | 4 | 30 minutes | | 5 | 2 hours | | 6 | 6 hours | After 6 failed attempts, the delivery is abandoned and marked `failed` in the delivery log. Redirects are not followed, so a 301 or 302 counts as a failure — register the final URL. Return **HTTP 410 Gone** to deactivate the endpoint from your side. That delivery is marked failed without further retries and nothing more is sent to the endpoint until you register it again. View delivery history — the last 100 attempts, newest first: ``` GET /v1/webhooks/:id/deliveries ``` ```json { "deliveries": [ { "id": "whd_9f8e7d6c5b4a", "event": "intake.completed", "status": "failed", "attempts": 6, "response_code": 500, "error": "HTTP 500", "next_retry_at": null, "created_at": "2026-07-18T09:11:00Z", "delivered_at": null } ] } ``` The submitted payload is not returned here. This view exists to tell you why a delivery failed, and a payload can contain whatever your client uploaded. Retry one delivery by hand: ``` POST /v1/webhooks/:id/deliveries/:deliveryId/retry ``` This re-queues the delivery to go out on the next scheduled tick, through the same path as any other delivery — the SSRF re-check, a freshly computed signature, logged like any other attempt. It works on any delivery that has not already succeeded (a `409` is returned for one that has, and for one on an endpoint you have since switched off). It does not reset the attempt count: `attempts` keeps climbing from where it left off, so a delivery that already used all 6 attempts gets exactly one more try, not a fresh ladder — fix the endpoint first if you want more than that. Response: ```json { "delivery": { "id": "whd_9f8e7d6c5b4a", "event": "intake.completed", "status": "pending", "attempts": 6, "response_code": 500, "error": null, "next_retry_at": "2026-07-18T09:12:00Z", "created_at": "2026-07-18T09:11:00Z", "delivered_at": null } } ``` ## Testing Send a test delivery to your endpoint without triggering a real intake: ``` POST /v1/webhooks/:id/test ``` No request body — there is no way to choose which event to simulate. BriefGate always sends a fixed, fictional `item.submitted` payload: ```json { "event": "item.submitted", "intake_id": "in_test", "item_key": "test", "message": "This is a test delivery from BriefGate.", "timestamp": 1784212920 } ``` Note the shape is deliberately minimal and does not match a real `item.submitted` payload field-for-field (no `project_name`, `item_label`, `item_type`) — it exists to check that your endpoint is reachable and your signature verification works, not to exercise payload parsing. The delivery is queued and sent in the background, signed exactly like a real one, and shows up in the delivery log like any other attempt. The request returns immediately: ```json { "queued": true, "delivery_id": "whd_9f8e7d6c5b4a" } ``` ## Best practices **Verify the signature first.** Do not process the payload before calling your verification function. A request without a valid signature should be discarded immediately. **Use idempotency.** Webhooks can be delivered more than once in rare cases (network retries, infrastructure restarts). Check `intake_id` + `event` combination to avoid processing the same event twice. **Log the raw body before parsing.** If your JSON parser throws, you still want the raw body available for debugging. Store it before calling `JSON.parse`. **Respond quickly.** Your endpoint has 10 seconds to return a 2xx response before the request is aborted and counted as a failed attempt. If your handler does heavy work (calls external APIs, builds files), acknowledge immediately and process in a background queue. **Do not rely on delivery order.** `item.submitted` events may arrive before or after `intake.completed`. Design your handler to handle events out of order. --- ## Security URL: https://briefgate.dev/docs/security # Security BriefGate asks your clients for logos, copy — and passwords. That last one changes what this product is: a service that collects credentials is infrastructure, and infrastructure has to say plainly what it does and does not protect you from. Everything below describes the system as it is built today. Where a protection does not exist, this page says so rather than leaving it out. ## What BriefGate is not **It is not zero-knowledge.** A `secret` value is encrypted with a libsodium sealed box the moment it arrives, and the private half of that key pair lives in the server environment, not in the database. A stolen database dump therefore yields ciphertext alone. But the server that receives the value can read it — that is how it hands the value to your agent — so an attacker who owns the running process could read a secret in flight. Any product claiming otherwise while holding the key is claiming something it cannot deliver. **It holds no certification.** There is no ISO 27001, no SOC 2, and no external penetration test. BriefGate is operated by one person. This is stated because a security assessment should rest on what exists. ## Secrets A `secret` item is the only field type that gets its own handling end to end. - The value is encrypted on receipt with a libsodium sealed box (`crypto_box_seal`) and is never written to disk in plaintext. - The private key is held in the server environment and is never stored in the database, so a full database dump cannot be decrypted. - Reading it requires an API key carrying the `secrets:read` or `admin` scope. A key without that scope is told the value exists and nothing more. - It is released **once**. The retrieval is atomic: the first read marks it revealed, and a later read returns the time of that reveal instead of the value. A five-minute window after the first reveal lets the *same* key repeat the *same* read, so a request lost in transit does not cost you the value. - Every reveal is written to the audit log with the key that did it. - A secret leaves through exactly three doors, and each of them spends the one reveal: `get_intake_results` with the right scope, the **Reveal** button on one item in the dashboard (`POST /v1/intakes/:id/items/:key/reveal`, owner session required, audited against the person rather than a key), and a ZIP asked for with `include_secrets=true`. The dashboard deliberately reveals one item at a time on a click, never by rendering a page: merely opening an intake must not burn a value. What this buys you: a client can send a WordPress password to your agent without it sitting in an inbox, a chat log, or a support ticket. ## Credentials and sessions | | | |---|---| | Account passwords | argon2id | | API keys, portal tokens | 256 bits of randomness, stored as a SHA-256 digest; plaintext shown once at creation | | Two-factor | TOTP, optional, per user | | Client portal access | magic link (one stable link per intake, token stored hashed, valid for `portal_link_ttl_days` — default 30 — from the most recent send), exchanged for a session cookie scoped to **that one intake** | | Portal session lifetime | 14 days | | Login and sign-up | 10 attempts per hour per IP address | API keys are hashed with SHA-256 rather than argon2id on purpose. The key is 256 random bits, so there is no dictionary to slow an attacker down with, and a password hash on every agent request would cost tens of milliseconds for no security gain. Passwords, which people choose, get argon2id. A password reset invalidates every session and does **not** issue a new one, so TOTP still stands between an attacker with a reset link and the account. ## Signing in an agent without pasting a key Two flows exist besides creating a key in the dashboard and copying it into config, so an agent can be granted access without a secret ever passing through a terminal or a chat transcript. **Device login** (`npx @briefgate/mcp login`) follows RFC 8628. The CLI requests a `device_code` and a short `user_code`, shows the user code, and polls `/v1/auth/device/poll` every few seconds. Both codes are stored hashed, not in plaintext, and expire after 10 minutes if nobody approves them. Approving one requires an active dashboard session — the tab that clicks **Allow** must already be signed in, so the flow cannot be completed by someone who only has the code. The API key it hands back is a normal API key in every respect: same scopes, same revocation, same audit trail, and it appears on the keys page labeled with the client and hostname that requested it (e.g. "Claude Code on laptop"), so it can be told apart from keys created directly in the dashboard. **OAuth 2.1** backs the hosted endpoint (`https://mcp.briefgate.dev/mcp`). It is the standard authorization-code flow with PKCE (S256 only) for **public clients** — no client secret is ever issued or accepted, matching what an MCP client running on someone's machine or in a browser actually is. Dynamic client registration (RFC 7591) is open at `/v1/oauth/register`, and metadata is published at `https://api.briefgate.dev/.well-known/oauth-authorization-server`. Redirect URIs must be `https://` or a loopback address; anything else is refused. Access tokens are short-lived (1 hour) API keys and are revocable the same way any key is; refresh tokens last 30 days and **rotate on every use** — a refresh token that gets used after being stolen invalidates the legitimate one, and the theft becomes visible in the audit log as two uses of the same token in a short window. Authorization codes, access tokens and refresh tokens are all stored hashed, never in plaintext. Both flows end where a dashboard-created key does: something revocable shows up on the keys page, and it only ever lands in the account of someone who was signed into the dashboard at the moment they clicked **Allow**. ## Files - Served only through signed URLs valid for 24 hours. The URLs are not guessable and not listable. - Scanned for malware before they are made available. A file whose scan errors or times out is **withheld**, not served unscanned. - Every file carries a SHA-256 checksum, computed on receipt and returned with the results, so you can verify that what you downloaded is what the client uploaded. - Stored in Cloudflare R2 with the EU jurisdiction restriction. ## Webhooks The endpoint you register receives every event on the account, so it is treated as an account-wide decision: only the account owner can add, remove or test one, and creating one issues a signing secret shown once. - Every delivery is signed: `X-BriefGate-Signature: t=,v1=` over `.`. Verify it before trusting a payload. - The target address is re-resolved and re-checked **immediately before each request leaves the box**, not only at registration. Checking only at registration is a time-of-check/time-of-use gap: a hostname that resolved to a public address then can resolve to `169.254.169.254` now. - Private, loopback, link-local and unique-local ranges are refused, in both their IPv4 and IPv6-mapped spellings. - Redirects are not followed, so a redirect cannot walk the request into a private address. - Each attempt times out after 10 seconds; the response body is drained to a 4 KB cap so a hostile endpoint cannot exhaust memory. - Six attempts with exponential backoff (1 min, 5 min, 30 min, 2 h, 6 h between attempts), then the delivery is marked failed and can be sent again by hand from the dashboard. - `410 Gone` from your endpoint deactivates it — the documented way to unsubscribe from the receiving end. The payload never contains a portal link. A portal link is a bearer credential into your client's intake, and a chat channel usually has more readers than the intake does. ## Where the data is | | | |---|---| | Application and database | netcup GmbH, Nuremberg, Germany | | Files | Cloudflare R2, EU jurisdiction restriction | | Transactional email | Resend (US) — EU-U.S. Data Privacy Framework and SCCs 2021/914 | | SMS, only if you enable it | Twilio (US) — same basis | | Payments | Stripe (US) — billing data only, never client data | | Error monitoring | Sentry / Functional Software, Inc. (US) — EU data residency, held in Germany | The full list, with the transfer basis for each, is in the [Data Processing Agreement](./dpa.md). ## Retention and deletion - Default: contents removed 150 days after completion. Configurable from 1 to 3650 days, per account or per intake. - `retention.mode: "on_delivery"` removes contents roughly 24 hours after your agent collects the results — the moment the second copy on our server stops being a service and starts being a liability. Use it for anything with credentials in it. - `DELETE /v1/intakes/:id` removes the intake, every submitted value, every file in R2 and the whole reminder history, immediately and irreversibly. - Deleting your account marks it immediately and completely; the purge runs after 30 days. - Backups are encrypted with `age` to a public key before they leave the host, so the machine that writes a backup cannot read it back, and the private half is not kept on that machine. They are held for 14 days, which is the window in which deleted data can still exist in a backup. ## Auditing Sensitive operations are written to an append-only audit log recording the actor, the action, the IP address and the timestamp: secret reveals, key creation and revocation, seat changes, logins. The application exposes no path that deletes from it. You can read your own account's log in the dashboard or through `GET /v1/audit`. ## Abuse and rate limits - API requests: 60, 600 or 3000 per hour depending on plan. - Invitations are capped per account per hour (30 on every plan), and — on the Free plan — also per account per **day** (10 invitations per UTC day; no daily cap on Solo, Studio, or Agency). Manual reminders have their own, separate caps: 1 per intake per hour and 20 per account per hour, on every plan — they are not part of the daily invitation cap. Neither the API nor the dashboard can be used to send mail at someone from our domain. Hitting an invitation cap while creating an intake leaves it as a draft (`invitation_sent: false`) instead of failing the call; hitting one while sending an existing draft returns a `429` and the draft stays a draft — either way, the response says so rather than silently not sending. - A sender name or custom e-mail wording may not contain a link (web address, bare domain, or e-mail address), on any plan — the only link in a BriefGate e-mail is the portal button. Custom sender name and e-mail wording are themselves a paid-plan feature (see [Billing](./billing.md#custom-branding)); the Free plan uses a built-in sender identity instead, so a Free account cannot put an arbitrary brand name in the From line. - Reminders respect quiet hours and stop on a hard bounce or spam complaint — a bounced address is never chased again. ## Error monitoring Application errors are reported to Sentry (Functional Software, Inc.), with EU data residency — events go to `de.sentry.io` and are held in Germany. What is sent: the error type and stack trace, the request method and path (query strings stripped), the request id, and the account id when known. What is never sent: request bodies, cookies, `Authorization` headers or API keys, email addresses (scrubbed to `[email]`), anything a client submitted, or secret values. In the browser, only unhandled JavaScript errors in the dashboard and portal, and failed API calls (status code only, no response body) are reported — there are no breadcrumbs, and the URL's query string is stripped before anything is sent. Sentry retains events for up to 90 days. ## Tracking Next to none. The marketing site counts page views with Cloudflare Web Analytics, which sets no cookie and stores no identifier in the browser (privacy notice §12). Beyond that: no tag manager, no session recording, no advertising pixel — and nothing at all in the dashboard or in the client portal beyond the error monitoring described above. The only cookies are the ones that make sign-in and the portal session work; they are listed in the [Privacy Policy](./privacy.md). ## Reporting a vulnerability Email **privacy@briefgate.dev** with enough detail to reproduce it. You will get a human reply. Please do not run automated scanners against the production service or test against another customer's account or portal — report it and it will be checked properly. --- ## Billing and Plans URL: https://briefgate.dev/docs/billing # Billing and Plans Most of what follows is for a human at the dashboard, not for an agent: `POST /v1/billing/checkout`, `POST /v1/billing/portal`, `POST /v1/billing/addons/*`, and `POST /v1/team/*` all require a signed-in dashboard session (a browser cookie) — an MCP agent's API key cannot call them. The one billing endpoint an agent can call directly is `GET /v1/usage`, which accepts either a session or an API key. Upgrading, paying, and inviting teammates all have to happen through the dashboard UI. ## Plan comparison | Feature | Free | Solo | Studio | Agency | |---|---|---|---|---| | Monthly price | $0 | $29 | $50 | $79 | | Active intakes | 1 | 15 | 30 | 60 | | Items per intake | 10 | Unlimited | Unlimited | Unlimited | | Seats | 1 | 1 | 1 | 3 | | Storage | 1 GB | 25 GB | 50 GB | 100 GB | | API rate limit | 60 req/h | 600 req/h | 1,500 req/h | 3,000 req/h | | Secrets vault | No | Yes | Yes | Yes | | Item revisions | No | Yes | Yes | Yes | | Custom branding | "Powered by BriefGate" + referral link | Your logo + colors, no referral link | + [Custom portal domain](./custom-domains.md) | + [Custom portal domain](./custom-domains.md) | | [Custom sending domain](./custom-domains.md) | No | No | Yes | Yes | | Chase schedules | default, off | All (gentle/default/aggressive/custom/off) | All | All | | Templates | 7 public (Czech-language) | 7 public + custom | 7 public + custom | 7 public + custom + team-shared | | Invitations per day | 10 | No daily limit | No daily limit | No daily limit | | Support | Community | Email, 48h | Priority email, 24h | Priority email, 24h | | Annual billing | — | $23.20/mo (–20%) | $40/mo (–20%) | $63.20/mo (–20%) | Annual billing is charged as a single upfront payment. The per-month figures above show the effective monthly cost. Studio is for one person who needs the agency features — own domain, priority support — without paying for seats. It carries every Agency capability except extra seats and the larger quotas: both custom domains are available, and support gets the same 24h priority target. The daily invitation cap is separate from, and on top of, the account-wide limit of **30 invitations per hour** that applies on every plan (see [POST /v1/intakes/:id/send](./rest-api.md#post-v1intakesidsend)) — Free is bound by whichever of the two it hits first. ## Custom branding Custom branding covers everything a client sees that would otherwise identify BriefGate instead of you: your **logo**, **accent color**, **sender name**, and the **wording** of the invitation and reminder emails (`email_copy` — see [Chase engine](./chase.md#writing-your-own-subject-and-intro)). All four are gated together, on the account (`PATCH /v1/account`) and per intake (`branding`/`email_copy` on `define_intake`/`POST /v1/intakes`). On the Free plan, client emails and the portal use a built-in sender identity instead of a name you choose — "Your developer" in English, "Váš dodavatel" in Czech (localized to the client's own language), shown together with the account owner's verified login email, e.g. `Your developer (jan@firma.cz)`. The From line reads `Your developer via BriefGate`. A Free account's own `brand_sender_name`/`email_copy` change is refused with `402 plan_required` (reason `custom_branding`); a per-intake `sender_name`/`email_copy` value is still accepted and stored, but is not used while the account is on Free — it takes effect automatically if the account later upgrades. Links are never allowed in a sender name or in custom email wording, on any plan — a web address, a bare domain (`example.com`), or an email address is rejected with a validation error. The portal button is the only link BriefGate ever puts in one of these emails. Custom text is also always rendered as plain text: HTML written into a sender name or into `email_copy` shows up as literal text to the client, never as markup. ## Add-ons | Add-on | Price | Plan | |---|---|---| | Extra storage | +50 GB for $5/month | Solo, Studio, Agency | | Additional Agency seat | +$15/seat/month | Agency | | SMS credit pack | 50 SMS credits per pack | Studio, Agency | ### Changing extra storage Storage renews with the plan, so it is a line item on the existing subscription rather than a separate purchase. Set how many 50 GB blocks you want: ``` POST /v1/billing/addons/storage ``` ```json { "blocks": 2 } ``` The change applies immediately and Stripe prorates it. `{ "blocks": 0 }` removes the add-on. Requires an active paid subscription. ### SMS credit packs SMS credits are metered per message, so a pack is a one-off Stripe purchase rather than a subscription line item — buy more whenever you run low. Available on Studio and Agency, since `sms` is a Studio and Agency feature: ``` POST /v1/billing/addons/sms-credits ``` ```json { "packs": 2 } ``` Response: ```json { "url": "https://checkout.stripe.com/c/pay/cs_live_...", "packs": 2, "credits": 100 } ``` Each pack is 50 credits (1–20 packs per purchase). Redirect the user to `url` to complete payment; credits are granted once Stripe confirms the payment via webhook, not from this response. A plan without the `sms` feature gets `plan_required`; a deployment without SMS sending configured (no Twilio credentials) refuses the purchase outright, since selling credits it cannot deliver would be taking money for nothing. ### Extra seats Seats are bought with the plan — pass `seats` to `POST /v1/billing/checkout`, or change the quantity later from the billing portal. A yearly plan bills seats yearly, because every recurring item on one subscription has to share a billing interval. A seat is a person who signs in to the dashboard. Clients never take one: they open their request through the link they were emailed and never get an account at all. Buying a seat does not fill it — invite someone into it from **Settings → Team**, or: ``` POST /v1/team/invites { "email": "colleague@example.com" } ``` They get an email with a one-time link, set their own password, and land in the same account with the `member` role. Members can see and run intakes; only the owner can invite, remove people, change billing or delete the account. Pending invitations count against the seat quota, so a stack of unopened invitations cannot reserve the same seat twice over. `GET /v1/team` returns the current roster and anything still pending; `GET /v1/usage` reports `seats.used` against `seats.limit`. Removing someone (**Settings → Team**, or `DELETE /v1/team/members/:id`) ends their sessions immediately and frees the seat. The owner cannot be removed. ## Upgrading Start a checkout session via API: ``` POST /v1/billing/checkout ``` ```json { "plan": "solo", "interval": "monthly" } ``` Response: ```json { "url": "https://checkout.stripe.com/c/pay/cs_live_..." } ``` Redirect the user (or open the URL in a browser) to complete payment via Stripe. After payment, the plan is active immediately and existing intakes are not affected. For annual billing, set `"interval": "yearly"`. Add `"seats": 2` to include extra Agency seats in the same checkout (Studio is a single seat and does not accept this parameter). The Stripe Checkout page accepts promotion codes. There is no API parameter for them — the person completing the checkout enters the code on the Stripe page. Current public code: `AGENT20` — 20% off subscription invoices for the first 3 months. On annual billing that means 20% off the first annual payment. ## Managing your subscription Open the Stripe Customer Portal to change plan, update payment method, or cancel: ``` POST /v1/billing/portal ``` Response: ```json { "url": "https://billing.stripe.com/session/..." } ``` Portal sessions expire after 5 minutes. Generate a new one if the user does not use it in time. EU/CZ consumers also have a statutory 14-day right of withdrawal, separate from this cancellation flow — see `docs/terms.md`. It is handled by `GET /v1/billing/withdrawal` (preview what a withdrawal right now would refund) and `POST /v1/billing/withdraw` (record it and cancel the subscription); both are dashboard-session-only, owner or member. ## Checking usage Works with either a dashboard session or an API key — no extra scope required. ``` GET /v1/usage ``` Returns current period usage against your plan limits: ```json { "tier": "solo", "active_intakes": { "used": 7, "limit": 15 }, "storage": { "used_bytes": 3221225472, "limit_bytes": 26843545600 }, "seats": { "used": 2, "limit": 2 }, "sms_credits": 0, "subscription": { "active": true }, "rate_limit_per_hour": 600, "invites_per_day": null, "features": { "secrets_vault": true, "revisions": true, "sms": false, "custom_branding": true, "custom_domain": false, "custom_templates": true }, "chase_schedules": ["default", "gentle", "aggressive", "custom", "off"] } ``` `active_intakes` counts intakes in `draft`, `sent`, or `in_progress` status. Completed and archived intakes do not count toward the limit — and a draft counts, deliberately, so an intake being assembled across several tool calls still occupies its slot. `subscription.active` tells you whether this is a real, paying Stripe subscription rather than a tier granted directly (comped, or set by an operator) — from the limits alone the two look identical. `features` mirrors the same feature flags as `GET /pricing.json`, but scoped to what this specific account can actually use right now. `invites_per_day` is the account's daily cap on invitation emails, or `null` when there is none — `10` on Free, `null` on Solo, Studio, and Agency. It is independent of `rate_limit_per_hour` (the API request limit) and of the 30-invitations-per-hour cap that applies on every plan. `chase_schedules` is what `chase_schedule` on `POST /v1/intakes` and `PATCH /v1/intakes/:id` will actually accept right now — on the Free plan that is `["default", "off"]`; see [Chase engine](./chase.md#schedules). ## Machine-readable pricing Agents can fetch current pricing without scraping the landing page: ``` GET https://api.briefgate.dev/pricing.json ``` No authentication required. Returns the `TIER_LIMITS` object with all plan features and numeric limits. The response is cacheable for 5 minutes (`Cache-Control: public, max-age=300`) and CORS is open, so any origin can fetch it directly. ## Data retention - Default: data is retained **150 days** after `intake.completed`, then automatically purged (files + submitted values) - Configure retention per account: ``` PATCH /v1/account {"retention_days": 365} ``` Valid range: 1 to 3650 days. - For immediate deletion of a specific intake (including all files in R2 storage): ``` DELETE /v1/intakes/:id ``` This is irreversible. The intake, all submitted values, all files, and all chase history are removed. For full account deletion, contact support. All data is removed within 30 days. ## If a payment fails Nothing is deleted, and nothing is switched off immediately. When Stripe reports a subscription as `past_due` or `unpaid`, the account keeps its plan and every add-on for a **14-day grace period**, so a card that expired over a weekend does not cost anyone their work. You will know about it: every owner on the account gets an e-mail the moment the grace period starts, with the amount that failed, the date the grace period ends and a one-click link to update the card in the Stripe customer portal. The dashboard shows the same warning as a banner on every page until the payment goes through, and a second e-mail confirms when it does. Stripe keeps retrying the card on its own during those two weeks (Smart Retries) and sends its own payment-failed notice as well. `GET /v1/auth/me` and `GET /v1/account` expose the state as `billing_grace_until` (ISO date or `null`) and `billing_grace_expired`, so an agent can surface it too. If the grace period ends without the payment succeeding, free-tier limits start applying to **new** intakes only. Intakes that already exist keep running: clients can still submit, reminders still go out, and results stay retrievable. Paying restores the plan on the next Stripe event, with nothing to restore manually. Data is only ever removed by the retention policy on an intake, by an explicit delete, or by account deletion — never by a failed payment. --- ## Rate Limits URL: https://briefgate.dev/docs/rate-limits # Rate Limits ## Limits by tier | Tier | Requests per hour | |---|---| | Free | 60 | | Solo | 600 | | Studio | 1,500 | | Agency | 3,000 | The window is a fixed clock hour: the counter resets at the top of every hour, not 60 minutes after your first request. A burst just before the hour and another just after therefore both go through. The counter belongs to the **account**, not to the individual API key. Issuing more keys does not raise your quota — all keys on an account draw from the same hourly budget. ## The 429 response When you exceed your limit, BriefGate returns HTTP 429: ```json { "error": "rate_limited", "message": "Rate limit of 60 requests/hour for the free plan reached. Retry after 1847s, or reduce polling frequency — use webhooks instead of polling get_intake_status in a loop.", "request_id": "req_abc123" } ``` The `Retry-After` response header contains the number of seconds to wait before retrying. Respect this header rather than polling with a fixed interval. ## The agent-loop problem Agents running in a loop can exhaust the Free plan's 60 req/h limit in minutes if they call `get_intake_status` on every iteration. An agent checking status every 5 seconds makes 720 requests per hour — 12x the Free limit. The correct approach is **webhooks**. Register a webhook endpoint for `intake.completed` and `item.submitted`. BriefGate calls your endpoint when something changes. You call BriefGate only when you need to act on a change. With webhooks: - Zero polling requests while waiting for client action - Near-instant notification when the client submits - Agent wakes up, calls `get_intake_results` once, continues building Register a webhook endpoint: ```bash curl -X POST https://api.briefgate.dev/v1/webhooks \ -H "Authorization: Bearer bg_live_xxxxx" \ -d '{"url":"https://yourapp.com/webhooks","events":["intake.completed","item.submitted"]}' ``` See [Webhooks](./webhooks.md) for the full setup guide. ## Recommended polling intervals If webhooks are not available for your deployment (e.g., running locally without a public URL), poll at these maximum rates to stay within limits with headroom for other API calls: | Tier | Maximum poll frequency | |---|---| | Free | Once every 5 minutes | | Solo | Once every 30 seconds | | Studio | Once every 15 seconds | | Agency | Once every 12 seconds | Use `ngrok` or a similar tunneling tool to expose a local webhook endpoint during development. ## Rate limit scope Rate limits are per **account**, not per API key. - Every key on the account draws from the same hourly counter, so creating more keys does not raise the limit - Use separate keys for different agent sessions and CI pipelines anyway: each can be revoked on its own, and the keys page shows which one was used last - Create additional keys at `GET /v1/keys` (list) and `POST /v1/keys` (create), or sign a tool in without pasting a key (see the quickstart) ## Invitation limits (a separate thing from the above) Everything above is about API *requests*. Sending a client an invitation is counted separately: 30 per account per hour on every plan, plus a Free-only cap of 10 per UTC day (`invites_per_day` in `GET /pricing.json`; `null` — no daily limit — on Solo, Studio, and Agency). When either is hit, `POST /v1/intakes` still creates the intake, as an unsent draft with `invitation_sent: false`, while `POST /v1/intakes/:id/send` answers `429` — see [POST /v1/intakes](./rest-api.md#post-v1intakes) and [POST /v1/intakes/:id/send](./rest-api.md#post-v1intakesidsend). Reminders sent by hand have their own cap: one per intake and 20 per account per hour. --- ## GDPR and Data Privacy URL: https://briefgate.dev/docs/gdpr # GDPR and Data Privacy ## EU data residency All data is processed exclusively in the EU. - **Application servers**: netcup GmbH, Nuremberg, Germany - **File storage**: Cloudflare R2 with EU jurisdiction policy — files are stored only in EU-region buckets - No data leaves the EU under any circumstances related to storage or primary processing ## What we store | Category | Contents | |---|---| | Intake metadata | Project name, client email, item definitions, timestamps | | Submitted values | Text, structured data, color lists, booleans, URLs | | File references | R2 object keys, filenames, MIME types, file sizes | | Secrets ciphertext | Encrypted blobs only — plaintext is never stored | | Audit log | Actor, IP address, action, timestamp | | Chase history | Sent reminders, delivery status, bounce records | Client IP addresses collected during portal access are stored alongside the session and audit records they belong to (`portal_sessions`, `sessions`, `audit_log`) and are used only for deduplication, rate limiting and fraud signals. They are never included in webhook payloads. ## Data retention - **Default**: 150 days after `intake.completed`, then automatic purge of all files and submitted values - **Configurable per account**: `PATCH /v1/account {"retention_days": N}` — valid range is 1 to 3650 days - **Configurable per intake**: the `retention` object on `define_intake` (below) - **Immediate deletion**: `DELETE /v1/intakes/:id` — removes the intake, all submitted values, all R2 files, and chase history immediately and irreversibly - **Account deletion**: removes all intakes, files, and personal data within 30 days of the request ### Delete as soon as the agent has the files Ninety days is a long time to keep a client's photos and admin password after your agent already downloaded them. If an intake holds anything sensitive, set retention to `on_delivery`: ```jsonc { "project_name": "Website for John Finance", "client": { "email": "john@example.com" }, "retention": { "mode": "on_delivery" }, // + optional "anonymize": false "items": [ /* … */ ] } ``` The contents are then removed roughly 24 hours after `get_intake_results` returns a completed intake — the point at which you have the files and a second copy on our server is liability rather than service. | Field | Default | Meaning | |---|---|---| | `mode` | `"days"` | `"days"`: purge N days after the client finishes. `"on_delivery"`: purge shortly after you collect the results. | | `days` | account setting (90) | Days to keep after completion. Only valid with `mode: "days"`. | | `anonymize` | `true` | Keep the project record and delete everything belonging to the client. `false` deletes the whole intake. | Two guarantees worth knowing: - **An intake you never collect still expires.** `purge_at` is set the moment the client completes, from the day count. Delivery only ever brings that date *forward*, so `on_delivery` can never turn into "kept forever" on a project you abandoned. - **There is a grace window** of 24 hours. If your agent crashed between reading the response and writing the files to disk, you can ask again. Without it, one crash would mean asking the client to do the work twice. ### What `anonymize: true` actually removes | Deleted | Kept | |---|---| | Files (from R2), secrets, submitted values | Project name, creation and completion dates | | Client email, name, phone | Item keys, labels, types, statuses | | Magic token — the portal link stops working | Chase history (counts and timestamps) | | Live portal sessions | Audit log entries | What remains is the record *you* need — "I asked for 7 things on 15 July, all delivered by the 20th" — holding nothing of your client's. Set `anonymize: false` if you want even that gone. ## Subject rights Under GDPR, your clients (as data subjects) have rights over their personal data. As the data controller, it is your responsibility to honor these requests. BriefGate provides the following API support: **Right to access**: `GET /v1/audit?client_email=owner@bellacucina.cz` returns all interaction records tied to that email address across your account. **Right to erasure**: `DELETE /v1/intakes/:id` removes all data for a specific intake. For complete erasure of a client across all intakes, filter by `client_email` and delete each intake. Contact support for bulk erasure. **Right to portability**: Submitted data is available via `GET /v1/intakes/:id/results` as structured JSON and signed file URLs. Export as needed before the retention period expires. BriefGate does not provide a separate "export my data" endpoint for end clients (your clients). Providing data subject access is your responsibility as data controller. ## Data controller and processor relationship | Role | Party | Obligations | |---|---|---| | Data controller | You (the developer / agency) | Decide what data to collect, from whom, and for what purpose | | Data processor | BriefGate | Process data on your instructions, implement technical safeguards | A **[Data Processing Agreement (DPA)](./dpa.md)** is in force from the moment you create an account — Article 28(9) GDPR allows it to be concluded electronically, so no signature is needed. It adopts the European Commission's standard contractual clauses for controllers and processors (Decision (EU) 2021/915) unmodified. It documents: - Categories of data processed - Processing purposes - Security measures - Sub-processor list - Data subject rights procedures ## Subprocessors | Subprocessor | Role | Location | Legal basis | |---|---|---|---| | netcup GmbH | Application hosting | Germany (EU) | No transfer | | Cloudflare, Inc. | File storage (R2 EU jurisdiction) | US company, EU data | Data Privacy Framework + SCCs | | Plus Five Five, Inc. (Resend) | Transactional email delivery | US | Data Privacy Framework + SCCs | | Twilio Inc. | SMS delivery (optional add-on) | US | Data Privacy Framework + SCCs | | Stripe, LLC | Payment processing | US | Data Privacy Framework + SCCs | | Functional Software, Inc. (Sentry) | Error monitoring — never client-submitted content | US company, EU data residency (Germany) | Data Privacy Framework + SCCs | Each US subprocessor is an active participant in the EU-U.S. Data Privacy Framework **and** incorporates the standard contractual clauses of Decision (EU) 2021/914 — both bases are kept so that a change to the adequacy decision does not interrupt the transfer. See the [DPA](./dpa.md) for the detail; that page is the authoritative list. ## Security measures | Measure | Implementation | |---|---| | Secret values | libsodium sealed box encryption before storage | | File access | Signed R2 URLs with 24-hour validity — URLs are not guessable | | Passwords | argon2id hash | | API keys | argon2id hash — plaintext never stored after creation | | Transport | TLS 1.2+ for all connections | | Audit log | Immutable append-only log for sensitive operations | | Key isolation | Secrets private key never stored in the database | --- ## Data Processing Agreement URL: https://briefgate.dev/docs/dpa # Data Processing Agreement **Version 1.1 — in force from 6 September 2026** This Data Processing Agreement ("DPA") is entered into between the account holder ("Customer", the controller) and Radim Sekera, operating BriefGate ("BriefGate", the processor), and forms part of the Terms of Service. **It becomes binding when the Customer creates a BriefGate account.** No signature is required: Article 28(9) GDPR provides that the contract "shall be in writing, including in electronic form", and acceptance at sign-up satisfies that. BriefGate records which version of this DPA was accepted, by which user, and when; the Customer can retrieve that record at any time from account settings or by asking support. Where a Customer's own compliance process requires a countersigned copy, ask support and one will be issued naming the same terms. --- ## 1. Adoption of the Commission's standard contractual clauses BriefGate does not use bespoke processing terms. This DPA adopts, in full and unmodified, the **standard contractual clauses between controllers and processors set out in the Annex to Commission Implementing Decision (EU) 2021/915 of 4 June 2021** (the "Clauses"). That decision is used deliberately. Article 1 of it states that those clauses "fulfil the requirements for contracts between controllers and processors in Article 28(3) and (4)" of the GDPR — so compliance follows from the instrument itself rather than from anyone's drafting. Clause 2(b) permits their inclusion in a broader contract, which is what this DPA does. Where the Clauses offer a choice, the following applies: | Clause | Selection | |---|---| | Clause 1(a) | **Option 1** — Regulation (EU) 2016/679 (GDPR) | | Clause 5 (Docking clause) | Not applied | | Clause 7.7 (Sub-processors) | **Option 2** — general written authorisation, with 30 days' prior notice of changes (section 2 below) | Annexes I to IV of the Clauses are completed by Annexes I to IV of this DPA and form an integral part of it. In the event of a conflict between the Clauses and any other agreement between the parties, **the Clauses prevail** (Clause 4). The full text of the Clauses is published in the Official Journal at [eur-lex.europa.eu/eli/dec_impl/2021/915](https://eur-lex.europa.eu/eli/dec_impl/2021/915/oj/eng). ## 2. Sub-processors The Customer gives BriefGate general written authorisation to engage the sub-processors listed in Annex IV. BriefGate will notify the Customer in writing at least **30 days** before adding or replacing a sub-processor. The Customer may object within that period on reasonable data-protection grounds. If BriefGate cannot offer an alternative, the Customer may terminate the affected part of the service without penalty for the remaining prepaid term. BriefGate imposes on each sub-processor, by contract, data protection obligations equivalent to those in this DPA, and remains fully liable to the Customer for their performance (Clause 7.7(b) and (d)). ## 3. International transfers The Clauses do not by themselves cover transfers outside the EEA — Clause 1(f) says so expressly — so this section governs them. All storage and primary processing takes place in the EU. Application servers run at netcup GmbH in Nuremberg, Germany; files are stored in Cloudflare R2 buckets carrying the EU jurisdiction restriction. Transfers do occur to the US-based sub-processors named in Annex IV. For each, the transfer rests on the **EU-U.S. Data Privacy Framework** adequacy decision (Commission Implementing Decision (EU) 2023/1795), each of those companies being an active participant, **and additionally** on the standard contractual clauses adopted under Commission Implementing Decision (EU) 2021/914, which each of them incorporates into its own processing terms. Both bases are maintained on purpose, and the 2021/914 clauses apply on their own terms regardless of the status of the adequacy decision. That decision is currently subject to an appeal before the Court of Justice (Case C-703/25 P, following the General Court's dismissal of the action in Case T-553/23 on 3 September 2025), and its supervisory-independence premise has also been questioned following the US Supreme Court's decision in *Trump v. Slaughter* (29 June 2026). Should the adequacy decision cease to apply, the 2021/914 clauses continue to cover the same transfers without interruption, and BriefGate will notify Customers rather than let a transfer continue without a valid basis. ## 4. Assistance, breaches, and audits **Data subject requests.** The Customer is the controller and answers requests from its own clients. BriefGate will not respond to a data subject directly, and will notify the Customer promptly of any request it receives (Clause 8(a)). `GET /v1/audit?client_email=…`, `GET /v1/intakes/:id/results` and `DELETE /v1/intakes/:id` exist so that access, portability and erasure requests can be answered without BriefGate's involvement. **Personal data breaches.** BriefGate will notify the Customer without undue delay after becoming aware of a breach affecting data it processes, with the information listed in Clause 9.2, sent to the account's registered email address. Where all facts are not yet available the first notice will carry what is known and the rest will follow. **Audits.** BriefGate will make available the information necessary to demonstrate compliance (Clause 7.6(c)). Where that is not sufficient for the Customer's obligations, an audit may be carried out by the Customer or an independent auditor at reasonable notice, no more than once a year except where there are indications of non-compliance. ## 5. Deletion and return On termination the Customer chooses whether personal data is deleted or returned; absent a choice within 30 days, it is deleted (Clause 10(d)). Results remain retrievable in machine-readable form through `GET /v1/intakes/:id/results` until then. During the term, retention follows what the Customer configures: 150 days after completion by default, adjustable between 1 and 3650 days, or removal roughly 24 hours after the Customer collects the results (`retention.mode: "on_delivery"`). `DELETE /v1/intakes/:id` erases an intake, its files and its chase history immediately and irreversibly. Backups are encrypted and retained for 14 days, so data erased on request may persist in an encrypted backup for up to that period before ageing out. --- ## Annex I — List of parties **Controller (data exporter):** the Customer, as identified by the account record — the account name, the registered email address of the owning user, and any other users the Customer authorises. The Customer's acceptance of the Terms of Service constitutes its signature for the purposes of the Clauses, on the date the account was created. **Processor (data importer):** Radim Sekera, trading as BriefGate. Contact for data protection matters: privacy@briefgate.dev. Acceptance of a Customer account constitutes BriefGate's signature. Neither party has designated a data protection officer; neither meets the criteria in Article 37(1) GDPR. ## Annex II — Description of the processing **Categories of data subjects** - The Customer's own clients — the people invited to a portal to supply project material, and any individual identifiable from what they submit. - The Customer's users — the people who hold seats on the account. **Categories of personal data** | Category | Contents | |---|---| | Client contact data | Email address; name where supplied; telephone number where SMS reminders are used; time zone; language preference | | Submitted content | Whatever the Customer's item definitions request: text, structured values, colours, URLs, boolean answers, and uploaded files. Files may contain personal data the Customer did not anticipate — photographs of identifiable people, documents naming third parties — because the client chooses what to upload | | Credentials | Values submitted to `secret` items — passwords, API keys, hosting logins — held only as libsodium sealed-box ciphertext | | Account user data | Name, email address, argon2id password hash, session records | | Technical records | IP addresses attached to sessions, portal sessions and audit entries; timestamps; delivery status and bounce records for reminders | **Sensitive data.** BriefGate does not request data of the special categories in Article 9 GDPR and none of its item types is designed to collect it. It cannot be excluded that a client uploads a file containing such data on their own initiative. Where the Customer knows an intake will involve special-category data it must say so before creating it, so that additional safeguards can be agreed. The measures in Annex III — encryption at rest, access confined to signed URLs, audit logging of every reveal, configurable short retention — apply to all uploaded content regardless. **Nature of the processing.** Collection, storage, validation, structured retrieval, transmission of reminder emails and optional SMS, and erasure — carried out on the Customer's documented instructions, which are given through the API and the account settings. **Purpose.** To let the Customer request project material from its clients, chase the client until it arrives, and return it to the Customer in a structured form. **Duration.** For the term of the Customer's account, and thereafter as set out in section 5. Per-intake retention is as configured by the Customer. **Frequency.** Continuous for the duration of the agreement. ## Annex III — Technical and organisational measures Described concretely, as the explanatory note to the Clauses requires. **Encryption of personal data** - Values submitted to `secret` items are encrypted on receipt with a libsodium sealed box and are never written to disk in plaintext. The private key exists only in the server environment and is never stored in the database, so a complete database dump yields ciphertext alone. - Account passwords are stored as argon2id hashes. API keys and portal tokens are high-entropy random values stored as SHA-256 digests; the plaintext of an API key is shown once at creation and is never retained afterwards. - All connections use TLS; certificates are issued and renewed automatically. - Database backups are encrypted with `age` to a public key before they leave the host, so the machine that writes a backup cannot read it back. **Access control and authorisation** - Client access to a portal is by a single stable magic link per intake, whose token is stored hashed and is valid for a configurable number of days (default 30) counted from the most recently sent invitation or reminder. It is exchanged for a session cookie scoped to that one intake and valid for 14 days. - Files are served only through signed URLs valid for 24 hours; the URLs are not guessable and are not listable. - A `secret` value is released once. The retrieval token is invalidated on first reveal, and the API key used must carry the `secrets:read` or `admin` scope. A five-minute window after the first reveal allows the same key to repeat the same read, so that a request lost in transit does not cost the Customer the value; any read after that window returns the time of the reveal, not the value. - Login and sign-up are limited to 10 attempts per hour per IP address. - API requests are limited per key and per plan (60, 600 or 3000 per hour). **Storage and residency** - Application servers: netcup GmbH, Nuremberg, Germany. - Files: Cloudflare R2 with the EU jurisdiction restriction, which confines objects to buckets in the EU. **Integrity and event logging** - Sensitive operations are written to an append-only audit log recording the actor, the action, the IP address and the timestamp. The application exposes no path that deletes from it. - Uploaded files are scanned for malware before they are made available. A file whose scan errors or times out is withheld rather than served unscanned. - Every uploaded file carries a SHA-256 checksum, computed on receipt and returned with the results, so the Customer can verify that what it received is what the client sent. **Data minimisation and limited retention** - Item definitions are declared by the Customer, so only the data the Customer asked for is collected. - Default retention is 150 days after completion; `retention.mode: "on_delivery"` removes contents roughly 24 hours after the Customer collects the results, with a grace window so that one crashed agent does not force the client to do the work twice. - `anonymize: true` deletes everything belonging to the client while keeping the Customer's own project record. - IP addresses are used only for deduplication, rate limiting and fraud signals, and are never included in webhook payloads. **Assistance to the controller** The API endpoints named in section 4 are the mechanism by which BriefGate assists with data subject requests. For breach notification, the contact is the account's registered email address. **Measures not in place.** BriefGate holds no ISO 27001 or SOC 2 certification and commissions no external penetration test. It is operated by one person. This is stated because a compliance assessment should rest on what exists. ## Annex IV — List of sub-processors | Sub-processor | Role | Location | Basis for transfer | |---|---|---|---| | netcup GmbH | Application and database hosting | Germany (EU) | No transfer — processing stays in the EU | | Cloudflare, Inc. | File storage (R2, EU jurisdiction), website delivery | US company, data held in the EU | EU-U.S. Data Privacy Framework (active) and SCCs 2021/914 | | Plus Five Five, Inc. (Resend) | Transactional email delivery | US | EU-U.S. Data Privacy Framework (active) and SCCs 2021/914 | | Twilio Inc. | SMS delivery, only where the Customer enables it | US | EU-U.S. Data Privacy Framework (active) and SCCs 2021/914 | | Stripe, LLC | Payment processing — Customer billing data only, never client data | US | EU-U.S. Data Privacy Framework (active) and SCCs 2021/914 | | Functional Software, Inc. (Sentry) | Error monitoring — application error events only, never client-submitted content | US company, EU data residency (Germany, `de.sentry.io`) | EU-U.S. Data Privacy Framework (active) and SCCs 2021/914 | **Google sign-in.** Where a Customer chooses to sign in with a Google account, Google processes that sign-in as its own controller under its own terms, not on BriefGate's instructions, and receives no client data. It is named here for completeness rather than as a sub-processor under this Agreement. Participation in the Data Privacy Framework was verified against the official list at [dataprivacyframework.gov](https://www.dataprivacyframework.gov/list) on 26 August 2026. The current list of sub-processors is this page; changes are notified as set out in section 2. --- The English text of this DPA governs. Translations are provided for convenience and, where they differ, the English version prevails. --- ## About & Contact URL: https://briefgate.dev/docs/about # About BriefGate BriefGate is a client intake platform. It asks a client for the files, information, structured answers and credentials a project needs, and hands the answers back to whoever is running the project — from the dashboard in your browser, or through an AI coding agent over MCP or REST. See [what is BriefGate?](./what-is-briefgate.md) for the longer version. ## Who runs it BriefGate is operated by **Radim Sekera**, a Czech sole trader (OSVČ) trading as "BriefGate" — IČO 04217764, registered address Kostelní 2022/18, 741 01 Nový Jičín, Czech Republic. This is a one-person product, built and supported by the same person you'd reach at the email addresses below. See the [Terms of Service](./terms.md) for the full legal entity details. ## Contact - **Support** (product questions, bugs, billing): [support@briefgate.dev](mailto:support@briefgate.dev) - **Privacy and data protection** (GDPR requests, the DPA, security reports): [privacy@briefgate.dev](mailto:privacy@briefgate.dev) ## Where to find BriefGate - **npm**: [@briefgate/mcp](https://www.npmjs.com/package/@briefgate/mcp) - **GitHub**: [briefgate-mcp](https://github.com/sekera-radim/briefgate-mcp) (MCP client), [n8n-nodes-briefgate](https://github.com/sekera-radim/n8n-nodes-briefgate) (n8n community node) - **Writing**: [dev.to/briefgate](https://dev.to/briefgate) - **Listing**: [SaaSHub](https://saashub.com/briefgate-dev) - **Video**: [YouTube](https://www.youtube.com/@briefgate) - **MCP server directories**: [Glama](https://glama.ai/mcp/servers/sekera-radim/briefgate-mcp), [MCP Servers](https://mcpservers.org/servers/sekera-radim/briefgate-mcp), [M8ven](https://m8ven.ai/mcp/sekera-radim/briefgate-mcp), [MCP Market](https://mcpmarket.com/server/briefgate), [LobeHub](https://lobehub.com/mcp/sekera-radim-briefgate-mcp), [Smithery](https://smithery.ai/servers/sekera-radim/briefgate) ## Also by the same maker [Impri](https://impri.dev/) is a human-in-the-loop approval inbox for AI agents: when an agent is about to do something that should not happen without a person saying yes, it asks in Impri and waits. Open-core, with MCP and REST, by the same one-person team. ## Legal - [Terms of Service](./terms.md) - [Privacy Policy](./privacy.md) - [Data Processing Agreement](./dpa.md) - [Security](./security.md) --- ## Terms of Service URL: https://briefgate.dev/docs/terms # Terms of Service **Version 1.0 — in effect since 1 September 2026.** These are the operator's approved terms and the version presented for acceptance at sign-up. They describe how BriefGate actually operates; where a clause turns on a business judgment rather than a rule — the liability caps and their carve-outs in §9 — that judgment is the operator's and is stated plainly rather than hidden. --- ## 1. Who these terms are with BriefGate is operated by **Radim Sekera**, a Czech sole trader (OSVČ) trading as "BriefGate" (IČO: 04217764, registered address: Kostelní 2022/18, 741 01 Nový Jičín, Czech Republic). These Terms of Service ("Terms") are a contract between Radim Sekera ("BriefGate", "we", "us") and the person or organization that creates a BriefGate account ("Customer", "you"). BriefGate is a SaaS product for requesting, chasing, and structurally collecting project material ("intakes") from a Customer's own clients, used mainly by developers and agencies together with an AI agent over MCP or the REST API. See [briefgate.dev](https://briefgate.dev) and the [docs hub](./quickstart.md) for what the product does. BriefGate is open to both **business customers** and **consumers** (an individual acting outside their trade, business, or profession). Section 11 of these Terms applies only to consumers and gives you rights that a business customer does not have under Czech law. ## 2. Order of precedence Three documents govern the relationship, in this order when they conflict: 1. The **[Data Processing Agreement](./dpa.md)** ("DPA"), for anything touching the processing of personal data on your instructions. 2. These **Terms of Service**, for everything else commercial. 3. The **[Acceptable Use Policy](./acceptable-use.md)** ("AUP"), which these Terms incorporate by reference and which fills in the detail of what you may and may not do with the service. A provision in the AUP that a court read as conflicting with these Terms is read subject to these Terms; a provision in these Terms that conflicts with the DPA on a data-processing matter is read subject to the DPA. ## 3. The Data Processing Agreement and roles For your clients' personal data submitted through an intake, BriefGate processes it solely on your documented instructions and you are the **controller**; BriefGate is the **processor**. That relationship, the sub-processors, the security measures, and your rights and obligations as controller are set out in full in the [DPA](./dpa.md) and are **incorporated into these Terms by reference** — this document does not restate them, and where it touches the same ground the DPA's wording controls (§2). For your own account data — the information you give us to create and run your account, described in the [Privacy Notice](./privacy.md) — BriefGate is itself the **controller**, not your processor. The Privacy Notice, not the DPA, governs that data. ## 4. Accounts You must provide accurate information when creating an account and keep your login credentials confidential. You are responsible for activity under your account and API keys, including activity by team members you invite onto an Agency seat. Tell us promptly if you believe an API key or account has been compromised; BriefGate is not liable for loss arising from a key or password you failed to keep confidential. You must be able to form a binding contract to create an account: 18 or over, or otherwise the relevant Czech age of legal capacity. ## 5. The service BriefGate lets you define an "intake" (a set of items — text, files, images, colors, structured data, credentials, etc.), send it to your client through a hosted portal, chase them automatically by email, and retrieve the structured results via the REST API or MCP. The current feature set, item types, and plan-gated capabilities are described in the [docs hub](./quickstart.md); this section is not an exhaustive functional spec and the docs, not these Terms, are the place that changes as the product does. ## 6. Plans, pricing, and payment Current plans, prices (monthly and yearly), and what each plan includes are published at [briefgate.dev/pricing](https://briefgate.dev/#pricing) and via the machine-readable `GET /pricing.json` endpoint, and are **not repeated here** — those pages are the source of truth and these Terms would only go stale if they duplicated the numbers. What follows are the terms of sale that apply to whatever price is shown there at the time you buy. - Prices are quoted in **US dollars**. - Both **monthly** and **yearly** billing intervals are offered; yearly is charged as a single upfront payment. Subscriptions **auto-renew** for a further term of the same length unless cancelled before the renewal date. - Add-ons (extra storage, extra Agency seats) are billed as described on the pricing page and in the [billing docs](./billing.md). - **Price changes.** BriefGate may change plan prices or what a plan includes for future terms. If we do, the price you are currently paying is **locked for the remainder of your current paid term** — a change never applies retroactively to a period you have already paid for. We will give you reasonable notice (at least 30 days) before a price or limit change takes effect on your next renewal, so you can cancel before it does. - **Taxes.** BriefGate is operated by a Czech sole trader who is not registered for VAT. The prices shown are therefore final — no VAT is added at checkout. If that changes, it will be reflected in the prices shown and communicated the same way as any other change to these Terms (§12). ## 7. Cancellation, non-payment, and termination **Cancellation by you.** Cancel any time from the billing portal (`POST /v1/billing/portal`). Access continues until the end of the period you have already paid for; there are no partial refunds for the unused portion of a period. At the end of that period your account reverts to the Free plan — nothing is deleted (see the next paragraph). **Non-payment.** If a renewal payment fails, Stripe marks the subscription past-due and BriefGate gives you a **14-day grace period** during which your plan, limits, and features stay exactly as they were — nothing is downgraded or restricted while we wait for you to fix your payment method. If payment still has not succeeded when the grace period ends, **Free-plan limits then apply to creating new intakes** (you cannot start a new active intake beyond what Free allows). This is the full extent of what non-payment does: **existing intakes keep running exactly as before, and nothing is deleted.** Paying successfully at any point — during the grace period or after — restores your paid plan's limits immediately. **Termination by BriefGate.** We may suspend or terminate your account for material breach of these Terms or the AUP, including the grounds for suspension set out in the [AUP](./acceptable-use.md#4-suspension-and-termination). Where the breach is capable of being fixed and does not involve active harm to third parties (spam, abuse, illegal content), we will give you notice and a reasonable opportunity to fix it first. Where it does involve active harm — in particular the grounds a Resend compliance flag can trigger — we may suspend the affected intake, sending capability, or account immediately and notify you afterward. **Effect of termination.** Sections 8, 9, and 10 survive termination. Data handling on termination (deletion vs. return, and the timeline) is governed by the DPA (§5) and the [GDPR page](./gdpr.md), not restated here. ## 8. Intellectual property **Yours.** You own the content you put into BriefGate: your intake definitions, item schemas, chase message templates and copy, your logo and branding, and the data your clients submit through your intakes. Nothing in these Terms transfers ownership of any of that to BriefGate. **Ours.** BriefGate owns the BriefGate software, API, portal, documentation, and the BriefGate name and marks. Your subscription grants you a non-exclusive, non-transferable right to use the service for your own business during the term — not a license to the underlying software. ## 9. Liability Nothing in this section limits liability that cannot be limited under Czech law, including liability for death or personal injury caused by negligence, fraud, or fraudulent misrepresentation. Subject to that, BriefGate's total liability to you arising out of or in connection with these Terms is limited to the amount you paid BriefGate in the 12 months before the claim arose, and BriefGate is not liable for indirect, incidental, or consequential loss, or loss of profit, revenue, or data, except as follows — three situations get their own, separate treatment because a single blanket cap would either under- or over-protect depending on whose fault the loss actually was: **(a) A security failure affecting the secrets vault.** If plaintext of a `secret`-type item is exposed because of a failure in BriefGate's own vault implementation (the sealed-box encryption, key handling, or the one-time reveal logic described in the [secrets docs](./secrets.md)) rather than because of how you configured or used it, BriefGate's liability for that specific incident is not capped by the general limit above and instead follows the breach-notification and remedy provisions of the DPA. This carve-out does not extend to a secret you retrieved and then mishandled yourself, or to a key compromised through your own account. **(b) Harm arising from your own chase content or your own recipients.** BriefGate is a delivery mechanism you configure. We are not liable for the content of the chase emails you write, for whether you had a lawful basis to contact a given recipient (that is squarely your obligation under the [AUP](./acceptable-use.md)), or for any claim a recipient brings against you arising from a message you chose to send them. This includes complaints, regulatory action, or third-party claims arising from your own use of the sending capability. **(c) Data lost through your own retention settings or a DELETE your own API key issued.** Retention (`retention_days`, `retention.mode` on an intake) and `DELETE /v1/intakes/:id` are configuration and API calls that only your account or an API key you issued can make, and each is documented as irreversible where it says so. BriefGate is not liable for data lost because a retention setting expired as configured, or because an API key you issued — whether used by you, your agent, or someone who obtained the key through your own failure to keep it secret — called a delete or purge endpoint. If you believe BriefGate deleted something outside of what you configured or requested, that is not within this carve-out and is treated as an ordinary claim under the general limit above. ## 10. Service levels and delivery **No uptime guarantee.** BriefGate does not currently offer a service level agreement with uptime commitments or service credits. Support response times are stated per plan on the [pricing page](https://briefgate.dev/#pricing) and in the [billing docs](./billing.md) as **target first-response times, not guarantees** — they describe what we aim for, not a commitment backed by a remedy, and missing one does not entitle you to a credit or refund. **Reminder delivery is best-effort.** Chase emails are sent through a third-party provider (currently Resend) and their delivery, speed, and inbox placement depend on that provider, on spam filtering at the recipient's end, and on factors outside BriefGate's control. We do not guarantee that a reminder is delivered, read, or delivered within any particular time, and BriefGate is not liable for a project delay caused by a reminder that did not arrive. ## 11. Consumer rights (Czech Republic) This section applies only if you are a **consumer** — a natural person entering this contract outside your trade, business, or profession — under Czech Act No. 89/2012 Coll., the Civil Code ("NOZ"). If you are acting for a business (including as a sole trader, freelancer, or agency), this section does not apply to you and the ordinary commercial terms above govern instead. **Pre-contractual information (§ 1811 and § 1820 NOZ).** Before you complete a purchase, BriefGate provides — through this document, the pricing page, and the checkout flow — its identity and contact details (§1 above), the main characteristics of the service (§5), the total price including how it is billed (§6), the duration of the contract and how to terminate it (§7), and the information required by § 1820 NOZ on withdrawal, complaints handling, and out-of-court dispute resolution (below). If any required item is missing from this set, contact us before purchasing and we will provide it. **14-day right of withdrawal.** As a consumer you may withdraw from the contract without giving a reason within **14 days** of concluding it. The easiest way is the **"Withdraw from the contract" button on the Billing page** of your dashboard, which records your withdrawal, cancels your subscription immediately, and sends you a written acknowledgement; a clear statement by email is equally valid. You never have to give a reason, and the reason field on that form is optional. Where you have not invoked the immediate-access waiver below, withdrawing entitles you to a refund of amounts paid, without undue delay and using the same payment method you used, within 14 days of us being notified. The 14 days run from the day your paid subscription starts, which is the day your payment completes. The dashboard shows that date and the resulting deadline, and it keeps showing them after the deadline has passed. A withdrawal sent after the deadline is still recorded and we will come back to you on what can be refunded — the button does not stop working. **Waiver for immediate access to digital content (§ 1837 písm. l) NOZ, implementing Article 16(m) of Directive 2011/83/EU).** BriefGate is a digital service delivered immediately on payment — your account is upgraded and usable the moment checkout completes, not after 14 days. Before you can start a paid checkout from the dashboard you are asked to say whether you are buying **for your business** or **as a private individual**. Nothing is pre-selected and the upgrade button does not work until you choose. - Choosing "for my business" records this declaration: *"I am buying BriefGate in the course of my business, trade or profession, and not as a consumer."* This section then does not apply to you. - Choosing "as a private individual" offers a **separate, unticked** checkbox, which is the waiver. Ticking it records this consent: *"I expressly ask BriefGate to start providing the paid plan immediately, before the 14-day withdrawal period ends, and I acknowledge that I lose my right to withdraw from the contract once the service has been fully performed."* The waiver is never bundled into accepting these Terms, is never pre-ticked, and can be left untouched: leaving it unticked does not block the purchase. What it changes is when the plan begins. Tick it and the plan starts as soon as your payment clears. Leave it unticked and **the plan starts, and the first payment is taken, only after the 14 days have passed** — until then you keep the free plan, you are charged nothing, and you can withdraw at no cost at all. That is the honest consequence of not asking us to begin: we do not begin. Ticking the box as a business declaration has no effect — a business has no withdrawal right to waive. **What you get back if you withdraw.** Where the plan started immediately at your request and you then withdraw, you pay for the days you had it and we refund the rest (§ 1834 NOZ). A day begun counts as a day used. Where the plan had not started yet, nothing has been charged and there is nothing to refund. The dashboard shows you the figure before you confirm, and the refund goes back to the card you paid with. We store the exact sentence you agreed to, along with the date and the checkout it belongs to, and the dashboard shows that sentence back to you on the Billing page. A purchase made through the REST API or MCP, where there is no form to declare on, is recorded as undeclared and treated as a consumer purchase **without** a waiver — the full 14 days apply. **Complaints and out-of-court dispute resolution.** For a complaint about the service, contact us first (see §1). If a dispute is not resolved directly, a consumer resident in the Czech Republic may bring it to the **Czech Trade Inspection Authority (Česká obchodní inspekce, ČOI)**, ústřední inspektorát, Štěpánská 567/15, 120 00 Praha 2, [www.coi.cz](https://www.coi.cz), the competent body for out-of-court consumer dispute resolution under Czech law. *BriefGate does not use the EU Online Dispute Resolution (ODR) platform — the European Commission permanently discontinued it on 20 July 2025 — and does not reference it as an option.* ## 12. Changes to these Terms We may update these Terms to reflect changes in the service, the law, or how we operate. For a change that materially reduces your rights or increases your obligations, we will give at least 30 days' notice by email to your account's registered address before it takes effect; continuing to use BriefGate after that date constitutes acceptance. Other changes (clarifications, typo fixes, matching a DPA update) take effect on posting. ## 13. General **Governing law.** These Terms are governed by the law of the Czech Republic, without prejudice to any mandatory consumer-protection provisions of the country where a consumer Customer is habitually resident. **Severability.** If a provision is found unenforceable, the rest of these Terms remain in effect and the unenforceable provision is read as narrowly as needed to make it enforceable. **Assignment.** You may not assign these Terms without our consent. We may assign them in connection with a merger, acquisition, or sale of substantially all of the BriefGate business, on notice to you. **Force majeure.** Neither party is liable for delay or failure caused by events beyond its reasonable control. **Entire agreement.** These Terms, the DPA, and the AUP are the entire agreement between you and BriefGate regarding the service and supersede prior discussions on the same subject. **Contact.** Questions about these Terms: privacy@briefgate.dev for data-protection matters (see the [Privacy Notice](./privacy.md)), or support@briefgate.dev for everything else. --- ## Privacy Notice URL: https://briefgate.dev/docs/privacy # Privacy Notice **Version 1.7 — in effect since 13 October 2026.** This notice describes BriefGate's actual data handling as implemented in the product. Every cookie, retention period, and recipient named below was checked against the running code rather than written from intent; where a period or a lawful basis rests on a judgment rather than on a number in the code, the judgment is stated here instead of being left implicit. This is the notice linked from the Google OAuth consent screen and from your account settings. It is addressed to **you, the account holder** — the person who signs up for and uses BriefGate — under **Article 13 of the GDPR**. If you are looking for how BriefGate handles **your own clients'** data (the people you send an intake to), that is a separate relationship in which you, not BriefGate, are the controller. It is covered in depth in the [GDPR page](./gdpr.md), which this notice cites rather than repeats in §6 below. ## 1. Who is the controller For the personal data described in this notice, the controller is: **Radim Sekera**, trading as BriefGate (a Czech sole trader / OSVČ). IČO: 04217764. Registered address: Kostelní 2022/18, 741 01 Nový Jičín, Czech Republic. Contact for data protection matters: **privacy@briefgate.dev**. BriefGate has not designated a data protection officer; it does not meet the criteria in Article 37(1) GDPR that would require one. ## 2. What data we collect about you | Category | Examples | Source | |---|---|---| | Account identity | Name, email address, Google account identifier (if you sign in with Google), password hash (argon2id) if you use a password | You, at sign-up | | Session and authentication | `bg_session` cookie value, session creation/expiry timestamps, IP address and browser user-agent string at login | Generated when you sign in | | Billing | Stripe customer ID, subscription status and tier, invoices — card numbers are handled by Stripe and never reach BriefGate's servers | You, via Stripe Checkout/Portal | | Account configuration | Retention settings, branding, custom domain, API keys (hashed), webhook URLs, team members you invite | You | | Usage and audit | Actions you take (login, key creation, secret reveals, intake operations), IP address, timestamp, in the append-only audit log | Generated by the product | | Support communication | Anything you send us when asking for help | You | | Sign-up attribution | Which campaign link brought you to the sign-up page (`source`, `medium`, `campaign`, `content`, `term`, `gclid`) | The address of the page you followed to sign up, captured once at sign-up | Providing your name, email address, and a means of signing in is a contractual requirement: without them there is no account and BriefGate cannot provide the service. Billing details become necessary only if you move to a paid plan. Everything else in the table above is either generated by the product as you use it or optional — declining it costs you the feature it belongs to, nothing more. This is distinct from the data your own clients submit through an intake (their contact details, files, and any secret credentials) — that data is described in the [GDPR page](./gdpr.md), and BriefGate is your processor for it, not its controller (see the [DPA](./dpa.md)). ## 3. Why we process it, and the lawful basis | Purpose | Data used | Lawful basis (Art. 6 GDPR) | |---|---|---| | Create and operate your account, provide the service you subscribed to | Account identity, configuration, sessions | Performance of a contract (6(1)(b)) | | Billing and invoicing | Billing data | Performance of a contract (6(1)(b)); statutory retention is a legal obligation (6(1)(c)) | | Keep the service secure — rate limiting, fraud and abuse signals, audit trail | Session/login IP addresses, audit log | Legitimate interest (6(1)(f)) — protecting the service and other customers from abuse | | Respond to support requests | Support communication | Performance of a contract (6(1)(b)) / legitimate interest (6(1)(f)) | | Measure which campaign or post brought a sign-up | Sign-up attribution | Legitimate interest (6(1)(f)) — understanding what marketing works, read only by the operator | | Comply with legal obligations (tax, accounting, lawful requests from authorities) | Billing and account records | Legal obligation (6(1)(c)) | BriefGate does not currently run marketing email campaigns to account holders; if that changes, any marketing communication will be sent only on the basis of your consent (6(1)(a)) or an equivalent narrow legitimate interest with an opt-out, and this notice will be updated to say so before it happens. ## 4. Cookies | Cookie | Purpose | Who it's set for | Lifetime | |---|---|---|---| | `bg_session` | Keeps you signed in to the BriefGate dashboard | You, the account holder | 30 days (configurable by the operator) | | `bg_portal` | Keeps a client's portal session active while they work through an intake | Your client, on the intake portal — not you | 14 days | | `bg_oauth_flow` | Ties a Google sign-in back to the browser that started it, so someone else cannot finish your sign-in | You, only during a Google sign-in | 10 minutes | | `bg_lang` | Remembers whether you are reading briefgate.dev in English or Czech | Anyone visiting the marketing site | 1 year | That is the complete list — BriefGate sets no others, on any of its sites. They are strictly necessary or plain preference cookies: they keep you (or your client) authenticated, protect a sign-in in progress, or remember a language. None is used for advertising, analytics, or cross-site tracking (the cookieless page-view measurement on the marketing site is described in §12), there is no tag manager or session recording anywhere in the product, and Czech/EU cookie-consent rules do not require a consent banner for cookies of this kind. `bg_portal` is listed here for completeness because it is set by BriefGate infrastructure, even though the person it identifies is your client, not you — your clients' use of the portal is covered under your own privacy notice to them, which is your responsibility as controller (see the [GDPR page](./gdpr.md), "Subject rights"). ## 5. How long we keep your account data - **Account and configuration data**, including sign-up attribution: for as long as your account is active, plus a period after closure to handle any outstanding billing, dispute, or legal-hold need. - **Billing records (invoices, payment records)**: kept for the period Czech tax and accounting law requires — in practice at least three years from the end of the tax period concerned, and longer where accounting or VAT rules extend it. This is longer than the life of your account regardless of when you close it, and it is the one category that survives an erasure request. - **Audit log entries**: retained as part of the append-only security log described in the [GDPR page](./gdpr.md) and the [DPA](./dpa.md) Annex III; it is not deleted on request because its purpose is to provide a reliable record of account activity, including in the period around any dispute. - **Account deletion**: on request, BriefGate deletes your account and personal data within 30 days, save for what a legal obligation (billing records) requires it to keep. This is separate from **intake data** — the material your clients submit — whose retention you control per-account and per-intake as described in the [GDPR page](./gdpr.md) ("Data retention"). ## 6. Who we share it with - **Sub-processors who support the service**: netcup GmbH (hosting, Germany), Cloudflare, Inc. (storage/CDN), Plus Five Five, Inc. (Resend, transactional email), Twilio Inc. (SMS), Stripe, LLC (payments), Functional Software, Inc. (Sentry, error monitoring, EU data residency). Their role, location, and transfer basis are detailed in the [DPA](./dpa.md) (Annex IV) and the [GDPR page](./gdpr.md), which this notice incorporates by reference rather than duplicating a table that would then have to be kept in sync in two places. - **Google LLC**, if — and only if — you choose to sign in with a Google account. Google then processes that sign-in as its own controller under its own terms, not on BriefGate's behalf; it learns that you signed in to BriefGate. Signing in with an email address and password avoids this entirely. See the [DPA](./dpa.md) Annex IV, "Google sign-in". - **Legal and safety**: where required by law, to protect BriefGate's rights, or to investigate abuse of the service (see the [Acceptable Use Policy](./acceptable-use.md)). - **Your own clients, on the Free plan.** Without custom branding (Solo plan and up), the invitation and reminder e-mails and the client portal show your account's verified login e-mail address next to the built-in sender name, e.g. "Your developer (you@example.com)" — this happens even if you have set a different Reply-To address. It lets the client tell who is asking, in the absence of a sender name you chose yourself. This stops once the account has custom branding. - We do not sell your personal data, and we do not share it for third-party advertising. ## 7. International transfers Application processing happens in the EU (Germany); some sub-processors are US companies, and transfers to them rest on the EU-U.S. Data Privacy Framework together with the 2021/914 standard contractual clauses as a fallback. The detail — including the pending Court of Justice appeal noted against the adequacy decision — is in the [DPA](./dpa.md) §3, which is the authoritative statement for both this notice and the GDPR page. ## 8. Your rights As a data subject, you have the right to: - **Access** the personal data BriefGate holds about you. - **Rectify** inaccurate or incomplete data — much of this you can do yourself in account settings. - **Erase** your data ("right to be forgotten"), subject to the legal-obligation retention in §5. - **Restrict** processing in the circumstances set out in Article 18 GDPR. - **Port** your account data to yourself or another provider in a structured, machine-readable format. - **Object** to processing based on legitimate interest (§3). - **Withdraw consent** at any time, where processing is based on consent, without affecting processing carried out before the withdrawal. To exercise any of these rights, email **privacy@briefgate.dev**. We will respond within the time limits set by the GDPR (normally one month). We may ask you to verify your identity before acting on a request. **Right to lodge a complaint.** If you believe BriefGate has not handled your personal data lawfully, you have the right to complain to the Czech data protection authority: **Úřad pro ochranu osobních údajů (ÚOOÚ)** Pplk. Sochora 27, 170 00 Praha 7, Czech Republic [www.uoou.cz](https://www.uoou.cz) or to the supervisory authority of your own EU member state of residence, if different. ## 9. Automated decision-making BriefGate does not make any decision about you, based solely on automated processing, that produces legal or similarly significant effects for you within the meaning of Article 22 GDPR, and it does no profiling. To be precise rather than reassuring: rate limiting **is** automatic, and a request over the limit is refused by code with no human involved. What it does not do is decide anything about you as a person — it throttles a request, tells you when to retry, and lifts by itself. Closing, suspending, or refusing an account is a decision a human makes, and abuse signals only bring something to that person's attention. ## 10. Security The technical and organizational measures protecting your account data — encryption, access control, key isolation, audit logging — are the same ones described in detail in the [DPA](./dpa.md) Annex III, which applies to account data as much as to intake data. ## 11. Changes to this notice We will update this notice as the product or our processing changes, and post the new version here with an updated version number. Material changes will be notified to your account's registered email address. ## 12. If you are not an account holder Two groups of people reach BriefGate without ever signing up, and this notice covers them too. **Visitors to briefgate.dev.** The site measures page views with Cloudflare Web Analytics, which runs without cookies, without any identifier stored in your browser and without cross-site tracking; Cloudflare, Inc. processes the request metadata as our processor and we see only aggregate counts, referrers and pages. There is no advertising pixel and no session recording. The site sets one cookie, `bg_lang`, to remember which language you are reading in. Server logs at the hosting layer record ordinary request metadata, including IP addresses, and exist to keep the site available and to investigate abuse — legitimate interest, Article 6(1)(f). A link to the sign-up page may carry campaign parameters (such as `utm_source` or `gclid`) in its address; nothing is stored from these unless you go on to create an account, as described in §2 and §3. **People who open the public demo.** The demo at `/v1/demo` gives anyone a throwaway client portal without an account. Here BriefGate is the controller, not a processor for somebody else: your IP address is used to rate-limit how many demo portals one visitor can create, a `bg_portal` cookie keeps the session, and anything you type or upload is stored exactly as a real client's answers would be. The whole demo intake, files included, is **deleted within one day**, no reminder is ever sent, and no email address is collected. Do not put anything real into it — it is there to show you what your own clients would see. **Clients you send an intake to** are a different case again: for their data BriefGate is the processor and the account holder is the controller, so the notice that applies is the account holder's, not this one. See the [GDPR page](./gdpr.md). --- ## Acceptable Use Policy URL: https://briefgate.dev/docs/acceptable-use # Acceptable Use Policy This Acceptable Use Policy ("AUP") is part of the [Terms of Service](./terms.md) and governs how you may use BriefGate to contact people — your clients — who never agreed to any BriefGate contract. It exists because that is not a theoretical risk: when BriefGate sends a chase email through Resend on your behalf, **Resend holds BriefGate responsible for that traffic**, and a pattern of spam complaints or a provider compliance flag against BriefGate's sending infrastructure puts every customer's deliverability at risk, not just yours. This policy is how that responsibility is passed down to the account that actually wrote the message and chose the recipient. If there is a conflict between this AUP and the Terms of Service, the Terms govern (see their order-of-precedence clause). ## 1. You need your own lawful basis to contact your client BriefGate is a delivery and chasing mechanism. It has no relationship with your client and no way to know whether you are entitled to email them. **You are solely responsible for having your own lawful basis** — under GDPR, Czech law, CAN-SPAM, TCPA, or whatever regime applies to you and your recipient — for every address and phone number you put into an intake. In practice this means, at minimum: - You have an existing relationship with the person (they are your client, or someone who asked you for the quote/project the intake relates to). - You are not purchasing, scraping, or otherwise acquiring contact lists to push through BriefGate's chase engine. BriefGate is not a party to your engagement with your client and does not review individual intakes before they are sent. That review, when it happens, happens after the fact — from bounce/complaint signals (§3) or a provider flag — which is why this obligation sits with you up front rather than with us as a gate. ## 2. What you may not do with an intake Regardless of your lawful basis to contact someone, you may not use BriefGate to: - Send unsolicited bulk messages, or any message a reasonable recipient would call spam. - Contact someone who has unsubscribed, bounced, or asked you to stop — the chase engine already stops on a hard bounce or spam complaint (see the [chase docs](./chase.md)); manually working around that stop is a breach of this policy. - Impersonate another person or organization, or misrepresent who is asking for the material. - Send content that is illegal, fraudulent, defamatory, harassing, or that facilitates any of those. - Distribute malware, phishing links, or content designed to compromise a recipient's device or accounts, through any item type. - Use a `secret` or `file`/`file_list`/`image` item to collect data that is **unrelated to the stated project the intake is for**. Item labels and help text must accurately describe what is being collected and why; a "secret" item is for the credentials a project actually needs, not a general-purpose data-collection field, and a file item is for project deliverables, not an unrelated document drop. - Use the service to violate any applicable law, including data protection, anti-spam, and telecommunications law in your jurisdiction or your recipient's. - Attempt to circumvent BriefGate's rate limits, plan limits, or abuse detection. **How impersonation and bulk mail are limited technically**, not just by this policy: a sender name or custom e-mail wording may never contain a link — a web address, a bare domain, or an e-mail address — on any plan, because the only link that belongs in one of these e-mails is the portal button. On the **Free plan**, a custom sender name and custom e-mail wording are not available at all (that's part of custom branding, Solo plan and up): invitations and reminders go out under a built-in sender identity instead, with your account's verified e-mail address shown next to it. The Free plan is also capped at **10 invitation e-mails per UTC day**, on top of the 30-per-hour cap every plan has — see [Billing](./billing.md#custom-branding). ## 3. Bounces, complaints, and provider flags BriefGate monitors delivery signals from Resend, including hard bounces, spam complaints, and compliance flags raised by the provider against your sending activity. When one of these occurs: - The chase engine automatically stops sending to a bounced or complaint-flagged address on the affected intake (see the [chase docs](./chase.md)). - A pattern across multiple intakes or recipients, or a compliance flag raised by Resend itself against your account's traffic, is treated as evidence of a policy breach and reviewed by BriefGate, whether or not any single message looks clearly abusive in isolation — providers flag accounts on aggregate signals, and BriefGate has to respond at the same level to keep sending working for every customer. ## 4. Suspension and termination BriefGate may, at its discretion and proportionate to the issue: - Suspend chase sending on a **specific intake**, without suspending the rest of your account, where the signal is isolated to that intake. - Suspend an **entire account's** sending capability or access where the issue is account-wide, repeated, or where the provider (Resend) has flagged the account itself rather than one intake. - Terminate the account for a material or repeated breach of this policy, under the termination provisions of the [Terms of Service](./terms.md#7-cancellation-non-payment-and-termination). Where the risk is a live compliance flag from Resend threatening BriefGate's own sending reputation, we may act immediately and notify you afterward, rather than waiting for a cure period — the alternative is other customers' mail being throttled or blocked because of one account's traffic. For anything short of that, we will tell you what triggered the review and give you a chance to explain or fix it before suspending. Suspension for a policy breach does not entitle you to a refund for the suspended period, and does not pause billing — see the [Terms of Service](./terms.md#9-liability) on the customer's own chase content and recipients being outside BriefGate's liability. ## 5. Reporting abuse If you receive a chase email from a BriefGate customer that you believe breaches this policy — an unwanted message, a suspicious link, or a message unrelated to any project you agreed to — you can report it to **privacy@briefgate.dev**. Reports involving personal data are handled under the same process as any other data-protection contact (see the [Privacy Notice](./privacy.md)). ## 6. Relationship to provider terms Because BriefGate sends through Resend, your use of the email features is also subject to that provider's own acceptable use policy as it applies to traffic routed through BriefGate's accounts. A breach of the provider's policy through your use of BriefGate is treated as a breach of this AUP. --- ## Collect Files & Documents From Clients URL: https://briefgate.dev/docs/how-to-collect-documents-from-clients # How to Collect Files and Documents From Clients The fastest way to collect files or documents from clients is one list, sent once, with a deadline and a fixed reminder schedule — not a slow trickle of separate emails, transfer links, or shared-folder invites. The six steps below cover the full process, a comparison of the alternatives, and a checklist you can copy into your next project kickoff. ## Why this is the part that stalls projects Ask any freelancer or agency where a project actually loses time, and it is rarely the work itself. A five-page website is a few days of focused effort. What stretches that into six weeks is everything the project needs from someone who is not you: the logo file sitting in a folder on a laptop nobody has opened since 2019, the "about us" paragraph nobody has written yet, the hosting password that lives in an email thread from three providers ago. None of that is complicated to produce. It is just easy to postpone, because the client has a full-time job that is not "assemble files for my web designer," and your one request competes with everything else in their inbox. A single email that lists everything you need, sent once, is the single most common way this fails — not because clients are careless, but because a long list with no structure and no deadline reads as optional homework, and optional homework loses to whatever is due today. The fix is not asking harder. It is turning "please send me your stuff" into a process with a clear list, a clear deadline, and a system that follows up so you do not have to. ## A step-by-step process for collecting documents from clients ### Step 1: Write the exact list before you ask for anything Open the project brief or your own template and write down every distinct piece of information the project needs, at the level of "logo file," not "branding." A typical small business website needs somewhere between eight and fifteen concrete items once you count photos, copy sections, and technical access separately rather than lumping them together. If you find yourself writing "assets" as a single line, break it into what "assets" actually contains — a client cannot picture "assets," but they can picture a logo file and five photos of their storefront. This is also the moment to sort items into two buckets: what blocks you from starting, and what only blocks you from finishing. A logo and the site's basic copy usually block the start. A Google Analytics ID or a final round of photos often does not — you can wire up the tracking slot and swap in a placeholder image without losing a day. Decide this upfront, because it changes what you chase first (see the [full checklist](/docs/website-project-intake-checklist) for a category-by-category breakdown of what belongs in each bucket). ### Step 2: Ask once, in one place, with a deadline Send one request that contains the whole list, not a trickle of "oh, one more thing" emails over three weeks. A scattered request is what turns a ten-minute task for the client into a background dread they keep avoiding, because they can never be sure they have actually finished responding to you. Attach a deadline to the request, even an informal one — "if I have everything by the 14th, the first draft is ready the following week" gives the client a reason to act now rather than eventually. Tie the date to something they care about (their own launch date, a season, an event) rather than to your internal schedule, which means nothing to them. Where the request lives matters too. A list buried in the body of an email gets lost the moment the thread has six replies in it. A shared link — a form, a shared folder, or a small portal built for exactly this — that shows what is still outstanding survives longer than a scrolling inbox does. ### Step 3: Make it easy to answer, not just easy to ask Every item on your list should be answerable without homework. "Send your logo" is fine. "Send your brand guidelines" sends most small business owners into a shrug, because they do not have brand guidelines — they have a logo, maybe two colors, and a font they picked once in Canva. Ask for the artifact they actually have, not the deliverable a design agency would produce. For anything with a technical requirement — a minimum image width, a specific file format, a maximum file size — say so in the request itself, in plain language, rather than finding out after they upload a 200px logo. "SVG or PNG, at least 512 pixels wide" prevents a whole review-and-resend cycle that a vague "high resolution please" does not. ### Step 4: Follow up on a schedule, not on memory The single biggest point of failure in document collection is not the first request — it is the second one. People intend to reply and then the moment passes, and unless something nudges them again, it keeps passing. A sensible default is a reminder two or three days after the first request, another about a week later, then weekly until it is done or you have a reason to stop. Whether you do this by hand or with a tool, the reminder needs to say what is *still* missing, not repeat the entire original list — a client who has already sent the logo does not want to be asked for it again, and a reminder that ignores their progress reads as not having been read in the first place. This is the part manual processes tend to skip, because remembering exactly what came in and what did not, for every open project, does not scale past two or three clients at once. ### Step 5: Handle credentials differently from everything else Passwords, API keys, and hosting logins are not documents, and treating them like one is a real risk, not a formality. A password pasted into an email thread sits in plaintext in two inboxes and every backup of both, indefinitely, long after the project that needed it is over. If a client's email account is ever compromised, that thread is still there. At minimum, ask for credentials somewhere other than the body of an email — a password manager's one-time-share link is a low-effort improvement over plaintext. If you are collecting logins as a routine part of client work, a tool built around a one-time reveal (the value is shown once, to the person who asked for it, then gone) closes the gap that email leaves open; BriefGate's [secrets vault](/docs/secrets) is one implementation of that pattern for client credentials. ### Step 6: Confirm receipt and check quality before you build on it Getting a file is not the same as getting a usable file. A logo submitted as a low-resolution JPEG screenshot of a business card will look broken on a retina screen. A copy block twice your character budget will break a hero section's layout. Check what arrived against what you actually need before you build on top of it, and if something falls short, say exactly what is wrong and what you need instead — "this needs to be at least 512px wide, and if you have the original SVG that would be ideal" gets a usable file back far faster than "can you send a better one." ## A request checklist you can copy Adapt this to the project, but as a starting point, a typical client-facing project needs some version of each of these: - **Logo** — the actual file, not a screenshot of it. Ask for SVG or a large PNG. - **Brand colors** — hex codes if they have them; "the blue from our storefront sign" if they do not, plus a photo you can sample from. - **Key copy blocks** — homepage headline, a short "about" paragraph, anything with legally sensitive wording (pricing, policies, disclaimers) that should come from the client rather than be invented. - **Photos** — a minimum count and a minimum resolution, stated up front, not discovered after upload. - **Existing site or account access** — the current site's admin login, domain registrar access, any third-party accounts (analytics, email marketing, booking system) that the new work needs to connect to. - **Legal or compliance material** — a privacy policy, terms of service, or industry-specific disclosures if the project needs them; these should come from the client or their lawyer, not be drafted on their behalf without review. - **Business specifics** — opening hours, service area, pricing structure, anything that is a fact about their business rather than a design decision. For the fuller version of this list, grouped by category with a note on what to request before kickoff versus what can wait, see the [website project intake checklist](/docs/website-project-intake-checklist). ## Ways to collect files from clients, compared The six steps above work with any channel. Which channel fits depends on how many items you need, how often, and whether any of them is a password. - **Email attachments** — zero setup, and genuinely the fastest option for one or two items. It breaks down once a thread has six replies: nothing shows what's still missing, and nothing reminds the client if they forget. Pairing it with a shared Drive or Dropbox folder for anything email rejects is the most common upgrade — see [BriefGate vs. email and a shared drive folder](/docs/email-and-drive-alternative). - **File-transfer links** — handle large batches (full-resolution photos, video, a site backup) that email would bounce, but collect files only, with no checklist and usually a short expiry before the link and files disappear. - **Cloud-drive file requests and shared folders** — fit naturally if your team already lives in that drive; Dropbox's version is compared item-by-item in [BriefGate vs. Dropbox file requests](/docs/dropbox-file-requests-alternative). Neither handles credentials, and a shared folder specifically requires the client to have or create an account. - **Form builders** — add structure (files, text, and choices in one place) for a known, fixed list, but most expect a single submission rather than an ongoing checklist, upload-size caps are often tighter than a photo gallery needs, and a generic form field is not an encrypted credential store. [BriefGate vs. Google Forms, Typeform, and Jotform](/docs/google-forms-alternative-for-client-files) breaks down the specifics. - **Dedicated intake portals** — typed items instead of a folder, visible per-item progress, scheduled reminders, and, where the tool offers it, a one-time-reveal path for credentials (see Step 5 above). The tradeoff is more setup than firing off an email, and it's its own subscription to manage — not the right fit for a single file from a single person. BriefGate is one example of this category, alongside human-run tools like Content Snare; see [BriefGate vs. Content Snare](/docs/content-snare-alternative). | Situation | Best fit | |---|---| | One or two files, once, no follow-up needed | Email attachments | | A single large batch of files (photos, video, backups) | File-transfer link | | Ongoing files from a project that already lives in your team's cloud drive | Shared folder or cloud-drive file request | | A fixed, known list of mixed files and short answers, collected once | Form builder | | A recurring project type with more than five or six items | Dedicated intake portal, ideally from a saved template | | Any credential — a password, an API key, a hosting login | A tool with an encrypted, one-time-reveal secrets flow, not email or a generic form field | ## Common mistakes that slow this down **Asking for everything in the order it occurred to you**, rather than grouping it — a client scanning a disorganized list underestimates how long it will take and puts it off. **Not stating constraints up front** — file formats, size limits, character counts — so every submission needs a second round. **Chasing inconsistently** — a burst of reminders followed by weeks of silence trains the client to wait you out. **Collecting credentials the same way as everything else**, which is a security problem waiting for the day an inbox gets compromised. **Treating "sent" as "done"** without checking whether what arrived actually meets the brief. ## Frequently asked questions ### How do you get a client to actually send their content? Turn the open-ended ask into a short list of named items with a real deadline, put it behind one link instead of an email thread, and follow up on a fixed schedule that says exactly what's still missing. The six steps above cover the full sequence in detail. ### What do you do if a client never sends the logo? Give a real deadline tied to a consequence they care about — most stalls resolve once there's something concrete at stake. If it still doesn't arrive, work with what exists: a phone photo of a sign or business card is enough to sample brand colors from, and a text-only wordmark can stand in for a logo file without forcing a rebuild once the real one shows up. ### How do you collect passwords from clients safely? Never inside the body of an email or chat message — a compromised inbox exposes every message ever sent through it, not just the newest one. A password manager's one-time-share link is a reasonable minimum; a tool built specifically for a one-time credential reveal, shown once to the person who asked and then discarded, closes the gap that plaintext leaves open indefinitely. ### What's a good reminder schedule for missing files? A sensible default is a nudge two or three days after the first request, a more specific follow-up about a week later, then weekly until it's resolved. See [why clients don't send materials](/docs/why-clients-dont-send-materials) for the full four-checkpoint cadence and what to say at each one. ### Is it okay to just resend the same list every week? No — resending everything makes it look like their earlier progress wasn't noticed, which trains a client to stop bothering. Say specifically what's still outstanding each time, and acknowledge what already arrived. ## Where BriefGate fits Most of the process above works with nothing more than a shared folder, a spreadsheet, and discipline. Where it tends to break down is the middle: remembering what is still missing across several live projects, chasing without nagging, and keeping credentials out of your inbox. [BriefGate](/) is built for that specific gap — an AI coding agent (or you, from the dashboard) declares the list of items a project needs, the client gets one link with no account to create (your branding on paid plans), and BriefGate tracks what is submitted, chases what is not on a schedule you set, and hands back typed, validated data instead of a folder of mismatched files. It does not replace the judgment calls in this article — what to ask for, when it is needed by, whether what came back is good enough — it just takes the bookkeeping and the follow-up off your plate. See the [item types reference](/docs/item-types) for the full range of what it can collect, from a single logo to a structured set of opening hours. --- ## Web Design Brief Checklist URL: https://briefgate.dev/docs/website-project-intake-checklist # Web Design Brief Checklist: What to Ask the Client For A web design brief checklist covering everything a typical website project needs from the client, grouped by category, with a short reason for each item and whether it can wait until after kickoff. ## How to use this checklist This is a reference list, not a script — cut anything your project does not need and add anything specific to it. Every item below carries two things: a one-line reason it matters, and a rough call on timing, because not everything belongs in the same request. **Before kickoff** means the project cannot really start without it, or starting without it means redoing work later. **Can come later** means you can begin with a placeholder or a sensible default and swap in the real thing once it arrives, without losing time. Getting this split right is most of what makes an intake request feel reasonable instead of overwhelming — a list of twelve things due tomorrow reads very differently from four things due tomorrow and eight that can follow over the next two weeks. If you want the process this checklist plugs into — how to phrase the request, how to follow up, how to handle the items that never come back — see [how to collect documents and files from clients](/docs/how-to-collect-documents-from-clients). ## Identity and brand | Item | Why you need it | Timing | |---|---|---| | Logo file (SVG or high-res PNG) | A screenshot or a resized JPEG will not scale cleanly to a favicon, a retina header, or print. Ask for the source file, not an export someone made for a slide deck. | Before kickoff | | Brand colors (hex codes if they have them) | Guessing colors from a screenshot introduces drift the client will notice even if they cannot articulate why. If they do not have hex codes, a phone photo of something branded (a sign, a business card) is enough to sample from. | Before kickoff | | Typography preference, if any | Most small clients do not have a defined typeface and are fine with your recommendation — but ask, rather than assume, if they already use a specific font on printed material. | Can come later | | Existing style guide or brand book | Rare below a certain company size, but when it exists it settles a dozen small decisions (logo clear space, color usage, tone) that would otherwise be a back-and-forth. | Can come later | ## Content | Item | Why you need it | Timing | |---|---|---| | Homepage headline and intro copy | The single piece of text most likely to hold up a launch if it is missing, because it is also the hardest for a client to write — ask for it first and expect it to need a revision round. | Before kickoff | | Secondary page copy (about, services, etc.) | Structure and layout can proceed with placeholder text, but final copy changes line counts and section heights, so build it in once it exists rather than treating it as a drop-in swap at the end. | Can come later | | Photos (with a minimum count and resolution stated up front) | A phone photo at full resolution is almost always fine; a photo already resized for a Facebook post usually is not. State the minimum width in the request instead of finding out after upload. | Before kickoff for hero/key photos, later for the rest | | Team bios and headshots | Needed for an about or team page, rarely for the homepage — usually safe to leave for a later round. | Can come later | | Testimonials or reviews | Real client language outperforms placeholder copy by enough that it is worth a specific ask ("can you paste your three best Google reviews") rather than a generic "any testimonials?" | Can come later | | Video or other media assets | Often the last thing ready and the most negotiable — confirm whether the project actually needs it before treating it as a blocker. | Can come later | Copy deserves its own request rather than a single row on this table — it splits into page copy, SEO title/description, microcopy, and legal text, each with a different writer and a different deadline. See [website copy from clients](/docs/website-copy-from-clients) for how to ask for each piece. ## Technical access and integrations | Item | Why you need it | Timing | |---|---|---| | Current website admin login, if one exists | Needed to migrate content, redirect old URLs, or simply see what is there before replacing it. Ask for this as a credential, not a document — see the note on handling logins below. | Before kickoff | | Domain registrar access or DNS delegation | Launch day depends on this. Finding out the client does not have their own registrar login (an old developer registered it for them) two days before launch is a common and avoidable delay. | Before kickoff | | Hosting account access, if the project keeps existing hosting | Same reasoning as the registrar: confirm access exists before you need it, not when you need it. | Before kickoff | | Analytics tracking ID (e.g. Google Analytics) | Nice to wire in from day one, but a site can launch and collect a data gap of a few days without lasting damage — not worth delaying launch over. | Can come later | | Email marketing or CRM integration details | Usually a later-stage connection (newsletter signup, form routing) rather than a structural requirement of the site itself. | Can come later | | Third-party booking, payment, or scheduling accounts | If the site's core function depends on one of these (a restaurant's reservation system, a shop's payment processor), treat it as a launch blocker, not an integration to add later. | Before kickoff if launch-critical | Credentials deserve a different handling path than everything else on this list. A password sitting in an email thread is a standing liability, not a filed document — it stays readable in every backup of that inbox indefinitely. Collect logins somewhere built for a one-time handoff rather than in the body of a message; BriefGate's [secrets vault](/docs/secrets) encrypts a submitted credential and releases it once, to the person who asked, which is closer to how a password should travel than an email ever is. ## Legal and business | Item | Why you need it | Timing | |---|---|---| | Business name, address, and contact details exactly as they should appear | Small inconsistencies (a slightly different phone number in the footer versus Google listings) hurt local search and look sloppy. Get the exact, current version rather than assuming last year's version is still right. | Before kickoff | | Opening hours, service area, or other operational facts | These are facts about the business, not design decisions, and only the client can supply them correctly. | Before kickoff | | Pricing or service packages, if shown on the site | Ask whether this is meant to be public before designing a page around it — some businesses deliberately keep pricing off the website. | Before kickoff if the site will show it | | Privacy policy and terms of service | These carry legal weight and should come from the client or their lawyer, not be invented on their behalf, especially for a site that collects any personal data. | Can come later, but before launch | | Industry-specific disclosures (health, finance, legal, alcohol) | Requirements vary by sector and jurisdiction; flag early that this is the client's responsibility to confirm, not a default template will not cover it. | Before kickoff for regulated industries | | Sign-off on who has authority to approve the final site | On any project with more than one stakeholder, confirm this once at the start rather than discovering a second decision-maker after launch. | Before kickoff | ## Questions to ask before design starts The checklist above lists what to collect. Before any of it gets collected, a short set of judgment calls needs answering — not deliverables, but decisions that shape what the deliverables above should even look like. Skipping these is how a project discovers its real target audience, or its actual budget, in week five, after work has already gone in the wrong direction. ### Business and goals - **What should this site accomplish in the first six months?** Turns "make it look professional" into a measurable target — more bookings, fewer support calls, a credible presence for a funding pitch. - **What's the single action you want a visitor to take?** A phone call, a purchase, a booking, or a newsletter signup each changes how every page gets designed. - **Who are your two or three biggest competitors, and what do you like or dislike about their sites?** Gives real reference points instead of abstract style words, and often reveals a feature the client assumes is standard. - **What's driving this project now — a rebrand, a broken old site, a new business, something else?** The reason shapes what "done" looks like more than any brief does. - **What would make this project a failure, even if the site looks great?** Surfaces the one hidden requirement — a specific integration, a legal disclosure, a stakeholder's opinion — before it becomes a week-five surprise. ### Audience - **Who is your ideal customer?** The basis for every other content and design decision — a site for retirees and a site for university students shouldn't share a template. - **What device do most of your visitors use — mostly phone, or mostly desktop?** Tells you where to spend the mobile-testing time, rather than treating both equally by default. - **What questions do people ask before they buy or book with you?** This is the FAQ page and half the homepage copy, already written by the client without realizing it. - **What makes someone hesitate to choose you over a competitor?** The honest answer is worth more than any tagline — it tells you what the copy needs to overcome. ### Brand and style - **Name three websites you like the look of, and say why.** Concrete references settle arguments about taste far faster than adjectives do. - **Pick three words for how you want the brand to feel.** "Playful," "clinical," and "luxury" each rule out entire design directions before anything's been drawn. - **Any colors, fonts, or styles you specifically want to avoid?** Often more useful than what they want — a client with a strong opinion about a previous designer's choices will tell you. ### Timeline and expectations - **What's the budget range for this project?** Uncomfortable to ask, essential to know before scoping something the client can't afford — offer three tiers rather than asking for a number cold. - **How available will you be for feedback and approvals during the project?** A client who disappears for two weeks mid-project needs a different schedule than one who replies within the hour. - **Do you want ongoing maintenance and support after launch, or a one-time build?** Changes what "finished" means, and whether the relationship continues after the invoice is paid. ### How to ask these The deliverables in the checklist above work fine as an asynchronous form, because the client can look things up — their current hosting login, an old invoice with pricing. The questions in this section work better live: a written answer to "what feel do you want" tends to arrive short and vague ("modern, but not too corporate"), and only becomes useful once you can ask a follow-up ("modern like what, specifically?"). A practical split that works for most small web projects: send the checklist above as a form before kickoff, and save this section for a short call once the form is back. ## Frequently asked questions ### What should you ask a client before starting a website project? The short version: brand assets (logo, colors), core content (a homepage headline and key copy), technical access (the current site's login, domain registrar, hosting), and business facts (hours, address, pricing). The categories above break each one down further, with a note on what blocks the start versus what can wait. ### How many items should a client intake checklist have? Enough to be specific, not exhaustive — a typical small business site needs eight to fifteen distinct items once photos, copy sections, and technical access are counted separately instead of bundled under a vague heading like "assets." A shorter list of concrete asks gets answered faster than a longer list of vague ones. ### What if the client doesn't have brand guidelines or hex color codes? Most small clients don't. Ask for what they actually have: the logo file, and a phone photo of anything branded — a sign, packaging, a business card — that you can sample a color from. Waiting for guidelines that were never written just stalls the project. ### How do you collect login credentials from a client without emailing passwords? Never in the body of an email or chat message — it stays readable in every backup of that inbox indefinitely. A password manager's one-time-share link is a reasonable baseline for occasional use; across many client projects, a vault that encrypts the credential on the server and reveals it once, to the person who asked — BriefGate's secrets vault works this way — removes the risk of anyone forgetting to delete the email afterward. ### What if the client never sends the logo or key photos? Set a real deadline and say what happens if it's missed — most stalls resolve once there's an actual consequence attached. If it still doesn't arrive, fall back to what's available: a phone photo of a sign or business card is enough to sample brand colors, and a text-only wordmark can launch in place of a logo file without forcing a rebuild later. ### What's the difference between this checklist and an onboarding questionnaire? There isn't a separate page for one — the judgment-based questions that shape a project (goals, audience, brand feel, budget) are folded into [Questions to ask before design starts](#questions-to-ask-before-design-starts) above, so this one page covers both the concrete deliverables to collect and the decisions that shape them, instead of splitting them across two documents. ## Where BriefGate fits Turning this checklist into an actual request is the part most tooling skips: someone still has to send it, track what came back, chase what did not, and keep the credentials rows separate from everything else. [BriefGate](/) exists for that step. An AI coding agent — or you, from the dashboard — declares this list as typed items with the constraints above baked in (minimum image width, required versus optional, a schema for structured facts like opening hours), and BriefGate generates one branded client portal, sends the reminders on a schedule you choose, and hands back validated data instead of a folder of mismatched files and a stalled email thread. The [restaurant, advisor, and club website templates](/docs/templates) cover a version of this exact checklist pre-built for those three project types, so a recurring project type does not mean rebuilding the list from scratch each time. **Send this checklist to your client with BriefGate** — [start free](https://app.briefgate.dev/app/login?tab=signup&utm_source=docs&utm_medium=checklist-cta&utm_campaign=website-project-intake-checklist), no card required, and turn the table above into a portal with reminders instead of a one-off email (with your own branding from the Solo plan). --- ## Website Copy From Clients URL: https://briefgate.dev/docs/website-copy-from-clients # Website Copy From Clients: What to Ask For and How to Get It Every web project has a moment where the design is ready, the pages exist, and the only thing missing is the words to put in them. That moment lasts a lot longer than anyone plans for, because "send me your copy" is the vaguest request on the whole intake list, and it usually gets treated that way. ## What "copy" actually covers Copy is not one deliverable. It's at least four different kinds of text, and treating them as one request is why the client sends back a single paragraph and calls it done. - **Page copy** — the headline, subheadline, and body text for each page: homepage, about, services, contact. This is the one people think of first, and it's also the slowest to arrive. - **SEO title and meta description** — the `` tag and meta description for each page, shown in search results. Most clients don't know these exist as separate fields from the page text, so they need to be asked for explicitly, not folded into "the copy." - **Microcopy** — button labels, form field hints, error messages, empty states, confirmation text. Small, easy to skip, and the reason a finished site still feels unpolished when every field says "Submit" and every error says "Something went wrong." - **Legal text** — privacy policy, terms of service, cookie notice, any industry-specific disclosure. This one is not a copywriting task at all; it's a compliance document, and it has to come from the client or their lawyer, never invented on their behalf by whoever is building the site. Splitting the request this way also splits the timeline correctly. Page copy and legal text can take weeks; SEO fields and microcopy can be turned around in a day once someone sits down to do them. Asking for all four under one heading means the fast ones wait on the slow ones for no reason. ## Who should actually write it **The client** is the only source for anything factual: what the business does, who it's for, what makes it different, the legal documents, the exact wording of a guarantee or a policy. No one else can write this correctly, because no one else knows it. **A copywriter** earns their fee on persuasion and structure — turning what the client knows into a homepage that reads well and gets to the point. Worth it on anything client-facing and commercial; usually overkill for an internal tool's microcopy. **The agency or developer** should default to writing the small, low-stakes stuff: button labels, form hints, empty states, the boilerplate a site needs to not look broken. Writing the homepage headline on the client's behalf and hoping they'll correct it if it's wrong is a bad bet — most clients accept whatever they're handed rather than push back, and a fabricated fact then ships to production. **AI-drafted copy** is a legitimate first pass for structure and phrasing — a starting point that's faster to edit than a blank page. It is not a source of facts. An AI draft that states a founding year, a certification, or a price the writer invented to fill the sentence is worse than a blank field, because a blank field gets noticed and a plausible-sounding wrong fact doesn't. Draft with it, but every factual claim in the draft still needs a client to confirm or correct it before it goes live. ## How to ask, so the answer actually shows up The request that gets ignored is "can you send over your website copy." The one that gets answered names the field, gives a length, gives an example, and gives a date: - **Homepage headline** — one sentence, roughly 8–12 words, the thing you'd want someone to read if they only read one line. *Example: "Family-run Italian kitchen in the heart of Riverside, open since 2009."* Due before the design review. - **About page body** — 150–300 words: who you are, how you started, what makes the business different. Due one week after kickoff. - **Service or product descriptions** — 40–80 words per item, one paragraph each, written the way you'd describe it to a customer standing in front of you. Due alongside the photos for the same page. - **SEO title and description per page** — a title under 60 characters and a description between 120 and 160 characters, or "leave blank and I'll draft one for your review" if that's genuinely easier for the client. Due whenever the page copy is final, not before. - **Legal pages** — privacy policy and terms, from the client or their lawyer, or a note that they want a standard template reviewed instead. Due before launch, not before kickoff — this one can run in parallel with everything else. Each item on that list is answerable in one sitting. A client staring at "send your copy" doesn't know where to start and defers the whole thing; a client staring at "one sentence, 8 to 12 words, by Friday" either writes it in five minutes or replies asking a real question — both are progress. ## Structuring copy for a multi-page site The list above covers the four kinds of copy; on a site with more than a handful of pages, "page copy" itself still needs splitting down to the page level, or it comes back as one undifferentiated document. Ask per page, not per site: - **Page title and URL slug**, if the client cares about the exact wording — some do, for SEO reasons; most don't. - **Headline and subheadline** for every page past the homepage, same shape as the homepage item above. - **Body copy, broken into the sections the template actually has.** A page built from three content blocks should get three separate fields, not one paragraph the developer has to split up themselves — this matters most on page-builder platforms like WordPress, where each block is its own editable region. - **Images for that page specifically**, with a minimum count and dimension stated — "3–6 photos, minimum 1600px wide, for the services gallery," not "send some photos." - **Any embeds or third-party widgets the page needs** — a booking calendar, a map, a review feed — and whether the client already has an account with that service. A worksheet shaped this way maps directly onto how the page actually gets assembled, so content arrives ready to place instead of needing to be re-chunked by whoever builds the site. ## When it doesn't come in It won't all arrive on time, and the fix is not one more polite email. Two things work: **Break it smaller and chase what's actually missing.** A single "copy" request that's 80% done still shows as one unfinished item; five separate fields that are four-fifths done show as four checked boxes and one specific ask, which is both more honest about progress and easier to follow up on. A scheduled reminder that names the exact missing field lands better than a person having to remember to nag, and it's the kind of thing worth automating rather than carrying in your head across every open project. **Decide, in writing, what a missed deadline does to launch — before you're in one.** The two live options are: launch with a clearly-marked placeholder ("Copy coming soon — check back next week") and swap it in once it arrives, or hold the launch until the real text lands. What doesn't work, and happens more often than anyone admits, is shipping lorem ipsum or a copy-pasted competitor's paragraph because nobody wanted to be the one to delay launch — and then it sits there for months because fixing "temporary" text is nobody's job once the site is live and the invoice is paid. Decide which of the two real options applies to this project before the deadline arrives, not after it's already missed. ## Where BriefGate fits Turning the list above into an actual request is the part that usually lives in an email thread instead of a system: someone has to phrase each field, track what came back, and remind the client about the two things still missing without re-explaining the other three that are already done. An AI coding agent — or you, from the dashboard — declares each field as a typed item (`text` for the SEO title with a character limit, `longtext` for the about-page copy with a length range, `file` for the logo) with `define_intake`, and BriefGate generates one branded, no-account portal link for the client, sends the reminders on the schedule you pick, and hands back validated values instead of a half-finished email thread. Logins collected in the same request go in as `secret` items, which BriefGate encrypts on its server before they're stored — see [Secrets](/docs/secrets) for how that works. A fact with a fixed shape — opening hours, the registered legal business name for the footer and the privacy policy — goes in as a `structured` or short `text` item instead of another paragraph to parse, and a vague answer (an FAQ reply that doesn't actually answer the question) gets a [`request_revision`](/docs/mcp) call that flags exactly what's missing in the client's own portal, instead of a reply-all nobody reads in full. For the rest of what a website project needs beyond the words — logo, photos, technical access — see the [website project intake checklist](/docs/website-project-intake-checklist). ## Frequently asked questions ### What copy does a website actually need from the client? At minimum: page-by-page body copy (homepage, about, services), an SEO title and meta description per page, small microcopy (buttons, form hints, error and empty states), and legal text (privacy policy, terms, cookie notice) from the client or their lawyer — not invented by whoever builds the site. ### Should a web developer write the client's website copy? Only the small, low-stakes pieces — button labels, form hints, boilerplate. Anything factual (what the business does, its history, its claims) has to come from the client, because a developer or agency guessing at facts and hoping the client corrects them usually ships wrong information instead. ### Is AI-generated website copy safe to use? As a first draft for structure and phrasing, yes — it's faster to edit than a blank page. Not as a source of facts: an AI will confidently state a founding year, a certification, or a price it invented to complete the sentence, and every factual claim in a draft needs the client to confirm it before publishing. ### What if the client never sends their website copy? Split the request into small, specifically-worded fields instead of one open-ended ask, and decide in advance whether a missed deadline means launching with a clearly-marked placeholder or holding launch — the failure mode to avoid is shipping lorem ipsum or invented text because nobody wanted to delay the site, and then never getting around to replacing it. ### How should I structure a copy request for a site with many pages? Ask per page, not per site: page title and slug if it matters, headline and subheadline, body copy split into the sections the template actually has, and images sized for that specific page. A page built from three content blocks should get three separate fields, not one paragraph to divide up afterward. **Send this request to your client with BriefGate** — [start free](https://app.briefgate.dev/app/login?tab=signup&utm_source=docs&utm_medium=guide-cta&utm_campaign=website-copy-from-clients), no card required, and turn the fields above into a branded portal with reminders instead of an email thread. --- ## Email Templates: Requesting Client Materials URL: https://briefgate.dev/docs/email-templates-requesting-materials-from-clients # Email Templates for Requesting Materials From Clients Clients ignore vague requests buried in a busy inbox. These five copy-paste templates — request, two reminders, an escalation, a thank-you — fix that. ## Why the first email usually fails Most "please send over your logo and photos" emails get skimmed once and then buried by the next twenty messages that land in the client's inbox that day. It isn't that the client doesn't care about the project — it's that the request didn't ask for anything they could act on in the ninety seconds they had free. A vague ask produces a vague non-answer, or no answer at all, and three weeks later you're the one explaining to your own client why the site isn't live yet. The fix is mostly structural, not tonal. A request that gets answered has: - **One clear action**, not a paragraph of context followed by a buried ask. - **A finite list**, named item by item, not "the usual stuff" or "everything you have." - **A visible way to measure progress** — a link, a checklist, or at minimum a line saying what's already in and what's still missing. - **A deadline that means something**, tied to a date the client already cares about (their own launch, not yours). Everything below builds on that structure. Copy the templates, fill in the brackets, and keep the tone as written — polite and specific reads as competent; apologetic and vague reads as optional. ## Subject lines and thread hygiene Reply in the same email thread every time instead of starting a new one. A client who has three separate threads about "the logo" cannot tell which one is current, and neither can you when you search your own inbox six weeks later. Subject line rules that hold up across all five templates: | Stage | Subject pattern | Why | |---|---|---| | Initial request | `{project_name} — a few things we need to get started` | Names the project, not you or your company; frames it as a short list. | | Gentle reminder | Reply on the same thread, unchanged subject | A reminder is not new information; a new subject line makes it look like it is. | | Firm reminder | Reply on the same thread, or prefix with `Action needed:` if it's been over a week | The prefix should be rare enough that it still means something when it appears. | | Escalation | `{project_name} is on hold — need {items} to continue` | States the consequence plainly instead of implying it. | | Thank-you | Reply on the same thread | Closes the loop the client can see, which matters more than it sounds. | ## The templates Placeholders are in `{braces}`. Delete anything in a template that doesn't apply to your project rather than leaving it half-filled — a template with unfilled brackets reads worse than no template at all. ### 1. Initial request ``` Subject: {project_name} — a few things we need to get started Hi {client_name}, To get {project_name} moving, I need the following from you: - {item_1} (e.g. your logo, ideally the original SVG or AI file) - {item_2} (e.g. 5-10 photos of {subject}) - {item_3} (e.g. your current opening hours / pricing / bio text) {one_sentence_reason_it_matters, e.g. "The logo drives the whole color palette, so it's the one thing I can't start without."} Whatever you have is fine — I can work with rough drafts and will follow up with questions rather than waiting for something perfect. If you can get this to me by {deadline}, we stay on track for {milestone}. Thanks, {your_name} ``` ### 2. Gentle reminder (first follow-up) Send this if nothing has arrived after 2–4 business days. Keep it short — a long reminder reads as nagging; a short one reads as a nudge. ``` Subject: (same thread) Hi {client_name}, Just a quick nudge on the list from {day_of_week} — still need: - {remaining_item_1} - {remaining_item_2} No rush if you're mid-week busy, but flagging it so it doesn't slip past {deadline}. Happy to hop on a 5-minute call if that's faster than typing it all out. {your_name} ``` ### 3. Firm reminder (second follow-up) Send this 5–7 days after the first request, or 3–5 days after the gentle reminder if the deadline is close. The tone shifts from "nudge" to "this is now affecting the timeline" — still polite, but no longer soft. ``` Subject: Action needed: {project_name} Hi {client_name}, We're now {days_overdue} days past the date we'd hoped to have these, and it's starting to push the whole timeline back: - {remaining_item_1} - {remaining_item_2} If something's blocking you on any of these — you don't have the file, you're not sure what I mean, whatever it is — just reply and tell me. That's faster for both of us than guessing. If I don't hear back by {new_deadline}, I'll need to push {milestone} out accordingly. {your_name} ``` ### 4. "We're blocked" escalation Send this only after a firm reminder has gone unanswered and a real deadline is now at risk. This is the one email in the set that states a consequence rather than just implying one — use it sparingly, because it only works if it's rare. ``` Subject: {project_name} is on hold — need {items} to continue Hi {client_name}, I want to flag clearly rather than let this drift: {project_name} is paused until {items} come in. I can't {specific_next_step, e.g. "build the homepage layout" or "set up the payment page"} without them. If the original deadline of {deadline} no longer works on your end, that's fine — just tell me the real date and I'll replan around it. What I want to avoid is discovering the delay only when we get close to launch. If it would help, I'm glad to jump on a call this week to walk through exactly what's needed and knock it out together. {your_name} ``` ### 5. Thank-you and confirmation Send this the moment everything (or a meaningful batch) arrives. It costs thirty seconds and does two things reminders can't: it closes the loop visibly, and it gives you a paper trail of what you actually received, in case a version gets superseded later. ``` Subject: (same thread) Hi {client_name}, Got everything — thank you! Confirming what's in: - {item_1}: received - {item_2}: received - {item_3}: received I'll take it from here. Next you'll hear from me is {next_milestone}, around {date}. {your_name} ``` ## How much time to leave between reminders There's no universal number, but a cadence that works for most small web and design projects looks like this: first reminder at day 2–3, second at day 5–7, escalation around day 9–12 if the deadline allows it. Compress that for a hard launch date; stretch it for a client you know is slow but reliable — chasing a dependable client on a tight schedule reads as distrust, not diligence. If you're running several projects at once, this is also where manually tracking "who did I email and when" stops scaling. A scheduled reminder cadence — send at T+2 days, T+5 days, T+9 days, then weekly — removes the part of the job that's pure bookkeeping rather than judgment. BriefGate's [chase engine](./chase.md) runs exactly that kind of schedule automatically, stopping the moment an item arrives and handing the intake back to you if it stalls, so you're not the one deciding each morning whether today's the day to send template #3. ## When the missing item is a login, not a file If what's stuck is a password or an API key rather than a photo, don't use these templates as written — asking for credentials over email creates a plaintext copy that sits in an inbox indefinitely. See [How to Get Client Logins Securely](./how-to-get-client-logins-securely.md) for the safer alternatives and what to do once you've received one. These templates cover the email side of the conversation. For the wider process — what to ask for, in what order, and how to validate what comes back — see [How to Collect Documents From Clients](./how-to-collect-documents-from-clients.md). ## Where BriefGate fits These templates work as-is over plain email — nothing here requires any tool. Where they start to feel manual is at the fourth or fifth concurrent client, when remembering who's overdue and drafting the reminder yourself becomes the job. BriefGate turns the item list into a [typed checklist your client fills in on a portal page](./portal.md), sends the reminders on the schedule above under your name, and hands your agent (or you) back structured data instead of a folder of attachments to sort through. It's the same request, automated rather than retyped. See [what BriefGate does](/) or start with a [restaurant, advisor, or club project template](./templates.md) if you run the same kind of project repeatedly. --- ## Getting Client Logins Securely URL: https://briefgate.dev/docs/how-to-get-client-logins-securely # How to Ask Clients for Logins and Passwords Securely Sending logins by email or WhatsApp leaves a permanent password in a chat log. Here are safer options, ranked worst to best, plus what to do after. ## What access you'll actually need Not every project needs all of these, but most website work touches at least three or four: - **Hosting control panel** — cPanel, Plesk, or the provider's own dashboard (Wedos, Active24, Forpsi, and similar are common in the Czech market). - **Domain registrar / DNS** — to add records for email sending, verify a custom domain, or point the domain at a new host. - **CMS admin** — WordPress, Shopify, Webflow, or whatever the site already runs on, if you're rebuilding rather than starting fresh. - **Google Analytics and Search Console** — usually granted as a user on the existing property rather than handed over as a password. - **Social media business accounts** — Facebook Business Manager, Instagram, or a Google Business Profile, needed if the project touches ads or reviews. - **Payment gateway** — Stripe, GoPay, Comgate — only if you're wiring up checkout, and usually the most sensitive item on the list. The common thread: these are almost never things a client hands over once and forgets. Most of them support inviting a second person with a specific role, which matters for what follows. If you're assembling the full list of what a website project needs beyond credentials, see the [website project intake checklist](./website-project-intake-checklist.md). ## Why not email or WhatsApp A password sent by email doesn't disappear when the project ends. It sits in the client's Sent folder, your Inbox, both of your phones if mail is synced, and any backup either of you has ever taken — indefinitely, in plaintext, searchable by anyone who later gets into either account. WhatsApp is marginally better in transit (it's end-to-end encrypted) but identical in the outcome that matters: the message never expires, and a phone left unlocked on a table shows the password to whoever picks it up. Neither channel was built to hold credentials. Both were built to hold conversation, and a password typed into a conversation behaves exactly like the rest of the conversation — it gets backed up, forwarded, searched, and quoted back into replies without anyone intending harm. The same goes for shared notes and team chat tools like Slack or Microsoft Teams — a password pasted into a channel sits there for just as long, and is visible to everyone who has access now or is added later. ## The options, worst to best ### 1. Plain email or chat message The password is typed directly into the body of an email or a WhatsApp message. It works, in the sense that you now have the password. Everything else about it is a liability: no expiry, no record of who else has seen it, no way to know if it leaked until something goes wrong. Use this only when nothing else is available and the account is genuinely low-stakes — a free newsletter tool, say, not hosting or payments. ### 2. A shared entry in a password manager The client adds you as a collaborator on one entry in 1Password, Bitwarden, or similar, rather than typing the password anywhere. This is a real improvement: the value never appears in an inbox, and revoking access is one click instead of a password reset. The catch is that it assumes the client already uses a password manager and is willing to set up sharing correctly, which a lot of small-business clients simply haven't done. It also still lands the client's actual, permanent password in your vault rather than something scoped to the project. ### 3. A temporary account with least privilege Instead of the client's own login, they create a second account for you — a collaborator invite on WordPress, a "Users" entry on the hosting panel, a team member on Google Analytics — scoped to only what the task needs, and only for as long as the project runs. Most platforms in the list above support this natively: WordPress has roles below Administrator, Google Analytics has per-property access levels, most hosts support a secondary cPanel or FTP user. This is the option to reach for by default. It answers the two questions that matter most — what can this account do, and when does it stop existing — without asking the client to adopt a new tool. ### 4. A one-time, auto-expiring credential For the cases where a temporary account isn't possible — a hosting provider with no multi-user support, a single admin login with no roles — the better shape than "send me the password" is a channel built specifically to hand off one secret exactly once: the client types it into a field that encrypts it immediately, you retrieve it a single time, and after that retrieval nobody — including the client, re-opening the same page — can see it again. It never sits in an inbox because it's never in an email to begin with. BriefGate's [secret item type](./secrets.md) works this way: the value is sent over HTTPS and encrypted on the server before it's stored, released to your agent or your dashboard exactly once, and gone from both after that, whether or not you remembered to write it down. If you're already using BriefGate to collect a logo and some copy for the same project, adding one `secret` item for "current site login" replaces the separate WhatsApp message you'd otherwise have sent for it. ## How to ask, without it sounding like a security lecture Most clients haven't thought about any of this, and a wall of security caveats reads as friction, not care. Frame the request around what they need to do, not why email is unsafe: > "Could you add me as an Administrator on your WordPress site (Users → Add New) rather than sending the login? Takes about a minute and means I never see your actual password." That gets the least-privilege account without ever using the word "security." If the platform genuinely has no multi-user option, fall back to asking for the value through whatever vault or one-time link you're using, with a one-line reason: "so it's not sitting in an email afterward." ## If you're the client sending the logins Forward this section to a client who's asking how to send a login over safely, or who got a BriefGate portal link and isn't sure what the lock icon on it means. If your developer's request came through BriefGate's [secret item type](./secrets.md), here's what actually happens when you fill it in. The field is marked with a lock icon and a note that it's shown only once. You type the value the same way you'd type a password anywhere else, and it travels over HTTPS to BriefGate's server, where it's encrypted immediately — a public-key sealed box — before anything is written to a database. The plaintext is never stored; only the encrypted version is kept. Your developer, or their coding agent, retrieves it exactly one time. The instant that happens, the plaintext is gone from BriefGate's side — not hidden, not archived, actually gone. If you reload the same page afterward, there's nothing to see; the field just shows that it's already been delivered. Nobody — not you, not BriefGate, not anyone else — can pull that value back up a second time. One practical detail: if nobody retrieves the credential within 30 days of you submitting it, it expires on its own and can't be recovered. If that happens, your developer will ask you to enter it again — it's not a sign anything went wrong, just the same one-time design working as intended. ## After the handoff: the checklist Getting access is the easy half. What happens when the project ends is where most of the actual risk sits, because a stale collaborator account is a working login nobody is watching. - **Rotate**, not just for accounts you created — for anything the client's original password may have touched if it was ever typed into an email or a chat, even temporarily. - **Remove your temporary account or collaborator invite** the moment your work is done, not "at some point." An open ticket to delete access later is an access grant that never actually ends. - **Confirm the client still holds primary ownership** — the original admin account, the domain registrar login, the Stripe account owner — so nothing about their business depends on your account staying active. - **Document what was granted and when**, even briefly: which accounts, what role, what date it was revoked. Six months later, when the client asks "who has access to our site," you want an answer that isn't "I think just us." - **Tell the client what to do with anything sent insecurely before you got involved.** If a password arrived by email before you had a chance to suggest an alternative, say so and recommend they change it — a five-second, no-blame heads-up costs nothing and closes the gap. ## Where BriefGate fits Everything above works with plain accounts and a password manager — no tool required. Where it gets tedious is running it project after project: remembering to ask for a role rather than a password, chasing the client when they forget, and keeping the eventual credential out of your own inbox. BriefGate folds a credentials request into the same [checklist](./portal.md) as the logo and the copy — the client fills in a masked field, you retrieve it once through your agent or the dashboard, and it's gone from BriefGate's side the moment you do. See [what BriefGate does](/), or read the companion piece on [requesting the rest of the project's materials](./email-templates-requesting-materials-from-clients.md) if credentials are only one item on a longer list. --- ## Why Clients Don't Send Materials URL: https://briefgate.dev/docs/why-clients-dont-send-materials # Why Clients Don't Send Materials (and What to Do) Clients rarely withhold a logo or photos on purpose — they stall from being overwhelmed, an unclear ask, no deadline, or no one owning it on their end. This page diagnoses why; for the step-by-step process to fix it, see [how to collect documents from clients](/docs/how-to-collect-documents-from-clients). ## Why "just send it over" doesn't work Every web project has a moment where the ball leaves your court and lands in the client's. You need their logo, their copy, their photos, maybe an old CMS password. You send a friendly email — "whenever you get a chance, could you send over your logo and some photos?" — and then nothing happens for two weeks. It feels personal. It isn't. From the client's side, that email arrived between forty other things they consider more urgent: their actual job, their kids, an invoice they're chasing. Your open-ended, undated, unowned request loses every time it competes with something that has a due date attached. The problem isn't that they don't care about the project. It's that you gave them nothing that forces a decision about when to act. This is also, structurally, not their job. They hired you to make the technical and creative decisions. Being handed a vague homework assignment — "send us your brand assets" — puts them back in a role they didn't sign up for. The less specific the ask, the more it feels like work, and the more it gets deferred. ## Diagnose the real cause Different stalls have different causes, and the fix only works if it matches the cause. Before assuming a client is simply slow or difficult, check which of these patterns fits: | Symptom | Likely cause | Fix | |---|---|---| | Agrees enthusiastically, then goes silent | Overwhelmed by an open-ended list ("send us everything you have") | Split the ask into small, individually completable items | | Sends half the files, ignores the rest | Doesn't know the exact format, size, or quantity needed | State constraints explicitly — "5 to 15 photos, JPG or PNG" beats "some photos" | | Says "I'll get to it" for weeks | No deadline, and no consequence attached to missing one | Give an explicit due date tied to your own project timeline | | Materials arrive scattered across email, WhatsApp, and a Dropbox link | No single place to submit or check what's still needed | Point them at one link and one status page, not a thread | | Total silence from a request sent to "the team" | No named owner on the client's side | Address one specific person, not a shared inbox or group | | Uploads a screenshot instead of the source file | Doesn't understand why the low-res version doesn't work | Explain the requirement in the client's terms ("blurry on phones") not yours ("under 512px") | Most stalled projects are a combination of two or three of these, not one. A vague ask sent to a shared inbox with no due date fails for three separate reasons at once, and fixing only one of them won't be enough. ## Four fixes that make materials arrive ### One place, not a thread Every time a client has to remember which email thread, which shared folder, or which text message the request lives in, you've added a decision they have to make before they can even start. Consolidate everything they owe you — files, text, credentials — behind one link. A single page that shows what's done and what's left removes the guesswork about whether they already sent something and you lost it, which is a real and common source of the standoff where both sides think the ball is in the other's court. ### Small chunks, not one big ask "Send us your brand assets, some copy, and your opening hours" is one request that feels like three separate chores, each vague enough to postpone. Break it into a checklist with a handful of named, specific items — logo, hero text, opening hours, five to fifteen photos — each with a one-line explanation of what it's for. A checklist with a progress bar gets finished item by item, in spare five-minute windows, in a way a single open-ended email never does. If you want the full list of what to ask a new client for and why, see our [web design brief checklist](/docs/website-project-intake-checklist) — turning that list into a structured request is most of the fix on its own. ### A deadline and a named owner "Whenever you get a chance" sets no deadline, so nothing competes with the client's actual deadlines. Give a real date, ideally tied to a consequence they care about ("we need this by the 14th to keep the launch date"). And send it to one named person, not a general inbox or "your team" — a request with nobody's name on it is nobody's job to finish. ### A reminder cadence, not manual nagging A single request, however well written, will still get missed. The fix isn't sending it once and hoping — it's a planned sequence of reminders that don't require you to remember to send them, phrased so the fifth one doesn't sound like the first one did. ## A reminder cadence that works A workable rhythm has four checkpoints, each with a different job: - **Day 0 — the invite.** State exactly what's needed, why it matters for their project, and roughly how long it will take (most checklists run five to fifteen minutes). One link. No ambiguity about where to submit. - **Day +3 — the friendly nudge.** Short and warm, not a guilt trip. If they've already sent something, say so — "thanks for the logo, still waiting on photos and opening hours." Restate the same link. - **Day +7 — the specific ask.** Name the exact one or two items still outstanding, not "the rest of the materials." Offer an alternative for anyone stuck: a ten-minute call, or permission to send something rough ("a phone photo of the menu is fine for now"). - **Day +10 — the last reminder before consequence.** State plainly what happens if nothing arrives — the launch slips, or you proceed with placeholder content that they'll need to review and approve later. No pressure tactics, just the actual consequence. Building and babysitting that sequence by hand across several active projects is exactly the kind of thing that quietly eats a week a month. BriefGate's [chase engine](/docs/chase) runs a schedule like this automatically once you set it up — sending only for what's still missing, respecting the client's working hours, and stopping the moment they finish or after enough reminders that continuing wouldn't help. ## Put it in the contract A cadence of reminders handles clients who are stalling by accident. It does nothing for the rare client who simply never sends anything. For that, the fix has to live in the contract, not in your inbox. The clause below is a starting point to adapt, not legal advice — have it reviewed by a lawyer licensed in your jurisdiction before you use it in a real agreement. > **Client-Supplied Materials.** Client agrees to provide all materials listed in the project intake (logos, copy, images, and any required credentials) within [X] business days of the effective date of this agreement, or by [specific date]. If Client has not provided the required materials within [X + grace period] days after that deadline, [Company] may, at its discretion: (a) pause work on the affected deliverables without adjusting the overall project deadline; (b) proceed using placeholder content, with any resulting rework billed at the standard hourly rate; and/or (c) treat the delay as a change in scope subject to the change-order process described in Section [_]. Materials submitted after this point will be incorporated as time allows, not guaranteed by the original delivery date. The clause matters less for its legal weight — most agencies never invoke it — and more because naming a deadline and a consequence up front changes how the client treats the whole request. It stops looking optional the moment it's in a document they signed. ## Frequently asked questions ### Is it normal for clients to take weeks to send basic materials? Yes, and it's rarely personal — your request is competing with everything else already in their inbox, not with nothing. The diagnosis table above breaks down the handful of specific reasons this is more likely than a client simply not caring. ### Should reminders go through the same channel as the original request? Generally yes. A client who's used to seeing your emails will more easily recognize and act on a follow-up sent the same way; switching channels — email to text, for instance — can read as escalation and put them on the defensive. Keep everything pointed at the same single link across every reminder, too. ### Do I need a lawyer to write a materials-deadline clause into my contract? Yes — have any clause reviewed by a lawyer licensed in your jurisdiction before using it in a real agreement. The sample clause in this guide is a starting point for that conversation, not something to paste in unreviewed, since enforceability and required disclosures vary by jurisdiction. ### Does offering a call instead of a form actually help? Sometimes. Offering a short call as an alternative to filling something out unblocks a client who's genuinely stuck rather than avoiding it, particularly at the day-7 reminder stage. It doesn't scale as the default for everyone, though — a form is faster for anyone who isn't actually stuck. ### Can a client's silence mean they've lost interest in the project? It's possible, but it's the least common explanation. Check the more mundane causes first — overwhelm, no deadline, no named owner — before concluding the client has walked away. When it really is that, the contract clause here is what turns an open-ended stall into a deliberate decision instead. ## Where BriefGate fits Everything above works whether or not you use any particular tool — a shared folder with a checklist and a calendar reminder gets you most of the way there. BriefGate exists for the parts that are tedious to build by hand across many projects at once: a branded [client portal](/docs/portal) that needs no login, a chase schedule that runs itself, and typed results an AI coding agent can read back without re-parsing an email. If you're setting up the request itself, our guide to the [web design brief checklist](/docs/website-project-intake-checklist) covers exactly what to ask for before you send anything. Start at [briefgate.dev](/) if you want to see the whole flow end to end. --- ## E-Commerce Website Intake Checklist URL: https://briefgate.dev/docs/ecommerce-website-intake-checklist # E-Commerce Website Intake Checklist Everything specific to selling online that a client needs to supply before an online store can launch, grouped by category, with the reason and timing for each. ## What this checklist adds to a regular website build An online store needs everything a normal website needs — logo, brand colors, homepage copy, domain access — plus a layer that only exists because the site takes payments and ships or fulfills orders. That layer is what this page covers. For the shared basics every website project needs, see the [website project intake checklist](./website-project-intake-checklist.md); do not ask for those items twice. As with any intake, sort items into what blocks the build from starting and what can follow with a placeholder. A missing product photo rarely stops development; a missing decision on which payment provider to integrate usually does, because it changes what code gets written. For how to actually get all of this out of a client — which collection method fits which situation — see [the best way to request files from clients](./how-to-collect-documents-from-clients.md). ## Products and catalogue | Item | Why | Timing | |---|---|---| | Full product list with names and short descriptions | Shapes the catalogue structure before a single template is built. | Before kickoff | | Categories and how they nest | Changes navigation and URL structure — guessing it means rebuilding both later. | Before kickoff | | Variants (size, color, material) and their structure | A shirt in four sizes and three colors is one product with twelve variants, not twelve products — but only if built that way from the start. | Before kickoff | | SKU or another unique product identifier | Without one, matching a spreadsheet row to a product across import rounds is guesswork by name alone. | Before kickoff | | Product photos, per product or variant | The most commonly late item here — see launch blockers below. | Hero/bestsellers before kickoff, rest can come later | | Full product count, even an estimate | Twenty products and two thousand need different import methods and catalogue features from day one. | Before kickoff | ## Pricing and tax | Item | Why | Timing | |---|---|---| | Price per product, gross or net of tax | Changes what's stored and displayed — confirm once, explicitly, rather than assume from spreadsheet formatting. | Before kickoff | | VAT rate per product or category, if it varies | A single global rate breaks the moment one product line differs (books, food, digital goods are common exceptions). | Before kickoff | | Currency and which countries are served | Determines whether multi-currency support is needed from launch — a bigger scope difference than it sounds. | Before kickoff | | Discount and promotion rules, if planned at launch | A percentage code is simple; tiered bulk discounts are a different feature and need scoping, not mid-build discovery. | Can come later unless launch depends on it | | Business registration details for invoices | The fields a valid invoice needs are set by the seller's own registration, not by design preference. | Before kickoff | ## Media | Item | Why | Timing | |---|---|---| | Product photos meeting a stated minimum resolution | State size and background style up front — mismatched phone photos are a common, avoidable revision round. | Key products before kickoff | | Category or banner images for homepage/landing pages | Marketing images, distinct from catalogue photos, and often forgotten since they map to no database row. | Can come later | | Size charts or fit guides, for apparel and similar goods | A support-ticket reducer, not a launch blocker — flag early so it isn't missed entirely. | Can come later | | Product videos, if used | Confirm the platform actually supports video before treating it as a requirement. | Can come later | ## Logistics and payments | Item | Why | Timing | |---|---|---| | Payment methods to accept | Determines which gateway integration gets built — expensive to change after checkout code exists. | Before kickoff | | Payment gateway account, verified and approved | Most gateways require the merchant's own verification before processing live payments — usually the slowest step on this list. | Before kickoff — see launch blockers | | Shipping carriers and rate structure | Shapes checkout flow and, if rates are live, which carrier API gets integrated. | Before kickoff | | Carrier account credentials, if rates or labels are fetched live | Needs the client's own carrier account, not a generic one — this is a credential from their existing supplier, not from you. | Before kickoff if live rates are in scope | | Product weights and dimensions | Required for weight-based shipping; missing it for even a few products breaks checkout for those items. | Before kickoff | | Fulfillment process (in-house, third-party warehouse, dropshipping) | Changes what happens after payment — notify a warehouse, generate a picking list, or just email the client. | Before kickoff | | Return and exchange policy specifics | Feeds the legal return page and any in-store return-request feature. | Can come later, but before launch | ## Legal and compliance | Item | Why | Timing | |---|---|---| | Terms of service and a return/withdrawal policy | Consumer sales typically require a stated right of withdrawal — content from the client or their lawyer, not invented for them. | Can come later, but before launch | | Privacy policy and cookie consent | A store collecting names, addresses, and payment data discloses more than a brochure site and needs consent for tracking. | Can come later, but before launch | | Industry-specific restrictions (age-restricted or regulated goods) | Some categories carry disclosure or age-verification rules a generic template won't cover. | Before kickoff if the catalogue needs it | | Complaints/claims process, where locally required | Often a separate published requirement from the general return policy. | Can come later, but before launch | ## Accounts and access | Item | Why | Timing | |---|---|---| | Domain, hosting, and DNS access | Launch-critical here specifically — a live store can't reschedule a domain cutover the way a brochure site can. | Before kickoff | | Payment gateway API keys, once approved | A credential, and should never travel by email — see the note on secrets below. | Arrives once the gateway account clears verification | | Shipping carrier account access, if integrated | Same handling as gateway keys: a credential, not a document. | Before kickoff if live shipping is in scope | | ERP, accounting, or inventory-system access, if syncing is needed | Needs that system's API credentials and usually a contact who understands its data model. | Before kickoff if in scope, otherwise later | | Marketplace or social-commerce accounts, if products list elsewhere | Relevant only if inventory or orders sync across channels — confirm scope first. | Can come later | ## Marketing | Item | Why | Timing | |---|---|---| | Analytics and ad-tracking IDs | Best wired in before launch so first sales are measured; a short gap causes no lasting damage. | Can come later | | Email marketing or abandoned-cart tool details | Usually a post-launch connection, not a structural requirement. | Can come later | | Planned launch promotions or discount codes | If a promotion is meant to go live at launch, its logic has to be built in, not bolted on the day before. | Before kickoff if planned | ## The product-data spreadsheet For any catalogue beyond a handful of items, product data usually arrives as a spreadsheet, and its quality decides how much manual cleanup the import needs. Ask the client to fill in a template with these columns rather than accepting whatever format they already have: - **SKU or unique ID** — one per sellable variant, not one per product name - **Product name** and **short description** - **Category**, and subcategory if the catalogue nests - **Price**, with a column noting gross or net of tax - **VAT rate**, if it varies across the catalogue - **Variant attributes** (size, color, material), one column per attribute, one row per variant - **Stock quantity** - **Weight and dimensions**, for shipping calculation - **Image filename(s)**, matched exactly to the files actually supplied - **Barcode/EAN**, if the client's existing systems use one Common mistakes to flag before import: variants crammed into one free-text field instead of one row each; prices silently mixing gross and net in the same column; image filenames that don't match what was actually uploaded, byte for byte; and a "category" column that's really a comma-separated list of tags — a different structure that needs modeling as one. ## What tends to block e-shop launches A handful of items above cause a disproportionate share of delays, and none are things the developer controls directly: - **Payment gateway verification.** Most gateways require business documents and banking details, with approval taking days to weeks, entirely on the client's side. Start this on day one, not the week before launch. - **Tax and invoicing setup.** Wrong VAT rates or invoice numbering are invisible during development and expensive to unwind once real orders have gone out. - **Product photography and copy for the full catalogue**, not just the hero products used in mockups. Three good photos out of twenty products is not launch-ready. - **Legal pages drafted by the wrong person.** A copied terms-of-service template is a liability, not a shortcut, and needs the client's own review. - **A live shipping or fulfillment integration with no working carrier account behind it.** The code can be finished with nothing to connect to. Starting these five on day one, rather than waiting for the "content" phase, moves the actual bottleneck earlier, while there's still time to absorb it. ## Frequently asked questions ### What information do you need before you can quote an e-commerce project? Enough to scope it, not the full catalogue: a rough product count, which payment methods and countries need supporting, and the fulfillment model (in-house, third-party warehouse, or dropshipping). Each of these changes what gets built enough to matter for a quote, well before detailed product data is ready. ### How do you handle a client whose product catalogue isn't ready yet? Build the structure — categories, the variant model, checkout — against a handful of real hero products, and agree on the spreadsheet template before the client starts filling it in. Reformatting hundreds of rows after the fact costs far more than defining the columns up front. ### Should product prices include tax or not? Ask the client explicitly rather than guessing from spreadsheet formatting — a gross/net mismatch is invisible until real orders start reconciling incorrectly against the client's accounting. ### Do you need a live shipping carrier integration to launch? Not necessarily. A flat-rate or manual shipping table is a legitimate way to launch, and switching to live carrier rates afterward is an addition rather than a rebuild, as long as checkout was built with that in mind from the start. ### How do you securely collect a client's payment gateway API keys? The same way as any other credential: never in an email or chat message. A leaked payment gateway key is a materially bigger risk than a leaked CMS password, so it deserves at least the same one-time-reveal handling — BriefGate's secrets vault is built for exactly this kind of credential. ### What if the client hasn't set up their payment gateway account yet? Start the verification process on day one — it's usually the slowest step on the whole list, often taking days to weeks entirely on the client's side. Build and test checkout against the gateway's sandbox keys in the meantime so development isn't blocked waiting on their paperwork. ## Where BriefGate fits Collecting this list is a bigger version of the problem [BriefGate](/) solves for any website project: someone has to ask for each item precisely, track what's come back across a longer, more mixed list than a brochure site needs, and keep payment and carrier credentials out of an inbox. An AI coding agent — or you, from the dashboard — can declare this checklist as typed items, with constraints like minimum photo resolution or a required VAT field built into the request, and let BriefGate's [chase engine](./chase.md) follow up on what's outstanding while the [secrets vault](./secrets.md) handles gateway and carrier credentials with a one-time reveal instead of email. The built-in `eshop-cs` [template](./templates.md) is a Czech-language, 10-item starting point that fits the Free plan; for an English intake or the full list above, build the items from this checklist. **Send this checklist to your client with BriefGate** — [start free](https://app.briefgate.dev/app/login?tab=signup&utm_source=docs&utm_medium=checklist-cta&utm_campaign=ecommerce-website-intake-checklist), no card required; from the Solo plan, gateway credentials come in through the encrypted vault instead of your inbox. --- ## Brand Design Brief Checklist URL: https://briefgate.dev/docs/logo-and-brand-design-brief-checklist # Brand Design Brief Checklist: What to Ask the Client A logo brief that skips positioning, usage and file formats produces revision after revision. Here is what to ask before any concept work starts. ## Why a thin brief produces endless revisions "Something modern and clean, maybe blue" is not a brief. It is a placeholder for a brief, and every round of "not quite that" that follows is the client filling in, one rejected concept at a time, the information a real brief would have collected up front. Logo work is unusually unforgiving of a thin brief. A homepage built against placeholder copy can absorb the real copy later without much rework — the layout barely changes shape. A concept built without knowing the mark has to work as a single-color embroidery patch, or that a competitor already owns the obvious color, is often not a revision away from correct. It's a restart. The fix isn't a longer conversation about taste; it's a specific set of questions, asked before the first sketch, that catches the constraints taste alone won't surface. This checklist assumes the shared basics — business goals, target audience at the level of "who buys from you" — are already covered somewhere. If they aren't, run the [web design brief checklist](./website-project-intake-checklist.md) first; what follows here goes one layer deeper, into the questions specific to a mark rather than a website. Building an app rather than a site instead? The [mobile app project intake checklist](./mobile-app-project-intake-checklist.md) covers the store accounts and technical items a logo brief doesn't touch. ## The brief, group by group Seven groups of questions, each with a one-line reason it matters. Not every project needs every row — a solo consultant refreshing a personal logo can skip the trademark question; a national franchise cannot skip it. ### Business and positioning | Question | Why it matters | |---|---| | Where does the business sit on price and quality — budget, mid-market, or premium? | A mark that reads premium over a budget price point creates a mismatch the client will feel but can't name. | | Does the name need explaining, or does it need to be pronounced correctly on sight? | An invented or foreign-sounding name may need a phonetic hint or a supporting icon a plain wordmark can't give it. | | Does this mark need to work as a standalone icon — app icon, social avatar, favicon — separate from the full logo? | A wordmark that only makes sense at full width forces an awkward crop the same week the site launches. | | What single association should someone form in the first second of seeing it? | Trustworthy, fast, handmade, cutting-edge — each points to different shapes and colors; this is the one-sentence brief everything else supports. | ### Audience | Question | Why it matters | |---|---| | Where will people most often encounter this mark first — a phone screen, a storefront, a business card, a highway sign? | A detail that reads clearly on a card can vanish at billboard distance or app-icon size; design for the common encounter, not the flattering one. | | Does your industry have a visual convention your audience expects — navy and serif for law, rounded and bright for children's brands? | Knowing it lets you meet it deliberately or break it deliberately, instead of by accident. | | Will the same mark travel across very different contexts — a formal invoice and a casual social post? | A logo that only works in one register forces a second version later; better to know that up front. | ### Personality and values | Question | Why it matters | |---|---| | Pick three words for how the mark should feel. | "Playful," "precise," and "warm" each rule out entire visual directions before anything is drawn — the fastest filter in the whole brief. | | Any words, colors, or shapes that would feel wrong for this brand? | A strong negative is often clearer than a positive preference, and clients volunteer it readily once asked. | | Name a brand outside your own industry whose personality feels close to what you want. | An outside reference (a bank that wants to feel like a favorite coffee shop) says more than a paragraph of adjectives. | ### Competitors and references | Question | Why it matters | |---|---| | Who are your two or three direct competitors, and what do you think of their logos? | Shows you the visual field you're either fitting into or deliberately standing out from — designing in ignorance of it risks landing on something a competitor already owns. | | Is there a logo you admire, in any industry? What specifically do you like about it? | Push past "I like that one" to the specific element — the weight, the negative space, the color pairing — because the whole logo is rarely what's actually wanted. | | Is there a logo, in your industry or not, that you actively dislike? Why? | As useful as the positive reference, and clients are often more articulate about what repels them than what attracts them. | ### Usage and formats | Question | Why it matters | |---|---| | Where will this mark physically appear — packaging, a vehicle, signage, embroidery, a favicon, a social avatar? | Each context has its own failure mode a screen mockup won't reveal: embroidery loses detail, vehicle wraps need to read at speed, favicons lose everything but the boldest shape. | | Does it need a horizontal lockup, a stacked lockup, and an icon-only version? | A scoping question, not a design one — three lockups is a larger job than one, and the client should know that before work starts. | | Does it need to work in a single color and in reversed (light-on-dark) form? | A mark that only works in full color fails the moment it needs an invoice, a stamp, or a dark-mode app icon. | | What is the smallest size it needs to stay legible at? | Detail that reads beautifully at business-card size can turn into a smudge at favicon size — know the floor before designing toward it. | ### Constraints and existing assets | Question | Why it matters | |---|---| | Is there anything about the current logo — a shape, a color, an icon — that the business is known for and shouldn't lose? | Years of recognition attached to a particular blue is an asset even when everything else is being replaced; losing it by accident is a real cost. | | Has a trademark search been done, or does one need to happen before final designs are shown? | Cheaper to raise before concepts are picked than to fall for a mark that conflicts with an existing registration. | | Is there an existing tagline that needs to be incorporated into the lockup, or kept separate? | Changes whether you're designing one component or two that have to work together at every size. | ### Deliverables and timeline | Question | Why it matters | |---|---| | How many initial directions, and how many revision rounds, are included? | The most common source of scope disputes on logo projects — agree the number before the first concept, not after the third "just one more tweak." | | What final file formats are needed — vector source, print-ready PDF, transparent PNG, a favicon? | Each is a different production step; finding out a print-ready CMYK file is needed after delivering only web PNGs means redoing the export. | | Who has final sign-off? | Settle this once, at the start — a second decision-maker appearing after approval is the most expensive kind of surprise. | | Is there a hard delivery date, and what's driving it? | A rebrand tied to a trade show or funding announcement has a real deadline; one without a driving event has more room to negotiate the revision count above. | ## Collecting the actual materials Answers to the questions above are half the brief. The other half is physical material, and it is worth asking for by name rather than a general "send anything relevant": - **The existing logo file, in whatever format the client has it** — even a low-resolution export from an old business card. Not for reuse; it's the fastest way to see what visual equity exists to keep or deliberately discard. - **An existing brand guide**, if one exists, as a PDF. Rare below a certain company size, but it answers several constraint questions above without a back-and-forth. - **Photos of the mark in its current physical contexts** — signage, a vehicle, packaging — as ordinary phone photos. These show real-world failure modes a digital file alone won't. - **Screenshots or links for the competitor and reference logos** named above. Don't rely on memory of what a competitor's site looks like; pull it up and look again. - **A moodboard of likes and dislikes** — a shared Pinterest board or a handful of saved screenshots. Ten images with one line each ("like the weight, not the color") reveal more usable taste than a paragraph of adjectives. ## Running it: call versus written brief, before versus after kickoff Split the questions the way you'd split any client request: what benefits from a conversation, and what just needs looking up. Positioning, personality words, and competitor opinions are shorter and vaguer in writing than out loud — "modern, but not corporate" only becomes useful once someone asks "modern like what, specifically?" A written form suits everything else: usage, constraints, deliverables and timeline are factual enough that the client answers them accurately without a call, often more accurately, since they can check a file instead of memory. Unlike a website project, where placeholder text is a normal way to start before every asset exists, a logo brief mostly resists a partial start. A concept sketched against an incomplete brief usually isn't a revision away from right once the missing piece — a trademark conflict, a required embroidery version — surfaces; it's a restart. Treat the seven groups above as a before-kickoff block, in full, even at the cost of a short delay. The materials above are more forgiving: one more competitor screenshot can arrive a day in without derailing the first round of concepts. ## Where BriefGate fits Turning this checklist into an actual request, instead of a document nobody reads before answering three of nine questions, is a structuring problem more than a design one. [BriefGate](/) lets an agent — or you, from the dashboard — declare the seven groups above as typed items: `image` for the existing logo file, `color_list` for colors to avoid or preserve, `file` for a brand guide, `structured` for grouped answers like usage constraints, all covered in [item types](./item-types.md). The client gets one branded portal instead of an email with nine questions buried in the body, and if this brief is one piece of a larger website build, it sits alongside the rest of the [website project intake checklist](./website-project-intake-checklist.md) in the same request rather than a separate thread. **Send this checklist to your client with BriefGate** — [start free](https://app.briefgate.dev/app/login?tab=signup&utm_source=docs&utm_medium=checklist-cta&utm_campaign=logo-and-brand-design-brief-checklist), no card required, and stop chasing logo files and moodboards over email. --- ## Mobile App Project Intake Checklist URL: https://briefgate.dev/docs/mobile-app-project-intake-checklist # Mobile App Project Intake Checklist: What to Collect First Everything a client needs to hand over before an app gets built — store accounts, branding, API keys, legal pages — grouped with a reason and timing. ## Why app intake is its own list A website project stalls on a missing logo or a login nobody can find. An app project stalls on those too, plus a category a website never has: accounts only the client can create, submissions only the account owner can approve, and a store review process that happens once, late, and rejects the whole build over one missing piece. A privacy policy URL that's a nice-to-have on a website is a hard submission requirement here. A payment integration that could ship in week three of a website blocks the first TestFlight build if it's core to the app. This list is organized the same way as our general [website project intake checklist](./website-project-intake-checklist.md), but the categories and the timing calls are different enough that treating an app like "a website with an icon" produces avoidable delays. If the project also needs a new brand identity, pair this with the [logo and brand design brief checklist](./logo-and-brand-design-brief-checklist.md) — that one covers the mark itself; this one covers everything around it. ## The checklist, group by group **Before kickoff** means the project can't meaningfully start, or starting without it means redoing work later. **Can come later** means development can proceed with a placeholder or a sensible default until the real thing arrives. ### Accounts and access | Item | Why you need it | Timing | |---|---|---| | Apple Developer Program enrollment, under the client's own identity | Only the client can start this, and it's outside your control once requested — hand it off on day one rather than waiting to need it. | Before kickoff | | Google Play Console developer account, under the client's own identity | Same reasoning as Apple: it has to be the client's account, requested before you're blocked on it. | Before kickoff | | You added as a collaborator with a development role, not full account ownership | Lets you build, test, and submit without holding the keys to an account you don't own — more below. | Before kickoff | | Access to an existing app listing, if you're taking over a live app | A transfer or collaborator request from the previous developer's account, arranged before you need to ship an update. | Before kickoff if replacing an existing app | | App Store Connect / Play Console API credentials, if you're automating builds or releases | Only needed once a CI/CD pipeline exists to consume them. | Can come later | ### Identity and store listing assets | Item | Why you need it | Timing | |---|---|---| | App name and app icon source file | The name may need reserving on both stores before someone else takes it, and the icon shapes a chunk of the design work. | Before kickoff | | Store description (short and long, per store's format) | Needed for submission, not for building — placeholder copy is fine until then. | Can come later | | Screenshots or the raw material to produce them (mockups can be generated once the UI exists) | Can't really be finished before there's a UI to screenshot, though brand direction for them should be settled early. | Can come later | | Category and search keywords | Affects discoverability, not functionality — a submission-time decision. | Can come later | | Support URL and privacy policy URL | Both stores require live URLs at submission; the privacy policy needs real content, not a placeholder, if the app collects any user data. | Can come later, but before submission | ### Content | Item | Why you need it | Timing | |---|---|---| | Which languages the app needs to support | Changes the technical setup for text, layout, and date/number formatting — expensive to retrofit once the app is built around a single language. | Before kickoff | | In-app copy — onboarding text, screen labels, empty states, error messages | Structure and layout can proceed with placeholder text; final copy is a content pass, not a redesign, once it exists. | Can come later | | Licensed media (stock photos, icon sets, fonts) the client has rights to | Confirms what's usable without a separate licensing conversation mid-build. | Can come later | | Legal text that has to live inside the app itself (a terms acceptance screen, disclaimers) | Distinct from content that only needs to exist online — some of it has to be a screen the user sees and accepts. | Can come later, but before submission | ### Integrations and credentials | Item | Why you need it | Timing | |---|---|---| | API keys for any service the app's core function depends on (maps, payments, a booking system) | If the app doesn't work without it, it's part of the build from day one, not an integration to add later. | Before kickoff if core to the app | | Backend or CMS credentials, if the app talks to an existing system | Same reasoning as a website keeping its existing hosting: confirm access exists before integration work starts. | Before kickoff | | Push notification credentials (an APNs key for iOS, a server key for Android) | Only needed once push is actually being wired up and tested. | Can come later | | Payment processor account, under the client's own name, if the app takes payments | Ownership matters even more here than for a website — see the note below. | Before kickoff if payments are core | | Social login app credentials (a Facebook or Google OAuth app, if "sign in with…" is planned) | A configuration step that runs in parallel with the rest of the build, not a blocker for starting it. | Can come later | ### Legal and compliance | Item | Why you need it | Timing | |---|---|---| | Privacy policy | Required for store submission the moment the app collects any user data; it should come from the client or their lawyer, not be invented for them. | Before kickoff | | What user data the app actually collects and why | Both stores ask for this explicitly at submission, and the answer shapes whether a consent screen is needed at all — better known before the data model is built. | Before kickoff | | Terms of service | Carries legal weight the same way a privacy policy does. | Can come later, but before launch | | Age rating questionnaire answers (violence, user-generated content, gambling elements, etc.) | A submission requirement, not a build requirement — answered once the app's content is settled. | Can come later | | Industry-specific disclosures (health data, financial services, children's apps) | Requirements vary by sector and store policy; confirming this is the client's responsibility, not something a default template covers. | Before kickoff for regulated industries | ### Testing and release | Item | Why you need it | Timing | |---|---|---| | Minimum OS version and device range to support | Affects which features are safe to use — settle it before writing code that assumes a newer OS than the client's users actually have. | Before kickoff | | Email addresses for internal testers (TestFlight, Play internal testing track) | Needed once there's a build worth testing. | Can come later | | Expectations for analytics or crash reporting | Cheap to wire in during the build, awkward to bolt on once the app has real users and a data gap. | Can come later | | A hard release date, and what's driving it | An event-driven launch has a real deadline shaping how much testing time is realistic; one without has more room. | Before kickoff | | Who has final sign-off to submit to the stores | Submission is often the one step that can't be undone quietly — confirm who approves it once, at the start. | Before kickoff | ## Why store accounts should belong to the client, not you It's tempting to enroll the client's app under your own developer account — it's faster, you already have one, and the client doesn't need to fill in a form. It's also the single most common source of a painful conversation later. A developer account is the app's home. Its identity, review history, existing users' ability to receive updates, and any active subscriptions all live under that account, not under the app itself. If the account belongs to you and the working relationship ends, moving the app to the client's own account is a formal transfer process between two developer accounts, not a quick setting change, and it can interrupt the app's ability to ship updates while underway. If the account belongs to the client from the start, ending the relationship just means removing your collaborator access — the app never has to move at all. The same logic that applies to a hosting login applies here, at higher stakes: the account that can delete the app or hand it to someone else should be the one the client controls. Add yourself as a team member with a role scoped to what the work needs — both Apple and Google support this — rather than building under an account the client needs your cooperation to ever leave. ## Handing over credentials and API keys safely Everything in the integrations and credentials group above is either an invite (add me as a collaborator with a specific role) or a secret (a single API key, a payment processor's secret key, a backend password with no scoped-access option). Treat them differently: an invite should always be scoped to what the task needs, the same principle covered in more depth in [how to ask clients for logins and passwords securely](./how-to-get-client-logins-securely.md). A secret that can't be scoped — a raw API key, a webhook signing secret — shouldn't travel by email or chat at all, since it sits there indefinitely once sent. BriefGate's [secret item type](./secrets.md) exists for exactly that case: the value is encrypted the moment the client enters it and released once to whoever asked, rather than living on in an inbox. ## Where BriefGate fits Requesting the accounts and can-wait items on this list separately — a form for one, an email for another, a follow-up call for a third — is how a client ends up needing four reminders about four different things. [BriefGate](/) lets an agent, or you from the dashboard, declare this whole checklist as one set of typed items: `secret` for the payment processor key, `image` for the app icon, `structured` for the data-collection answers, all covered in [item types](./item-types.md). The client gets one branded portal and one progress bar instead of a scattered thread, BriefGate chases the outstanding items on a schedule you set, and the accounts-and-access group can even be marked as your own to-dos rather than the client's, using an owner-assigned item, if it's you who needs to remember to request the transfer. --- ## Client Intake Form Template URL: https://briefgate.dev/docs/client-intake-form-template # Client Intake Form Template A client intake form template covers what almost any agency or freelancer needs before starting a project — who the client is, what they're trying to achieve, what they already have, what you need from them, and when it's due. The fields below work as a copy-paste checklist on their own, and as a [downloadable PDF](/assets/downloads/client-intake-form-template.pdf) you can print or send as-is. ## Why one template, not one per project type Most intake templates online are built for a single niche — a web design questionnaire, a branding brief, a marketing intake — and duplicate most of their fields across each other. Underneath the surface differences, every client-facing project needs the same six kinds of information: who to contact, what the project is, what it should achieve, what materials already exist, what access it needs, and when it's due. This page covers that shared core. If you're specifically building a website, the [web design version](#web-design-version) below adds the few web-specific fields (pages needed, opening hours, analytics) on top of it; for a pure logo or brand identity project, see the [logo and brand design brief checklist](/docs/logo-and-brand-design-brief-checklist). Five kinds of field cover nearly everything on an intake form, and mixing them up is where most homemade forms go wrong: - **Text** — a short, structured answer: a name, an email, a URL. - **File** — an asset the client already has: a logo, a PDF, a set of photos. - **Choice** — a fixed set of options, so you get back a value you can act on instead of a sentence you have to interpret. - **Credential** — a login or a password. Not a text field — see [why](#why-credentials-get-their-own-field) below. - **Structured** — a small set of related facts with a fixed shape, like an address or opening hours, where you want the same fields back every time. ## The form, section by section ### 1. Contact | Field | Type | Why ask | |---|---|---| | Client or business name | Text | Needed to personalize everything else — a proposal, an invoice, the project name itself. | | Primary contact name and role | Text | Who you reach when something's unclear; a title tells you whether they can make final calls. | | Email address | Text | Where the finished brief, reminders, and the eventual deliverable all go. | | Phone number (optional) | Text | For anything too time-sensitive to wait on an email reply. | ### 2. Project basics | Field | Type | Why ask | |---|---|---| | Project type | Choice | Website, brand identity, marketing campaign, app, other — routes which later sections actually apply. | | Do you have an existing site or brand? | Choice (yes/no) | Distinguishes a from-scratch project from one with existing constraints to work within. | | Link to existing site or brand materials | Text (URL) | Only relevant if the answer above is yes; saves a round trip asking for it separately. | | What's driving this project now? | Text | A rebrand, a broken old site, a new launch — the reason shapes what "done" looks like more than any brief does. | ### 3. Goals | Field | Type | Why ask | |---|---|---| | What should this achieve in the first few months? | Text (long) | Turns "make it look professional" into something you can actually check against later. | | Who is this for? | Text (long) | The target audience is the basis for almost every content and design decision downstream. | | What would make this a failure, even if it looks great? | Text (long) | Surfaces the one hidden requirement — a legal disclosure, a stakeholder's pet feature — before it's a week-five surprise. | ### 4. Content and materials | Field | Type | Why ask | |---|---|---| | Logo | File | The actual file, not a screenshot of it — ask for SVG or a large PNG. | | Brand colors | Choice (color list) | Hex codes if they exist; a phone photo of something branded to sample from if they don't. | | Key copy or messaging | Text (long) | A headline, an about paragraph, anything legally sensitive (pricing, disclaimers) that should come from the client, not be invented. | | Photos or other assets | File (multiple) | State a minimum count and resolution up front, not after a 400px photo arrives. | ### 5. Access | Field | Type | Why ask | |---|---|---| | Existing site or hosting login | Credential | Never a plain text field — see the section below on why. | | Domain registrar access | Credential | Finding out two days before launch that the client doesn't have this is a common, avoidable delay. | | Third-party accounts (analytics, email, social) | Credential or Text | Whatever the new work needs to connect to; ask which ones apply rather than assuming. | ### 6. Timeline and budget | Field | Type | Why ask | |---|---|---| | Hard deadline, if any | Text | A launch date, an event, or a campaign start — distinguishes a real constraint from an aspirational one. | | Budget range | Choice | Offering three tiers gets an honest answer faster than asking a client to name a figure cold. | | Who has final sign-off | Text | Confirm this once at the start, especially the moment there's more than one stakeholder. | ## Web design version A website project needs everything above, plus a handful of fields specific to the medium. Add these on top of the six sections when "project type" is a website — the questionnaire framing and the section titles stay the same, only these rows are new: | Field | Type | Why ask | |---|---|---| | Which pages does the site need? | Choice (multiple) | Home, About, Services, Contact, Blog, and so on, picked from a fixed list rather than free text, so the answer maps straight onto a sitemap. | | Typography preference, if any | Choice | Most clients are fine with your recommendation; ask so the ones who care can say so before a design round gets built on the wrong font. | | Opening hours | Structured | Monday–Friday, Saturday, Sunday as three fixed fields rather than a paragraph to parse — only relevant for a business with set hours. | | Analytics tracking ID | Text | Nice to wire in from day one, but a site can launch and collect a data gap of a few days without lasting damage — not worth delaying launch over. | Nothing else changes: the admin login for an existing site, domain registrar access, and the exact address and contact details for the footer are already covered above under Access and Content and materials, the same as for any other client-facing project. ## Why credentials get their own field A password typed into the same box as the project brief gets stored, copied, and backed up exactly like the brief — in plaintext, in whatever tool held the form, indefinitely. Nothing about a form makes a credential safer just because the rest of the form is harmless. The fix is a field built for a one-time handoff: encrypted the moment it's submitted, shown once to the person who asked for it, then gone. [How to get client logins securely](/docs/how-to-get-client-logins-securely) covers the reasoning in more detail; [the secrets vault](/docs/secrets) is BriefGate's implementation of it — encrypted on the server the moment it arrives, never in the client's browser, and never a "zero-knowledge" claim we can't back up. ## Download the template The [client intake form template PDF](/assets/downloads/client-intake-form-template.pdf) has every field above, grouped into the same six sections, ready to print or fill in on screen — one page, no tracking, no signup. It's a starting point to adapt, not a fixed form: drop what a given project doesn't need, and add anything specific to your own process. ## Common mistakes **One long field for "brand stuff" or "assets."** A client can't picture "assets" — only a logo file and a set of photos. Break every bundled request into the individual files or facts it contains. **No minimum resolution stated on photo or logo fields.** "High resolution please" produces a phone screenshot about half the time; "at least 512px wide" produces a usable file. **Credentials collected the same way as everything else** — worth repeating, because it's the mistake with the worst downside. **No deadline attached to the form.** A request with no due date competes with everything else in a client's inbox that does have one, and loses. **Sending the form once and never following up** — most stalled intakes aren't refusals, they're a moment that passed unnoticed; see [why clients don't send materials](/docs/why-clients-dont-send-materials) for the reminder cadence that fixes it. ## Sending this same template through BriefGate Everything above works as a plain PDF or a shared document — that's the point of publishing it as one. Where it tends to fall short past the first few projects is the same place any static form does: nothing tracks who's answered what, nothing reminds a client who's gone quiet, and a credential typed into a form field sits exactly as exposed as it would in an email. An AI coding agent — or you, from the dashboard — can turn this exact list into a live client portal with one call to `define_intake`. Each row above maps to a real item type: the text fields stay `text` / `longtext`, the logo and photos become `image` and `file_list` with format and size constraints, brand colors become `color_list`, project type and budget range become `select`, the web design version's pages-needed field becomes `multiselect` and opening hours becomes `structured`, and every credential becomes a `secret` item — sealed on BriefGate's server the moment it's submitted and released to your agent exactly once. The client gets one branded link with nothing to sign up for (see [the client portal](/docs/client-portal-without-account)), BriefGate chases them on a schedule until every required item is in, or until the reminder cap is reached and the intake is marked stalled for you to step in (see the [chase engine](/docs/chase)), and your agent reads the finished intake back with one call to `get_intake_results` — typed data, not a PDF to re-key by hand. The full type reference is in [item types](/docs/item-types). On the Free plan an intake holds up to 10 items and has no secrets vault, so send a trimmed version of this list there (ten items, no credential rows); from the Solo plan up, the whole list goes out as is, credentials included. If you run the same kind of project repeatedly and want to save this exact field set as a reusable template — so a new project starts pre-filled instead of rebuilt from scratch — that's a paid feature starting on the Solo plan; see [templates](/docs/templates) for how saved templates work and what's included on each plan. ## Frequently asked questions ### Is a PDF client intake form enough, or do I need a portal? For a single project, a PDF or a shared document works fine — print it, email it, or drop it in a shared drive. A portal starts earning its keep once you're running more than a couple of projects at once and can't reliably remember who still owes what, or once a form field would have to hold a password. ### What's the difference between this and a web design intake form? There isn't a separate one — the web-specific fields (pages needed, opening hours, analytics ID) are folded into the [web design version](#web-design-version) section above, so this one template covers both a website project and anything else client-facing. ### Can I just put a password field in the PDF or a generic form? You can, but it's not a safe place for one — a filled-in PDF or a form's stored answers sit around indefinitely, readable by anyone with access to the file or the account behind the form. Collect credentials separately, through something built for a one-time reveal, rather than folding them into the same document as everything else. --- ## Client Intake for Cursor Agents URL: https://briefgate.dev/docs/cursor-client-intake # Client Intake for Cursor Agents: Collect Assets Without Leaving the Editor BriefGate MCP lets a Cursor agent collect a client's logo, copy, and credentials through a tracked portal instead of stalling mid-build. ## The problem Cursor's agent can scaffold and build most of a client website in one session, then stall on the same thing every time: the logo, the homepage copy, or the client's hosting login are missing, and nobody in the chat can produce them. You can ask the agent to pause and remind you to email the client, but the reminder just sits in a chat transcript nobody reopens. Two weeks later the project has stalled because the client never sent the photos, with no record of when you asked or whether you asked twice. The bottleneck is not the coding. It is the gap between "I need this from the client" and having it in a usable, typed form inside the same session where you are building. ## The solution BriefGate MCP closes that gap. Cursor's agent calls `define_intake()` with a list of typed items — a logo, hero copy, an opening-hours schedule, a WordPress login. BriefGate emails the client a branded portal link, validates what they submit in real time, and chases them automatically on a schedule you choose. When the client is done, the agent calls `get_intake_results()` and gets typed data and signed file URLs back — no parsing, no re-asking, no guessing whether "the logo" means the 200px JPEG from three emails ago. ## Setting up BriefGate MCP in Cursor Cursor reads MCP server configuration from `mcp.json` — either `.cursor/mcp.json` in a project (shared with a team when checked into the repo) or `~/.cursor/mcp.json` globally. Both use the same `mcpServers` object. You can add BriefGate two ways. ### Option A — hosted endpoint with OAuth (fewest moving parts) Add the hosted Streamable HTTP endpoint with no key at all: ```json { "mcpServers": { "briefgate": { "url": "https://mcp.briefgate.dev/mcp" } } } ``` Open Cursor's **Settings → Tools & Integrations**, find the `briefgate` entry, and click **Needs login**. Cursor opens your browser to the BriefGate dashboard to sign in and approve access, then stores the resulting credentials — nothing else to paste into the config file. ### Option B — local package with an API key (for CI, or if you'd rather not do a browser redirect) ```json { "mcpServers": { "briefgate": { "command": "npx", "args": ["-y", "@briefgate/mcp"], "env": { "BRIEFGATE_API_KEY": "bg_live_xxxxx" } } } } ``` Get the key from [https://app.briefgate.dev/app](https://app.briefgate.dev/app), then restart Cursor after editing `mcp.json`. Both options expose the same 13 tools: `define_intake`, `add_items`, `update_item`, `update_intake`, `list_intakes`, `get_intake_status`, `get_intake_results`, `request_revision`, `send_chase`, `manage_recipients`, `manage_webhook`, `list_folders`, and `create_folder`. ## Telling the agent when to use it Cursor rules work the same way `CLAUDE.md` does for Claude Code — add a project rule (`.cursor/rules/briefgate.mdc`, or a plain note in your existing rules file) so the agent reaches for BriefGate instead of asking in chat: ``` When you need an asset, credential, or piece of copy from the client: 1. Call define_intake with items[] describing exactly what is needed 2. The client is emailed a portal link automatically — do not email them yourself 3. Continue with other work; check get_intake_status or wait for the intake.completed webhook rather than blocking on a reply 4. Call get_intake_results to retrieve typed data and file URLs 5. Use type: "secret" for any password, API key, or login — never ask for credentials directly in chat or a commit message ``` ## A worked example **Agent:** "The site structure is in place. Before I can finish the booking page I need the current menu, access to Google Business Profile, and the API key for the reservation widget. Creating a BriefGate intake." The agent calls `define_intake`: ```json { "project_name": "Karlin Noodle Bar — Website Refresh", "client": { "email": "petra@karlinnoodlebar.cz", "name": "Petra", "language": "en" }, "items": [ {"key": "menu_pdf", "type": "file", "label": "Current menu (PDF)", "required": true, "constraints": {"formats": ["pdf"]}}, {"key": "gbp_access", "type": "secret", "label": "Google Business Profile login", "required": true}, {"key": "reservation_widget_key", "type": "secret", "label": "Reservation widget API key", "required": true} ], "chase_schedule": "default" } ``` BriefGate returns an `intake_id` and a `portal_url`, and emails Petra right away. See [item types](item-types.md) for the full list of constraints each type accepts, and [the MCP tools reference](mcp.md) for every field `define_intake` takes. **Agent:** "Intake sent. Petra will get an email at petra@karlinnoodlebar.cz. I'll continue building the booking page layout with placeholder content and pick this up once these three items are in." ## While the client fills the portal The agent does not have to wait idle. It keeps working on whatever does not depend on the missing items — layout, navigation, placeholder sections. BriefGate's [chase engine](chase.md) sends reminder emails on the schedule you set (`default` is T+2d, T+5d, T+9d, then weekly), so nobody has to remember to follow up. A registered `manage_webhook` endpoint reports `intake.completed` the moment the client finishes; otherwise `get_intake_status` checks progress cheaply. ## Resuming across Cursor sessions Cursor work is usually split across many short sessions, not one long-running conversation — close the editor, come back tomorrow, maybe on another machine. The next session has no memory of an intake created earlier unless something outside the chat records it, so note the `intake_id` in a comment near the code that depends on it: ``` // BriefGate intake in_8f3kQmR2 — menu PDF, GBP login, reservation widget key ``` Before assuming nothing has arrived — or worse, calling `define_intake` again and sending Petra a second portal link — a new session checks status first with `get_intake_status(intake_id: "in_8f3kQmR2")`. If the `intake_id` itself got lost, `list_intakes(client_email: "petra@karlinnoodlebar.cz")` finds the same intake by the client's address instead. ## Resuming with the results Once the portal shows everything submitted, the agent calls `get_intake_results`: ```json { "status": "completed", "results": { "menu_pdf": { "url": "https://files.briefgate.dev/in_8f3kQmR2/menu_pdf.pdf?token=...", "filename": "karlin-noodle-bar-menu.pdf", "mime": "application/pdf" }, "gbp_access": {"value": "petra@karlinnoodlebar.cz:MyPassword123", "first_reveal": true}, "reservation_widget_key": {"value": "rw_live_9f2kQmR2xY", "first_reveal": true} } } ``` **Agent:** "Menu, Google Business Profile login, and the reservation widget key are in. Storing both credentials in the project's secrets manager, then wiring the widget into the booking page and linking the menu PDF from the homepage." ## Handling credentials For `gbp_access` and `reservation_widget_key` above, `type: "secret"` is what makes them safe to move this way instead of `text`. The value travels to BriefGate over HTTPS and is sealed there — on BriefGate's server, not in the client's browser or by the agent — with a libsodium sealed box before it is ever written to the database. The agent does not decrypt anything itself: BriefGate's server returns the plaintext exactly once, on first reveal, through `get_intake_results`. A `secret` item needs the Solo plan or higher — a Free-plan intake rejects it with `plan_required` — while the rest of an intake's items work on any plan. See [Secrets](secrets.md) for the one-time-reveal mechanics, and [how to ask for client logins securely](how-to-get-client-logins-securely.md) if the agent only has a rough sense of what a project needs. ## Requesting a fix If the returned menu file turns out to be a blurry phone photo of the printed menu, not an actual export, the agent does not need a new email thread: ``` request_revision( intake_id: "in_8f3kQmR2", item_key: "menu_pdf", note: "The menu came through as a photo of the printed page and it's too blurry to typeset. Could you export a proper PDF from whatever tool you used to make it, or a flat, straight-on scan?" ) ``` The client sees the note on the flagged item in their portal, re-uploads, and the agent's next `get_intake_results` call picks up the corrected file — all inside the same tracked intake, with no separate email to lose track of. --- ## Async human input for coding agents URL: https://briefgate.dev/docs/async-human-input-for-coding-agents # Async Human Input for Coding Agents MCP elicitation asks whoever is running the agent, in the same session. An answer from a client who isn't there needs an asynchronous channel instead. ## The gap: elicitation is synchronous and in-session MCP's `elicitation/create` request (part of the stable [2025-06-18 specification](https://modelcontextprotocol.io/specification/2025-06-18/client/elicitation)) lets a server ask the connected client for structured information mid-call, nested inside whatever tool is running. The client must declare the `elicitation` capability at initialization, and the response comes back as one of three actions — `accept` with the submitted data, `decline`, or `cancel`. The message flow in the spec is a single round trip: server asks, client shows UI to the user in front of it, that user answers, the client replies to the server, and the original call continues. That shape is exactly right for "confirm this before I proceed" or "which of these three options do you want" — questions the person driving the agent can answer in the next few seconds without leaving the terminal. It is the wrong shape for a question aimed at someone who is not part of the session at all. A client-intake workflow — "get the client's logo, hero copy, and CMS login before continuing the build" — needs an answer from a business owner who has never opened Claude Code and won't see any UI the MCP client renders. Elicitation has no path to that person; it only reaches whoever is on the other end of the current connection. The spec also puts a second, sharper boundary on it: **"Servers MUST NOT use elicitation to request sensitive information."** That rules out asking for a password or an API key through elicitation even when the right person is in the session — one more reason credential collection needs its own mechanism rather than a bigger elicitation prompt. ## Tasks: durable and pollable, but still the same client The [Tasks extension](https://modelcontextprotocol.io/extensions/tasks/overview) is worth naming precisely: it's an **experimental, opt-in extension** to core MCP (documented in the `ext-tasks` repository), not a ratified part of the base spec, and it requires both the client and the server to negotiate support for it explicitly — actual support varies by client. Where it applies, it solves a real piece of the puzzle: instead of blocking a connection for the length of a long-running operation, the server returns a durable `taskId` immediately, the caller polls `tasks/get` (or subscribes to `notifications/tasks`), and if the task needs input mid-flight it moves to an `input_required` state that's resolved with `tasks/update`. That gets you two things elicitation alone doesn't: a handle that survives a disconnect, and a task that can sit in `input_required` for as long as it needs to instead of holding a connection open. What it does not get you is a way to reach someone outside the MCP session. The `input_required` state is still answered by whoever is operating the same connected client — a person approving a deployment inside the tool they're already using. A client who has never installed an MCP client and never will still isn't reachable through `tasks/update`, for the same reason elicitation can't reach them: both mechanisms resolve within the client-server connection, not outside it. ## What reaching a third party actually requires Getting an answer from someone who isn't in the session takes three things neither elicitation nor Tasks provide on their own: 1. **A channel that works without an MCP client** — email, a link, a web form. The person needs to be reachable the way they're already reachable, not the way your agent is. 2. **State that outlives the request** — something the agent can check back on minutes, hours, or days later, because the answer isn't coming in the next few seconds. 3. **Chasing** — a way to prompt the person again if they don't respond, because a single email sent once is easy to miss or forget. This is a product-level concern, not a protocol one — MCP defines how a server talks to a client, not how a client's operator reaches a third party who has no client at all. ## The pattern with BriefGate BriefGate's MCP tools are built around exactly this gap. The flow: 1. **`define_intake`** creates the request — a list of items (text, files, or `type: "secret"` for credentials) — and emails the client a portal link. The client fills it in from their phone or laptop; no account, no MCP client, no software to install. 2. **`get_intake_status`** is a cheap, synchronous check: how many items are in, which are still pending, when the client last opened the portal. Calling it is a normal step in an agent's loop, not an error path. 3. **`manage_webhook`** registers an HTTPS endpoint so the agent's process is notified the moment something changes (`item.submitted`, `intake.completed`, `intake.stalled`, and others), instead of polling on a guess. 4. **`get_intake_results`** retrieves the typed, submitted data once it's in — including a one-time reveal for any `secret` item, since credentials never travel through the earlier steps in plaintext. `define_intake`'s response includes a `follow_up` block that names which of the two check-back strategies fits: `"recommended": "webhook"` when an active endpoint already covers the relevant events, or `"schedule"` with a concrete `every_hours` and an `until` timestamp when it doesn't. An agent doesn't have to guess how often to check back — the API states it. Chasing is handled the same way a person would do it, minus the part where a person forgets: `chase_schedule` on `define_intake` (`gentle`, `default`, `aggressive`, or a custom interval) sends reminder emails automatically until the client finishes or the intake stalls, at which point `intake.stalled` fires with the specific `missing_items` still outstanding. ## How the agent should behave while waiting The behavior worth internalizing: **a pending status is a normal answer, not a failure.** An agent that calls `get_intake_status` and gets `{"status": "in_progress", "progress": {"submitted": 2, "total": 5}}` has learned something useful — three items are still outstanding — and should report that plainly and move on to whatever else it can do, rather than retrying in a tight loop or treating the incomplete state as an error. Concretely: - If a webhook is registered, don't poll at all — build (or continue other work) until the notification arrives, then react to it. - If no webhook is registered, follow the `follow_up.schedule` interval rather than inventing a polling cadence. - Never substitute an elicitation prompt for a question meant for the client. If the person who needs to answer isn't the one running the agent, that question belongs in `define_intake`, not `elicitation/create`. - Never ask for a credential through elicitation or a chat message — the [secrets vault](./secrets.md) exists precisely because the spec forbids the former and email leaves a permanent copy for the latter. - On `intake.stalled`, don't keep silently re-polling — surface it, since the chase engine has already exhausted its own attempts and a human now needs to intervene by some other channel. The short version: elicitation answers "what does the person in front of me want right now," and — where a client and server both support it — Tasks answers "how do I not block a connection while that same person thinks about it." Neither answers "what does the client, who isn't here, want," and that's a separate, async channel by design. --- ## Get client assets into your coding agent URL: https://briefgate.dev/docs/how-to-get-client-assets-into-your-coding-agent # How to Get Client Assets Into Your Coding Agent Every coding agent hits the same wall: the code is ready to go, and the client's logo, copy, or login isn't — and there's no good way to hand it over. ## The problem Claude Code, Cursor, Codex, and every agent like them are fast at the part they can see: files, structure, logic. They're useless at the part they can't see — a logo sitting on the client's laptop, a paragraph of homepage copy nobody has written yet, a password to a booking system the agent has no way to ask for safely. The agent hits that wall, and from there the project's speed depends entirely on a human loop the agent has no part in: you email the client, the client forgets, you follow up, the client sends something usable eventually, if the thread doesn't die first. That gap — between "the agent needs this" and "this exists somewhere the agent can read it" — is often the single slowest part of a client project, slower than any actual coding. ## Three ways people currently handle it, and why each falls short **Paste it into the chat.** Works for a sentence of copy. Falls apart for a file, because most agent chats either can't take an upload from a client who was never given access to the session, or the client pastes a screenshot of a logo instead of the source file, and now someone has to ask again. It also leaves no record: a request buried in a chat transcript from three weeks ago is not a request anyone reopens. **A shared Drive folder.** Better for files, still manual on both ends. You have to create the folder, share it, describe what should go in it in a separate message, notice when something new lands, and manually check whether the client actually put in the *right* thing — a 200px logo export instead of the source file is still a 200px logo export once it's in the folder. Nothing validates it, nothing reminds the client if they stop halfway, and nothing tells the agent when it's actually complete. **A generic form.** Typeform, Google Forms, a contact form bolted onto the site — these handle short text fields reasonably well and fall over on everything else a real project needs: no file uploads sized or typed the way a logo or a gallery needs to be, and nowhere safe to put a password. A client typing their WordPress login into a form field that emails it to you in plaintext is a liability wearing the shape of a solution. ## The pattern that actually closes the gap What works is inverting who initiates: instead of the agent (or you) chasing the client, the agent declares exactly what it needs — as typed, validated fields, not a paragraph of prose — and the client fills a portal built for that one job. 1. **The agent declares what's missing.** Not "please send some photos," but "12 to 20 photos, JPG or PNG, food and interior" — a shape the system can actually check. 2. **The client gets one link.** No account to create, no software to install. They open it, see a short list, and fill in or upload each item at their own pace. 3. **The system chases automatically.** Reminders go out on a schedule, addressed from you, without you or the agent remembering to follow up. 4. **The agent resumes on its own signal.** Instead of waiting on a reply in a chat window, the agent gets a webhook or checks a status endpoint, and picks the work back up the moment the answer exists — typed, validated, ready to use. BriefGate is built around exactly this pattern for AI coding agents specifically: the agent calls `define_intake()` with a list of typed items (files, images, structured data, one-time credentials), BriefGate handles the portal, validation, and chasing, and the agent calls `get_intake_results()` when it's done — no parsing, no re-asking, no PDF glued into an email that never should have carried a password in the first place. See [how BriefGate's item types work](./item-types.md) and [the chase engine](./chase.md) for the mechanics. ## Setting it up in your agent Any MCP-capable agent can use BriefGate this way — the pattern above doesn't depend on which one you use. Here's the one-line setup for the three most common ones, each with a full walkthrough: ### Claude Code ```bash claude mcp add --transport http briefgate https://mcp.briefgate.dev/mcp ``` Then run `/mcp` inside Claude Code, pick **briefgate**, and choose **Authenticate** — no key to copy or paste. Full guide: [Client Intake for Claude Code](./claude-code-client-intake.md). ### Cursor Add the hosted endpoint to `.cursor/mcp.json` or `~/.cursor/mcp.json`: ```json { "mcpServers": { "briefgate": { "url": "https://mcp.briefgate.dev/mcp" } } } ``` Then click **Needs login** next to the `briefgate` entry under **Settings → Tools & Integrations**. Full guide: [Client Intake for Cursor Agents](./cursor-client-intake.md). ### OpenAI Codex ```bash codex mcp add briefgate --url https://mcp.briefgate.dev/mcp codex mcp login briefgate ``` The first command registers the endpoint in `~/.codex/config.toml`, shared by the Codex CLI, its IDE extension, and the ChatGPT desktop app; the second runs Codex's own OAuth flow for it. Full guide: [Client Intake for OpenAI Codex](./codex-client-intake.md). ### Other agents BriefGate is a standard MCP server over Streamable HTTP with OAuth 2.1, plus a local stdio package for a client that would rather not do a browser redirect — nothing about the setup is specific to the three agents above. Any agent that speaks the Model Context Protocol should be able to add it the same way: point it at `https://mcp.briefgate.dev/mcp`, or run `npx -y @briefgate/mcp` locally with an API key. That should cover agents like Windsurf, Gemini CLI, or GitHub Copilot's agent mode, though we haven't walked through each one's specific configuration screen — if you hit a snag with a client not covered by name here, the [quickstart](./quickstart.md) documents all four connection methods generically enough to adapt. ## Once it's connected The setup differs slightly per agent; what happens after `define_intake()` is called does not. The client gets one branded portal link by email, submits what's asked for, gets chased automatically if they stall, and the agent picks the results back up — typed and ready — whether it asked through Claude Code, Cursor, Codex, or anything else speaking MCP. ## Next steps | Topic | Document | |---|---| | Full reference for all 13 MCP tools | [mcp.md](./mcp.md) | | All item types and their constraints | [item-types.md](./item-types.md) | | How the automatic reminders work | [chase.md](./chase.md) | | Handling passwords and API keys safely | [secrets.md](./secrets.md) | --- ## Client Intake for OpenAI Codex URL: https://briefgate.dev/docs/codex-client-intake # Client Intake for OpenAI Codex: Collect Assets Without Leaving the Terminal Codex can scaffold a booking flow in one session, then wait days for a client's gallery, price list, and booking-tool login to show up by email. ## The problem A photography studio hires you to rebuild their booking site. Codex gets the structure, the calendar widget, and the pricing page laid out fast — then stalls, because the site needs a real portfolio gallery, an actual price list, and admin access to whatever booking tool they already use, and none of that exists in the chat. You ask the client for it. They reply two days later with six phone photos pasted into an email and a screenshot of a spreadsheet. The booking-tool password never comes, because nobody wants to type a password into an email thread, and they'd be right not to. The gap is not Codex's coding speed. It's the distance between "the site needs 30 to 40 portfolio photos, a price list, and a login" and having those three things in a form Codex can actually use. ## The solution BriefGate MCP gives Codex a tool for this instead of a chat message. Codex calls `define_intake()` with a typed list of what the project needs. BriefGate emails the client a branded portal link, validates uploads as they come in, and chases the client automatically on a schedule you pick. When everything is in, Codex calls `get_intake_results()` and gets back files, structured data, and one-time credential reveals — no re-asking, no guessing which photo in the thread is the final one. ## Adding BriefGate to Codex Codex reads MCP server configuration from `~/.codex/config.toml` (or a project-scoped `.codex/config.toml` in a trusted project). The Codex CLI, the IDE extension, and the ChatGPT desktop app all share this same file, so a server you add once from the terminal is available in all three. ### Option A — local package, added from the CLI ```bash codex mcp add briefgate --env BRIEFGATE_API_KEY=bg_live_xxxxx -- npx -y @briefgate/mcp ``` This writes a `[mcp_servers.briefgate]` table to `config.toml`: ```toml [mcp_servers.briefgate] command = "npx" args = ["-y", "@briefgate/mcp"] [mcp_servers.briefgate.env] BRIEFGATE_API_KEY = "bg_live_xxxxx" ``` Get the key from [https://app.briefgate.dev/app](https://app.briefgate.dev/app). Prefer not to paste one into a config file at all? Add the server without `--env`, then call BriefGate's own `login` tool from inside a Codex session — it prints a short code and opens the dashboard in your browser, and once approved the key is stored in `~/.briefgate/credentials.json` for you. This is a separate step from anything Codex itself runs; it's a tool the BriefGate MCP server exposes, documented in [mcp.md](./mcp.md#login). ### Option B — hosted endpoint, OAuth BriefGate also runs a hosted Streamable HTTP endpoint with OAuth 2.1, and Codex's own MCP client supports both transports and OAuth natively — a `url` field instead of `command`/`args`, and a dedicated login step: ```bash codex mcp add briefgate --url https://mcp.briefgate.dev/mcp codex mcp login briefgate ``` The first command registers the endpoint; the second starts Codex's own OAuth flow for it, opening a browser to sign in and approve access. This mirrors how any Streamable HTTP MCP server with OAuth connects to Codex — it isn't a BriefGate-specific integration, just the general mechanism, documented on OpenAI's [Codex MCP page](https://developers.openai.com/codex/mcp). One caveat worth knowing before you plan around it: local `config.toml` is shared by the CLI, the IDE extension, and the ChatGPT desktop app, but **not** by ChatGPT's web interface — the web client reaches MCP-backed tools through installed plugins instead of reading your local config, so a server you add from the terminal will not automatically appear there. Either option exposes the same 13 tools: `define_intake`, `add_items`, `update_item`, `update_intake`, `list_intakes`, `get_intake_status`, `get_intake_results`, `request_revision`, `send_chase`, `manage_recipients`, `manage_webhook`, `list_folders`, and `create_folder`. ## Telling Codex when to use it Codex reads project instructions from `AGENTS.md`. Add a section so it reaches for BriefGate instead of asking in chat: ``` ## Client asset collection When the project needs a file, image, credential, or piece of copy from the client: 1. Call define_intake with items[] describing exactly what's needed 2. The client is emailed a portal link automatically — never ask for it in chat 3. Keep building whatever doesn't depend on the missing items 4. Check get_intake_status, or register a webhook with manage_webhook, instead of waiting idle for a reply 5. Call get_intake_results once complete 6. Use type: "secret" for any password or API key — never plain text ``` ## A worked example **Agent:** "The booking calendar and pricing layout are done. To finish the site I need the portfolio gallery, the current price list, and access to the booking tool you're already using. Setting up a BriefGate intake." Codex calls `define_intake`: ```json { "project_name": "Lucia Ferraro Photography — Booking Site", "client": { "email": "lucia@ferrarophoto.com", "name": "Lucia", "language": "en" }, "items": [ { "key": "gallery", "type": "file_list", "label": "Portfolio gallery", "help": "30 to 40 of your best shots, full resolution as exported from your camera or editing software — not resized for Instagram. We'll use the sharpest ones as the homepage hero.", "required": true, "constraints": { "formats": ["jpg", "png"], "min_count": 30, "max_count": 40 } }, { "key": "price_list", "type": "file", "label": "Current price list", "required": true, "constraints": { "formats": ["pdf"] } }, { "key": "booking_tool_login", "type": "secret", "label": "Booking tool admin login", "help": "Username and password for the scheduling system you use today, so we can pull your existing packages and availability rules.", "required": true } ], "chase_schedule": "default" } ``` **Agent:** "Intake sent to Lucia. I'll keep building the gallery grid and pricing template against placeholder content until these come in." Note the honest limit in the `gallery` item: `file_list` accepts a format list and a min/max count, but — unlike the single-upload `image` type — it has no minimum-width constraint the portal can enforce. The 40-image ask is capped and validated; "full resolution" is guidance in the help text the client reads, not something BriefGate rejects a low-resolution file over. See [item-types.md](./item-types.md) for what each type actually checks. ## Resuming across sessions Codex sessions, like most terminal agent sessions, don't persist a running memory of what's still outstanding once you close the terminal. Note the `intake_id` somewhere it'll survive — a comment near the code that depends on it, or a line in `AGENTS.md` for the project — and check `get_intake_status(intake_id: "in_...")` at the start of the next session before assuming nothing arrived, or calling `define_intake` again and sending Lucia a second link. ## Handling the results Once the gallery, price list, and login are all in, Codex calls `get_intake_results`: ```json { "status": "completed", "results": { "gallery": [ { "filename": "portrait-01.jpg", "url": "https://files.briefgate.dev/.../portrait-01.jpg?token=...", "width": 4032, "height": 3024 } ], "price_list": { "filename": "ferraro-photo-pricing-2026.pdf", "url": "https://files.briefgate.dev/.../price_list.pdf?token=..." }, "booking_tool_login": { "value": "lucia@ferrarophoto.com:MyPassword123", "one_time": true, "first_reveal": true } } } ``` The secret's `value` field is present only on this first call — store it in a secrets manager immediately, per [secrets.md](./secrets.md), because a later `get_intake_results` call won't return it again. If a photo in the gallery turns out to be a low-res export after all, `request_revision(intake_id, "gallery", note)` flags it without a new email thread — see [mcp.md](./mcp.md#request_revision) for the full call. ## Next steps | Topic | Document | |---|---| | Full reference for all 13 MCP tools | [mcp.md](./mcp.md) | | All item types and their constraints | [item-types.md](./item-types.md) | | Connecting other agents | [Get client assets into your coding agent](./how-to-get-client-assets-into-your-coding-agent.md) | --- ## BriefGate With AI Assistants URL: https://briefgate.dev/docs/ai-assistants # BriefGate With AI Assistants BriefGate is one MCP server — `https://mcp.briefgate.dev/mcp`, plus the local `npx -y @briefgate/mcp` package — that works the same way across every MCP-capable AI assistant: the assistant defines what it needs from a client, BriefGate emails them a portal link and chases them automatically, and the assistant retrieves typed results when the client is done. This page links the setup guide for each client and says plainly what is confirmed working and what isn't. ## Setup guides by client Signed in to BriefGate? The dashboard's **AI agents** page ([app.briefgate.dev/app/agents](https://app.briefgate.dev/app/agents)) has the snippet for each of these clients ready to copy. | Client | Transport | Auth | Status | Guide | |---|---|---|---|---| | Claude Code | Hosted HTTP or local `npx` | OAuth (auto) or API key / device login | Confirmed working | [Guide](./claude-code-client-intake.md) | | Cursor | Hosted HTTP or local `npx` | OAuth (auto) or API key | Confirmed working | [Guide](./cursor-client-intake.md) | | OpenAI Codex (CLI, IDE extension, ChatGPT desktop app) | Hosted HTTP or local `npx` | OAuth or API key | Confirmed working | [Guide](./codex-client-intake.md) | | claude.ai (web) | Hosted HTTP, custom connector | OAuth (auto, dynamic client registration) | Confirmed working | [Guide](./claude-ai-client-intake.md) | | Claude Desktop | Hosted HTTP (connector) or local `npx` | OAuth (auto) or API key / device login | Confirmed working | [Guide](./claude-desktop-client-intake.md) | | VS Code / GitHub Copilot | Hosted HTTP or local `npx` | OAuth (auto, via VS Code's MCP client) or API key | Confirmed working | [Guide](./vscode-copilot-client-intake.md) | | Gemini CLI | Hosted HTTP or local `npx` | OAuth (auto discovery) or API key | Config confirmed against official docs; not run end-to-end by us | [Guide](./gemini-cli-client-intake.md) | | ChatGPT (Developer mode) | Hosted HTTP, custom connector | OAuth (auto, dynamic client registration) | Config confirmed against official docs; not run end-to-end by us | [Guide](./chatgpt-client-intake.md) | | Windsurf (Cascade / Devin Desktop) | Hosted HTTP | API key header (confirmed); OAuth documented but exact config not confirmed | Header-based config confirmed; OAuth not confirmed | [Guide](./windsurf-client-intake.md) | "Confirmed working" means we've either connected it ourselves or the exact configuration is already documented and in production use. Where a row says "not run end-to-end by us," the configuration matches the client's own official documentation and BriefGate's OAuth implementation (OAuth 2.1, PKCE, RFC 7591 dynamic client registration — the same mechanism behind every "OAuth (auto)" row in this table), but we haven't personally walked through that specific client's login screen to confirm it. Each guide says so again at the point it matters, and gives you the fallback (usually an API key) if the automatic flow doesn't work for you. ## Why one server works everywhere BriefGate's hosted endpoint speaks the Model Context Protocol over Streamable HTTP and publishes standard OAuth 2.1 discovery metadata (`/.well-known/oauth-authorization-server`) with dynamic client registration and PKCE — any client that implements the MCP authorization spec can register itself and connect without a manually issued client ID. Clients that would rather not do a browser redirect (CI, scripts, or a client without OAuth support) can use a plain `Authorization: Bearer` header with an API key from [https://app.briefgate.dev/app](https://app.briefgate.dev/app) instead — every guide above documents both. All 13 tools — `define_intake`, `add_items`, `update_item`, `update_intake`, `list_intakes`, `get_intake_status`, `get_intake_results`, `request_revision`, `send_chase`, `manage_recipients`, `manage_webhook`, `list_folders`, `create_folder` — are identical across every client, and map 1:1 to the [REST API](./rest-api.md) for anything that isn't MCP at all. ## Not an agent-only tool Everything above is for the moments an AI assistant is doing the asking. A person can do the exact same thing by hand, with no agent and no API key, from the [dashboard quickstart](./dashboard-quickstart.md) — the client sees the same portal either way. ## Beyond chat assistants: n8n The clients above are conversational AI assistants. If you want BriefGate inside a workflow-automation tool instead — triggered by a CRM event, feeding a Google Drive upload, or given to an n8n AI Agent as a tool — see [BriefGate for n8n](./n8n.md): a verified community node (`n8n-nodes-briefgate`), available on n8n Cloud and self-hosted n8n. For Zapier, see [BriefGate for Zapier](./zapier.md): four instant triggers, two actions and two searches, available today as a private beta through an invite link while the integration waits for Zapier's review. ## Pricing for agent users Promotion code `AGENT20` gives 20% off subscription invoices for the first 3 months (on annual billing: 20% off the first annual payment). It is entered on the Stripe Checkout page. Plans and limits: [Billing and Plans](./billing.md). ## Next steps - [MCP tools reference](./mcp.md) — full parameter list for all 13 tools - [Item types](./item-types.md) — what each item type validates, including `secret` - [Quickstart](./quickstart.md) — the shortest path to a first working connection --- ## ChatGPT as an MCP Client URL: https://briefgate.dev/docs/chatgpt-client-intake # ChatGPT as an MCP Client: Ask the Client From Inside a Chat Using ChatGPT as an MCP client means it can call tools that write, not just ones that search and read — which is what lets a ChatGPT session that is scaffolding or reviewing client work connect to BriefGate and ask the client directly for the logo, the copy, or a login, instead of you copying that request into an email. ## The problem ChatGPT is increasingly used to draft the plan, the copy, or the code for a client project, and it hits the same wall a coding agent does: the client's logo, brand colors, and hosting credentials live in an inbox, not in the chat. A regular connector in ChatGPT can search and read from a service, but creating something — like a new client request — needs more than read access. ## The solution OpenAI's **Developer mode** is what unlocks full MCP tool calls (not just search/fetch) inside a ChatGPT conversation, which is what a write action like `define_intake` needs. Once BriefGate is added as a developer-mode connector, ChatGPT can call it directly: define what's needed from the client, and later check whether it has arrived, without leaving the conversation. ## Adding BriefGate as a connector **1. Turn on Developer mode.** In ChatGPT, go to **Settings → Apps & Connectors → Advanced settings** and switch on **Developer mode**. On a Business or Enterprise workspace, an admin may need to allow custom connectors first, under workspace connector settings. **2. Add the connector.** Go to **Settings → Connectors**, choose **Create** (or **Add custom connector**), and fill in: - **Name:** BriefGate - **MCP server URL:** `https://mcp.briefgate.dev/mcp` - **Authentication:** OAuth Save it, and ChatGPT opens a browser window to the BriefGate dashboard to sign in and approve access — there is no client ID to paste. BriefGate's hosted endpoint supports OAuth 2.1 with PKCE and RFC 7591 dynamic client registration, which is what lets ChatGPT register itself automatically the first time it connects, the same mechanism it uses for other custom connectors. **3. Enable it in a conversation.** Click the **+** in the chat composer, open **Connectors**, and turn BriefGate on for that conversation (or a specific GPT). ## What this gets you All 13 BriefGate tools become callable: `define_intake`, `get_intake_status`, `get_intake_results`, `add_items`, `update_item`, `update_intake`, `list_intakes`, `request_revision`, `send_chase`, `manage_recipients`, `manage_webhook`, `list_folders`, `create_folder` — the same set documented in the [MCP reference](./mcp.md), 1:1 with the REST API. ## A worked example **You:** "Set up a BriefGate request for the Nováková project — I need their logo, the homepage copy, and their WordPress login." ChatGPT calls `define_intake` with those three items (an `image`, a `longtext`, and a `secret`), BriefGate emails the client a portal link, and ChatGPT can report back: "Sent — I'll let you know when it's complete" (or you ask it to check with `get_intake_status` later in the same or a new conversation). ## Handling the results When the client is done, call `get_intake_results` (or ask ChatGPT to check) to get typed values back: the logo as a signed file URL, the copy as plain text, and the WordPress login decrypted and released once. A `missing` array in the response names anything still outstanding, so a half-finished intake is never silently treated as done. ## What we haven't verified ourselves OpenAI documents Developer mode and custom MCP connectors this way as of September 2026, and BriefGate's OAuth implementation matches what ChatGPT expects (standard discovery, dynamic client registration, PKCE). We have not run this connection end-to-end ourselves against a live ChatGPT account — menu names and plan availability (Plus/Pro/Business) can change on OpenAI's side faster than this page does. If a step above doesn't match what you see in your ChatGPT settings, OpenAI's own [Developer mode help article](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt) is the current source of truth. ## Next steps - [MCP tools reference](./mcp.md) — full parameter list for all 13 tools - [Item types](./item-types.md) — what `image`, `secret`, and the other item types validate - [Quickstart](./quickstart.md) — the same hosted endpoint, for Claude Code, Cursor, or any other MCP client --- ## Client Intake for Gemini CLI: From the Terminal URL: https://briefgate.dev/docs/gemini-cli-client-intake # Client Intake for Gemini CLI: Collect Client Assets From the Terminal Gemini CLI reads MCP servers from `settings.json`, and BriefGate's hosted endpoint works with it the same way it works with Claude Code: point the CLI at the URL, and Gemini's own OAuth flow handles the rest. ## The problem Gemini CLI builds and edits real projects from the terminal, and like any coding agent it stalls at the same point: the client's logo, the page copy, or a login exists somewhere outside the terminal, usually in an inbox the agent can't read. ## The solution Gemini CLI calls `define_intake` with a list of typed items, BriefGate emails the client a portal link and chases them on a schedule, and the agent calls `get_intake_results` once everything is in — typed values and signed file URLs, no re-asking. ## Setting up BriefGate MCP in Gemini CLI Gemini CLI reads MCP server configuration from `~/.gemini/settings.json` (global) or `.gemini/settings.json` in a project. ### Option A — hosted endpoint with OAuth (recommended) ```json { "mcpServers": { "briefgate": { "httpUrl": "https://mcp.briefgate.dev/mcp" } } } ``` No API key or client ID needed here. Gemini CLI's MCP client discovers OAuth automatically: it detects a `401` from the server, reads the OAuth metadata BriefGate publishes at `/.well-known/oauth-authorization-server`, performs dynamic client registration, and walks you through the browser login on first use — the same discovery flow Claude Code and VS Code use against the same endpoint. Run `/mcp` inside Gemini CLI afterwards to confirm `briefgate` shows as connected. ### Option B — local package with an API key (for CI, or to skip the browser step) ```json { "mcpServers": { "briefgate": { "command": "npx", "args": ["-y", "@briefgate/mcp"], "env": { "BRIEFGATE_API_KEY": "bg_live_xxxxx" } } } } ``` Get the key from [https://app.briefgate.dev/app](https://app.briefgate.dev/app) (**API Keys** in the dashboard sidebar). Both options expose the same 13 tools: `define_intake`, `add_items`, `update_item`, `update_intake`, `list_intakes`, `get_intake_status`, `get_intake_results`, `request_revision`, `send_chase`, `manage_recipients`, `manage_webhook`, `list_folders`, `create_folder`. ## Telling the model when to use it Add a note to `GEMINI.md` (Gemini CLI's equivalent of `CLAUDE.md`) so the agent reaches for BriefGate instead of leaving a TODO in the code: ``` When a client-supplied asset, credential, or piece of copy is missing: 1. Call define_intake with items[] describing exactly what is needed 2. Do not email the client yourself — BriefGate sends the portal link 3. Continue other work; poll get_intake_status or wait for the webhook 4. Call get_intake_results once complete, and use the typed values directly 5. Use type: "secret" for any password, API key, or login ``` ## A worked example **You:** "Before we wire up payments, ask the client for their Stripe secret key and the shop's opening hours." Gemini calls `define_intake` with a `secret` item (`stripe_secret_key`) and a `structured` item (`opening_hours`, a small JSON Schema for day/open/close). The client fills the portal from their phone; Gemini checks back later with `get_intake_status` and continues once `get_intake_results` reports both items received. ## Resuming across sessions `list_intakes` finds the request from a later session by project name or client email — the intake lives on BriefGate's side, not in the CLI's local state, so a new terminal session or a different machine picks up exactly where the last one left off. ## Not yet installable as a one-line extension Gemini CLI also supports installable extensions (`gemini extensions install <url>`) for a zero-config setup. BriefGate doesn't have one published yet — the `settings.json` method above is the one that works today; check [briefgate-mcp on GitHub](https://github.com/sekera-radim/briefgate-mcp) for whether that's changed. ## Next steps - [MCP tools reference](./mcp.md) — full parameter list for all 13 tools - [Item types](./item-types.md) — what each item type validates - [Quickstart](./quickstart.md) — the same hosted endpoint for Claude Code, Cursor, or any other MCP client --- ## Client Intake for Windsurf: Assets From Cascade URL: https://briefgate.dev/docs/windsurf-client-intake # Client Intake for Windsurf: Collect Client Assets From Cascade Windsurf's agent (Cascade) reads MCP servers from `mcp_config.json`. BriefGate's hosted endpoint connects the same way any remote Streamable HTTP MCP server does, with an API key as the fastest path to a working setup. A naming note first: Windsurf's editor is now distributed as part of **Devin Desktop** (Cognition acquired Windsurf), and its current official docs live at `docs.devin.ai` rather than the old `docs.windsurf.com` — if a link below looks unfamiliar, that's why. ## The problem Cascade can build most of a client website or app in one session, then stalls on the same thing every agent does: the logo, the homepage copy, or a hosting login the client hasn't sent yet. ## The solution Cascade calls `define_intake` with the list of items needed, BriefGate emails the client a portal link and chases them automatically, and Cascade calls `get_intake_results` once everything has arrived. ## Setting up BriefGate MCP in Windsurf Add a server to `mcp_config.json` (Windsurf settings → Cascade → MCP Servers → view raw config, or the project-level file). ### Option A — hosted endpoint with an API key (verified path) ```json { "mcpServers": { "briefgate": { "serverUrl": "https://mcp.briefgate.dev/mcp", "headers": { "Authorization": "Bearer bg_live_xxxxx" } } } } ``` Get the key from [https://app.briefgate.dev/app](https://app.briefgate.dev/app) (**API Keys** in the dashboard sidebar). This is the configuration we've confirmed against Windsurf/Devin Desktop's published `mcp_config.json` format for a remote Streamable HTTP server. Windsurf's docs also state that Cascade supports OAuth for remote MCP servers, and BriefGate's hosted endpoint speaks standard OAuth 2.1 with dynamic client registration and PKCE (the same mechanism Claude Code and VS Code use against it) — but we have not confirmed the exact `mcp_config.json` syntax Cascade expects to trigger that flow instead of a static header. If Cascade prompts you to authenticate rather than reading the header above, follow its in-app flow; otherwise, the header-based setup above is the one to rely on. ### Option B — local package with an API key ```json { "mcpServers": { "briefgate": { "command": "npx", "args": ["-y", "@briefgate/mcp"], "env": { "BRIEFGATE_API_KEY": "bg_live_xxxxx" } } } } ``` Both options expose the same 13 tools: `define_intake`, `add_items`, `update_item`, `update_intake`, `list_intakes`, `get_intake_status`, `get_intake_results`, `request_revision`, `send_chase`, `manage_recipients`, `manage_webhook`, `list_folders`, `create_folder`. ## Telling Cascade when to use it Add a rule (Windsurf → Customizations → Rules, or a project `.windsurfrules` file): ``` When you need a file, credential, or piece of copy from the client: 1. Call define_intake with items[] describing exactly what is needed 2. Do not email or message the client yourself — BriefGate sends the portal link 3. Continue with other work; check get_intake_status rather than blocking 4. Call get_intake_results to retrieve typed data and file URLs 5. Use type: "secret" for any password, API key, or login ``` ## A worked example **You:** "The booking page needs the current menu PDF and the Google Business Profile login. Ask the client." Cascade calls `define_intake` with a `file` item and a `secret` item. The client uploads and fills in from their phone; Cascade picks the results up with `get_intake_results` on the next relevant turn. ## Next steps - [MCP tools reference](./mcp.md) — full parameter list for all 13 tools - [Item types](./item-types.md) — what each item type validates - [Quickstart](./quickstart.md) — the same hosted endpoint for Claude Code, Cursor, or any other MCP client --- ## Client Intake for VS Code (Copilot) URL: https://briefgate.dev/docs/vscode-copilot-client-intake # Client Intake for VS Code and GitHub Copilot: Ask the Client Without Leaving the Editor VS Code's built-in MCP support (used by GitHub Copilot's agent mode, and by any other chat extension that reads the same `mcp.json`) connects to BriefGate's hosted endpoint with OAuth handled automatically by the editor. ## The problem Copilot's agent mode can scaffold and edit a real client project, then hits the same wall every coding agent does: the logo, the page copy, or a hosting login lives in an inbox, not in the workspace. ## The solution The agent calls `define_intake` with typed items, BriefGate emails the client a portal link and chases them on a schedule, and the agent calls `get_intake_results` once everything has arrived — typed values and signed file URLs, ready to use. ## Setting up BriefGate MCP in VS Code VS Code reads MCP servers from `.vscode/mcp.json` (workspace, shareable with a team) or the user-level `mcp.json` (Command Palette → **MCP: Open User Configuration**). ### Option A — hosted endpoint with OAuth (fewest moving parts) ```json { "servers": { "briefgate": { "type": "http", "url": "https://mcp.briefgate.dev/mcp" } } } ``` No `oauth` block is needed: BriefGate's server publishes standard OAuth 2.1 discovery metadata (`/.well-known/oauth-authorization-server`) and supports dynamic client registration with PKCE, and VS Code's MCP client handles that automatically — a browser window opens for you to sign in and approve access the first time you connect, the same way it does for other remote MCP servers that support discovery. ### Option B — local package with an API key (for CI, or a non-interactive setup) ```json { "servers": { "briefgate": { "command": "npx", "args": ["-y", "@briefgate/mcp"], "env": { "BRIEFGATE_API_KEY": "${input:briefgate_api_key}" } } }, "inputs": [ { "id": "briefgate_api_key", "type": "promptString", "description": "BriefGate API key", "password": true } ] } ``` The `inputs` entry makes VS Code prompt for the key once and store it securely, instead of it sitting in plain text in `mcp.json`. Get a key from [https://app.briefgate.dev/app](https://app.briefgate.dev/app) (**API Keys** in the dashboard sidebar). Both options expose the same 13 tools: `define_intake`, `add_items`, `update_item`, `update_intake`, `list_intakes`, `get_intake_status`, `get_intake_results`, `request_revision`, `send_chase`, `manage_recipients`, `manage_webhook`, `list_folders`, `create_folder`. ## Telling the agent when to use it Add a note to your repo's Copilot instructions file (`.github/copilot-instructions.md`): ``` When a client-supplied asset, credential, or piece of copy is missing: 1. Call define_intake with items[] describing exactly what is needed 2. Do not email the client yourself — BriefGate sends the portal link 3. Continue other work; check get_intake_status rather than blocking on a reply 4. Call get_intake_results once complete, and use the typed values directly 5. Use type: "secret" for any password, API key, or login ``` ## A worked example **You, in Copilot Chat (agent mode):** "Before the contact form can send mail, ask the client for their SMTP credentials and the address it should send to." Copilot calls `define_intake` with a `secret` item and a `text` item. The client fills the portal from their phone; you (or Copilot, on the next relevant turn) call `get_intake_results` and wire the values straight into the environment config. ## Next steps - [MCP tools reference](./mcp.md) — full parameter list for all 13 tools - [Item types](./item-types.md) — what each item type validates - [Quickstart](./quickstart.md) — the same hosted endpoint for Claude Code, Cursor, or any other MCP client --- ## Client Intake for Claude Desktop URL: https://briefgate.dev/docs/claude-desktop-client-intake # Client Intake for Claude Desktop: Ask the Client From a Chat Claude Desktop connects to BriefGate two ways: as a remote custom connector (no install, browser-based sign-in) or as a local MCP server via `claude_desktop_config.json`. Both give you the same 13 tools. ## The problem A lot of client project work — reviewing copy, planning a page, checking a brief — happens in a plain Claude Desktop chat, not inside a coding agent. The same bottleneck shows up anyway: the client's logo or their hosting login is sitting in an inbox, and someone has to go get it. ## Option A — remote custom connector (no install) Go to **Settings → Connectors** in Claude Desktop (the same **Customize → Connectors** panel claude.ai uses — Claude Desktop and claude.ai share connector configuration), choose **Add custom connector**, and enter: - **Name:** BriefGate - **URL:** `https://mcp.briefgate.dev/mcp` Leave **Advanced settings** (OAuth Client ID/Secret) blank — BriefGate's server supports dynamic client registration, so Claude registers itself automatically the first time you connect, the same way it does for the hosted endpoint in claude.ai (see the [claude.ai connector guide](./claude-ai-client-intake.md)). This is available to individual Pro and Max plans, not only Team and Enterprise; the Free plan is limited to one custom connector total. ## Option B — local package via `claude_desktop_config.json` Open **Settings → Developer → Edit Config** (or edit the file directly — `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows) and add: ```json { "mcpServers": { "briefgate": { "command": "npx", "args": ["-y", "@briefgate/mcp"], "env": { "BRIEFGATE_API_KEY": "bg_live_xxxxx" } } } } ``` Get the key from [https://app.briefgate.dev/app](https://app.briefgate.dev/app) (**API Keys** in the dashboard sidebar), or skip the key entirely and run `npx -y @briefgate/mcp login` once in a terminal — it opens a device-flow login in your browser and stores the resulting credentials for the local package to use. Restart Claude Desktop after editing the config. Both options expose the same 13 tools: `define_intake`, `add_items`, `update_item`, `update_intake`, `list_intakes`, `get_intake_status`, `get_intake_results`, `request_revision`, `send_chase`, `manage_recipients`, `manage_webhook`, `list_folders`, `create_folder`. ## A worked example **You:** "Draft a BriefGate request for the Kovář project: their logo, three product photos, and the shop's opening hours." Claude calls `define_intake` with an `image`, a `file_list`, and a `structured` item. BriefGate emails the client a portal link; you check progress later with `get_intake_status`, or ask Claude to look, in the same or a new conversation — the intake lives on BriefGate's side, not in the chat's memory. ## Handling the results `get_intake_results` returns typed values once the client is done: the logo and photos as signed file URLs, the hours as structured JSON. Anything still missing is named in a `missing` array rather than silently treated as complete. ## Next steps - [MCP tools reference](./mcp.md) — full parameter list for all 13 tools - [Item types](./item-types.md) — what each item type validates - [claude.ai (web) setup](./claude-ai-client-intake.md) — the same connector from a browser, including Team/Enterprise setup - [Quickstart](./quickstart.md) — the same hosted endpoint for Claude Code, Cursor, or any other MCP client --- ## Client Intake for claude.ai: Ask From a Browser URL: https://briefgate.dev/docs/claude-ai-client-intake # Client Intake for claude.ai: Ask the Client From a Browser claude.ai connects to BriefGate as a custom connector — no install, no API key to copy, sign in once from your browser. ## The problem Not every project conversation happens in a coding agent. A lot of client work — reviewing a brief, drafting copy, planning a page — happens in a plain claude.ai chat, and it hits the same bottleneck: the client's logo or their hosting login lives in an inbox nobody in the conversation can reach. ## Adding the connector Individual Pro and Max accounts: go to **Customize → Connectors**, click **+**, choose **Add custom connector**, and enter: - **Name:** BriefGate - **URL:** `https://mcp.briefgate.dev/mcp` Leave **Advanced settings** (OAuth Client ID/Secret) blank. BriefGate's hosted endpoint supports OAuth 2.1 with PKCE and RFC 7591 dynamic client registration, so claude.ai registers itself automatically and walks you through sign-in and consent on the BriefGate dashboard — nothing to paste. The Free plan allows one custom connector; Pro and Max have no fixed limit documented by Anthropic as of this writing. **Team and Enterprise:** an organization owner adds it once under **Organization settings → Connectors → Add → Custom → Web** with the same URL; members then turn it on individually from **Customize → Connectors** in their own chats, without repeating the setup. Once added, enable BriefGate per conversation with the **+** button in the composer → **Connectors**. ## What this gets you All 13 tools become callable: `define_intake`, `get_intake_status`, `get_intake_results`, `add_items`, `update_item`, `update_intake`, `list_intakes`, `request_revision`, `send_chase`, `manage_recipients`, `manage_webhook`, `list_folders`, `create_folder` — see the [MCP reference](./mcp.md) for full parameters. ## A worked example **You:** "Set up a BriefGate request for the Dvořák rebrand: the old logo files, the new tagline copy, and access to their Google Business Profile." Claude calls `define_intake` with a `file_list`, a `longtext`, and a `secret` item. BriefGate emails the client a portal link and chases them on the schedule you set; come back to the same conversation later (or a new one) and ask Claude to check `get_intake_status`. ## Handling the results `get_intake_results` returns typed values once the client has submitted everything: files as signed URLs, text as plain strings, credentials decrypted and released exactly once. A `missing` array names anything still outstanding. ## Next steps - [MCP tools reference](./mcp.md) — full parameter list for all 13 tools - [Item types](./item-types.md) — what each item type validates - [Claude Desktop setup](./claude-desktop-client-intake.md) — the same connector, plus a local-install option - [Quickstart](./quickstart.md) — the same hosted endpoint for Claude Code, Cursor, or any other MCP client --- ## Client Onboarding Automation: Deal to Kickoff URL: https://briefgate.dev/docs/client-onboarding-automation # Client onboarding automation: from signed deal to a project folder that is already full The stretch between a client saying yes and the work actually starting is mostly the same four steps on every project: decide what you need from them, ask for it, follow up until it arrives, and hand it to whoever builds. None of those four steps requires a human to do them by hand every time — and the difference between doing them by hand and automating them is the difference between a kickoff that waits on a logo file and one that starts with everything already in the folder. This guide is tool-agnostic. It covers what is actually worth automating in this stretch, what BriefGate does with each piece, and which of four routes — the dashboard, Zapier, n8n, or your own code against the API — fits your shop. The three linked guides at the end go deep on each specific tool; this one is the map. ## What is actually worth automating Two of the four steps above are mechanical and repeat identically across projects: **asking** (send the same kind of request, in the same shape, every time a deal closes) and **following up** (send reminders until it's done, stop the moment it is). Both are pure overhead — there is no judgment call in sending a reminder email, and doing it by hand mostly means someone forgets to. The other two steps are not mechanical, and automating them past a point makes the intake worse, not better. **Deciding what you need** still requires a person to think about the specific project — a template gets you most of the way, not all of it. **Reviewing what comes back** — is this logo actually usable, is this copy actually final — is a judgment call a client-facing person should make, not a rule engine. BriefGate's own review step reflects this split: a submitted item auto-approves after a set number of hours if nobody acts on it, but nothing stops you from opening the item and requesting a revision first (see [Dashboard quickstart](./dashboard-quickstart.md#5-review-what-comes-back)). So the useful automation target is narrower than "the whole onboarding process": define the request once, send it without writing an email, chase it without writing a reminder, and hand off what comes back in a form the next step can use directly. That is also exactly the shape of what BriefGate does. ## Start from a reusable request, not a blank page Every BriefGate item has a type — `text`, `longtext`, `file`, `file_list`, `image`, `color_list`, `select`, `multiselect`, `boolean`, `url`, `secret`, or `structured` — twelve in total, each with its own constraints (minimum image width, a JSON Schema for structured facts like opening hours, allowed file formats). See [Item types](./item-types.md) for the full reference. Typed items mean the portal validates the client's answer before it can be submitted, and whoever reads the result gets a usable value, not a screenshot to eyeball. The part that actually saves the re-typing is a **template**: a saved item list you point a new intake at instead of rebuilding it. Seven public templates (websites for a restaurant, an advisor and a club, a general website, an e-shop, a logo and brand identity, and a mobile app, all Czech-language) ship on every plan including Free, and Solo ($29/month) and up can save their own. On Agency plans, templates any seat member creates are visible to the whole team, so the list only has to be built once per project type. See [Templates](./templates.md) for the full built-in item sets and how overriding one item while keeping the rest works. ## Sending it without writing an email Once the request exists — from scratch, from a template, or from an AI coding agent calling `define_intake` — sending it does not mean composing an email. BriefGate emails the client a personal link to their portal: no account, no password, nothing to install. The client sees a branded page (on paid plans) listing what is still needed and what is already done, and nothing on that page mentions how the request was built — dashboard or agent look identical to the client. See [What is BriefGate?](./what-is-briefgate.md#what-happens-in-between-either-way) for what that portal experience actually looks like. One detail worth knowing if you're wiring this into your own code: the `portal_url` an intake returns does not, by itself, open the portal — it needs a one-time sign-in token that the API never returns. The client's emailed link carries that token; a link you construct yourself from `portal_url` alone will not work. ## The follow-up cadence running on its own This is the piece that turns "send once and hope" into "send once and it gets done." You pick a cadence when the intake is created (or change it afterward without re-sending the invitation) and BriefGate handles timing, deduplication, and quiet hours from there — see [Chase engine](./chase.md) for the complete reference. | Schedule | Reminders | |---|---| | `default` | T+2 days, T+5 days, T+9 days, then weekly | | `gentle` | T+3 days, T+8 days, then every 14 days (also skips weekends) | | `aggressive` | T+1 day, T+3 days, T+5 days, then every other day | | `custom` | Every interval you set — defaults to every 3 days if left unspecified, bounded between 5 minutes and 90 days | | `off` | No automatic reminders | Reminders are held outside the client's local 8:00–19:00 window unless you explicitly turn quiet hours off, and every schedule except `gentle` still sends on weekends. The chase engine stops the moment the client finishes, and stops permanently — marking the intake stalled and firing a webhook — once it hits the reminder cap (three attempts by default), so it hands the problem back to you instead of nagging forever. On the Free plan, only `default` and `off` are available; the other cadences need Solo and up. ## The handover at the end When the intake completes, there are two shapes the result can take, and which one you want depends on who's on the receiving end. If a human is going to open the result — a designer picking through photos, an account manager reviewing what came in — **Download everything (ZIP)** on the intake page bundles every file plus a `podklady.pdf` and `podklady.md` summary into one download, organized into one subfolder per item, exactly as the client uploaded it. See [ZIP download](./zip.md) for the full contents and the size limit. If code is going to consume the result — your own script, a Zapier or n8n step, an AI coding agent — `get_intake_results` (or `GET /v1/intakes/:id/results`) returns typed JSON: signed URLs with checksums for files, a validated object for structured items, plain values for everything else, and a `missing` array naming anything still outstanding. Either way, a `secret` item (a password or API key the client entered) is encrypted on the server on receipt and released once — never end-to-end encrypted, never zero-knowledge, and never rendered on any screen more than that one time. ZIP downloads leave secrets out by default so the one-time reveal stays available; including them consumes it, same as reading them through the API. ## Which of the four routes fits your shop All four routes end up defining the same request, sending the same portal link, and running the same chase engine underneath — what differs is where the "when this happens, do that" logic lives. **The dashboard, by hand.** No code, nothing to connect. You build the intake, send it, and watch it come in from the browser. Right for a shop running a handful of intakes at a time where a person is already looking at the dashboard anyway. See [Dashboard quickstart](./dashboard-quickstart.md). **Zapier.** You already have deals, files, and notifications flowing through Zapier and want intake to be one more step in that chain — a CRM "deal won" trigger starting an intake, a completed intake dropping files into Drive. Right for a shop whose stack is already built on no-code connectors. See [Zapier client intake automation](./zapier.md). **n8n.** The same building blocks as Zapier, self-hosted, plus the option to hand BriefGate to an AI Agent node as a tool it decides to call on its own. Right for a shop that wants Zapier-style automation without a third party holding the workflow, or that is already building agentic workflows in n8n. See [n8n client intake automation](./n8n.md). **Your own code, against the API and webhooks.** Full control: a custom agent loop, a CI pipeline, a backend service reacting to `intake.completed` in real time instead of polling. Right for a shop with engineering capacity that wants intake wired directly into its own systems rather than through a third-party automation platform. See [Client intake webhooks guide](./client-intake-webhooks-guide.md), the [REST API reference](./rest-api.md), and [Webhooks](./webhooks.md). Whichever route you pick, the mechanical middle — the request, the send, the chase — is the same. What you're really choosing is where the rest of your business logic already lives, and connecting BriefGate to that instead of building a fifth place for it. --- ## React to intake events in your code URL: https://briefgate.dev/docs/client-intake-webhooks-guide # Reacting to Client Intake Events in Your Own Code The moment a client finishes an intake, the files, copy, and credentials you asked for already exist — typed, validated, ready to read. The question is how your code finds out. This guide is for developers who'd rather receive a webhook and act on it directly than route the event through an iPaaS like Zapier or n8n first. It assumes you already know [what webhooks are and how they're signed](./webhooks.md) — that page is the reference; this one is the how-to. We'll build a receiver that verifies the signature, decides what to do per event, and fetches typed results once an intake is done — enough to kick off a build, drop files into a repo or bucket, post to your own dashboard, or hand the results to a coding agent. The examples use Express, since that's what BriefGate's own quickstart snippets use, but the logic ports directly to Fastify, Hono, or a plain Node `http` server — the only Express-specific part is getting the raw body. ## Registering the endpoint Register your receiver with only the events you plan to act on — if you just need to know when material is ready, you may not need `item.submitted`: ```bash curl -X POST https://api.briefgate.dev/v1/webhooks \ -H "Authorization: Bearer bg_live_xxxxx" \ -H "Content-Type: application/json" \ -d '{ "url": "https://yourapp.com/webhooks/briefgate", "events": ["intake.completed", "intake.stalled", "chase.bounced"] }' ``` The response includes a `secret` shown exactly once — save it as `BRIEFGATE_WEBHOOK_SECRET` or similar; there's no way to fetch it again, only to delete the endpoint and register a new one. Full request/response shapes and the Slack/Discord chat format are in [the webhooks reference](./webhooks.md); this guide covers only the `raw` format, the one meant for code. ## Getting the raw body right The signature is computed over the exact bytes BriefGate sent, not your parsed object — if a JSON body parser runs first and you re-serialize to check the signature, whitespace or key-order differences make legitimate requests fail. Capture the raw string before parsing: ```javascript import express from 'express'; const app = express(); // Stash the raw bytes for verification; req.body still parses normally. app.use(express.json({ verify: (req, _res, buf) => { req.rawBody = buf.toString('utf8'); }, })); ``` ## Verifying the signature BriefGate signs every delivery with `X-BriefGate-Signature: t=<unix>,v1=<hex>`, where `v1` is `HMAC-SHA256(webhook_secret, "${t}.${rawBody}")` in hex. Reject anything more than 5 minutes old to block replay, and compare `v1` with `timingSafeEqual`, never `===` — a plain string comparison leaks timing information about how many leading characters matched, which is exactly what a signature check shouldn't do: ```javascript import { createHmac, timingSafeEqual } from 'crypto'; function verifyBriefGateSignature(rawBody, secret, signatureHeader) { if (!signatureHeader) throw new Error('Missing signature header'); const parts = Object.fromEntries( signatureHeader.split(',').map(p => p.split('=', 2)), ); const t = parts['t']; const v1 = parts['v1']; if (!t || !v1) throw new Error('Malformed signature header'); // 5-minute tolerance window, same as BriefGate enforces on its own side. if (Math.abs(Date.now() / 1000 - Number(t)) > 300) { throw new Error('Timestamp outside tolerance window'); } const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex'); const a = Buffer.from(v1, 'hex'); const b = Buffer.from(expected, 'hex'); // timingSafeEqual throws on a length mismatch, so check that explicitly first. if (a.length !== b.length || !timingSafeEqual(a, b)) { throw new Error('Signature mismatch'); } } ``` One shortcut to avoid: re-signing the parsed `req.body` with `JSON.stringify(req.body)` instead of the raw string. Key order and spacing aren't guaranteed to match what BriefGate actually sent, so that rejects valid requests intermittently — the `verify` callback above is the fix, capturing the exact bytes once before Express touches them. ## Wiring the route ```javascript app.post('/webhooks/briefgate', async (req, res) => { try { verifyBriefGateSignature(req.rawBody, process.env.BRIEFGATE_WEBHOOK_SECRET, req.header('X-BriefGate-Signature')); } catch (err) { return res.status(400).send('invalid signature'); // discard without acting on the payload } const event = req.header('X-BriefGate-Event'); // same as req.body.event, but available pre-parse const { intake_id } = req.body; res.status(200).send('ok'); // acknowledge before doing any real work handleEvent(event, req.body, intake_id).catch(err => { console.error('webhook handler failed', { event, intake_id, err }); }); }); ``` Responding before `handleEvent` finishes matters: delivery has a 10-second budget, and building files or calling another API can easily run longer. Do the slow work after replying, or hand it to a queue. ## Which events to act on, and how The full event list and payload shapes are in [the webhooks reference](./webhooks.md#events); here's what each one is *for* in a code-driven pipeline: - **`intake.completed`** — usually matters most. All required items are in; call `get_intake_results` and start whatever the results unlock. - **`item.submitted`** — fires per item, before the intake is complete. Useful to start processing one asset early, but it can arrive before *or* after `intake.completed` for the last item — don't assume ordering. - **`intake.stalled`** — the reminder allowance is used up and BriefGate has stopped chasing. A signal for a human, not a retry loop. - **`intake.overdue`** — fires once, when a due date has passed with something still outstanding. Good for a dashboard flag. - **`chase.bounced`** — a reminder hard-bounced or was reported as spam. `still_chasing` says whether BriefGate gave up on that recipient or intake entirely. - **`client.viewed`** / **`intake.archived`** — lower-signal lifecycle events; most pipelines just log these. ```javascript async function handleEvent(event, payload, intakeId) { switch (event) { case 'intake.completed': await fetchResultsAndKickOffBuild(intakeId); break; case 'intake.stalled': await notifyOwnerToFollowUpManually(intakeId, payload.missing_items); break; case 'chase.bounced': if (!payload.still_chasing) await flagIntakeForManualOutreach(intakeId); break; default: console.log('unhandled event', event, intakeId); // client.viewed, intake.archived, etc. } } ``` ## Idempotency and retries BriefGate retries a delivery on anything other than `2xx`, six attempts in total backing off over about eight and a half hours, and can rarely deliver the same event twice even after a `2xx`. Your handler should be safe to run twice — key on `intake_id` + `event` and skip work already done: ```javascript const seen = new Set(); // swap for Redis/DB in anything beyond a single process async function fetchResultsAndKickOffBuild(intakeId) { const dedupeKey = `intake.completed:${intakeId}`; if (seen.has(dedupeKey)) return; seen.add(dedupeKey); const results = await getIntakeResults(intakeId); // ... start the build, write files, whatever comes next } ``` Anything other than `2xx` — including a crash before you respond — is treated as a failed attempt and retried on the schedule in [the reference doc](./webhooks.md#retries). Returning `410 Gone` deliberately deactivates the endpoint, the documented way to unsubscribe without a separate API call. ## Pulling typed results Once you have an `intake_id` from `intake.completed`, fetch the results — the event itself deliberately carries only `intake_id`, `project_name`, and `timestamp`, not the answers. ```javascript async function getIntakeResults(intakeId) { const url = new URL(`https://api.briefgate.dev/v1/intakes/${intakeId}/results`); // A secret item can only be revealed once — don't burn it in a pipeline that logs everything. url.searchParams.set('exclude_secrets', 'true'); const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.BRIEFGATE_API_KEY}` }, }); if (!res.ok) throw new Error(`results fetch failed: ${res.status}`); return res.json(); } ``` `GET /v1/intakes/:id/results` is API-key only — no dashboard session — since it also advances an `only_new` cursor and can reveal secrets, both of which only make sense for a service acting on its own key. See [the REST API reference](./rest-api.md#get-v1intakesidresults) for the full response shape and the `only_new`/`include_pending` parameters. If you do need a credential — say, to log into a client's WordPress install and push a plugin — drop `exclude_secrets` and read it with the `secrets:read` scope. Handle it like the one-time value it is: read it, use it, don't write it to your own logs in plaintext. Secret items are encrypted with a libsodium sealed box on arrival at BriefGate's server, never on the client — see [the secrets vault reference](./secrets.md) for what that does and doesn't protect against. ## Handing results to a coding agent If the next step is an agent rather than a script, you don't need to shuttle the payload into a prompt by hand. An MCP-capable agent with BriefGate connected can call `get_intake_results` itself once it knows the `intake_id` — your receiver's job becomes "notice `intake.completed` and wake the agent up," not "extract and reformat the data." See [Get client assets into your coding agent](./how-to-get-client-assets-into-your-coding-agent.md). One thing to watch: an endpoint receives every event on the account, across every intake — filter on `intake_id` inside your handler if you run several projects through one account. ## Related - [Webhooks reference](./webhooks.md) — full event list, payload shapes, delivery log, retries, Slack/Discord format - [REST API reference](./rest-api.md) — every endpoint, including `GET /v1/intakes/:id/results` - [Secrets vault](./secrets.md) — how `secret` items are encrypted and revealed - [Get client assets into your coding agent](./how-to-get-client-assets-into-your-coding-agent.md) — the MCP-first path, if an agent is the thing waking up --- ## Route client files to Drive, Dropbox, Slack URL: https://briefgate.dev/docs/client-files-to-drive-dropbox-slack # Where the Client's Files Should Land The best outcome for a finished intake isn't a link you have to remember to open — it's a project folder that already has everything in it, and a Slack message that already told you so. BriefGate doesn't do that routing itself: there is no native Google Drive or Dropbox export, and no button that files things into a folder on its own. What it gives you instead is everything a Zapier zap, an n8n workflow, or your own script needs to do that routing for you — typed results with signed file URLs, a ZIP of the whole intake, and webhooks that fire the moment something arrives. This is the destination-side half of client intake; the collection side — what you ask for and how it gets chased — is covered in [Collecting files from clients](./how-to-collect-documents-from-clients.md). ## Two ways to get the files out Every file a client uploads is reachable two ways, and which one you reach for depends on whether you want individual files or the whole bundle. **Typed results, per item.** [`GET /v1/intakes/:id/results`](./rest-api.md#get-v1intakesidresults) (the `get_intake_results` MCP tool, and the action Zapier and n8n both call under the hood) returns one entry per item, keyed by its `key`. A `file` item comes back as `{ url, filename, mime, size, checksum_sha256 }`; a `file_list` item comes back as an array of the same shape, one per uploaded file; an `image` item adds `width`/`height`. The `url` in every case is a **signed URL valid for 24 hours** — download it or hand it to the next step promptly, and if 24 hours pass before you get to it, call `get_intake_results` again for a fresh one. The same 24-hour window applies to the single-file endpoint, [`GET /v1/intakes/:id/items/:key/files/:fileId`](./rest-api.md#get-v1intakesiditemskeyfilesfileid), which redirects straight to the signed URL instead of returning it as JSON. See [item types](./item-types.md) for the exact shape each item type returns. **Everything as one ZIP.** [`GET /v1/intakes/:id/download`](./zip.md) bundles every uploaded file into one archive, each in its own item's subfolder, alongside a `podklady.pdf`/`podklady.md` summary of the whole intake — labels, statuses, decisions, waivers. It's the right pick when a human is going to open the folder by hand rather than a workflow tool processing each file individually, or when you want the summary document sitting next to the files. It tops out at 2 GB (`413 download_too_large`); above that, fall back to typed results and fetch each file's signed URL on its own. Check [`GET /v1/intakes/:id/download/preflight`](./zip.md#api) first if you want the byte count before committing to the download. Either way, this is read access to what BriefGate already has — routing it into Drive, Dropbox, a bucket, or a repo is a step your automation tool takes after the fetch, not something BriefGate does for you. ## A Zapier route into a project folder in Drive [BriefGate's Zapier integration](./zapier.md) has exactly the pieces this needs: the **Intake Completed** trigger fires once every required item is in, and its payload already carries `project_name` — no extra lookup needed to name the destination folder. From there: 1. **BriefGate: Intake Completed** — trigger. 2. **BriefGate: Get Intake Results** — the search action that reads back typed values and signed URLs for every approved item. 3. **Google Drive: Create Folder** (or find-or-create, so re-running the zap for the same intake doesn't duplicate it) — named from `project_name`, e.g. `Bella Napoli — Website`. 4. **Google Drive: Upload File** — one step per file item, pointing at that item's `url` from step 2, dropped into the folder from step 3. For a `file_list` item with several files, loop over the array (a Sub-Zap, or a Formatter step that splits it into line items) instead of one Upload File step per item — five file fields is fine as five steps, but a photo gallery of unknown size isn't. This is the same pattern the integration's own [Completed intake → files in Drive](./zapier.md#example-zaps) example uses. ## An n8n route into storage [BriefGate's n8n node](./n8n.md) covers the identical shape for a self-hosted workflow: the **BriefGate Trigger** node listens for `intake.completed` (registering a webhook on your account while the workflow is active), and its payload carries `project_name` the same way Zapier's does. From there, [n8n's own worked example](./n8n.md#example-workflows) is: **BriefGate Trigger** (`intake.completed`) → **BriefGate: Get Results** → an **HTTP Request** node per file, downloading each signed URL → a storage node (**Google Drive**, or n8n's built-in **Dropbox** node for a Dropbox destination) uploading it into a folder named after the client or project. The HTTP Request step matters: a signed URL is a direct download link, not something the Drive or Dropbox node can point at as a remote source — fetch the bytes yourself and pass the binary data downstream. Five ready-to-import templates built on this and two other patterns are linked from [n8n's resources](./n8n.md#resources). ## A Slack notification that says what's arrived BriefGate can post to Slack directly, without a workflow tool in between: register a webhook with `"format": "slack"` and BriefGate posts a plain sentence to the channel for each event you subscribe to — see [Webhooks: Slack and Discord](./webhooks.md#slack-and-discord). Subscribed to `item.submitted`, that's one line per file as it lands (`The client submitted "logo" for Bella Napoli — Website.`); subscribed to `intake.completed`, one line when the whole thing is done. That's the fast path for "let the team know," and it needs no automation platform at all. Saying what's still missing takes a step further than the built-in format goes — compose it yourself in Zapier or n8n: trigger on `item.submitted` or on a schedule, call `get_intake_status` (or read the `missing` array `get_intake_results` returns) for the intake's current progress, and post "3 of 5 items in for Bella Napoli — Website. Still waiting on: hero copy, opening hours." BriefGate's webhook supplies the raw event; your workflow tool supplies the summary — the same combination behind the [Zapier](./zapier.md#example-zaps) and [n8n](./n8n.md#example-workflows) "heads-up in Slack" examples. ## Naming and foldering that survives more than three projects A folder-per-client scheme that works for the first three projects usually breaks by the tenth, once two clients share a name or a project gets renamed halfway through. A few things keep it working: - **Name the destination folder from `project_name`, not the client's name alone.** It's on every relevant webhook payload and on the results response, so no extra lookup is needed, and it disambiguates a client with more than one project running at once. - **Include the intake id somewhere stable** — the folder's description, a hidden marker file, or a spreadsheet row keyed by `intake_id` — so renaming `project_name` later doesn't orphan the automation's find-or-create step, which would otherwise create a second folder instead of reusing the first. - **Match BriefGate's own [folders](./rest-api.md#folders)** (`folder_id`) to your Drive/Dropbox structure if you use both. BriefGate's folders only organize the dashboard's intake list and don't drive anything on the Drive/Dropbox side, but keeping the two in sync gives "where did this intake's files go" one consistent answer instead of two. - **Borrow the ZIP's own filename convention** — `podklady-<project>-<intake id>.zip` — as a naming reference that already bakes in both fields (see [ZIP download](./zip.md#whats-in-the-zip)). ## Secrets are deliberately excluded from automation None of the routes above should ever carry a `secret` item — and by default, they can't. Zapier's **Get Intake Results** search action always sends `exclude_secrets=true`: secret items are left out of the response entirely, without being revealed, because Zapier keeps every step's output in your Zap history and a secret can only be revealed **once**, ever, across the whole account (see [Secrets vault](./secrets.md)). The same reasoning holds for any n8n workflow or script you write yourself — call `get_intake_results` with `exclude_secrets: true`, or simply don't grant the API key the `secrets:read` scope, and a `wp_admin` password can't end up piped into a Drive file, a Dropbox folder, or a Slack channel by accident. Read a credential in the dashboard instead, where the owner's **Reveal** click is the one-time reveal itself and the value never touches a webhook payload, a Zap history, or an n8n execution log. If it needs to reach a teammate, that's a deliberate second step through your own secrets manager — not something that should ever be automatic. ## Related - [Zapier client intake automation](./zapier.md) - [n8n client intake automation](./n8n.md) - [Client intake webhooks guide](./client-intake-webhooks-guide.md) - [Client onboarding automation](./client-onboarding-automation.md) - [ZIP download](./zip.md) - [REST API reference](./rest-api.md) - [Secrets vault](./secrets.md) --- ## A client portal with no account URL: https://briefgate.dev/docs/client-portal-without-account # A client portal with no account Your client gets an email, taps a link on their phone, and is looking at a page asking for their logo files. No password to invent, no "confirm your address" loop first, no app to install. They upload three photos, paste a URL, close the browser. If they come back the next day from the same phone to finish the last item, the page still remembers who they are and what they already sent. That experience — open a link, do the thing, leave — is the design goal. Getting there without an account means the portal still has to answer every question an account would normally answer: who is this, are they allowed to see this particular intake, and what stops someone else from reading it. This page is about how BriefGate answers those without asking the client to sign up, and what that choice costs. ## What the client experiences 1. You call `define_intake`. BriefGate creates a portal at a unique slug (`https://p.briefgate.dev/8f3kqmr2`) and emails the client an invitation. 2. The email's link is that portal URL with a token appended (`?t=...`) — that token is what actually gets them in. The bare `portal_url` shown in the API response and the dashboard does not carry it; on its own it is not a working link. 3. The client clicks it. The browser exchanges the token for a session cookie and lands them in the portal — see [Client Portal](./portal.md#magic-link-flow). 4. They fill in items and upload files, closing the tab at any point; everything autosaves. Returning through the same link later picks up exactly where they left off. 5. If they lose the email, a chase reminder — automatic, or one you trigger with `send_chase` — resends the link (see [Chase Engine](./chase.md)). No password, no email-confirmation step, no "forgot password" flow to maintain on either side. The identity check already happened by the time BriefGate sent the invitation: you supplied the client's address when you called `define_intake`. ## What that means technically An account substitutes a password (something the client knows) for identity. Here, the substitute is possession of a link — a bearer credential, the same category as a session cookie or an API key, mailed instead of typed. Three choices make that safe enough to build on: **The token is never stored as plaintext.** The magic token is derived server-side from the intake and a server secret (an HMAC, not a random value you'd have to keep a copy of); the database only ever sees its hash, the same treatment API keys and portal session tokens get. A stolen database dump hands out hashes, not working links. **The link keeps working for its whole validity window, not just once.** It's tempting to assume a link should die the moment it's clicked. This one doesn't: it stays valid until it hits its TTL — an account setting, `portal_link_ttl_days`, 30 days by default — and clicking it again, the next morning, from a different device, keeps working. That matches the job: a client fills in half an intake, gets distracted, comes back days later on their laptop instead of their phone. A single-use link would strand them with nothing to do but email you for a new one; a link that survives repeated use means "click it again" just works, on any device, until it genuinely expires. **Every send extends the same link's life, instead of replacing it.** An intake has one stable link for its whole life — the invitation, every scheduled reminder, and a manual `send_chase` all carry the identical URL. What changes on each send is the clock: the TTL counts down from the *most recent* email sent for that intake, so an active chase sequence keeps pushing the expiry out rather than the link quietly going stale mid-cadence. An old email sitting in an inbox for months still points at a working link, right up until `portal_link_ttl_days` passes since the last thing BriefGate sent about that intake. **The resulting session is scoped tightly.** Redeeming a link gets the client an httpOnly cookie, restricted to `/portal` paths so it's never sent to the API, valid for 14 days. It authorizes exactly one intake — not the client's other projects, not anyone else's portal. There's no broader "client account" behind it that a leaked cookie would expose. ## The alternatives, and why they lost **An account with a password.** The default reflex for "give someone access to something," and wrong for this job. The person filling in a BriefGate intake isn't your user — it's your client's staff, a subcontractor, someone's assistant, filling in one form for one project they may never touch again. Asking them to invent a password for a site they'll visit once creates exactly the friction this product exists to remove: a client who bounces off a signup form doesn't send the logo files either. An account is also an ongoing liability — a password to secure, reset, and eventually let the client walk away from — for a relationship with a natural end date. **A link that dies on first click.** Often the right call for something like a password-reset email, where the goal is a tight, one-shot proof of inbox ownership. Wrong shape here, because the job isn't proving identity once — it's letting someone return across days and devices without an account to remember who they are between visits. A single-use link routes every return trip through you: dead link, client emails you, you trigger another `send_chase`. That's a support burden invented by the security model, not by anything the client did. **Email attachments and reply-by-email.** Some competitors let a client reply with a ZIP attached, skipping the portal entirely. It looks like less friction, but it throws away what the portal buys you: no antivirus scan, no content-type sniffing, no HEIC conversion, no per-item validation, no encryption for sensitive values. Every protection in [Security](./security.md) — the malware scan, the sealed-box encryption on `secret` items, the signed download URLs — exists because the file or value passed through the portal's pipeline. An emailed attachment bypasses all of it by construction, which is why BriefGate never attaches client-brief files to outgoing mail either (see [Client brief](./portal.md#client-brief)). ## The honest cost None of this is free, and it's worth being direct about the trade. **Anyone holding the link holds the access.** There's no second factor behind a portal link the way there is behind a password plus TOTP. If a client forwards the invitation to a subcontractor, that person can now submit — and see — everything already on the intake. That's often exactly what you want (see [More than one person at the client](./chase.md#more-than-one-person-at-the-client) for the supported way to add a second recipient deliberately), but it also means a link pasted into the wrong Slack channel or a shared inbox is a real exposure. BriefGate has no way to tell whether the person who redeemed a link is the client you emailed or someone they forwarded it to. **A forwarded email forwards the access, for a while.** Because the link keeps working until its TTL rather than dying after one use, an old invitation sitting in a shared mailbox stays a live credential for up to `portal_link_ttl_days` — 30 days by default, and every reminder that goes out resets that clock, so an intake under active chase keeps the old forward alive too. Set `retention.mode: "on_delivery"` (see [Security → Retention and deletion](./security.md#retention-and-deletion)) where that window is uncomfortable, so the underlying data is gone well before the link's TTL would matter. **There's no client-side recovery flow.** If a client loses the email, the fix is on your side: trigger a resend. Simpler than a password reset, but the client has no self-service way back in — they have to reach you, or wait for the next scheduled reminder. Weighed against an account nobody would want to create for a form they'll fill in once, this is the trade BriefGate makes on purpose: treat the link as the credential, protect it the way any bearer token should be protected — hashed at rest, scoped narrowly, its lifetime capped and renewed only by BriefGate's own sends — and accept that whoever holds it has the access. The same trade every magic-link product makes, made explicit instead of glossed over. --- ## How client credentials are stored URL: https://briefgate.dev/docs/client-credentials-encryption-explained # How client credentials are stored At some point in almost every project, someone needs a password. A WordPress admin login, a domain registrar's API key, the FTP credentials for a hosting account nobody has touched in three years. The usual path for that value is an email, a chat message, or a shared document — all of which keep a plaintext copy of a working credential sitting around indefinitely, readable by anyone with access to that inbox, channel, or drive. BriefGate's `secret` item type exists so that path doesn't have to be the default. This page explains exactly what happens to a credential a client types into the portal, what protection that buys you, and — just as importantly — what it does not. We would rather you know precisely where the line is than assume a stronger guarantee than the one that actually exists. ## What happens when a client fills in a secret field On the portal, a `secret` item renders as a masked password field with a lock icon and a note: "Encrypted — shown once to your provider only." The client can show what they typed to check it, but once it has been submitted there is no way to recover the value through the portal. When the client submits it, the value travels to the server over HTTPS. On arrival — before anything is written to the database — it is encrypted with a **libsodium sealed box** (`crypto_box_seal`) using BriefGate's public key. Only that ciphertext is stored. The plaintext exists in server memory for as long as it takes to seal it, and later, briefly, during a reveal — it is never written to disk and never appears in a log. The private half of that keypair lives only in the server's environment configuration. It is never stored in the database. A stolen database dump — every row, every table — yields ciphertext and nothing else. ## The property we do not have Here is the honest part: BriefGate is **not zero-knowledge**, and this is **not end-to-end encryption**. Both of those terms mean the same thing in practice — the service operator holds no key capable of decrypting the data. That is not true here. The private key that opens a sealed secret lives on BriefGate's server, and the server that receives your client's password is the same server that can, when asked correctly, decrypt it. A product that collects a password behind a sealed box and also holds the key to open it is not zero-knowledge, no matter how the box is described. It's worth being specific about why, rather than treating this as a shortcut. Real end-to-end encryption requires a key that only the intended recipient holds, generated and kept on a device that never hands it to the server in between. BriefGate's portal is deliberately built so a client needs no account, no app, and no setup — they open a link on whatever phone or laptop is in hand and fill in a field. There is nowhere in that flow for a client-held key to live: no persistent identity to attach it to, no install step to generate it in, no session that outlives the one form submission. And even if a key could be conjured up on the client's device for that one visit, it would then need to reach whoever reads the credential later — you, or your agent, querying the intake through the API days afterward — without the server ever seeing it. That's a substantially harder problem than this product takes on, so rather than fake the property, we don't claim it. What sealing on arrival does buy you is real, just narrower: protection against a compromised database or a leaked database backup, as long as the server's private key isn't stolen along with it. It does not protect a secret from a server that has been fully compromised by an attacker capable of reading process memory or calling BriefGate's own decrypt path. Full detail on that boundary, along with the rest of the platform's security posture, is on the [Security](./security.md) page. ## Revealed exactly once A secret can be decrypted exactly one time, through any of three paths, and all three draw on the same one-time reveal: - Your agent calls `get_intake_results` (MCP, or `GET /v1/intakes/:id/results`) with an API key carrying the `secrets:read` or `admin` scope. This reveals every secret item on the intake in that call. - You click **Reveal** on a single credential in the dashboard, which calls `POST /v1/intakes/:id/items/:key/reveal`. This reveals one item, and requires an owner's dashboard session — an API key cannot call it. - You (or a `secrets:read`/`admin` key) download the intake's ZIP with `include_secrets=true`, which reveals every still-unrevealed secret and writes the values into `podklady.pdf`. Whichever of these happens first gets the plaintext. Every other path is told the credential was already revealed. There is a five-minute grace window that lets the *same caller* — the same API key, or the same owner in the dashboard — repeat its own call and get the value again, so a dropped connection between our response and your process doesn't destroy the credential. That window is tracked per caller identity: an agent revealing through the API and the owner clicking Reveal moments later never share it. Every reveal, from any path, is written to the audit log with the actor, IP address, and timestamp. ## If you spend the reveal by accident There is no way back through the same item. A second call gets `secret_unavailable: true` (API) or `already_revealed: true` (dashboard), along with the timestamp of the original reveal. The only recourse is [`request_revision`](./mcp.md#request_revision), asking the client to enter the credential again — the same recourse that applies if a secret simply expires (30 days after submission, if nobody reveals it in time) before anyone collects it. ## A credential is meant to be read, not routed An integration that replays every step of a run — Zapier's task history, a Make scenario log — is a bad place for the one and only readable copy of a credential to land, since you can't clear an entry from someone else's execution log after the fact. `get_intake_results` accepts `exclude_secrets=true` for exactly this case: every other item comes back normally, and secret items are reported as still available rather than revealed, untouched, waiting for a dashboard click or a deliberate follow-up call. Downloading an intake as a ZIP (`GET /v1/intakes/:id/download`) follows the same default — leave `include_secrets` off and the file contains everything else, with credentials simply absent; set it to `true` and the download itself becomes the reveal, embedding the values in `podklady.pdf`. That's a deliberate, explicit choice each time, not one you can trip over. The pattern we'd recommend follows from this: let an agent collect files, text, and structured answers on autopilot, and let a person open the dashboard and click Reveal when a credential like a hosting login actually needs to be typed into a server or a control panel — once, by someone, rather than carried from step to step through a workflow tool. ## What this buys you A client's WordPress password, API key, or hosting login doesn't have to sit in an email thread, a Slack channel, or a support ticket, outliving its usefulness by years. It arrives encrypted, stays encrypted at rest, can be read exactly once by whoever needs it, and every one of those reads is logged. That's a real improvement over how credentials usually move between a client and whoever is building their site — even though it stops short of a guarantee that BriefGate itself cannot see the value in flight. See [Secrets Vault](./secrets.md) for the full API reference, and [Security](./security.md) for how this fits into the rest of the platform. --- ## When a crawler finds a shared link URL: https://briefgate.dev/docs/shared-links-and-crawlers # When a crawler finds a shared link On 17 September 2026 a Bing Webmaster Tools site scan of briefgate.dev flagged two pages for a missing H1. Both were demo client portals on `p.briefgate.dev`, each with a magic token in the query string (`p.briefgate.dev/<slug>?t=…`). Bing reached them by following the redirect from the public demo link on the marketing site — nobody had linked a real client's portal from anywhere crawlable, but the demo one, by design, is. Nothing leaked: the intakes behind those URLs are demo data, confirmed against the database. Nobody was locked out either, because the token isn't single-use — reasons below. But a portal URL has no business sitting in a search engine's crawl log at all, and the fix is worth writing up, because every tool that emails people an access link has the same problem. ## Four kinds of automated opener A link mailed to a human doesn't only get opened by that human: - **Search crawlers** (Googlebot, Bingbot, site-scan tools). Increasingly render JavaScript, but usually not on the first pass — a scan does a fast synchronous `GET` of raw HTML first, and only some pages get queued for a later, rendered pass. The first fetch alone logs the URL, token included. - **Chat and link-preview fetchers** — Slack, iMessage, WhatsApp, Discord, Teams. A plain `GET` builds a preview card the instant a link is pasted, whether anyone clicks it or not. No JavaScript runs. - **Mail security scanners** — Microsoft Defender Safe Links, Proofpoint, Mimecast. Rewrite links in incoming mail and fetch the original at delivery time, sometimes again at click time — the classic killer of single-use tokens, since the scanner's `GET` can spend the link before the recipient opens the email. - **Corporate web proxies and gateways** — outbound filters that fetch a URL as part of scanning traffic, same shape as a mail scanner, different trigger. Only search crawlers meaningfully execute JavaScript, and not on every request. The other three are `GET`-only — no script runs. Any protection that depends on JavaScript running does nothing for three out of four. ## "It is unlisted" is not a control A link nobody linked to feels private. It isn't: a preview bot fetches it the moment it's pasted into a channel, a mail scanner fetches every link in every message regardless of who can see it, and a page that loads its own images or analytics sends the current URL as `Referer` on those requests. Anywhere a fetch gets logged — a crawler's history, a proxy's access log, a webmaster-tools dashboard — the fact that a link was never linked from an indexed page doesn't stop it being crawled once, and once is enough to be recorded forever. "Unlisted" describes how a human finds a link; none of the four openers above find links that way. ## What actually happened, mechanically A portal URL is `<host>/<slug>?t=<token>`. The page is client-rendered (Nuxt): the initial HTML is close to an empty shell, and the page's own JavaScript reads the `t` query parameter on mount, exchanges it for a session, then calls `history.replaceState()` to strip the token back out of the address bar. Bing's fast first-pass fetch never runs that script — it reads the raw, near-empty HTML, which is why the scan reported a missing H1 rather than a rendered page. The exchange itself also isn't something a `GET` can trigger. `GET /portal/:slug` requires an existing session cookie; it isn't how a token gets redeemed. Redemption happens at `POST /portal/:slug/redeem`, called by the page's own script, never by a browser just following a link. A `GET`-only fetcher — the common case for three of the four opener types — cannot spend the token, mint a session, or trigger the `client.viewed` webhook, no matter how often it requests the URL. Even where a token *is* redeemed, it isn't consumed: `redeemMagicToken` checks it against a stored hash, constant-time, and accepts it until it expires on its own schedule (`portal_link_ttl_days`, 30 days by default, counted from the intake's most recent send), not on first use. That's what kept this incident from locking anyone out — a deliberate trade, not an accident that happened to help. ## Why noindex alone wasn't the answer These pages already carried a `noindex` meta tag, and it wasn't enough, because a crawler has to fetch the page to read it — the fetch, query string included, has already happened and been logged by the time the crawler learns it shouldn't index what it just read. The fix that addresses the fetch itself is `robots.txt` on the portal host: ``` User-agent: * Allow: /app/login Disallow: / ``` `app.briefgate.dev` and `p.briefgate.dev` share one build, so one file covers both. The dashboard sits behind login, so only its login page is worth indexing; everything else, portals above all, is disallowed. `Allow: /app/login` wins over `Disallow: /` by longest-match, keeping login crawlable while every token-bearing path stays untouched. A compliant crawler now never issues the `GET` that would have logged the URL — stronger than asking it not to index what it already fetched. `robots.txt` only binds crawlers that honor it, which is why it's one layer, not the whole answer. ## The concrete measures - **Disallow the token-bearing host in `robots.txt`** — stops the fetch, not just the index entry. - **`noindex` as defense in depth**, useful against crawlers that ignore `robots.txt`, useless against the fetch itself. - **Hash tokens at rest.** A portal token is a 256-bit HMAC of the intake under a server-side secret, so it can't be guessed without that secret, and only its SHA-256 digest is stored, so a database leak doesn't hand out working links. - **Compare in constant time**, and run a dummy comparison when the slug doesn't exist, so timing gives an attacker as little as possible to guess a token or enumerate slugs with. - **Extend the link's life on every reminder, cap it between sends.** An intake has one stable link, so there is nothing to rotate — but each reminder pushes `portal_link_ttl_days` out from that send, and if the sends stop, so does the extension. An old copy sitting in an inbox or a crawler's log stays live only as long as the intake is still being chased, and goes dead once the last send falls out of the window. A session already in progress is a separate cookie and is unaffected either way. - **Keep the session short-lived and scoped** — a separate `httpOnly` cookie limited to portal paths, good for 14 days, tied to one intake. - **Exchange over `POST`, never `GET`** — nothing that just fetches the URL can spend anything. - **Rate-limit the exchange endpoint**, per IP and per slug. - **Strip the token from the address bar right after use**, so nothing the page loads afterward carries it in a `Referer` header or browser history. ## Why the token isn't single-use, on purpose Consuming a token on first read looks like the obvious fix, but it creates a worse failure: a mail scanner's `GET` — the opener most likely to fetch before the human does — would burn the link before the recipient opens their inbox, and they'd see "this link has expired" through no fault of their own. BriefGate's token stays valid until it expires on its own schedule, an expiry the next reminder simply pushes back rather than replacing the token itself. Security comes from the token being unguessable, hashed at rest, and rate-limited on the redeem path, not from single use — the same property that makes the system resilient to a scanner's premature fetch is what made a crawler's fetch harmless here. ## If you mail people access links 1. Put the token-bearing host under `robots.txt`, not just `noindex`. 2. Assume every link gets fetched by a preview bot and a mail scanner before the recipient. 3. Make the state-changing exchange a script-triggered `POST`, never a bare `GET`. 4. Hash tokens at rest and compare them in constant time. 5. Cap the link's lifetime and extend it only from your own sends, rather than trusting one link to stay valid indefinitely. 6. Choose deliberately between single-use and scanner-safe — replay and premature expiry trade off against each other. 7. Strip the token from the address bar as soon as it's used. See [Security](./security.md) for BriefGate's handling of client data, [Chase](./chase.md) for reminders and the portal link's lifetime end to end, and [Portal](./portal.md) for what a client sees on the other end of the link. --- ## Reminders that arrive at a sensible hour URL: https://briefgate.dev/docs/reminder-cadence-design # Reminders that arrive at a sensible hour The point of a reminder is that materials show up without you having to remember to ask again. Get the cadence wrong and you get the opposite: a client who mutes your sender, or one who genuinely forgot and never hears from you until the deadline is gone. BriefGate's chase engine is built around getting that balance right by default, and adjustable when your project needs something else. ## Why "every 3 days" is the wrong default A fixed interval treats a client on day one the same as a client on day thirty, and a gentle branding project the same as an aggressive one with a hard deadline. Neither is true in practice. Early on, a short gap is reasonable — the client is still orienting, and a nudge two days in is barely a nudge. Weeks in, the same two-day gap reads as nagging, because whatever stopped them the first time hasn't changed just because you emailed again sooner. BriefGate's built-in schedules **decelerate**: reminders start close together, while the ask is still fresh, and space out the longer it goes unanswered — the way a person would actually follow up by hand, without you hand-tuning an interval per client. Pick a schedule once, when you call `define_intake`, and the engine runs it: timing, deduplication, and quiet hours handled from that point on. ## The five schedules | Schedule | Reminders | Cadence | |---|---|---| | gentle | T+3d, T+8d, then every 14 days | For sensitive client relationships | | default | T+2d, T+5d, T+9d, then weekly | Recommended for most projects | | aggressive | T+1d, T+3d, T+5d, then every other day | For hard deadlines | | custom | Every `chase_interval` `chase_interval_unit` (default every 3 days) | When no preset fits | | off | None | Manual only | Set it once, on the intake: ```json { "project_name": "Bella Cucina Website", "client": {"email": "owner@bellacucina.cz"}, "items": [...], "chase_schedule": "default" } ``` You are not locked into the choice — `PATCH /v1/intakes/:id` can change the schedule after the invite has already gone out, and BriefGate re-plans the remaining reminders from the new settings rather than making you delete the intake and start over (which would hand the client a second link). One thing worth knowing before you reach for `custom`: **the Free plan only has access to `default` and `off`.** Solo, Studio, and Agency get all five. ## Quiet hours, in the client's own time zone A reminder that lands at 2am doesn't get read any faster — it just sits at the top of an inbox looking like it was sent by a machine, because it was. BriefGate holds reminders outside **8:00–19:00 in the client's own local time**, set via `client.timezone` on the intake (defaults to UTC if you don't set it). If a scheduled send falls in that window, it isn't skipped — it's held until the next allowed time, so nobody misses a reminder, it just arrives at a decent hour. That protection is on by default and can be turned off with `respect_quiet_hours: false`, which is worth doing for a deliberately rapid custom cadence — a 30-minute interval that respects quiet hours would otherwise sit idle for the entire night rather than checking in. ## Weekends Only the **gentle** schedule skips weekends outright. Every other schedule — `default`, `aggressive`, `custom` cadences included — sends on Saturday and Sunday too. If your project genuinely runs on a five-day week and a Saturday email would feel off, `gentle` is the schedule built for that; the others assume a reminder landing on a weekend is still useful to the client, even if you personally aren't working that day. ## Stopping: completion, the cap, and a webhook instead of forever The moment a client submits everything required, chasing stops automatically — there's no cleanup step on your side. If they don't, BriefGate doesn't chase indefinitely by default either. Every intake has a reminder cap, `max_reminders`, defaulting to **3** — raise it, or set it to `"unlimited"`, and that stop no longer applies. Once the configured number of reminders have been sent, the intake **stalls**: BriefGate cancels any reminders still scheduled and fires the `intake.stalled` webhook instead of continuing to email the client on its own. The webhook payload carries `missing_items` — the required items still outstanding, by key — so you know exactly what to raise when you follow up yourself. That hard stop is deliberate, not a missing feature. An intake nobody has answered after three reminders won't be rescued by a fourth or a tenth on autopilot — it needs a human decision (different channel, different contact, or accept it's stalled), and every automated email until then spends your sending domain's reputation for no return. If a fast cadence genuinely needs more attempts before it's worth escalating — a 30-minute interval burns through 3 reminders in ninety minutes — raise `max_reminders` when you set the schedule. A stalled intake doesn't quietly resume just because you change the cadence: it stays stalled until `max_reminders` is raised past the number already sent, or set to `"unlimited"` — the same action that gets it moving again. Raising the cap doesn't dump every reminder the schedule missed while stalled onto the client at once; it picks the cadence back up at its next regular slot, the same as if it had never stopped. A manual `send_chase` counts toward the cap the same as a scheduled reminder — it's one of the attempts, not a freebie outside the count. ## What a bounce means — and why it goes to a person Not every bounce means the address is dead, so BriefGate doesn't treat them all the same. A permanent bounce or a spam complaint retires the address immediately. A bounce that arrives *after* a confirmed delivery of the same message is left alone — usually a forwarding rule or quarantine gateway behind the client's real inbox, not a dead address, and treating it as dead would silently cancel every future reminder. A temporary bounce (full mailbox, greylisting) with no delivery is tolerated twice; the third undelivered soft bounce that address has accumulated on the intake retires it — the count doesn't reset just because a delivery happened at some other point in the history. BriefGate fires `chase.bounced` on every bounce or complaint, not only the ones that end up retiring the address — the payload carries `still_chasing` and `delivered_before` so you can tell a retirement apart from a soft bounce that left the schedule untouched. When an address *is* retired, BriefGate marks it bounced on the intake and stops sending to it — any other recipient on the same intake keeps being chased normally. That's why a retirement deserves a person, not another automated retry: the failures that survive BriefGate's own filtering (dead mailbox, spam complaint) are exactly the ones an email can't fix. A `chase.bounced` event with the address retired is the signal to reach the client another way, not to wait for the schedule to try again. ## One link, kept alive by the cadence Every reminder — scheduled or manual — carries the same magic link the client got in the very first invitation; BriefGate never issues a second one for the same intake. What each send does is extend how long that link stays valid: the TTL (`portal_link_ttl_days`, an account setting) counts down from the most recent email, so an active cadence keeps pushing the expiry out on its own. That's a practical upside for cadence design: a client who lost or deleted an earlier email doesn't need a recovery flow, since the next scheduled reminder hands them the exact same link, still working, and resets its clock in the process. If they're mid-fill with an active portal session, that session is a separate cookie and is unaffected either way. ## Picking a schedule for the project - **Ongoing or repeat-client relationships, where tone matters more than speed** — `gentle`: fewer, spaced-out touches, no weekend mail. - **Most projects, no unusual deadline or relationship pressure** — `default`, the one available on every plan including Free. - **A hard deadline, a client who needs pushing** — `aggressive`: daily-ish at first, tapering to every other day. - **Anything none of those fit** — `custom`, with your own interval. Pair a short interval with a raised `max_reminders`; the default cap of 3 is sized for `default`, not for minutes or hours. - **A one-off send, no automation** — `off`, and nudge by hand with `send_chase`. Whichever you pick, quiet hours and the reminder cap default to on and to 3, keeping the client from seeing a flood — both are safeguards you can explicitly relax, so a custom schedule that turns either off is worth configuring with care. The engine is built to stop asking on its own, not just to keep asking politely. --- ## Client API Keys to Your Coding Agent URL: https://briefgate.dev/docs/client-api-keys-without-chat-history # Getting Client API Keys to Your Coding Agent Without Leaving Them in Chat Have the client paste the key into a BriefGate portal as a `secret` item, then pull it with `get_intake_results` — the plaintext is handed to your agent exactly once, instead of sitting in a chat thread with the client, a Slack channel, or an email you'd have to remember to delete. ## The problem with the obvious channels A coding agent building a client's site eventually needs something only the client has: a Stripe secret key, a Mapbox token, a Google Maps API key, the credentials for a third-party service the agent is wiring up. The fastest way to get it is to ask — in the chat, over Slack, in an email reply. All three leave the same trace: a plaintext credential sitting permanently in a transcript, a channel history, or an inbox, searchable by anyone who later gets access to that chat, that Slack workspace, or that mailbox. None of them were built to hold a secret; they just happen to be wherever the conversation was already happening. It's also not a question an agent can route around on its own. MCP's `elicitation/create` request can ask whoever is driving the agent a quick question mid-session, but the spec draws a hard line around exactly this case: *"Servers MUST NOT use elicitation to request sensitive information."* And even setting that rule aside, elicitation only reaches the person on the other end of the current connection — not a client who has never opened an MCP client and isn't part of the session at all. [Async human input for coding agents](./async-human-input-for-coding-agents.md) goes through why that gap exists in the protocol itself; this page is about the practical workaround. ## The workflow Declare the key as a `secret` item when you create the intake: ```json { "project_name": "Bella Napoli — Website", "client": {"email": "owner@bellanapoli.com", "name": "Maria"}, "items": [ { "key": "maps_api_key", "type": "secret", "label": "Google Maps API key", "help": "From your Google Cloud Console — used to show your location on the new site. Encrypted, and revealed to your developer only once.", "required": true } ] } ``` The client opens the portal link BriefGate emails them and sees a masked password field with a lock icon, not a text box that looks interchangeable with every other field on the form. They can show what they typed to check it, and once they submit, the value is cleared from their side of the screen and can't be recovered through the portal. What happens to it next is encryption, not just UI: the value travels over HTTPS and is sealed with a libsodium sealed box on arrival at the server, before anything touches the database. [How client credentials are stored](./client-credentials-encryption-explained.md) covers that mechanism end to end, including the one thing worth being precise about — it's server-side encryption, not end-to-end or zero-knowledge. Once the client has submitted it, call `get_intake_results`: ```json { "intake_id": "in_8f3kQmR2" } ``` ```json { "results": { "maps_api_key": { "value": "AIzaSyD-9tSrke72PouQMnMX-a7eZSW0jkFMBWQ", "one_time": true, "first_reveal": true, "expires_at": "2026-11-04T10:22:00Z" } }, "meta": { "maps_api_key": { "type": "secret", "status": "approved", "submitted_at": "2026-10-05T09:12:00Z" } } } ``` That `value` field is only there because this is the first successful read. Call `get_intake_results` again later, or with a different key, and `value` is gone; a companion `meta` entry reports `secret_unavailable: true` instead. BriefGate does give a short safety margin for the realistic failure mode, a response that never arrived: the same API key calling again within 5 minutes of the first reveal gets the same value back, so a dropped connection doesn't cost you the key. Past that window, the only way to see it is a fresh one — asking the client to submit it again. Every reveal — whether it's your agent's API call or the account owner clicking Reveal in the dashboard — is recorded in the account's audit log (who, their IP, and when), which the owner can read from the dashboard. And if the client doesn't have the credential yet, mark the item `required: false` when you declare it; the intake still completes without it instead of blocking on a value that doesn't exist. ## Where it goes after your agent has it BriefGate's one-time reveal solves the "get it out of chat" problem; what you do with the value afterward is on you, the same as any other credential an agent handles. The honest, boring answer is the one you'd give for any secret: write it to a local `.env` file that's in `.gitignore` and never gets committed, or into whatever secret manager the project already uses, and reference it from code as `process.env.MAPS_API_KEY` rather than inlining the literal string anywhere a diff or a log might catch it. Don't echo it back into the chat to confirm you received it — the whole point of the one-time reveal is that the value existed in exactly one place after the client typed it, and printing it to a terminal the client (or a screen-sharing viewer) might see undoes that. If the agent is running unattended — a CI job, a scheduled task — using an API key instead of a logged-in session, note that reading a `secret` item needs the `secrets:read` scope (or `admin`) on that key specifically; `intakes:read` alone isn't enough, and an attempt without it comes back with the item simply omitted and a `meta` entry explaining why. That's worth setting up deliberately rather than reaching for `admin` out of convenience, since `secrets:read` is exactly the privilege the task needs and nothing more. ## What this doesn't cover Secret items are only available on BriefGate's Solo, Studio, and Agency plans — the Free plan returns `plan_required` if you try to add one, so this workflow assumes the account has been upgraded. And a secret auto-expires 30 days after submission if nobody ever reveals it, which is a reasonable backstop but not a substitute for reading it promptly once the client has submitted. This also isn't the only way a client might hand over an API key — a password manager's shared entry is a fine alternative when both sides already use one, and [Getting client logins securely](./how-to-get-client-logins-securely.md) weighs that option against BriefGate's portal. What a `secret` item buys you specifically is a workflow your agent can drive end to end, from `define_intake` to `get_intake_results`, without a human relaying the value by hand in either direction. ## Related - [How client credentials are stored](./client-credentials-encryption-explained.md) — the encryption mechanism behind every `secret` item, and what it doesn't claim - [Async human input for coding agents](./async-human-input-for-coding-agents.md) — why MCP elicitation can't reach a client, and what the alternative looks like - [Secrets vault](./secrets.md) — full reference: plans, scopes, reveal windows, expiry - [Item types](./item-types.md) — the `secret` type's fields, alongside the other eleven - [MCP tools](./mcp.md) — `get_intake_results` and `define_intake` in full --- ## One list, every project URL: https://briefgate.dev/docs/intake-templates-for-repeatable-projects # One list, every project The first restaurant website you build, you type out the item list from scratch: logo, hero copy, the restaurant's story, opening hours, a gallery of food and interior shots, maybe a menu PDF. The second restaurant website, you're typing almost the same list again — same items, same constraints, different client. A template exists so that the second time is a click, not a re-type. A BriefGate template is a saved set of item definitions — key, type, label, constraints, all of it — that you point a new intake at instead of building items one by one. `define_intake` (or the dashboard's **New intake** screen) fills the intake with everything the template holds, and you're free to still adjust it for the specific client. ## Build the list once The moment you notice you're asking for the same things on a third project in a row, that's the list worth saving as a template. It doesn't have to be perfect the first time — reuse it as often as the project type comes up, and when it needs to change, save it again under a new name rather than looking for an update button; there's no endpoint to edit a template in place yet, so a revision is a new template, not a patch to the old one. Two ways to get a template into your account: - **From the dashboard**, build an intake the normal way and click **Save as template** next to the Send button once you're happy with the item list. It stores the item definitions, the language, and the intake settings currently set on the form (chase cadence, retention, and the rest — branding is the one exception) — deliberately never the client's name, e-mail, or project name — so the exact same template is safe to hand to the next client without editing out anything personal. - **Through the API**, `POST /v1/templates` builds a template from scratch, from a logged-in dashboard session only — an agent's API key can't call it (there is no endpoint to copy an existing intake into one either — that direction only works from the dashboard button). You give it a `name`, a `language` (`cs`, `en`, or `de`), and an `items` array in the same shape `define_intake` expects. There's no `slug` field to set; the slug is derived from `name` automatically. Custom templates — the ones you build yourself — need a Solo plan or above. On Free, `POST /v1/templates` returns a `plan_required` error, and the dashboard button isn't available either. That's not a limitation you fight around for long, though: Free still gets the seven built-in templates below, which cover a real project type each. ## Seven you don't have to build Every plan, including Free, has seven public templates available from day one: - **`restaurant-web-cs`** — logo, hero copy, the restaurant's story, opening hours, a photo gallery, an optional menu PDF, optional brand colors, and an optional GA4 tracking ID. - **`advisor-web-cs`** — logo, a professional portrait, a one-line headline, a longer bio, up to six services, optional brand colors, and contact details. - **`club-web-cs`** — logo, a motto, the club's history, founding year, what the club does and when it meets, an optional event gallery, contact details, and optional social links. - **`web-cs`** — logo, hero copy, an about section, optional subpage copy, optional photos, optional brand colors, contact details, optional pricing, an optional access note, and an optional GA4 tracking ID. - **`eshop-cs`** — logo, hero copy, a product catalog, optional product photos, optional brand colors, VAT handling, payment methods, shipping, invoice details, and optional terms of service. - **`logo-brand-cs`** — price-quality positioning, a one-line brief, three brand words, optional competitors, an optional slogan, an optional existing logo, an optional moodboard, deliverable formats, an approver, and optional revision rounds. - **`mobile-app-cs`** — app name, target languages, an app icon, optional screenshots, store description, user data disclosure, optional integrations, an optional store-accounts note, an optional privacy policy URL, and optional release constraints. All seven are Czech-language templates — their labels and help text are written in Czech, since they were built for real agency work rather than as generic placeholders. `eshop-cs` is the built-in e-commerce template; `club-web-cs` is for clubs and associations, not stores. They can't be deleted and are always there, which makes them a safe default to start from even if you end up changing half the items. The four newer templates (`web-cs`, `eshop-cs`, `logo-brand-cs`, `mobile-app-cs`) each have exactly 10 items, so they fit inside the Free plan's 10-items-per-intake limit as-is. Point `define_intake` at one with the `template` field: ```json { "project_name": "Bella Cucina Restaurant Website", "client": { "email": "owner@bellacucina.cz", "name": "Marco" }, "template": "restaurant-web-cs" } ``` `items` becomes optional once `template` is set — omit it, or send `"items": []`, and every item comes from the template. Without a `template`, `items` is still required and non-empty, same as always. See [Item types](./item-types.md) for what each type validates, and the full item tables for all seven templates in [Templates](./templates.md). ## Adjust without starting over A template rarely fits a project perfectly, and it doesn't need to. Send an `items` array alongside `template` and BriefGate merges it with the template's own items: a `key` that matches a template item overrides that item, and a new `key` gets appended after the template items. ```json { "template": "restaurant-web-cs", "items": [ { "key": "menu_pdf", "type": "file", "label": "Menu (PDF)", "required": false, "help": "Only needed if you want a downloadable menu link." }, { "key": "allergen_info", "type": "file", "label": "Allergen information document", "required": false } ] } ``` One catch worth knowing before you try to save a keystroke: every entry in `items` has to be a complete item definition — `key`, `type`, and `label` are all required — even when all you actually want to change is whether it's required. There's no shorthand for patching a single field of a template item. ## Carry more than items A template can also hold every other setting a new intake needs besides its items: chase cadence, retention rules, branding, which folder new intakes land in, even a client brief. `POST /v1/templates` accepts an optional `settings` object with `due_in_days`, `chase_schedule`, `respect_quiet_hours`, `max_reminders`, `email_copy`, `retention`, `branding`, `folder_id`, and more — see [Templates](./templates.md#template-settings) for the full field list. These are defaults, not overrides: when you create an intake from a template, a field from `settings` applies only where the create-intake request leaves that field unset. Anything the request states explicitly always wins. `due_in_days` gets resolved into a real `due_date` at the moment the intake is created — a template can't carry a fixed calendar date, only an offset from whenever it's used. Branding is the one setting the dashboard's **Save as template** button can't carry — the New intake form has no branding field to save it from. Everything else in the list above, the button already stores from whatever the form currently holds; build the template through `POST /v1/templates` only if you specifically need branding set too. ## Where the payoff shows The first project with a new template costs you the same time it always did — you're still deciding what to ask for and writing the help text that makes each item make sense to a client who's never filled in an intake before. The second project is where it pays off: you point `define_intake` at the template, add the two or three things that are different about this particular client, and send. What used to be twenty minutes of writing item definitions is now the couple of minutes it takes to fill in a client's name and adjust one due date. On an Agency plan, that payoff extends across the team automatically — a template any seat creates is visible to every seat on the account, with no separate sharing step. If you're building a library across several project types, naming slugs consistently (`restaurant-web-v2`, `advisor-web-minimal`, `webapp-onboarding`) keeps them easy to tell apart as the list grows. ## Related - [Templates](./templates.md) — full reference, including all built-in item tables and the `settings` object - [Item types](./item-types.md) — what each item type validates and returns - [Dashboard quickstart](./dashboard-quickstart.md) — creating an intake from the browser, templates included --- ## When a Client Uploads the Wrong File URL: https://briefgate.dev/docs/wrong-file-revision-workflow # What to Do When a Client Uploads the Wrong File Call `request_revision` on that one item with a note describing what's wrong — from the dashboard or from your agent over MCP/REST. BriefGate flags just that item in the portal, emails the client, and the rest of the intake keeps moving; you don't re-send the whole thing or chase the correction yourself over email. ## Why this needs its own step A client can submit a file that passes every check BriefGate runs and still be the wrong file. A `file` item constrained to `formats: ["pdf"]` happily accepts a PDF that's the unsigned draft instead of the signed contract — the format is right, the content isn't, and no amount of format or size validation catches that, because BriefGate validates what it can verify mechanically (extension, size, pixel dimensions) and has no way to read the meaning of a document. The reference docs for item types are explicit about this boundary: "BriefGate does not infer constraints from file content or other heuristics." Catching the content mismatch is a human judgment call, made by whoever reviews what came in — and once you've made it, you need a way to send the client back to fix just that one item without derailing the rest of the intake or starting a side conversation by email. ## Calling request_revision From an agent, over MCP: ```json { "intake_id": "in_8f3kQmR2", "item_key": "signed_contract", "note": "This is the draft without your signature — I need the signed PDF you received back from the printer, not the version you sent for review." } ``` ```json { "status": "revision_requested", "item_key": "signed_contract" } ``` The REST equivalent is `POST /v1/intakes/:id/revision` with the same `item_key` and `note` in the body; from the dashboard it's a button on the item itself, with the note typed into a text box instead of JSON. All three paths land on the same state change, and the call only succeeds when the item is currently `submitted` or `approved` — asking for a revision on an item nobody has touched yet returns a `409 conflict`, since there's nothing wrong to flag. ## What the client sees, and when The client gets an email explaining a specific item needs attention. BriefGate starts that notification asynchronously the moment you call `request_revision` — it isn't queued for the client's next scheduled reminder slot the way an automatic chase is, and it isn't held back by quiet hours either, since this is a deliberate message about something specific rather than a generic nudge that can wait until morning — though the API response confirms the state change, not that the email was actually delivered. Clicking through takes them to the same portal link as always, where the flagged item now shows a banner with your exact note on it: > "This is the draft without your signature — I need the signed PDF you received back from the printer, not the version you sent for review." Only that item is affected. Everything else they already submitted stays exactly as it was — approved items stay approved, other pending items stay pending — and the item's status moves back to `needs_revision` so the client can re-upload it in the same spot. The moment they do, it returns to `submitted`, its 72-hour auto-approval clock (or whatever you set `auto_approve_hours` to) starts over, and `item.submitted` fires again on your webhook the same as any first submission. One distinction worth knowing if you're also using reminder schedules: a revision notice is not counted the way a scheduled reminder or a manual `send_chase` is against the intake's `max_reminders` cap. [Reminders that arrive at a sensible hour](./reminder-cadence-design.md) covers that cap in full — the short version here is that asking for a fix on a specific item doesn't eat into the budget of general nudges the cadence has left before the intake stalls. ## The Free plan doesn't have this Revision requests need the `revisions` feature, which is **not available on the Free plan** — both the dashboard button and the MCP/REST call return `plan_required` there. On Free, message the client yourself outside BriefGate and give them a way back in: either add a replacement item with [`add_items`](./mcp.md#add_items), or tighten the item's own constraints with [`update_item`](./mcp.md#update_item) so the wrong file no longer passes — that change needs `discard_submitted_value: true`, clears what they sent and puts the item back to `pending` for them to resubmit through the portal. (`discard_submitted_value` on its own, without a change that invalidates the answer, resets nothing.) Or upgrade. There's no substitute built into `send_chase`: it sends the same generic nudge about everything still outstanding, with no note field and no way to flag one specific item. ## Heading it off before it happens A revision request fixes a wrong file after the fact; the item definition is what keeps most wrong files from arriving in the first place. Three things do the actual work: - **`formats`**, so an upload that's the wrong file type — a `.docx` where you need a signed `.pdf`, a `.jpg` where you need a vector `.svg` logo — is rejected before the client can submit it, in the browser first and then, authoritatively, on the server. - **`min_width`/`min_height`** on an `image` item, so a logo exported at 200px for a social media post never reaches you labeled as the print-ready version. - **`help`**, the one field that does the most unglamorous work of all. "Upload the signed PDF you received by email" next to the upload button heads off a surprising number of wrong files that would technically have passed every constraint — a client who sees an unlabeled upload box and a client who sees that sentence make different choices about what to attach. ```json { "key": "signed_contract", "label": "Signed project contract", "help": "Upload the signed PDF you received back from the printer — not the draft you sent for review.", "type": "file", "required": true, "constraints": { "formats": ["pdf"], "max_bytes": 10485760 } } ``` None of that replaces `request_revision` — a client can still misread the clearest help text, or upload the correct format with the wrong content — but it narrows the set of cases that ever need one. The two are complementary: constraints and help text handle "obviously wrong," and `request_revision` handles "looks right, isn't." ## Related - [Item types](./item-types.md) — the full `constraints` reference for `file`, `file_list`, and `image` - [Client portal](./portal.md) — what the client sees end to end, including the revision banner - [Reminders that arrive at a sensible hour](./reminder-cadence-design.md) — how the `max_reminders` cap works, and why a revision notice doesn't count against it - [MCP tools](./mcp.md) — `request_revision` and `get_intake_results` in full - [REST API](./rest-api.md) — `POST /v1/intakes/:id/revision` --- ## Where a human still steps in URL: https://briefgate.dev/docs/agent-led-intake-human-checkpoints # Where a human still steps in An agent running BriefGate end to end looks, most of the time, like it needs nobody. It calls `define_intake` with the items a project requires, BriefGate mails the client a portal link, and the agent goes back to building. It finds out what changed by polling [`get_intake_status`](./mcp.md) on the schedule its own `define_intake` response recommended, or by registering a [webhook](./webhooks.md) and reacting to events instead of asking. Reminders go out in the client's language on the cadence the agent chose, without anyone drafting a follow-up by hand. None of that needs a person in the loop, and it's designed not to. A handful of moments in that same flow are different. Some of them BriefGate refuses to let an API key do at all, regardless of scope. Others it technically allows, but hands the agent enough rope that using it well is a judgment call, not a permission check. Both are deliberate — not missing features, but the shape of a tool built for a workflow where a client's money, credentials, or goodwill sit on the other end of the portal link. ## Reading a credential A `secret` item — a CMS password, an API key, a hosting login — is encrypted the moment it lands on BriefGate's server, before it ever reaches the database: HTTPS in, then a libsodium sealed box under a key that lives only in the server environment. That's encryption at rest with server-side decryption — not end-to-end, not zero-knowledge. BriefGate's server can read it back, and it does, exactly once. That "once" is the actual checkpoint, and it isn't purely a human one — it's a scope one. An agent's API key can reveal every secret on an intake through [`get_intake_results`](./mcp.md#get_intake_results), but only with the `secrets:read` or `admin` scope. Key creation defaults to `admin`, which includes it; giving an agent the narrower `intakes:read` and `intakes:write` instead, and adding `secrets:read` only when it must reveal credentials, is what actually keeps that scope out of its hands. Whether the agent can read a password at all is decided the moment someone hands it a key with that scope, or doesn't. The other path, clicking **Reveal** in the dashboard, is narrower still: it needs a live session, and only the account **owner** may use it — a team member gets `403 forbidden`. Whichever side gets there first wins the one-time reveal; the other is told it was already shown. There's no reading it "just to check." So the actual human step isn't reading the secret — it's the decision, made once, about which keys get to. ## Confirming what the agent can only propose Most items on an intake are answered by the client. A smaller category, items with `"assignee": "owner"`, never reach the client's portal — they're the agent's or owner's own to-dos, ticked off with `POST /v1/intakes/:id/items/:key/done`. Inside that category sits one type BriefGate calls a **decision**: an owner-assigned `select` or `multiselect` item where the agent may attach its own proposed answer and rationale. What the agent cannot do is settle it. `POST /v1/intakes/:id/items/:key/answer` is session-only, and the docs say plainly why: accepting that call from an API key "would let an agent confirm its own proposal and have the result recorded as `decided_by: owner` — exactly what separating a proposal from an answer exists to prevent." The read side shows the seam: every decision item carries `proposed_value`, `proposed_rationale`, and `decided_by: "agent"|"owner"`. It's a narrow feature, but the cleanest example of the general rule: an agent can do the analysis and hand over a recommendation, reasoning attached. It doesn't get to also sign off on its own recommendation. ## Objecting to a submission, or letting it stand There is no "Approve" button anywhere in BriefGate — not in the dashboard, not as an MCP tool, not as a REST endpoint. A submitted item auto-approves on its own after `auto_approve_hours` (72 by default, configurable per intake); the one thing you can do before then is [`request_revision`](./mcp.md#request_revision) with a note, which sends the item back to `needs_revision` rather than approving or rejecting it. Silence is acceptance; the only affirmative move is to object. Nothing technically stops an agent from calling [`request_revision`](./mcp.md#request_revision) on its own — it's one of the 13 MCP tools, and the recommended flow says to use it "instead of asking the client again yourself outside BriefGate." This isn't the API refusing the agent; it's a case where using the tool well needs something the API can't check. Whether a logo that's technically present — right format, right dimensions, on time — actually represents the client's brand is not something BriefGate can validate: an item definition is the single source of truth, nothing inferred from content, so it confirms an item is *usable by its own definition* and nothing about whether it's *good*. And `request_revision` fires a real email, worded by whoever called it, to a real client, in the owner's name, with no confirmation step in between. A judgment the API cannot make, landing in an action with no undo — that's why it's worth a person's eyes first, even though the tool never asks for one. ## Deciding what to ask for Nothing in BriefGate checks whether the item list an agent sends to `define_intake` is the right one. The API validates each item's own shape — a `pattern` a `text` value must match, a `min_width` an image must clear — but has no opinion on whether the keys and labels add up to what the project needs. An agent working from a half-remembered template instead of the brief in front of it gets a perfectly valid intake that chases a client for things nobody asked for, and misses the one credential it can't proceed without. That's why the [MCP guidance](./mcp.md) itself opens with when *not* to reach for BriefGate: skip it when the answer is already in the repo, already in the conversation, or belongs to the person you're talking to right now — the portal and its reminders are for people who aren't in the conversation. Getting the list right is a judgment call; BriefGate only enforces that whatever gets asked for is well-formed. ## When the client goes quiet The chase engine reminds a client on schedule, in their own language, inside their working hours, for as long as `max_reminders` allows — three attempts by default, adjustable up to a thousand or removed entirely. When that allowance runs out without a completed intake, BriefGate stops on its own, marks the intake stalled, and fires `intake.stalled` with the list of what's still missing. That's the edge of what automated chasing can do: the schedule ran, and the client still hasn't answered. An agent that receives `intake.stalled` isn't stuck — it can raise `max_reminders` or shorten the cadence with `update_intake`, or fire an immediate `send_chase`. What it can't do is anything BriefGate doesn't build a channel for: pick up the phone, reach the client somewhere the intake was never sent, or judge that this project should proceed without the missing piece. `intake.stalled` is, by design, an event meant for a person — the guidance for receiving it is to "consider reaching out to the client by other means." BriefGate hands back exactly the information needed to make that call, and stops there. ## What's rightly left to the agent None of this argues that BriefGate needs a human in every step — it's the opposite. Defining an intake from a project brief, watching its status without babysitting an inbox, pulling typed results the moment they're ready, and wiring them straight into the build: that's the entire reason BriefGate exists as an MCP server and not just a dashboard. The checkpoints above are narrow on purpose. They sit exactly where a wrong call is expensive and hard to undo — a credential read by the wrong caller, a decision an agent rubber-stamped for itself, a curt note landing in a client's inbox unread, an intake stalled because it asked for the wrong thing. Everywhere else, the agent keeps building, and the client fills things in on their own time. --- ## Why Client Reminder Emails End Up in Spam URL: https://briefgate.dev/docs/client-reminder-emails-spam # Why Client Reminder Emails End Up in Spam Reminder emails about a client project usually land in spam for one of three reasons: the sending domain's authentication doesn't fully check out (SPF, DKIM, or DMARC), the domain is shared with senders whose mail has a worse reputation than yours, or the message pattern itself reads like an automated blast rather than mail from a specific person about a specific project. None of those depend on what the reminder actually says — they're checked before a mail server ever reads the subject line. ## Authentication: the part a spam filter checks first Every receiving mail server runs three checks against the domain in the "From" address before it decides anything else: - **SPF** (Sender Policy Framework) — a DNS record listing which mail servers are allowed to send as that domain. - **DKIM** (DomainKeys Identified Mail) — a cryptographic signature on the message, verified against a public key published in DNS, proving the message wasn't altered in transit and really came from a server that holds the matching private key. - **DMARC** (Domain-based Message Authentication, Reporting and Conformance) — a policy record telling the receiver what to do when SPF or DKIM fails, and whether the domain in SPF/DKIM has to match the visible "From" domain ("alignment"). As of October 2026, Gmail and Yahoo's current bulk-sender guidance (in force since February 2024) requires full SPF+DKIM+DMARC with alignment, a sub-0.3% spam-complaint rate, and one-click unsubscribe — but only for senders pushing past roughly 5,000 messages a day to their users. A reminder about one client's project is nowhere near that volume, and the unsubscribe requirement specifically exempts genuinely transactional mail. What doesn't go away below that threshold is the underlying signal: Gmail and Yahoo (and every other major provider) still use SPF/DKIM/DMARC pass-or-fail as one input into whether a message is trustworthy, bulk sender or not. A domain missing DKIM, or one where SPF passes but doesn't align with the visible sender, looks more like something worth a second check — and spam folders are where second checks happen by default. The practical upshot: a domain with SPF and DKIM both configured and aligned starts every message with one fewer reason to be filtered. A domain missing either doesn't guarantee spam, but it removes a signal the filter would otherwise have given it credit for. ## Whose reputation is actually on your reminder Authentication proves *who* sent the mail. Reputation is a separate question — *has this sending identity behaved well before* — and it's tracked per domain (and per sending server), not per message. A **shared sending domain** means every account using that domain inherits the same reputation history. If BriefGate's shared domain carries a good reputation, your reminder benefits from it without you doing anything. Mail uses `intake@briefgate.dev` until a Studio or Agency sending domain is verified (see [Custom Domains](./custom-domains.md)); once it is, the display name drops the "via BriefGate" qualifier and mail switches to `intake@yourcompany.com`, or whichever local part you've configured, carrying your own domain's reputation rather than the shared one. Until a custom domain is verified, nothing breaks and nothing is held back — mail keeps going out from the shared domain exactly as before. A **dedicated domain** cuts the other way: your reputation is entirely your own, for better or worse. A brand-new domain, or one that's never sent transactional mail before, doesn't start with a bad reputation — it starts with *no* reputation, which filters treat cautiously until they've seen enough consistent, low-complaint sending to build trust. That's the trade custom domains make: full control over the identity the client sees, at the cost of a reputation you now have to earn rather than borrow. For most projects, the shared default is the right call precisely because it comes pre-earned; a custom domain is worth the ramp-up mainly when you're sending enough client reminders, from enough projects, that your own domain's reputation adds up faster than relying on a shared one, or when the client-facing identity matters enough on its own (an agency putting its own name in front of every client, not BriefGate's). ## Patterns that make a message look automated Authentication and reputation decide whether a server is willing to trust the domain at all. A third layer looks at the message itself, and at the sending pattern around it: - **Frequency.** The same recipient getting several nearly-identical messages close together reads like an automated loop, even when each one is legitimate. A fixed short interval — emailing every two or three days regardless of how long the request has been outstanding — is the clearest version of this pattern, because it's exactly how a crude mail-merge script behaves. BriefGate's gentle, default, and aggressive presets are built to avoid that shape by spacing reminders out as a request goes unanswered longer, rather than hammering at a constant interval — a custom schedule, by contrast, is itself a fixed interval, so it's worth pairing with a longer gap if deliverability matters. See [Reminders that arrive at a sensible hour](./reminder-cadence-design.md) for how the cadence itself is designed, and the reminder cap that stops it from escalating into exactly the pattern a spam filter is watching for. - **Time of day.** A message sent at 3am local time to the recipient is a pattern no human sender produces, and filters know it. BriefGate holds reminders to 8:00–19:00 in the client's own time zone by default — also covered in that same article — rather than firing on whatever schedule the server happens to run. - **Generic templates with no context.** A message with no reference to the specific project, sent from a name the client doesn't recognize, is harder for a filter to distinguish from a phishing attempt that also claims urgency and asks for action. Reminders that name the actual project and the actual sender don't just read better to the client — they give the filter less reason to flag the pattern as mass mail. ## What you can actually check - **Run a one-off deliverability test.** A tool like mail-tester.com sends you a throwaway address; mail to it and the result shows SPF, DKIM, and DMARC pass/fail individually, so a misconfigured record shows up by name rather than as a vague "went to spam." - **Check Google Postmaster Tools** (free, for any domain sending to Gmail addresses) for your domain's reputation and spam-rate trend if you're on a custom sending domain — there's nothing to check on the shared domain, since that reputation isn't yours to monitor. - **Ask the client to do the one thing that actually works immediately.** Replying to any BriefGate email, or adding the sender address to their contacts, is a stronger positive signal to most providers than any authentication fix, because it comes from the recipient's own behavior rather than from the message. It's worth a one-line ask the first time you send: "add this address to your contacts so our reminders don't get buried." - **If you're on Studio or Agency and considering a custom sending domain**, add it and verify the SPF, DKIM, and MX records in [Custom Domains](./custom-domains.md) *before* relying on it for a time-sensitive project — a domain mid-verification still sends from the shared address, so there's no gap in delivery, but you want the reputation question settled before a deadline, not during one. ## Related - [Reminders that arrive at a sensible hour](./reminder-cadence-design.md) — how BriefGate's chase schedules and quiet hours are designed - [Custom Domains](./custom-domains.md) — setting up your own sending and portal domain, step by step - [Client Portal](./portal.md) — what the client actually sees once a reminder lands - [Security](./security.md) — how BriefGate handles the data behind those reminders --- ## Choosing the right item type URL: https://briefgate.dev/docs/choosing-item-types # Choosing the right item type An intake is only as good as its items. Pick `text` where you meant `select`, or `file` where you meant `image`, and the client either sends something that doesn't validate as expected, or something valid that still isn't useful — a screenshot instead of a vector logo, a paragraph where a yes/no would have done. BriefGate has twelve item types. This is a guide to picking the right one, not a list of what each does — for the field-by-field reference, see [Item types](./item-types.md). ## Start from what you're actually asking for The type isn't a formatting choice, it's a contract: it decides what the portal shows the client, what gets validated before they can submit, and what shape `get_intake_results` hands back to you. Three questions narrow it down fast: 1. **Is this a file, or a value?** A logo is a file. A brand color is not — even though a client might think of it as "the blue from our logo," what you actually want back is a hex code, so it's `color_list`, not `image`. 2. **Is there a fixed set of acceptable answers?** If yes, that's `select` or `multiselect`, not `text` or `longtext` — see below for why that matters more than it looks like it should. 3. **Does the client choose it, or do you?** Most items are `assignee: "client"` by default. A to-do that's actually yours — "call the client", "register the domain" — is `assignee: "owner"` instead, and never reaches the portal at all. ## Text vs. longtext vs. structured `text` is for short, single-line, structured strings: a GA4 measurement ID, a tracking code, an account name. It defaults to a 2000-character cap and accepts a top-level `pattern` (an ECMAScript regex) to enforce a specific shape, like `^G-[A-Z0-9]+` for a GA4 ID. `longtext` is for prose — bios, mission statements, hero copy, anything the client needs room to actually write. Its default cap is much higher (20,000 characters), and in practice you'll usually tighten it with `max_chars` so a "short intro" item doesn't come back as three paragraphs. `structured` is for a value with more than one field that belongs together — opening hours with `mon_fri`/`sat`/`sun`, a services list, a contact block with `phone`/`email`/`address`. You define a JSON Schema and the portal renders a form from it: a flat object, a repeatable list of such objects (say, up to six services), or a list of single values. Keep the schema to those shapes, because deeper nesting and constructs like `oneOf` have no form for the client to fill in. What comes back through `get_intake_results` is validated against the schema on the server. The mistake to watch for: three separate `text` items for phone, email, and address is a worse fit than one `structured` item with those three properties — the free-standing items don't say they belong together, and there's nothing stopping the client from filling in two of three. ## select vs. multiselect vs. free text This is the single most common item-type mistake: asking a free-text question where the real intent is a limited set of choices. "What platform do you want?" as a `text` item gets you "wordpress", "Wordpress", "WP", and "not sure, whatever's easiest" from four different clients — four strings your downstream process now has to normalize by hand. The same question as a `select` with defined `options` (`value`/`label` pairs) returns exactly one of the values you defined, every time, with no normalization needed. `select` is for exactly one answer from a defined list. `multiselect` is for any number of answers, including none, from a defined list — "which services do you need," where more than one can apply. The result for `select` is always the `value` string, never the `label` the client saw; for `multiselect` it's always an array of `value` strings, even for one pick. Reach for `multiselect` with `min_count: 1` rather than `select` when zero-or-many is real — coercing a multi-answer question into `select` just pushes the client toward one option and leaving the rest unsaid. Reserve `boolean` for a true yes/no question — "do you have an existing website?" — rather than a two-option `select`; it renders as a simple toggle instead of a dropdown with two rows, and the result is a plain `true`/`false`. ## file vs. file_list vs. image `file` is one file: a signed PDF contract, a font file, a spreadsheet — anything where you need exactly one document and don't care about its pixel dimensions. `file_list` is a group of files under one item — a photo gallery, an asset pack — with `min_count`/`max_count` to enforce how many. It avoids a single catch-all "send me everything" `file` item: a client asked for one file sends one file, even if what you actually wanted was eight photos and a logo. Ask for what you need as separate, specifically-labeled items — or a `file_list` for a genuine group of similar files — instead of one item that quietly depends on the client reading your intent into the label. `image` is for when the file *is* an image and you care about more than just "it's a file" — minimum or maximum width and height, allowed formats, a size cap. Use `image` instead of `file` whenever you'd otherwise have to eyeball the upload afterward; BriefGate rejects an upload that breaks those constraints before it is accepted, so a 200px logo never reaches you in the first place. Unlike `file`, `image`'s `constraints.formats` has no default — any image format is accepted unless you set it, so list your allowed formats explicitly if you need to rule out, say, HEIC. ## url and secret `url` validates that the value is a proper http/https URL (a client who types `firma.cz` gets `https://firma.cz`). It doesn't restrict the domain, so when you specifically want, say, a Google Drive link and not any URL at all, say so in the item's `help`. `secret` is for credentials — CMS logins, API keys, anything that shouldn't sit around in plaintext. The value is sealed on the server with a libsodium sealed box before storage, never logged or included in webhook payloads, and can be revealed through `get_intake_results` only once (with a short grace window for a caller whose first read never arrived). That's encryption at the server, not end-to-end or zero-knowledge — worth being precise about when describing the security model to a client. Use `secret` for anything a client would call a password, `text` for anything else, even if it looks credential-adjacent (an account ID isn't a secret; the password to it is). ## Common mistakes, summarized - **A file item for a decision.** "Send me your logo file with your color preferences noted" is really two items: an `image` and a `color_list`. Splitting them means each validates on its own and the client can't submit one without the other. - **Free text where a choice belongs.** Any time you'd have to normalize the client's answer afterward — matching "wordpress"/"WP"/"Wordpress" back to one value — that's a sign the item should have been `select` or `multiselect`. - **One giant "send me everything" item.** A single `file` or `file_list` item covering unrelated materials (logo *and* photos *and* the signed contract) lets the client satisfy it with just one of those things. Give each category of material its own item, even if the intake ends up with more rows. - **`assignee: "owner"` on a client question, or vice versa.** An owner item never reaches the portal and never holds the intake open, so a genuine client question set to `assignee: "owner"` simply never gets asked. Your own to-do items don't belong as client items just because it's convenient to track them on the same intake. ## Related - [Item types](./item-types.md) — the full reference: constraints, examples, and exactly what `get_intake_results` returns for each type - [Templates](./templates.md) — built-in item sets that already make these choices for a few common project types - [Dashboard quickstart](./dashboard-quickstart.md) — building an intake's item list from the browser --- ## Case Study: Reminders vs Slack Follow-ups URL: https://briefgate.dev/docs/case-study-automated-client-reminders # Case Study: Five Slack Follow-ups Failed. Automated Reminders Didn't. A real client request that stalled on Slack got delivered five days after it moved into a BriefGate intake — with eleven automated notifications and zero manual follow-ups. This is not a customer testimonial. It is how the person who builds BriefGate uses it on his own client work. The numbers come straight from the production database, anonymized: no client name, no submitted content. ## The problem: asking again, and again I needed a set of documents from a client. I asked on Slack. Then I asked again. Five times over one to two weeks, and nothing arrived. Every follow-up had a cost that doesn't show up in any time sheet: remembering to ask, wording it politely one more time, and the growing feeling of being the person who nags. ## What changed On 2 September 2026 I created an intake in the BriefGate dashboard with one required item. No AI agent, no code — the browser only. The client received an email with a link to the portal, and the reminders took over from there. ## The result | | | |---|---| | Follow-ups on Slack before the intake | 5 over 1–2 weeks, no delivery | | Items in the intake | 1 | | Notifications BriefGate sent | 11 (1 invitation + 10 reminders) | | Time from sending to delivery | 121 hours (about 5 days) | | My own follow-ups after creating the intake | 0 | The reminders did what my Slack messages didn't: each one named the single missing item, linked straight to the place to upload it, kept arriving on a schedule, and none of them came from me personally. ## All my real requests so far Between 2 and 14 September 2026 I sent five real intakes (tests excluded). Three were completed — in under an hour, in 4.4 hours and in 121 hours. Two are still open, one of them after five reminders. Reminders don't guarantee a reply. What they remove is the part where you have to keep asking yourself. ## Try it on your own stuck request If a client owes you something right now, turn that one request into an intake: list the item, send the link, and let the reminders do the chasing. The free plan covers one active intake and needs no card. - [BriefGate for agencies and freelancers](/collect) - [Why clients don't send materials](/docs/why-clients-dont-send-materials) - [Email templates for requesting materials](/docs/email-templates-requesting-materials-from-clients) --- ## BriefGate vs Content Snare for developers URL: https://briefgate.dev/docs/content-snare-alternative # BriefGate vs Content Snare: The Developer's Alternative ## Introduction Content Snare is the established player in client asset collection. It is an excellent tool for agencies with human-led workflows: a project manager logs in, builds a request from templates and around thirty field types, and tracks which clients have responded. The workflow is designed around a person in the loop. BriefGate is built for a different use case. Your coding agent — Claude Code, a Cursor session, or any MCP-capable agent — is the primary actor. The agent calls `define_intake`, BriefGate emails the client and chases them automatically, and when everything is in, the agent calls `get_intake_results` and gets typed data it can immediately use to continue building. No human coordinator is required. You can also create intakes by hand in the dashboard, but the design choices below come from that agent-first starting point. If you are evaluating both for a developer-driven workflow where an AI agent is doing the heavy lifting, this comparison explains where each tool fits. For how a dedicated portal like these two compares to email, transfer links, and forms in general, see [the best way to collect files from clients](/docs/how-to-collect-documents-from-clients). ## Side-by-side comparison | Feature | Content Snare | BriefGate | |---|---|---| | Primary interface | Human dashboard (web UI) | MCP tools and REST API, plus a dashboard | | Define intake | Web UI request builder and templates | `define_intake()` from your agent, or the dashboard | | Client account needed | No by default; you can choose to require client registration | No, the client opens a magic link | | Retrieve results | Dashboard, answer export (Word, PDF, CSV), API | `get_intake_results()` returning typed JSON | | Field types | Around 30, including number, date, currency, dropdown, checkboxes, signature, ID verification, and colour picker | 12 typed items, including structured JSON validated against a schema, colour list, and encrypted secret | | Secrets / credential handling | No password or secret field type | Encrypted vault (libsodium, encrypted on the server), one-time reveal | | Automated reminders | Yes, default or custom schedule | Chase engine: preset cadences, custom interval on paid plans, quiet hours, reminder cap | | Webhooks | Yes | Yes (`item.submitted`, `intake.completed`, etc.) | | Public API | REST API with OAuth 2.0 | REST API with OpenAPI spec, plus `llms.txt` for AI agent autodiscovery | | MCP server | No native server; reachable through Zapier's generic MCP connector | Yes, first-party: `npx @briefgate/mcp` or hosted at `https://mcp.briefgate.dev/mcp` | | Agent-loop protection | N/A | Rate limits + `Retry-After` + webhook-first design | | EU data residency | Not offered as a guarantee | Yes (netcup Germany + Cloudflare R2 EU) | Facts about Content Snare were checked on 14 September 2026 against Content Snare's help centre, feature pages, and Zapier listing. We do not quote Content Snare's prices because we could not confirm the current figures; see their pricing page. Links are at the end of this page. ## When to choose Content Snare - Your intake workflow is run by a human project manager, not an agent - Your team needs a visual dashboard for tracking which clients have responded - You want client approval flows (client approves submitted content before it is considered final) - You need field types BriefGate does not have, such as e-signatures or ID verification - You are already using Content Snare and expanding an existing workflow - You need a no-code form builder that non-technical team members can operate Content Snare is mature, well-documented, and has a strong track record in agency settings. If the person building the deliverable is human and the intake coordinator is human, it remains an excellent choice. ## When to choose BriefGate - Your Claude Code or Cursor agent builds the deliverable and needs assets to continue - You want the agent to receive typed JSON through MCP tools, not an export it has to parse - You need credential collection (passwords, API keys) with proper encryption — the secrets vault handles this; Content Snare has no password or secret field type - You want the agent to call `get_intake_results` and immediately continue building, without a human handoff step in the middle - You run intakes yourself from the dashboard, but want credentials stored encrypted and reminders that run without you watching - You are building agentic software where the intake step is one automated stage in a larger pipeline The key difference: in BriefGate, the agent is a first-class actor. `define_intake` and `get_intake_results` are designed to be called from code, not copy-pasted from a dashboard. The result is typed JSON the agent can use directly — file URLs, parsed structured objects, validated strings — not a human-readable summary that needs further parsing. ## Migration from Content Snare If you are coming from Content Snare, the conceptual mapping is straightforward: | Content Snare | BriefGate | |---|---| | Request | Intake | | Section | Item group (use item ordering) | | Field | Item (with type) | | Template | Template | | Client reminder | Chase engine (automated) | | Completion notification | `intake.completed` webhook | Content Snare has no template export (its exports cover submitted answers as Word, PDF, or CSV), so templates are rebuilt rather than imported. Text, choice, and file fields map directly to BriefGate item types; numbers, dates, and similar fields can be collected as text or as a `structured` item with a JSON Schema; signatures and ID verification have no BriefGate equivalent. Define each template once with `POST /v1/templates` and your agent reuses it for every new client. The REST API has an OpenAPI spec at `GET https://api.briefgate.dev/v1/openapi.json`. ## Sources - Field and question types: https://contentsnare.com/help/knowledge-base/field-question-types/ - Client access and optional registration: https://contentsnare.com/help/knowledge-base/client-access/ - Automated reminders: https://contentsnare.com/features/automated-reminders/ - Approving and rejecting answers: https://contentsnare.com/help/knowledge-base/approve-reject-and-comment/ - Exporting answers: https://contentsnare.com/help/knowledge-base/exporting/ - Content Snare API: https://contentsnare.com/help/knowledge-base/content-snare-api/ - Webhooks: https://contentsnare.com/help/knowledge-base/webhooks/ - Content Snare on Zapier MCP: https://zapier.com/mcp/content-snare --- ## BriefGate vs Dubsado: collecting client assets URL: https://briefgate.dev/docs/dubsado-alternative # BriefGate vs Dubsado: when the missing piece is getting assets from the client ## Introduction Dubsado is a business-management suite for creative and service professionals: lead capture, proposals, contracts with e-signature, invoicing and payments, scheduling, a client portal, and a workflow builder that ties them together. In its own words: "Run your whole business, from first hello to final payment." Photographers, designers, coaches, and consultants use it as the one system their client relationship lives in. BriefGate covers one step of that relationship, the one that stalls projects: getting the logo, the copy, the photos, the hosting login, and a dozen small decisions out of the client after the contract is signed. In BriefGate that step is driven by your coding agent or by you: `define_intake` describes what the client owes, BriefGate sends a branded portal link and chases the client until everything is in, and `get_intake_results` hands the agent typed data it can build with. If you are a Dubsado user whose projects wait weeks for "the files", or a developer choosing where asset collection should live, this page shows where each tool fits. ## Side-by-side comparison | Feature | Dubsado | BriefGate | |---|---|---| | What it is | Whole-business suite: leads, proposals, contracts, invoices, payments, scheduling, workflows | Asset collection with automated chasing, driven by an agent or a person | | Primary interface | Web dashboard and mobile app | MCP tools and REST API, plus a dashboard | | Where files are collected | File uploader element inside a questionnaire, proposal, or lead capture form; not inside the client portal itself | Per-item uploads on a branded portal: `file`, `file_list`, `image` with format, size, and count constraints | | File size | Under 8 MB per file | Per-plan storage; large uploads go straight to object storage | | What else you can ask for | Questionnaire fields | 12 typed items: text, long text, URL, select, multi-select, boolean, colour list, structured JSON with a schema, encrypted secret | | Credential collection | No dedicated feature | Encrypted secrets vault with one-time reveal (Solo, Studio, and Agency) | | Automatic reminders | Workflow trigger "X days after form is not completed" sending a canned e-mail; SMS for these reminders not found in the help centre | Chase engine per intake: preset cadences, a custom interval on paid plans, quiet hours, reminder cap, e-mail, per-recipient bounce handling | | Public API | None listed on the integrations page; Zapier on the Premier plan | REST API with OpenAPI spec, webhooks, `llms.txt` | | MCP server | None found | Yes, `npx @briefgate/mcp` | | Pricing | Starter 335 USD per year, Premier 525 USD per year; extra brands and users as add-ons | Free plan; Solo 29 USD; Studio 50 USD; Agency 79 USD per month | | Trial | 21 days on Premier, no card required | Free plan, no card required | Facts about Dubsado were checked on 3 September 2026 against Dubsado's pricing and integrations pages and its help centre. Dubsado shows only annual prices on its site, so no monthly figure is given here. Links are at the end of this page. ## When to choose Dubsado - You want proposals, contracts, invoicing, payments, scheduling, and a client portal in one product, and asset collection is a small part of that - A person on your team runs onboarding from a dashboard and the "days after form not completed" trigger is enough of a reminder - You rely on Dubsado's accounting integrations (QuickBooks Online, Xero) and its payment processing - You have already built your workflows in Dubsado and moving would cost more than it saves Capterra reviewers rate Dubsado 4.2 out of 5 and praise the automation workflows, the all-in-one platform, and the branded client-facing documents; the recurring complaint is the learning curve and setup time. If the whole-business suite is what you need, BriefGate does not replace it. ## When to choose BriefGate - Your CRM, contracts, and invoicing live elsewhere and the only broken step is getting assets from the client - Your coding agent builds the deliverable and needs the assets as typed data, not as attachments on a questionnaire - Clients send files bigger than 8 MB: print-ready artwork, video, photo sets - You collect credentials and want them encrypted and revealed once, not typed into a form field - Reminders have to run on their own per client, over e-mail, without a person watching the dashboard - You need an API or an MCP server, not Zapier, and you want your data stored in the EU ## Using both Dubsado and BriefGate do not compete for the same step, so combining them is straightforward: 1. Sell and contract the project in Dubsado as you do today. 2. When the project starts, have your agent, or a Zapier zap on a Dubsado workflow step, call `POST /v1/intakes` with the items that project needs. 3. BriefGate chases the client and fires `intake.completed` when everything is in. Your agent picks up the results with `get_intake_results` and continues building. The client gets one branded portal for the assets and keeps using Dubsado for contracts and payments. ## Sources - Dubsado pricing, plans, add-ons, and trial: https://www.dubsado.com/pricing - Positioning and audience: https://www.dubsado.com/ - Client file uploader, 8 MB limit, not available inside the portal: https://help.dubsado.com/en/articles/1137391-client-file-uploader - Workflow trigger for forms not completed: https://help.dubsado.com/en/articles/3269966-workflow-triggers-client-progress - Workflow actions and payment reminders: https://help.dubsado.com/en/articles/3186297-workflow-actions-sending-content - Integrations page (Zapier, accounting, calendars, no public API listed): https://www.dubsado.com/integrations - Reviews: https://www.capterra.com/p/206389/Dubsado/reviews/ --- ## BriefGate vs HoneyBook: assets without a CRM URL: https://briefgate.dev/docs/honeybook-alternative # BriefGate vs HoneyBook: collecting client assets without the whole CRM ## Introduction HoneyBook is a client-management suite for independent service businesses: lead capture, proposals, contracts with e-signature, invoicing with built-in payments, scheduling, and a client portal, all in one product. Its own headline says it: "Manage every client, project, and payment all in one place." If you run a photography studio, an event business, or a small agency in the US, Canada, the UK, or Australia, and you want one tool for the entire client lifecycle, it is a strong choice. BriefGate does one part of that lifecycle and does it for a different actor. Once a project is sold, somebody has to get the logo, the copy, the photos, the hosting login, and a dozen small decisions out of the client. In BriefGate that somebody is your coding agent: it calls `define_intake`, BriefGate e-mails the client a portal link and sends reminders until the intake is complete or its configured reminder cap is reached, and the agent calls `get_intake_results` and gets typed data it can build with. No CRM, no invoicing, no proposals. This page is for people who have HoneyBook, or are evaluating it, and specifically need the asset-collection step to run itself. ## Side-by-side comparison | Feature | HoneyBook | BriefGate | |---|---|---| | What it is | Client lifecycle suite: leads, proposals, contracts, invoices, payments, scheduling | Asset collection with automated chasing, driven by an agent or a person | | Primary interface | Web dashboard and mobile app | MCP tools and REST API, plus a dashboard | | Where files are collected | Up to 3 file-upload blocks per smart file or lead form, up to 10 files and 15 MB per file; smart files accept JPG, PNG, PDF, GIF, lead forms JPG, PNG, GIF | Per-item uploads on a portal (your branding on paid plans): `file`, `file_list`, `image` with format, size, and count constraints | | What else you can ask for | Questions inside smart files and questionnaires | 12 typed items: text, long text, URL, select, multi-select, boolean, colour list, structured JSON with a schema, encrypted secret | | Credential collection | No dedicated feature | Encrypted secrets vault with one-time reveal (Solo, Studio, and Agency) | | Automatic reminders | Automatic reminder e-mails (an on/off setting); a full automation builder with configurable waits, plus SMS reminders, on Essentials and above | Chase engine per intake: preset cadences, a custom interval on paid plans, quiet hours, reminder cap, e-mail, per-recipient bounce handling | | Public API | No general public API; integrations go through Zapier (Essentials and above) | REST API with OpenAPI spec, webhooks, `llms.txt` | | MCP server | Official Claude connector since August 2026: works with your own account (projects, invoices, contracts, messages, questionnaire responses) and can create projects or send payment links; its documented actions do not include requesting assets from a client | Yes, `npx @briefgate/mcp` | | Availability | US, Canada, UK, Australia | Web-based; application and database hosted in Germany, files in Cloudflare R2's EU jurisdiction | | Pricing | Starter 29 USD per month billed yearly; automations and SMS reminders from Essentials, 49 USD billed yearly or 59 USD monthly; Premium 109 USD billed yearly or 129 USD monthly | Free plan; Solo 29 USD; Studio 50 USD; Agency 79 USD per month | | Trial | 30 days, no card required | Free plan, no card required | Facts about HoneyBook were checked on 3 September 2026 against HoneyBook's pricing page, help centre, and community forum; the MCP connector, upload limits, and pricing were rechecked on 14 September 2026. Links are at the end of this page. ## When to choose HoneyBook - You want one product for proposals, contracts, invoicing, payments, and scheduling, and asset collection is a small part of that - Your clients are in the US, Canada, the UK, or Australia and pay by card or ACH inside the platform - A person on your team runs onboarding from a dashboard and the automation builder is enough to remind clients - You want lead capture and a sales pipeline in the same tool as delivery HoneyBook reviewers on G2 and Capterra consistently praise the templates, the built-in payments, and having everything in one place. If that is what you need, BriefGate is not a replacement for it. ## When to choose BriefGate - You already have a CRM, invoicing, or contracts elsewhere and only the "get the assets from the client" step is broken - Your coding agent builds the deliverable and needs the assets as typed data, not as attachments inside a project record - You collect credentials (hosting, DNS, ad accounts) and want them encrypted and revealed once, not typed into a questionnaire - Reminders have to run on their own schedule per client, over e-mail, without a person watching - You are outside HoneyBook's four countries, or your clients are, or you need EU data residency - You want an agent to send the client an asset request and have the chasing run on its own; the documented actions of HoneyBook's Claude connector are creating and editing projects and sending payment links ## Using both HoneyBook and BriefGate do not compete for the same step, so combining them is straightforward: 1. Sell and contract the project in HoneyBook as you do today. 2. When the project starts, have your agent, or a Zapier zap on HoneyBook's "project moved to stage" trigger, call `POST /v1/intakes` with the items that project needs. 3. BriefGate chases the client and fires `intake.completed` when everything is in. Your agent picks up the results with `get_intake_results` and continues building. The client sees one portal for the assets (your branding on paid plans) and never has to learn a second dashboard. ## Sources - HoneyBook pricing, plans, and trial: https://www.honeybook.com/pricing - File uploads in smart files and lead forms: https://help.honeybook.com/en/articles/8776839-let-clients-upload-files-through-your-smart-files-and-lead-forms - Questions in smart files: https://help.honeybook.com/en/articles/5259731-ask-your-clients-questions-in-your-smart-files - Automatic reminder e-mails: https://help.honeybook.com/en/articles/2456470-set-up-automatic-reminder-emails-and-questionnaires-in-honeybook - Automations, triggers, waits: https://help.honeybook.com/en/articles/9519175-about-automation-triggers-actions-waits-and-conditions - Zapier integration: https://help.honeybook.com/en/articles/2209205-automate-tasks-with-zapier - No public API (HoneyBook community): https://community.honeybook.com/honeybook-product-talk-7/does-honeybook-have-an-api-for-integrations-918 - HoneyBook Claude connector: https://help.honeybook.com/en/articles/15686224-honeybook-claude-how-your-data-is-used - HoneyBook MCP announcement (19 August 2026): https://www.globenewswire.com/news-release/2026/08/19/3347702/0/en/honeybook-mcp-debuts-as-a-claude-connector-for-client-pipelines-invoices-and-contracts.html - Countries served and positioning: https://www.honeybook.com/ - Reviews: https://www.capterra.com/p/162588/HoneyBook/reviews/ --- ## BriefGate vs FileInvite URL: https://briefgate.dev/docs/fileinvite-alternative # BriefGate vs FileInvite: the alternative for agencies and developers ## Introduction FileInvite started as a general document-request tool but has repositioned around commercial and complex lending: its own site claims "500+ complex lenders" and "37,000+ five-star reviews", and the current feature set — PDF form-fill and multi-party signing, a borrower document portal, loan-origination and core-banking integrations, AI-powered email intake matching by loan and customer — is built for CRE, SBA, construction, and equipment-finance lenders processing dozens or hundreds of commercial loans a year. Pricing is annual and enterprise-shaped: $9,900/year for the Standard plan, custom quotes above that. BriefGate is not a lending tool. It is a client-intake service for agencies, freelancers, and AI coding agents: you list what a project needs (files, text, structured answers, credentials), the client gets one branded portal link with no account to create, and the results come back as typed data through the dashboard, a REST API, or an MCP server your agent can call directly. A self-serve free plan exists, and there is no annual contract. If you are choosing a document-collection tool for a web, design, or software project — not a loan file — this page lays out where each tool actually fits. ## Side-by-side comparison | Feature | FileInvite | BriefGate | |---|---|---| | Primary interface | Human dashboard (web UI), built for loan officers and processors | Dashboard, plus MCP tools and REST API for an AI agent | | Define a request | Web UI templates, some with conditional logic by loan amount or property type | `define_intake()` from your agent, or the dashboard | | Client account needed | No — borrowers access a secure portal via link; optional password protection | No — the client opens a magic link | | Item / field types | Files (PDF, Word, Excel, images), PDF form-fill, single and multi-party e-signature | 12 typed items, including structured JSON validated against a schema, colour list, and encrypted secret | | Secrets / credential handling | Not offered as a field type on the pages we checked | Encrypted vault (libsodium, encrypted on the server), one-time reveal | | Automated reminders | Yes — "Smart Notifications" at customizable intervals | Chase engine: preset cadences, custom interval on paid plans, quiet hours, reminder cap | | Webhooks | Not documented on FileInvite's public pages; Zapier triggers/actions exist, described as available on "Pro and Team" plans in the help centre, which is not one of the two plans shown on the current pricing page | Yes (`item.submitted`, `intake.completed`, etc.) | | Public API | "Enterprise-grade API", included only on the custom-quote Enterprise tier | REST API with OpenAPI spec, plus `llms.txt` for AI agent autodiscovery | | MCP server | Not offered | Yes, first-party: `npx @briefgate/mcp` or hosted at `https://mcp.briefgate.dev/mcp` | | Compliance certifications | SOC 2 Type II, MFA, document virus scanning | Not SOC 2 certified; see the security page for the current control set | | Data residency | Hosted on AWS across multiple regions; a specific region is selectable only on Enterprise | Yes, fixed EU (netcup Germany + Cloudflare R2 EU) | | Pricing | $9,900/year (Standard), custom quote (Enterprise) — no free tier, no monthly plan disclosed on the pricing page | Free tier (1 active intake, 10 items); paid from $29/month (Solo) | Facts about FileInvite were checked on 18 September 2026 against FileInvite's pricing, features, security, and integrations pages, its public homepage, and its help-centre Zapier article. We note above where FileInvite's own pages disagree with each other (Zapier plan names vs. current pricing tiers); we did not guess which is current. ## When to choose FileInvite - You are a commercial lender — CRE, SBA, construction, or equipment finance — processing dozens or hundreds of loans a year - You need native integrations with loan-origination systems, core banking platforms, Salesforce, or SharePoint, built and supported by FileInvite's own team - You need built-in PDF form-fill and multi-party e-signature as part of the same product - You need SOC 2 Type II certification, MFA, and document virus scanning out of the box, with an annual contract and dedicated support - You already run FileInvite for loan processing and are expanding within that workflow - An annual, enterprise-priced contract (from $9,900/year) fits your budget better than a monthly SaaS bill FileInvite is a mature, well-reviewed product in its chosen niche. If your document-collection problem is a loan file, not a web or software project, it is worth evaluating on its own terms. ## When to choose BriefGate - Your project is a website, an app, a brand identity, or any deliverable outside lending, and you need files, copy, structured answers, or credentials from a client - Your Claude Code or Cursor agent builds the deliverable and needs assets to keep going — it calls `define_intake` and `get_intake_results` directly, no human handoff or loan officer in the middle - You want a self-serve free plan to try the product, not a $9,900/year minimum commitment - You need credential collection (passwords, API keys) with proper encryption — FileInvite does not list a secret/password field type on its feature pages - You want a webhook-based, agent-loop-safe API with rate limits and `Retry-After`, documented with an OpenAPI spec, not an enterprise-only "custom API" behind a sales conversation - EU data residency matters and you want it guaranteed by default, not as an Enterprise-only option on US-hosted infrastructure The key difference is scope and audience: FileInvite optimized itself for one regulated, high-value vertical with an annual enterprise sales motion. BriefGate stayed general-purpose and self-serve, with the agent — not a loan processor — as the primary caller. ## Migration from FileInvite If you are coming from FileInvite for a non-lending use case, the concepts map like this: | FileInvite | BriefGate | |---|---| | Invite | Intake | | Checklist item / request | Item | | Template | Template | | Borrower portal | Client portal (magic link) | | Smart Notification | Chase engine (automated) | | Approve / reject | Auto-approve window, or a revision request (Solo plan or higher) | | Connected workflow integration | Webhook | FileInvite's PDF form-fill and multi-party e-signature have no BriefGate equivalent — if a signed document is part of what you collect, plan to keep a dedicated e-signature step outside BriefGate. Everything else — files, text answers, and credentials — maps onto BriefGate item types. Define each template once with `POST /v1/templates` and reuse it per client; the REST API has an OpenAPI spec at `GET https://api.briefgate.dev/v1/openapi.json`. ## Sources - Pricing: https://fileinvite.com/pricing/ - Features: https://fileinvite.com/features/ - Homepage and product claims: https://fileinvite.com/ - Security and compliance: https://fileinvite.com/security/ - Integrations: https://fileinvite.com/integrations/ - Zapier integration and plan availability: https://help.fileinvite.com/connect-using-zapier --- ## BriefGate vs Clustdoc for developers URL: https://briefgate.dev/docs/clustdoc-alternative # BriefGate vs Clustdoc: the developer's alternative ## Introduction Clustdoc is client-onboarding software for regulated, process-heavy industries: financial services, legal, real estate, staffing, and accounting firms that need to run the same onboarding checklist across many clients. It bundles a checklist and form builder, sequential e-signatures, identity verification and KYC/KYB, risk scoring, AI-assisted data extraction, a team inbox, and approval workflows into one product, priced per seat with a monthly application cap. It is built around a human operations team running a defined process, with a console for the team and a portal for the client. BriefGate is built for a different primary actor: your coding agent. It calls `define_intake`, BriefGate emails the client a branded portal link and chases them automatically, and once everything is in, the agent calls `get_intake_results` and gets typed data it can use to keep building. No operations team, no seat-based workflow builder, no compliance checklist — you can also run everything by hand from the dashboard, but the product is designed agent-first. If you are evaluating both for a developer- or agent-driven workflow, rather than a regulated onboarding team, this comparison explains where each tool fits. ## Side-by-side comparison | Feature | Clustdoc | BriefGate | |---|---|---| | Primary interface | Team console + client portal, built for an operations team | MCP tools and REST API, plus a dashboard | | Define a request | No-code checklist/form builder, process templates | `define_intake()` from your agent, or the dashboard | | Client account needed | Not confirmed on Clustdoc's public pages — described only as a "branded portal" | No, the client opens a magic link | | Item / field types | Document uploads, digital forms, spreadsheets, online payment, e-signature (sequential), identity verification / KYC-KYB | 12 typed items, including structured JSON validated against a schema, colour list, and encrypted secret | | Secrets / credential handling | Not listed as a field type on their features or security pages | Encrypted vault (libsodium, encrypted on the server), one-time reveal | | Automated reminders | Yes — scheduled email and SMS follow-ups (SMS is limited on the entry plan) | Chase engine: preset cadences, custom interval on paid plans, quiet hours, reminder cap | | Webhooks | Yes — HTTP POST on new submissions, configured under Team → Developers | Yes (`item.submitted`, `intake.completed`, etc.) | | Public API | REST API with sandbox account and code samples (Java, Node, PHP, Go); no published OpenAPI spec found | REST API with OpenAPI spec, plus `llms.txt` for AI agent autodiscovery | | MCP server | Not offered; no AI-agent or MCP connectivity found on their developer pages | Yes, first-party: `npx @briefgate/mcp` or hosted at `https://mcp.briefgate.dev/mcp` | | AI-assisted extraction | Yes — "Clustdoc AI" for data extraction/validation from submitted documents (Pro plan and up) | Not offered | | Data residency | Certified data centres in North America, Europe, and Asia; region choice not detailed for lower tiers | Yes, fixed EU (netcup Germany + Cloudflare R2 EU) | | Pricing | From €190 or $190/month (Pro: 3 seats, 50 applications/month, 25 GB storage); no free tier found | Free tier (1 active intake, 10 items); paid from $29/month (Solo) | Facts about Clustdoc were checked on 18 September 2026 against Clustdoc's pricing, features, security, and developer pages, its homepage, and its help-centre webhooks article. Client account requirements were not confirmed and are marked as such above rather than guessed; see their pricing page for current figures, which we do not otherwise quote beyond what is listed there. ## When to choose Clustdoc - You run onboarding for a regulated industry (financial services, legal, real estate, staffing) and need built-in KYC/KYB and identity verification - Your process has multiple approval steps, several team members, and sequential e-signatures, and you want a workflow/approval engine, not just a checklist - You want SMS reminders in addition to email - You want AI-assisted extraction and validation of data from submitted documents - You need data hosting across multiple regions (North America, Europe, Asia), not EU-only - A per-seat, monthly-application-capped plan (from €190/month) fits your operations budget and team size better than a per-agent, item-based one Clustdoc is a mature onboarding platform for teams running a defined, repeatable, often-regulated client process. If a human operations team owns the workflow and compliance is part of the job, it is a strong choice. ## When to choose BriefGate - Your Claude Code or Cursor agent builds the deliverable and needs assets to continue — it calls `define_intake` and `get_intake_results` directly, without a human operator running the checklist - You want the agent to receive typed JSON through MCP tools, not a submission it has to parse out of a team inbox - You need credential collection (passwords, API keys) with proper encryption — Clustdoc does not list a password/secret field type on its feature pages - You want to start free and pay as the project grows, rather than committing to a €190+/month seat-based plan with no free tier - You want EU data residency guaranteed by default (Germany specifically), not one of three possible regions - You are building agentic software where intake is one automated stage in a larger pipeline, not a standalone onboarding product for an ops team The key difference: in BriefGate, the agent is a first-class actor, not an integration bolted onto a human workflow tool. `define_intake` and `get_intake_results` are designed to be called from code, and the result is typed JSON the agent can use directly. ## Migration from Clustdoc If you are coming from Clustdoc, the conceptual mapping is straightforward: | Clustdoc | BriefGate | |---|---| | Flow / application | Intake | | Checklist item / form field | Item | | Process template | Template | | Client portal | Client portal (magic link) | | Automated follow-up | Chase engine (automated) | | Webhook | Webhook (`item.submitted`, `intake.completed`) | Clustdoc's sequential e-signatures, identity verification/KYC-KYB, risk scoring, and AI data extraction have no BriefGate equivalent — if your process needs those, plan to keep them as a separate step. Document uploads, form fields, and payment-adjacent text fields map onto BriefGate item types, including the encrypted `secret` type Clustdoc does not have. Define each template once with `POST /v1/templates` and your agent reuses it for every new client. The REST API has an OpenAPI spec at `GET https://api.briefgate.dev/v1/openapi.json`. ## Sources - Pricing: https://clustdoc.com/pricing/ - Features: https://clustdoc.com/features/ - Homepage and product claims: https://clustdoc.com/ - Security and compliance: https://clustdoc.com/security/ - Developer platform (API, sandbox, webhooks, Zapier): https://clustdoc.com/developers/ - Webhooks documentation: https://support.clustdoc.com/en/articles/10048684-how-to-use-webhooks --- ## BriefGate vs Dropbox file requests URL: https://briefgate.dev/docs/dropbox-file-requests-alternative # BriefGate vs Dropbox file requests: a folder link is not a checklist ## Introduction Dropbox file requests are the simplest way to let someone drop files into your Dropbox: you create a request, send the link, and anyone can upload without an account. The files land in a folder you chose, you get an e-mail for every upload, and on paid plans you can set a deadline and, on some of them, put your logo on the page. For "send me the photos from Saturday" it is hard to beat. Projects rarely need just "the files". They need the logo in SVG, the copy for three pages, the brand colours, a yes or no on the hero layout, and the hosting password, and they need all of it, from a client who answers one thing a week. BriefGate treats that as a checklist with a chase engine: your coding agent or you define the items with `define_intake`, the client gets a branded portal that shows what is still missing, BriefGate reminds them on a schedule until everything is in, and `get_intake_results` returns typed data the agent can build with. This page is for people who use Dropbox file requests for client work and keep chasing clients by hand. ## Side-by-side comparison | Feature | Dropbox file requests | BriefGate | |---|---|---| | What it collects | Files only | 12 typed items: files, images, text, URLs, choices, booleans, colour lists, structured JSON, encrypted secrets | | Required items and progress | No per-item state; a request is open or closed | Each item is pending, submitted, needs revision, approved, or waived; the portal shows progress | | Automatic reminders | None found; one invite, then a deadline with optional late uploads on paid plans | Chase engine per intake: preset cadences, a custom interval on paid plans, quiet hours, reminder cap, e-mail, per-recipient bounce handling | | Asking for a re-upload | No re-upload or revision flow documented; you contact the uploader yourself | `request_revision` with a note on Solo, Studio, and Agency; the client sees what to fix | | Credential collection | No; only a password on the request itself | Encrypted secrets vault with one-time reveal (Solo, Studio, and Agency) | | Uploader needs an account | No | No | | File size | 2 GB per file on Basic, Plus, Family; 250 GB on Professional and team plans | Per-plan storage; uploads go straight to object storage | | Branding | Logo and colours on Professional and Essentials, and for admins on some team tiers; Dropbox states it is not available for file requests on Standard and Business accounts | Your logo and accent colour on Solo, Studio, and Agency; custom portal domain on Studio and Agency | | Notifications | E-mail on send and on every upload | Webhooks for `item.submitted`, `intake.completed`, `client.viewed`, `chase.bounced`, and more | | API | Dropbox HTTP API `file_requests` endpoints | REST API with OpenAPI spec, `llms.txt` | | MCP server | Official remote Dropbox MCP server (beta) with tools to create, read, and list file requests; no per-item checklist or reminders on top | Yes, `npx @briefgate/mcp` | | Pricing | Part of Dropbox: Basic free with 2 GB; team plans from about 12 EUR per user per month | Free plan; Solo 29 USD; Studio 50 USD; Agency 79 USD per month | Facts about Dropbox were checked on 3 September 2026 against Dropbox's help centre, plan pages, and developer documentation; the MCP server and re-upload rows were rechecked on 14 September 2026. Links are at the end of this page. ## When to choose Dropbox file requests - You need files and nothing else, from people who already know what to send - Your team lives in Dropbox and wants the uploads in a specific shared folder with no extra tool - The uploads are big: raw photo sets or video, where the 250 GB per-file limit on paid plans matters - You already have a Dropbox plan and do not want another subscription ## When to choose BriefGate - The client owes a mix of files, text, decisions, and credentials, and you need to see what is still missing - Nobody has time to chase clients by hand; reminders have to go out on a schedule over e-mail - Your coding agent needs the results as typed data, not a folder to open and interpret - You need to send something back for a fix without deleting it - You need EU data residency and a portal in your own branding - You want your agent to get typed assets back (text, choices, credentials, files) through MCP or an API, not just files in a folder; Dropbox's MCP server can open a file request, but a file request only collects files ## Using both If your team keeps deliverables in Dropbox, let BriefGate collect and Dropbox store: 1. Define the intake with `define_intake`, including the files and every non-file item the project needs. 2. On `intake.completed`, have your agent call `get_intake_results` and copy the files into the project's Dropbox folder with the Dropbox API. 3. Set BriefGate's retention to `on_delivery` so the copies on BriefGate's side are removed shortly after your agent collects them. The client fills in one portal; your files still end up where your team looks for them. ## Sources - Creating a file request, deadlines, size limits, notifications: https://help.dropbox.com/share/create-file-request - Uploading to a file request without an account: https://help.dropbox.com/share/received-file-request - Branding availability, including the Standard and Business exception: https://help.dropbox.com/share/branded-sharing - Team plan prices: https://www.dropbox.com/business/plans-comparison - Personal plan prices: https://www.dropbox.com/plans - File request API: https://dropbox.tech/developers/streamline-file-collection-with-the-file-request-api and https://dropbox-sdk-python.readthedocs.io/en/latest/api/file_requests.html - Dropbox MCP server, including file request tools: https://help.dropbox.com/integrations/connect-dropbox-mcp-server --- ## BriefGate vs Google Forms for client files URL: https://briefgate.dev/docs/google-forms-alternative-for-client-files # BriefGate vs Google Forms for collecting client files Google Forms, Typeform, and Jotform are general-purpose form builders, not asset-collection tools — the gap shows up around files, passwords, and following up. ## What these tools are for Google Forms, Typeform, and Jotform build questionnaires: surveys, RSVPs, lead capture, order forms. Each does that well, and each has a free tier a lot of small businesses reach for when a designer or developer says "just send me a link." The trouble starts when the questionnaire needs to carry a logo, a hosting password, and photos larger than a phone comfortably attaches to an email — none of these products were built around that job. ## Where files break **Google Forms** lets the form owner set a per-file cap from 1 MB up to 10 GB, but every respondent must sign in with a Google account before uploading or submitting at all — a client without one, or unwilling to sign into one to send a logo, is stuck before they start. Files land in the owner's Google Drive and count against that Drive's own storage quota. **Typeform** caps every File Upload question at 10 MB, on every plan, with no way to raise it. A print-ready PDF or a short clip routinely exceeds that; Typeform's help center suggests routing around it by asking respondents to paste a Dropbox or Drive link into a Website question instead, which reintroduces the sign-in problem above. **Jotform** allows individual files up to 1 GB, but its free Starter plan caps total account storage at 100 MB across every form combined. Once uploads push the account over that upload storage limit, every form in the account is disabled until space is freed or the plan is upgraded — one client's photo set can quietly block the next client's uploads, on any form. ## Where passwords break None of the three has a field type built for a credential. A hosting login typed into a short-answer question is stored exactly like every other answer: in plaintext, in the response spreadsheet or dashboard, indefinitely, with no expiry and no one-time reveal. Anyone with view access to that sheet — a collaborator added months later, a shared-drive audit, a compromised account — can read it. It is the same failure mode as pasting a password into an email thread, just moved into a spreadsheet cell. ## Where following up breaks **Google Forms** has no reminder feature at all. **Typeform** sends a follow-up message after a response is submitted, but has no native way to nudge someone who hasn't submitted yet — its own community forum points users toward a CRM or a Zapier workflow for that. **Jotform**'s Reminder Emails come closer but aren't completion-aware: they go to a fixed recipient list on a schedule, and, by Jotform's own support answer, the feature does not check whether a given recipient has actually filled in the form — you remove someone from the list by hand once they've responded. ## Where agent access breaks Jotform and Typeform now ship official MCP servers, and all three expose REST APIs. Through them an agent can build a form or read responses, which is a different job from a coding agent declaring "I need this logo, these photos, and this login for this project" and getting typed results back when the client finishes. Sending the form to the client, reminding them about missing answers, and turning responses into project assets is still up to you with all three. ## Side-by-side | | Google Forms | Typeform | Jotform | BriefGate | |---|---|---|---|---| | Max file size | 1 MB–10 GB (owner-set) | 10 MB, fixed | 1 GB, but 100 MB total on free plan | Per-plan storage; large files go straight to object storage | | Respondent sign-in for uploads | Requires Google sign-in | Not required | Not required | Not required — one link, no account | | Credential field | None (plaintext in spreadsheet) | None | None | `secret` item: encrypted, revealed once | | Reminds incomplete respondents | No | No (post-submit only) | Static list, not completion-aware | Chase engine per intake, completion-aware | | MCP server | No official server for Forms; community servers exist | Official: create forms, read submissions | Official: build and edit forms, analyze responses, contacts, automations | Yes, `npx @briefgate/mcp` | | Price | Free | Free tier, paid from there | Free tier, paid from there | Free plan; Solo 29 USD/month | ## When Google Forms, Typeform, or Jotform are the right call - A short survey or an event RSVP with no files and no sensitive data - Every respondent already has a Google account and files stay well under the caps above - You want the widest possible integration ecosystem (Zapier, Sheets, CRMs) and asset collection is not the point of the form - You need a form live in five minutes and don't need anything to follow up automatically These are real strengths. A five-question survey does not need a chase engine or a secrets vault, and building one for that job would be over-engineering the request. ## Where BriefGate fits BriefGate is built around the specific job these tools weren't: an AI coding agent, or a person from the dashboard, calls `define_intake` with the files, text, and credentials a project needs, each declared with real constraints — minimum image width, allowed formats, a JSON Schema for structured facts like opening hours. The client gets one branded portal link, no account required, and can upload from a phone camera roll without ever signing into anything BriefGate runs. Credentials use the [secrets vault](secrets.md): sent over HTTPS and sealed on the server before they are ever stored, revealed once to the person who asked. The [chase engine](chase.md) tracks exactly which items are still missing per client and reminds only about those, on a schedule, until the intake completes or you tell it to stop. When it does complete, `get_intake_results` hands the agent typed data — a signed URL and checksum for a file, a validated object for structured data — instead of a spreadsheet row and a folder of downloads to sort out by hand. If a project already collects everything else — leads, contracts, payments — in a suite built around forms, there's no need to replace it: point that suite's completion step at `POST /v1/intakes` and let BriefGate own just the files and credentials, the same pattern covered in the [Dubsado comparison](dubsado-alternative.md) for a whole-business suite that isn't built for this step either. ## Sources - Google Forms file size options and the Google sign-in requirement to upload: https://support.google.com/docs/thread/52270064/maximum-size-of-file-uploaded-in-google-forms - Typeform File Upload question, 10 MB limit on all plans, not changeable: https://help.typeform.com/hc/en-us/articles/360051567012-File-Upload-question - Typeform has no native incomplete-response reminder: https://community.typeform.com/integrate-your-typeform-43/automated-email-reminder-to-responders-who-haven-t-completed-a-form-6240 - Jotform file upload size (1 GB) and free-plan 100 MB total storage cap: https://www.jotform.com/help/33-changing-the-file-upload-size-limit/ - Jotform Reminder Emails: does not check completion, static recipient list: https://www.jotform.com/answers/236288-can-jotform-send-automatic-reminder-emails-to-specific-people-who-have-not-completed-the-form-yet - Jotform account usage limits, upload storage over quota disables all forms: https://www.jotform.com/help/408-understanding-your-account-usage-and-limits/ - Typeform Create API: https://www.typeform.com/developers/create/ - Jotform MCP server: https://www.jotform.com/developers/mcp/ - Typeform MCP server: https://www.typeform.com/developers/mcp/ - Google Workspace MCP servers: https://developers.google.com/workspace/guides/configure-mcp-servers --- ## BriefGate vs Typeform URL: https://briefgate.dev/docs/typeform-alternative # BriefGate vs Typeform: a form builder is not a client checklist ## Introduction Typeform is a conversational form builder: one question at a time, animated transitions, a design system good enough that people forward the link unprompted. It is built for surveys, lead capture, NPS, and quizzes — questions with a known, bounded shape, answered in one sitting by someone with no reason to stop halfway. Client asset collection for a web, brand, or app project is a different shape of problem. The client doesn't have the logo, the copy, and the hosting password ready in one sitting — they have some of it now and the rest next week, if you chase them. BriefGate is built around that: your coding agent or you define the items with `define_intake`, the client gets a portal that shows what's still missing, a chase engine reminds them on a schedule, and `get_intake_results` returns typed data your agent can use directly. If you're deciding between the two for collecting project materials from clients, here's where each one actually fits. ## Side-by-side comparison | Feature | Typeform | BriefGate | |---|---|---| | Built for | Conversational surveys, lead gen, quizzes, NPS | Client asset collection: files, text, decisions, credentials | | File Upload question | Fixed 10 MB limit, every plan, no way to raise it | Per-plan storage; large files upload straight to object storage | | Respondent account required | No | No — one magic link, no account | | Credential / password field | No field type for this; a password typed into a question sits in plaintext in the response dashboard | Encrypted secrets vault (libsodium), one-time reveal | | Reminders for incomplete responses | None — Typeform sends a follow-up *after* submission, but has no native way to nudge someone who hasn't submitted yet | Chase engine per intake: preset cadences, custom interval on paid plans, quiet hours, reminder cap | | Ask for a re-upload / fix | No revision flow found | `request_revision` with a note; client sees exactly what to fix | | Item-level progress | A typeform is answered or not; no per-question completion state | Each item is pending, submitted, needs revision, approved, or waived | | Webhooks | Yes, on response submission | Yes — `item.submitted`, `intake.completed`, `client.viewed`, `chase.bounced`, `intake.stalled`, `intake.overdue` | | MCP server | Official, OAuth-only: tools for forms, automations, contacts, and insights | Yes, first-party: `npx @briefgate/mcp` or hosted at `https://mcp.briefgate.dev/mcp` | | API | Create API (REST) | REST API with an OpenAPI spec, plus `llms.txt` for agent autodiscovery | | EU data residency | Not offered on Free through Business; hosted on AWS in the US per Typeform's own subprocessor list. Available only on custom Enterprise plans | Yes (netcup Germany + Cloudflare R2 EU) | | Pricing | Free plan, then Basic from $25/mo (billed annually) for 100 responses/month, Plus from $50/mo for 1,000, Business from $83/mo for 10,000 | Free plan; Solo $29; Studio $50; Agency $79 per month | Facts about Typeform were checked on 16 September 2026 against Typeform's own pricing page, help center, and community forum. Prices shown are Typeform's discounted annual-billing rates; monthly billing costs more per month at every paid tier. Links are at the end of this page. ## Where the 10 MB limit actually bites Typeform's File Upload question caps every upload at 10 MB, on every plan, with no setting to raise it. A print-ready logo file, a short walkthrough clip, or a batch of product photos routinely exceeds that. Typeform's own help center suggests working around it by asking respondents to paste a Dropbox or Google Drive link into a Website question instead — which reintroduces exactly the "now they need an account somewhere else" friction a client portal is supposed to remove. ## Where reminders actually stop Typeform can send a message *after* someone finishes a form — a thank-you, a follow-up sequence. What it doesn't do, by Typeform's own community forum, is notice that someone opened the form, answered three of ten questions, and never came back — and nudge them. For a one-sitting survey that's rarely a problem. For "send me the logo, the copy, and the WordPress login," it's the difference between a project that starts on schedule and one that stalls on an unread email. ## When to choose Typeform - You're building a survey, a lead-gen form, an NPS survey, or a quiz — bounded questions, answered in one sitting - You want the most polished, animated form-filling experience for marketing or research - You need embedded payment collection, logic branching across dozens of question types, or Typeform's design themes - Files, if any, are small and incidental to the form, not the point of it - You don't need reminders, because the person filling it out has no reason to leave and come back ## When to choose BriefGate - The client owes a mix of files, text, decisions, and credentials, delivered over days or weeks, not one sitting - Files are the point — logos, brand photography, video, PDFs — and 10 MB is not enough - You need a hosting login or API key collected somewhere safer than a plaintext response row - Nobody has time to manually check who hasn't responded and nudge them - Your coding agent needs `get_intake_results` to return typed, structured data it can act on directly — not a response export to parse ## Sources - Typeform File Upload question, 10 MB limit on all plans, not changeable: https://help.typeform.com/hc/en-us/articles/360051567012-File-Upload-question - Typeform has no native incomplete-response reminder: https://community.typeform.com/integrate-your-typeform-43/automated-email-reminder-to-responders-who-haven-t-completed-a-form-6240 - Typeform pricing, plans, and monthly response caps: https://www.typeform.com/pricing/ - Typeform Create API: https://www.typeform.com/developers/create/ - Typeform MCP server, OAuth-only, tool list: https://www.typeform.com/developers/mcp/ - Typeform hosting on AWS (US) and data-residency terms: https://www.typeform.com/dpa/ and https://trust.typeform.com/subprocessors --- ## BriefGate vs Jotform URL: https://briefgate.dev/docs/jotform-alternative # BriefGate vs Jotform: a general-purpose form builder vs a client checklist ## Introduction Jotform is a broad form-and-workflow platform: a drag-and-drop builder with a large field-type catalogue, e-signature and multistep approval workflows through Jotform Sign and Jotform Workflows, and an app store of templates for nearly anything you'd put a form in front of. It's a genuine Swiss-army knife, and for teams that already run approvals or intake forms through it, that breadth is the appeal. BriefGate does one thing: collect the specific set of assets a project needs from a client, and keep after them until it's all in. Your coding agent (or you, from the dashboard) calls `define_intake`, the client gets a branded portal showing exactly what's outstanding, a chase engine reminds them automatically, and `get_intake_results` hands back typed JSON your agent can use immediately. If you're weighing the two for collecting project materials from clients, here's where they actually differ. ## Side-by-side comparison | Feature | Jotform | BriefGate | |---|---|---| | Built for | General-purpose forms, surveys, approvals, e-signature workflows | Client asset collection: files, text, decisions, credentials | | File upload size | Up to 1 GB per file | Per-plan storage; large files upload straight to object storage | | Total upload storage, free plan | 100 MB across every form in the account — once exceeded, **every form is disabled** until space frees up or you upgrade | 1 GB across every intake in the account (also one shared pool) — once exceeded, only the upload that would push you over is rejected with an upgrade prompt; other intakes and already-submitted files stay untouched | | Respondent account required | No | No — one magic link, no account | | Credential / password field | No field type for this; a password typed into a text field sits in plaintext in the response sheet | Encrypted secrets vault (libsodium), one-time reveal | | Reminders | "Reminder Emails" go to a fixed recipient list on a schedule — by Jotform's own support answer, the feature does **not** check whether a given recipient has actually responded; you remove them from the list by hand | Chase engine per intake: preset cadences, custom interval on paid plans, quiet hours, reminder cap, automatic once the item is submitted | | Approval / e-signature | Yes — Jotform Workflows has an Approval element (approve/deny, multistep, parallel) and an Approve & Sign element via Jotform Sign | `request_revision` for sending an item back with a note; approve or waive items in the dashboard. No e-signature field | | Item-level progress | A submission is complete or not; no per-field state across a multi-part checklist | Each item is pending, submitted, needs revision, approved, or waived | | Webhooks | Yes | Yes — `item.submitted`, `intake.completed`, `client.viewed`, `chase.bounced`, `intake.stalled`, `intake.overdue` | | MCP server | Official, OAuth-only: `form_list`, `create_form`, `edit_form`, `create_submission`, `get_submissions` | Yes, first-party: `npx @briefgate/mcp` or hosted at `https://mcp.briefgate.dev/mcp` | | API | REST API | REST API with an OpenAPI spec, plus `llms.txt` for agent autodiscovery | | EU data residency | Yes — Europe (Frankfurt) datacenter, automatic for accounts created in the EU, opt-in for others via account settings | Yes (netcup Germany + Cloudflare R2 EU) | | Pricing | Starter (free): 100 submissions/month, 100 MB total upload storage. Bronze $34/mo (annual): 1,000 submissions, 1 GB. Silver $39/mo: 2,500 submissions, 10 GB. Gold $99/mo: 10,000 submissions, 100 GB | Free plan; Solo $29; Studio $50; Agency $79 per month | Facts about Jotform were checked on 16 September 2026 against Jotform's own pricing page, help center, and support answers. Prices shown are Jotform's discounted annual-billing rates. Links are at the end of this page. ## Where the shared storage cap actually bites Jotform's free Starter plan caps *total* upload storage at 100 MB across every form in the account, not per form. One client's photo set or a couple of PDF contracts can fill that quota — and once it's full, Jotform disables every form on the account, including ones for other, unrelated clients, until you free space or upgrade. It's a shared-quota failure mode that doesn't show up until the first real project pushes past it. BriefGate's storage is also one pool per account (1 GB on the free plan), not per-intake — but hitting the cap only rejects the specific upload that would exceed it; existing intakes, submitted files, and every other client's project keep working. ## Where the reminder feature falls short Jotform's Reminder Emails are a real feature, unlike Typeform or Google Forms — but by Jotform's own support answer, they aren't completion-aware. They go out to a fixed list on a schedule regardless of who has already responded, and it's on you to notice someone finished and remove them from the list. BriefGate's chase engine is scoped to the intake itself: a client who has submitted everything stops receiving reminders automatically, because the reminder checks outstanding items, not a static recipient list. ## When to choose Jotform - You need e-signatures or a multistep approval workflow (approve/deny, parallel approvers) — Jotform has this natively; BriefGate doesn't - Your use case is broader than client intake: internal request forms, surveys, order forms, appointment booking - You want a huge library of pre-built templates and a wide field-type catalogue in one platform - You're already standardized on Jotform for other workflows and want one more form type inside it ## When to choose BriefGate - The client owes a mix of files, text, decisions, and credentials, delivered over days or weeks — not a single form submission - Files are large or numerous enough that a shared 100 MB free-tier quota is a real risk - You need reminders that actually stop once the client is done, without you maintaining a recipient list - You need a hosting login or API key collected somewhere safer than a plaintext response row - Your coding agent needs `get_intake_results` to return typed, structured data it can act on directly ## Sources - Jotform file upload size (1 GB) and free-plan 100 MB total storage cap: https://www.jotform.com/help/33-changing-the-file-upload-size-limit/ - Jotform account usage limits, upload storage over quota disables all forms: https://www.jotform.com/help/408-understanding-your-account-usage-and-limits/ - Jotform Reminder Emails: does not check completion, static recipient list: https://www.jotform.com/answers/236288-can-jotform-send-automatic-reminder-emails-to-specific-people-who-have-not-completed-the-form-yet - Jotform pricing and plan limits: https://www.jotform.com/pricing/ - Jotform Approvals and Approve & Sign workflow: https://www.jotform.com/products/approvals/ - Jotform MCP server and its tool list: https://www.jotform.com/developers/mcp/ - Jotform EU (Frankfurt) datacenter, automatic for EU-created accounts: https://www.jotform.com/help/871-how-to-store-your-data-on-eu-servers/ --- ## BriefGate vs email + Drive/Dropbox URL: https://briefgate.dev/docs/email-and-drive-alternative # BriefGate vs collecting client files by email and a shared folder ## Introduction Most agencies don't start with a client-intake tool. They start with an email — "here's a link to a Google Drive/Dropbox folder, please drop your logo, photos, and copy in there" — and a mental note to follow up if nothing shows up by Friday. No subscription, no new login for the client, nothing to set up. For a one-off ask, it works. The failure mode shows up on the second or third project, or the first client who isn't already comfortable with folders and permissions: files land in the wrong format, the password gets typed into the email body in plaintext, half the list never arrives, and "following up" becomes a recurring line item on your own to-do list instead of something that happens on its own. BriefGate replaces the folder-plus-email combination with a checklist your agent (or you) defines once, a portal the client can't get lost in, and reminders that go out without you writing them. This page is for anyone still running client intake this way and deciding whether a dedicated tool is worth adding. ## Side-by-side comparison | | Email + Google Drive/Dropbox | BriefGate | |---|---|---| | Setup cost | None — a folder and an email | Define items once with `define_intake`; reusable as a template after | | What it collects | Whatever the client puts in the folder, in whatever format | 12 typed items: files, images, text, URLs, choices, booleans, colour lists, structured JSON, encrypted secrets | | Client needs an account | To upload into a Drive folder as Editor, yes — a Google account signed in; Dropbox's own file-request links avoid this (see our [Dropbox comparison](/docs/dropbox-file-requests-alternative)) | No — one magic link, no account | | Attachment size, if emailed directly | Gmail caps a message at 25 MB total, then silently drops the attachment and inserts a Drive link instead | Per-plan storage; large files upload straight to object storage | | Knowing what's still missing | You open the folder and compare against your own mental list, or a spreadsheet you maintain by hand | Portal and dashboard show each item's status: pending, submitted, needs revision, approved, waived | | Reminders | You write and send them yourself, when you remember to | Chase engine per intake: preset cadences, custom interval on paid plans, quiet hours, reminder cap | | Notification when a client uploads | None by default — Drive's own upload notifications are opt-in and go to the folder owner, not a per-item checklist | Webhooks: `item.submitted`, `intake.completed`, `client.viewed`, `chase.bounced` | | Credential handling | Typed into the email body or a shared doc, in plaintext, indefinitely | Encrypted secrets vault (libsodium), one-time reveal | | Asking for a fix | A reply-all email thread | `request_revision` with a note; the client sees exactly what to redo | | Agent access | None — an agent would have to read your inbox and guess | `get_intake_results` returns typed JSON an agent can use directly; MCP server (`npx @briefgate/mcp`) or REST API | | Cost | Free, if you already pay for Drive or Dropbox for other reasons | Free plan; Solo $29; Studio $50; Agency $79 per month | Facts about Gmail and Google Drive were checked on 16 September 2026 against Google's own support pages. Links are at the end of this page. ## Where the folder-and-email approach actually breaks **Uploading requires an account.** Letting someone add files to a Drive folder you own requires Editor access and, per Google's own documentation, that they're signed into a Google account — a client without one, or who doesn't want to create one to send you a logo, is stuck before they start. A plain "anyone with the link" share is view-only; it doesn't grant upload rights. **Attachments have a hard ceiling.** Gmail caps a message at 25 MB total attachments; past that, Gmail strips the attachment and inserts a Drive link automatically — which routes you straight back into the account-and-permissions problem above. **Nothing reminds anyone.** Drive can notify you, the owner, when a file is added — an opt-in setting, not a default — but there is no first-party feature that reminds the *client* they haven't uploaded yet. That job stays on you, by hand, for every open item on every project. **Passwords end up in plaintext.** A hosting login typed into an email or a shared doc sits there unencrypted, readable by anyone with access to that thread or drive, indefinitely, with no expiry. ## When email + Drive/Dropbox is fine - A one-off ask from a client you already work with regularly, who knows exactly what to send - Files only, no credentials, no structured decisions to capture - You don't mind manually tracking who has and hasn't sent their part - You already pay for Drive or Dropbox and don't want another subscription for occasional use ## When to switch to BriefGate - You run more than the occasional project and are tired of writing the same follow-up email every week - Clients need a checklist, not a folder — so they know exactly what's still missing without asking you - You need to collect a password or API key somewhere safer than an email thread - Your coding agent needs the results as typed data it can act on, not files it has to guess the meaning of - You want reminders to happen automatically, on a schedule, without you remembering to send them ## Sources - Gmail attachment size limit (25 MB) and automatic fallback to a Drive link: https://support.google.com/mail/answer/6584 - Google Drive folder sharing, Editor role requires a signed-in Google account to add files: https://support.google.com/drive/answer/7166529 - Google Drive upload notifications are opt-in and notify the owner, not the uploader's counterpart: https://support.google.com/drive/answer/6318501 --- ## Client Intake for Claude Code URL: https://briefgate.dev/docs/claude-code-client-intake # Client Intake for Claude Code: Collect Assets Without Leaving Your Agent ## The problem Claude Code can build a complete website in an afternoon. Then it hits a wall: the client has not sent the logo, hero text, or their WordPress admin credentials. The agent waits. You wait. You send a follow-up email. Two weeks pass. The client sends a blurry JPG that is 200px wide. This is the bottleneck: not the building, but the gathering. Developers lose more time chasing assets than writing code. ## The solution BriefGate MCP. Claude Code calls `define_intake()` with a list of what it needs. BriefGate emails the client a branded portal link. The client uploads files, fills in text, and submits credentials — all in a clean web interface designed for non-technical people. BriefGate chases them automatically on the schedule you set. When everything is in, Claude Code calls `get_intake_results()` and picks up exactly where it left off — typed data, signed file URLs, structured objects, one-time credential values — ready to use without any parsing or transformation. ## Setup Two commands: ```bash npm install -g @briefgate/mcp claude mcp add briefgate -- briefgate-mcp --api-key bg_live_xxxxx ``` Get your API key at https://app.briefgate.dev/app. The MCP server connects Claude Code to BriefGate's API. After setup, tools like `define_intake`, `get_intake_results`, `get_intake_status`, `request_revision`, and `send_chase` are available to Claude Code in every session. Prefer not to paste a key? `claude mcp add briefgate -- npx -y @briefgate/mcp` followed by `npx -y @briefgate/mcp login` signs you in through the dashboard instead, or connect the hosted endpoint directly with `claude mcp add --transport http briefgate https://mcp.briefgate.dev/mcp` (then `/mcp` → briefgate → Authenticate inside Claude Code) for OAuth sign-in. See [Quickstart](./quickstart.md). ## Adding to CLAUDE.md Put this snippet in your project's `CLAUDE.md` so the agent knows when and how to use BriefGate: ``` ## Client asset collection Use the briefgate MCP tools when you need assets from the client: 1. Call define_intake with items[] listing what you need 2. The client will be emailed a portal link automatically 3. Check status with get_intake_status or wait for the intake.completed webhook 4. Call get_intake_results to retrieve typed data and file URLs 5. For credentials (passwords, API keys), use type: "secret" — they are encrypted Never ask the client directly for assets in conversation — use define_intake so everything is tracked and chased automatically. ``` ## A complete session example Here is what a Claude Code session looks like with BriefGate in place: **Agent:** "I have the site architecture ready. To continue building, I need the client's logo, hero copy, and Google Analytics ID. Let me create a BriefGate intake now." Agent calls `define_intake`: ```json { "project_name": "Bella Cucina Restaurant Website", "client": { "email": "marco@bellacucina.cz", "name": "Marco", "language": "en" }, "items": [ {"key": "logo", "type": "image", "label": "Restaurant logo", "constraints": {"min_width": 512}}, {"key": "hero_copy", "type": "longtext", "label": "Homepage headline and intro text"}, {"key": "ga4_id", "type": "text", "label": "Google Analytics 4 Measurement ID", "required": false, "pattern": "^G-[A-Z0-9]+$"} ], "chase_schedule": "default", "branding": {"sender_name": "Radim"} } ``` (`branding.sender_name` is [custom branding](./billing.md#custom-branding) — Solo plan and up. On Free it's accepted and stored but the client sees the built-in sender identity instead.) **Agent:** "Intake created. Marco will receive an email at marco@bellacucina.cz with a portal link. I will continue building the static structure and placeholder components. I will check back when assets arrive." *[Agent continues building. Chase engine sends a reminder at T+2d. Marco submits the logo and copy at T+3d. The `intake.completed` webhook fires.]* Agent calls `get_intake_results`: ```json { "status": "completed", "items": [ { "key": "logo", "type": "image", "status": "submitted", "value": { "url": "https://r2.briefgate.dev/signed/...", "filename": "bellacucina-logo.svg", "width": 1024, "height": 512, "mime_type": "image/svg+xml" } }, { "key": "hero_copy", "type": "longtext", "status": "submitted", "value": "Authentic Italian cuisine in the heart of Prague..." }, { "key": "ga4_id", "type": "text", "status": "skipped" } ] } ``` **Agent:** "Logo received — SVG, 1024x512. Hero copy in. GA4 ID skipped (optional). Continuing with implementation: placing logo in header, populating hero section with copy, skipping analytics snippet." ## Checking status without blocking Besides waiting for a webhook, Claude Code can check progress at any point by calling `get_intake_status`: ```json { "status": "in_progress", "progress": {"total": 3, "submitted": 2, "outstanding": 1}, "items": [ {"key": "logo", "status": "approved"}, {"key": "hero_copy", "status": "submitted"}, {"key": "ga4_id", "status": "pending"} ] } ``` A `due_date` on `define_intake` shows the client a deadline in the portal and the invite email. `chase_schedule: "default"` reminds them at T+2d, T+5d, T+9d, then weekly, until the intake completes or you turn the schedule off — the agent is never the one sending the follow-up, so it can keep building other parts of the project in the meantime instead of waiting idle. ## Handling secrets Credentials — WordPress admin, a Stripe secret key, a Google Analytics service account — need special handling. Use `type: "secret"` (Solo plan or higher; a Free-plan intake rejects the item with `plan_required`). ```json { "key": "wp_admin", "type": "secret", "label": "Current WordPress admin credentials", "help": "Username and password for wp-admin. Encrypted before storage, shown to your developer once." } ``` The client's input travels over HTTPS and is sealed on BriefGate's server with a libsodium sealed box before anything is written to the database. Only the ciphertext is stored; the plaintext is held in memory just long enough to seal it and, later, to reveal it once. When the agent calls `get_intake_results`, the secret item's entry in `results` carries the decrypted plaintext directly — but only the first time anyone reveals it: ```json { "wp_admin": { "value": "admin:MyPassword123", "one_time": true, "first_reveal": true, "expires_at": "2026-08-15T10:00:00Z" } } ``` That `value` is gone the moment it has been read: call `get_intake_results` again and the item drops out of `results` entirely, with `meta` marking it `secret_unavailable` because it was already revealed. The agent should move the value into a secrets manager before doing anything else with the response — it is never available again through the API. If nobody collects it within 30 days it expires the same way; ask the client to resubmit with `request_revision`. ## Requesting revisions When the agent reviews uploaded assets and finds quality issues, it can flag the item and ask the client to resubmit: ``` request_revision( intake_id: "int_01J3K...", item_key: "logo", note: "The uploaded logo is 200px wide. We need at least 512px for retina screens. If you have an SVG version, that would be ideal — SVG scales to any size without quality loss." ) ``` The client receives an email, sees the note on the flagged item in their portal, re-uploads, and submits. The `item.submitted` webhook fires again. The agent calls `get_intake_results` and finds the updated file. This keeps the revision loop within BriefGate — no separate email thread, no risk of the original submission being overwritten without a record. ## Tips **Draft before sending.** Pass `send: false` to `define_intake` to create the intake without emailing the client yet. Review the items, then release it with `POST /v1/intakes/:id/send` when you're ready — there's no MCP tool for sending a draft later, so that step goes over REST. **Process incrementally.** Set `only_new: true` on `get_intake_results` to retrieve only the items approved since your last call. Useful in a webhook handler that should act on new submissions without re-processing the whole intake each time. **Know when items auto-approve.** A submitted item auto-approves after `auto_approve_hours` (default 72) unless you review it first. Set it to `0` on `define_intake` if you want every item to wait for an explicit approval before it counts as done. **Reveal secrets once, immediately.** As covered above, a `secret` item's plaintext comes back exactly once through `get_intake_results` — store it in your secrets manager in the same turn, not in a later session.