# ideare > Where brands are born. ideare makes the brand kit of a small business from one file, brand.json: the logo in every version, colors and fonts, site icons, share cards, every social size, an email signature, a business card and guidelines in plain words. A brand has a private draft and public approved versions. Approved files live at `https://cdn.ideare.app/b//v/` (`latest/` follows the current version), and each brand has a public page at `https://ideare.app/b/`. Reading them needs no key. Everything else needs one. ## If you are an AI agent - Connect over MCP at https://api.ideare.app/mcp (Streamable HTTP). Sign in with OAuth, or send the key your person gave you as `Authorization: Bearer ideare_...`. Never guess a key, and never ask for one in the chat. - Start with `list_brands` for the slugs in the workspace, then `get_brand`. - `generate_symbols` and `generate_art` spend the workspace's credits. Say what a call costs before you make it, and never repeat it while its run is still going: follow it with `get_run`. - You can't publish on your own. From an AI app, `approve_draft` usually answers `proposed`: the owner approves it in one tap in the studio, at https://studio.ideare.app. Tell your person so, and don't call it again. - On the free plan, every key only reads. ## Put a brand in a codebase - `npx ideare init ` in the project's folder writes the brand's icons, share card, colors and fonts, and keeps them in step with `npx ideare pull`. It needs Node 20.3 or newer and no account. - `npm install @ideare/sdk` is the TypeScript client for the REST API. ## Connect ideare to an AI app Claude, ChatGPT, Cursor and other AI apps can read your brands, save changes to the draft, check them and make posts. Nothing goes public until an owner approves it. The guide: https://ideare.app/en/docs/mcp ### The address AI apps connect to ideare through MCP, a standard way for an AI app to use another service. Every app below uses this one address: ```text https://api.ideare.app/mcp ``` ### What you need - An ideare account, in the workspace whose brands the app will use. - In Claude and ChatGPT you sign in with your ideare account, so there's no key to copy. - Claude Code and Cursor take an API key instead. Make one in the studio, under API keys. It starts with `ideare_` and shows only once, so copy it right away. Only owners and admins can make keys. - On the free plan every key only reads: the app sees your brands but can't change them. Free holds 1 key, and each app you connect uses one. Pro holds 5, and they can send changes too. **Never paste a key into a chat. It goes in the app's settings and nowhere else.** Make a key in the studio: https://studio.ideare.app/keys ### Claude (desktop and web) 1. Open Customize, then Connectors. 2. Click + Add, then Add custom connector. 3. Name it ideare, paste the address and click Continue. Click Continue again on the next screen. 4. Under Authentication, pick Sign in now, keep the recommended option and click Add. 5. ideare opens in a tab. Sign in, pick the workspace and click Allow. On Claude's free plan you can add one custom connector. On Team and Enterprise, an owner adds it for everyone in the organization settings, then each person connects. ### ChatGPT On the web, with a paid plan. Turn on developer mode in Settings, under Apps. Then create an app, paste the address and keep OAuth as the way to sign in. ChatGPT opens ideare so you can sign in and allow it, as in Claude. ChatGPT moves these menus often. If you don't see developer mode, your plan or your workspace admin may not allow it. ### Claude Code In your terminal, with your key in place of `ideare_your_key`: ```sh claude mcp add --transport http ideare https://api.ideare.app/mcp --header "Authorization: Bearer ideare_your_key" ``` Or leave out `--header` and type `/mcp` in Claude Code to sign in through your browser instead. ### Cursor Put this in `~/.cursor/mcp.json`, the file in your home folder, so the key never ends up in a project's git: ```json { "mcpServers": { "ideare": { "url": "https://api.ideare.app/mcp", "headers": { "Authorization": "Bearer ideare_your_key" } } } } ``` Most other apps that take a remote MCP server read this same shape. ### Your first request Ask your app: > Show me my ideare brand crumb-crust. It calls `get_brand` with one argument, the brand's slug: ```json {"slug":"crumb-crust"} ``` You get the brand back: its name, colors, fonts and logo, and its share card once it has an approved version. The slug is the part after `ideare.app/b/` in the address of the brand's public page. Don't know it? Ask "Which ideare brands do I have?" first. ### What the app can do These are the app's tools, by job. It picks which one to use: you just ask in your own words. - **Read your brands**: Your brands, their draft, their approved versions and files, the files your team uploaded, and the credits left. Reading costs nothing. Tools: `list_brands`, `get_brand`, `list_versions`, `get_version`, `list_files`, `list_assets`, `get_usage`. - **Change the draft and ask for approval**: Start a brand, save the draft, check it before approval, bring back an older version, and send it to the owner to approve. Tools: `create_brand`, `update_draft`, `check_brand`, `restore_version`, `approve_draft`. - **Start from what you have**: Read a brand from a link (your site or a social profile), from your files or from a whole brand folder, then use what it found. Tools: `import_link`, `import_files`, `import_folder`, `get_folder_import`, `apply_import`. - **Names and words**: Suggest names, taglines and words for the brand, and check whether a name is free as a domain and as a social handle. Free, up to a daily limit. Tools: `generate_text`, `check_names`. - **AI pictures**: Draw symbol ideas and art in the brand's style. These spend credits: 1 per symbol idea, 1 per picture, and 2 for a bigger, 2K picture. Tools: `generate_symbols`, `generate_art`. - **Posts**: Draw a post from a template (a promotion, opening hours, the menu, a new product, a Pix card) or export one you made in the studio's editor. Tools: `render_template`, `list_designs`, `render_design`. - **Long work**: Follow work that takes a while, like AI pictures or a folder import, or stop it. Tools: `get_run`, `cancel_run`. ### What it can't do The app acts as you, with your role in the workspace. It sees only what a tool gives back. It can't publish. When it asks for approval, the owner gets a request and approves it in the studio in one tap. It can't delete a brand, change who's on your team, buy credits, or make or delete keys. ### Cut an app off Delete its key in the studio, under API keys. The app stops at once. A signed-in app's key carries the app's name. https://studio.ideare.app/keys Then remove ideare from the app too, so it forgets the key. What the app sees and what ideare keeps: https://ideare.app/en/privacy/ai-apps ### For programmers The server speaks MCP over Streamable HTTP: POST only, no session, one JSON answer per request. Send the key as `Authorization: Bearer ideare_...`. With no key it answers 401 with a `WWW-Authenticate` header that points to its OAuth metadata, so an app that speaks OAuth signs in on its own. The metadata: https://api.ideare.app/.well-known/oauth-protected-resource/mcp The first request, by hand: ```sh curl https://api.ideare.app/mcp \ -H "Authorization: Bearer ideare_your_key" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_brand","arguments":{"slug":"crumb-crust"}}}' ``` `tools/list` gives every tool with its input schema. The same list, with the REST routes, is in the OpenAPI file and in llms-full.txt. ### Errors Every refusal is `{error: {code, message}}`. Read it before you retry. `RATE_LIMIT_EXCEEDED`, `QUOTA_EXCEEDED` and `SERVICE_UNAVAILABLE` say how long to wait in `details.retryAfterSecs`. `PAYMENT_REQUIRED` means the credits ran out. `FORBIDDEN` means this key can't do that in this workspace, and a read-only key can only read. `CONFLICT` on a save means someone saved in between: start again from the current draft. ## MCP tools (26) The live server's `tools/list` is the contract, with each tool's input schema. These are the same tools. ### `list_brands`: List your brands The brands in your workspace, the most recently changed first, with the total. Each one says its current version and whether a change waits for approval. Costs no credits. - Changes nothing. - REST: `GET /v1/brands`. SDK: `ideare.brands.list()`. ### `get_brand`: Read a brand A brand with its draft: the masters (brand.json) as last saved, the draft's rev, the current version and any change waiting for approval. Send the rev back when you save or approve. Costs no credits. - Changes nothing. - REST: `GET /v1/brands/{slug}`. SDK: `ideare.brands.get()`. ### `create_brand`: Create a brand Start a brand with a name, and the masters you drew so far if you have them. It starts as a private draft; nothing is public until an owner approves it. The slug comes from the name when you leave it out, and becomes the brand's address: ideare.app/b/. Costs no credits. - Changes data, so a read-only key is refused. - REST: `POST /v1/brands`. SDK: `ideare.brands.create()`. ### `update_draft`: Save the draft Replace the draft's masters (brand.json). Send the draftRev you started from: if someone saved in between, you get a 409 with the current draft, so no change is lost. Saving publishes nothing. Costs no credits. - Changes data, so a read-only key is refused. - REST: `PUT /v1/brands/{slug}/draft`. SDK: `ideare.brands.updateDraft()`. ### `approve_draft`: Approve the draft From an owner or an admin: make the draft a new public version. Every file is drawn again and published at cdn.ideare.app/b//v/; follow the run to see it finish. From anyone else: ask the owner to approve this draft, which they do in one tap. Send the draftRev you looked at. Costs no credits. - Changes data, so a read-only key is refused. - REST: `POST /v1/brands/{slug}/approve`. SDK: `ideare.brands.approve()`. ### `check_brand`: Check a brand Check the draft the way an approval does: contrast, legibility at small sizes, text that fits, safe areas on every social size, and the copy rules. Each result says what to fix. Changes nothing. Costs no credits. - Changes nothing. - REST: `POST /v1/brands/{slug}/check`. SDK: `ideare.brands.check()`. ### `list_versions`: List a brand's versions Every approved version of a brand, newest first, with what changed in each. Versions are public: no key needed. Costs no credits. - Changes nothing. - Needs no key: approved versions are public. - REST: `GET /v1/brands/{slug}/versions`. SDK: `ideare.versions.list()`. ### `get_version`: Read a version One approved version and every file in it, each with its address and sha256. Ask for `latest` to get the version the brand points at now: the CLI resolves it here, then fetches the files of that exact version. Versions are public: no key needed. Costs no credits. - Changes nothing. - Needs no key: approved versions are public. - REST: `GET /v1/brands/{slug}/versions/{version}`. SDK: `ideare.versions.get()`. ### `restore_version`: Bring back an older version Put an older version's masters back in the draft and approve them as a new version, so the history only grows. From anyone but an owner or admin, this asks the owner to approve instead. Send the draft's current draftRev: the draft is replaced. Costs no credits. - Changes data, so a read-only key is refused. - REST: `POST /v1/brands/{slug}/versions/{version}/restore`. SDK: `ideare.versions.restore()`. ### `list_files`: List a brand's files Every file of a version (the current one when you leave it out): logos, site icons, share cards, social sizes, tokens, the email signature, the business card. Each has its address, type, size and sha256. Pass a group (web, logo, og, social, tokens, registry, docs, email, print) to get one folder. Costs no credits. - Changes nothing. - REST: `GET /v1/brands/{slug}/files`. SDK: `ideare.files.list()`. ### `render_template`: Draw a template Draw one of the brand's post templates with your words, as PNG or JPEG, and get a link to it that works for an hour. Templates: promotion, hours, menu, pix (send the Pix key), new-product, status-offer and carousel (5 pages). Sizes: ig-post, ig-square, ig-story, wa-status and share-card. Words that don't fit are refused, with which slot to shorten. Uses the draft unless you name a version. Costs no credits, within the hourly render allowance. - Changes nothing. - REST: `POST /v1/brands/{slug}/render`. SDK: `ideare.files.render()`. ### `get_run`: Read a run Where a long job stands (drawing a version's files, AI pictures, an import): queued with its place in line, running, or finished with its result or what went wrong. For live updates, open its eventsUrl as Server-Sent Events. Costs no credits. - Changes nothing. - REST: `GET /v1/runs/{id}`. SDK: `ideare.runs.get()`. ### `cancel_run`: Stop a run Stop a run that is queued or running. Credits for pictures not made yet come back. A version's cascade can't be stopped: once approved, its files finish. Answers the run as it stands. - Changes data, so a read-only key is refused. - REST: `DELETE /v1/runs/{id}`. SDK: `ideare.runs.cancel()`. ### `generate_text`: Suggest names and words Suggestions from what the business does: names, taglines in each of the brand's languages, a voice, palette moods and font tags. Free, within a daily allowance (see get_usage). - Changes data, so a read-only key is refused. - REST: `POST /v1/ai/text`. SDK: `ideare.ai.text()`. ### `generate_symbols`: Make AI symbol ideas Draw up to 4 symbol ideas for the brand with AI: vector, no letters, in its colors. Costs 1 credit per idea, taken when the run starts and given back for each one that fails. Answers with the run; each idea arrives as an event. - Changes data, so a read-only key is refused. - REST: `POST /v1/brands/{slug}/symbols`. SDK: `ideare.ai.symbols()`. ### `generate_art`: Make AI art Draw a picture in the brand's own style with AI, from your prompt and the brand's references. A 1k draft costs 1 credit and a 2k keeper costs 2, taken when the run starts and given back if it fails. Answers with the run. - Changes data, so a read-only key is refused. - REST: `POST /v1/brands/{slug}/art`. SDK: `ideare.ai.art()`. ### `import_link`: Read a brand from a link Read a site or a social profile and pull out the name, the about text, up to 6 colors and the logo, in about 20 seconds. The logo comes as it was and as a clean vector. Free, within a daily allowance. Answers with the run; its result is what it found, to start a brand from. - Changes data, so a read-only key is refused. - REST: `POST /v1/imports/link`. SDK: `ideare.imports.link()`. ### `import_files`: Read a brand from your files Read uploaded logos and pictures: find their colors and trace a logo into a clean vector, always next to your original. Upload first with create_upload. Free, within a daily allowance. Answers with the run. - Changes data, so a read-only key is refused. - REST: `POST /v1/imports/files`. SDK: `ideare.imports.files()`. ### `import_folder`: Read a whole brand folder Sort a brand folder or zip you already uploaded (up to 200 files): logos in every version, fonts, a guide PDF, posts and photos. Code reads each file first, then AI looks at the pictures and reads the guide. Each file comes back with the slot it fits and how sure we are, and nothing changes in a brand until you call apply_import. Free, within the daily import allowance. Answers with the run; read it with get_folder_import. - Changes data, so a read-only key is refused. - REST: `POST /v1/imports/folder`. SDK: `ideare.imports.folder()`. ### `get_folder_import`: See a folder import Where a folder import stands and, once it is read, where each file goes: its slot, how sure we are, the questions to answer, and what the guide said. Each picture has a link that works for an hour. Costs no credits. - Changes nothing. - REST: `GET /v1/imports/folder/{runId}`. SDK: `ideare.imports.getFolder()`. ### `apply_import`: Use a folder import Write a read folder into the brand: every file goes to its slot, with your moves made (a file moved into a logo slot sends the one there back to your files). For a brand, send its draftRev; without one, a new brand is made with `name`. Fonts ideare's catalog doesn't have stay private and are never published: list the ones you hold a license for in `licensed`. Only the draft changes: approve it to publish. Costs no credits. - Changes data, so a read-only key is refused. - REST: `POST /v1/imports/folder/{runId}/apply`. SDK: `ideare.imports.applyFolder()`. ### `list_assets`: List your files The files in your workspace's library, newest first: uploads, imported pictures, AI symbols and art. Each has a link that works for an hour. Costs no credits. - Changes nothing. - REST: `GET /v1/assets`. SDK: `ideare.assets.list()`. ### `check_names`: Check if a name is free For up to 5 names, see whether the domains (.com.br, .com and .app unless you say) and the social handles look free, with links to search trademarks at INPI, USPTO and EUIPO. `available` means no record was found, not that it is yours; `unknown` means nobody answered. Each name whose handles are checked uses one of the day's handle checks. Costs no credits. - Changes nothing. - REST: `POST /v1/names/check`. SDK: `ideare.names.check()`. ### `get_usage`: See your credits This month's credits: what your plan includes, what you used, the credits you bought, the welcome credits a new account starts with and when they expire, and what is left. Also today's text suggestions and imports against their daily allowance, and when each resets. Costs no credits. - Changes nothing. - REST: `GET /v1/usage`. SDK: `ideare.usage.get()`. ### `list_designs`: List your designs Your posts and other designs, the most recently changed first. Pass a brand to see only its designs. Costs no credits. - Changes nothing. - REST: `GET /v1/designs`. SDK: `ideare.designs.list()`. ### `render_design`: Export a design Draw one page of a design as PNG or JPEG, with the brand's draft, and get a link to it that works for an hour. Costs no credits, within the hourly render allowance. - Changes nothing. - REST: `POST /v1/designs/{id}/render`. SDK: `ideare.designs.render()`. ## REST only These calls are not MCP tools. They are REST routes on `https://api.ideare.app/v1`, with the same key: - `PATCH /v1/brands/{slug}` (`update_brand`): Change a brand's settings. SDK: `ideare.brands.update()`. - `DELETE /v1/brands/{slug}` (`delete_brand`): Delete a brand. SDK: `ideare.brands.delete()`. - `GET /v1/brands/{slug}/live-images` (`get_live_images`): Read the live image secret. SDK: `ideare.brands.liveImages()`. - `POST /v1/brands/{slug}/live-images/secret` (`rotate_live_image_secret`): Change the live image secret. SDK: `ideare.brands.rotateLiveImageSecret()`. - `POST /v1/imports/repo` (`read_repo`): Read a brand from a codebase. SDK: `ideare.imports.repo()`. - `POST /v1/assets` (`create_upload`): Upload a file. SDK: `ideare.assets.createUpload()`. - `POST /v1/assets/{id}/complete` (`complete_upload`): Finish an upload. SDK: `ideare.assets.completeUpload()`. - `GET /v1/designs/{id}` (`get_design`): Read a design. SDK: `ideare.designs.get()`. - `POST /v1/designs` (`create_design`): Start a design. SDK: `ideare.designs.create()`. - `PUT /v1/designs/{id}` (`update_design`): Save a design. SDK: `ideare.designs.update()`. - `DELETE /v1/designs/{id}` (`delete_design`): Delete a design. SDK: `ideare.designs.delete()`. ## Connect an AI app - [Conecte o ideare a um app de IA](https://ideare.app/docs/mcp): Português (Brasil) - [Connect ideare to an AI app](https://ideare.app/en/docs/mcp): English - [Conecta ideare a una app de IA](https://ideare.app/es/docs/mcp): Español ## Use a brand in your code - [Use uma marca no seu código](https://ideare.app/docs): Português (Brasil) - [Use a brand in your code](https://ideare.app/en/docs): English - [Usa una marca en tu código](https://ideare.app/es/docs): Español ## API reference - [Referência da API](https://ideare.app/docs/api): Português (Brasil) - [API reference](https://ideare.app/en/docs/api): English - [Referencia de la API](https://ideare.app/es/docs/api): Español ## Machine-readable files - [Full MCP and REST reference](https://ideare.app/llms-full.txt): How to connect, every tool and every route, in one file. - [MCP discovery metadata](https://ideare.app/.well-known/mcp.json): The MCP address and how it signs in. It is not a setup file for any one app. - [OpenAPI 3.1 reference](https://api.ideare.app/openapi.json): Every REST route, plus the MCP tools in `x-mcp-tools`. - [The brand.json format](https://ideare.app/schema/brand.v1.json): The JSON Schema of the masters every file is made from.