Developers

Grape API and Developer Documentation

The public Grape API, the OpenAPI specification, markdown content negotiation and the agent instruction file, in one page. No key, no signup.

Start here

One Base URL, No Key

Every endpoint below hangs off https://grape.cool/api/v1 and answers both GET and POST with the same result.

Read the plans

curl -s https://grape.cool/api/v1/plans

Answer a how do I question

curl -s "https://grape.cool/api/v1/search?q=transcription"

Fetch a help article body

curl -s https://grape.cool/api/v1/help-articles/{slug}

Read any page as markdown

curl -s -H "Accept: text/markdown" https://grape.cool/pricing

Or ask for the markdown URL directly

curl -s https://grape.cool/pricing.md

Post the same call instead of getting it

curl -s -X POST https://grape.cool/api/v1/changelog -H 'Content-Type: application/json' -d '{"platform":"desktop"}'

Endpoints

The Whole Surface

Sixteen read endpoints. Each one has an operation id, typed parameters and a response schema in the OpenAPI document.

Endpoint	Operation id	What it returns	Parameters
`/app`	`getApp`	Product identity, publisher, current desktop and mobile versions, platforms, and when to reach for Grape.	None
`/downloads`	`listDownloads`	Direct download links per platform and architecture.	`kind=desktop\|mobile`
`/plans`	`listPlans`	Free, Pro and Lifetime with prices and the full feature list of each.	None
`/features`	`listFeatures`	Every feature in the app today, with a description each.	None
`/products`	`listProducts`	The named parts of the app: agent, search, voice notes, canvas and the rest.	None
`/products/{slug}`	`getProduct`	One product area with its benefits and highlights.	None
`/solutions`	`listSolutions`	The twenty audiences Grape publishes a tailored page for.	`group`
`/solutions/{slug}`	`getSolution`	One audience with its outcomes, use cases and questions.	None
`/faqs`	`listFaqs`	Questions people ask before downloading, with the published answers.	None
`/changelog`	`listChangelog`	Desktop and mobile releases with the changes in each.	`platform=desktop\|mobile`
`/help-categories`	`listHelpCategories`	Help center categories and how many articles each holds.	None
`/help-articles`	`listHelpArticles`	Help article titles, descriptions and reading times.	`category`
`/help-articles/{slug}`	`getHelpArticle`	One help article including its full markdown body.	None
`/blog-posts`	`listBlogPosts`	Published posts, newest first.	`limit`
`/blog-posts/{slug}`	`getBlogPost`	One post including its full markdown body.	None
`/search`	`searchContent`	One term across help articles, posts, features, products, audiences and questions.	`q (required), limit`

Authentication

What Is Open and What Is Not

The public API needs nothing

Every endpoint under /api/v1 is open. There is no key to request, no header to set and no signup. Requests are limited to 1000 an hour per IP address.

Notes are not on it

The sync API the Grape apps use is private. It is authenticated with an account token issued inside the app after sign in, and it is not part of this specification.

Write endpoints

The contact form posts to /api/contact and the mailing list to /api/waitlist. Both are rate limited and both answer with the same error envelope. For anything else, write to [email protected].

Errors

Failures Come Back as JSON

Never as an HTML page. Switch on the code, show the message, follow the hint.

{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "No help article matches \"backupz\".",
    "hint": "List the available values at
      https://grape.cool/api/v1/help-articles and
      retry with one of the slugs it returns.",
    "documentation": "https://grape.cool/docs"
  }
}

`validation_failed` 400

A parameter was missing or outside the allowed values.

`not_found` 404

No record matches the slug in the path.

`not_acceptable` 406

The Accept header ruled out both HTML and markdown.

`rate_limited` 429

More than 1000 requests came from this IP address in an hour.

`internal_error` 500

The request could not be completed. Retry once, then write to us.

Recipes

No CLI, No SDK, No Wrapper

There is no CLI to install and no SDK to import. Every endpoint is plain HTTP and JSON, so curl, httpie, fetch or the HTTP client in your language works with no wrapper in between.

Find the answer to a how do I question

Search crosses every kind of content, so narrow it to a help article before asking for the body.

slug=$(curl -s "https://grape.cool/api/v1/search?q=transcription" \
  | jq -r 'first(.data[] | select(.type == "help-article")).url
           | split("/") | last')

curl -s "https://grape.cool/api/v1/help-articles/$slug" | jq -r '.data.body'

Check whether a newer version has shipped

The current version of each app, and what changed in it.

curl -s https://grape.cool/api/v1/app | jq '.data.versions'

curl -s "https://grape.cool/api/v1/changelog?platform=desktop" \
  | jq -r '.data[0] | "\(.version) \(.date)", (.changes[] | "  - \(.)")'

Answer a pricing question

Every plan, its price and what it includes, in one call.

curl -s https://grape.cool/api/v1/plans \
  | jq -r '.data[] | "\(.name) \(.price) \(.period)", (.features[] | "  - \(.)")'

Watch your own allowance

The throttling fields come back on every response, including this one.

curl -sI https://grape.cool/api/v1/plans | grep -i '^ratelimit'

Read a page as markdown instead of HTML

Works on any URL on the site, with or without an Accept header.

curl -s -H "Accept: text/markdown" https://grape.cool/pricing

curl -s https://grape.cool/pricing.md

Take the whole site in one fetch

Every page concatenated, for a context window rather than a crawler.

curl -s https://grape.cool/llms-full.txt

Rate limits

Every Answer Tells You What Is Left

Read the headers and slow down before you are turned away, rather than after. The allowance is per IP address.

`RateLimit-Limit`

How many requests the window allows. Always 1000.

`RateLimit-Remaining`

How many are left in the window for your IP address.

`RateLimit-Reset`

Seconds until the allowance refills.

`RateLimit-Policy`

The quota and window as one field: "public";q=1000;w=3600.

`RateLimit`

The same state in the combined form the IETF draft settled on.

`Retry-After`

Sent only with a 429. Seconds to wait before trying again.

Versioning

What Will Not Change Under You

The version is in the path. v1 is stable, and nothing here is deprecated.

What we promise inside a version

A field is only ever added to a response, never removed or retyped, within a version.
A new enum value can appear in a response, so treat an unknown one as unrecognised rather than as an error.
A breaking change means a new version under a new path, not an edit to this one.

How a retirement is announced

A `Deprecation` header carrying the date the version was deprecated.
A `Sunset` header carrying the date it stops answering.
A `Link` header with rel="successor-version" pointing at the replacement.
A `deprecation` object on the /api/v1 index and on this page.

A deprecated version keeps answering for at least 12 months after the Deprecation header first appears, and the Sunset header says exactly when it stops.

Machine readable

Files Written for Agents

OpenAPI specification

OpenAPI 3.1, one operation id per endpoint, typed parameters and response schemas. Also served as YAML at /openapi.yaml.

Agent instructions

llms.txt with the jobs Grape is right for, the jobs it is not, and a link to every page worth reading. The long form is at /llms-full.txt.

API index

The endpoint list as JSON, so a client can discover the surface without reading this page.

Markdown from any page on the site

Send Accept: text/markdown to any page URL and the same content comes back as markdown with Vary: Accept set, or add .md to the path if your client cannot set headers. A request that rules out both HTML and markdown gets a 406.

When to use Grape

The Jobs This Is the Right Tool For

Written for an agent deciding whether to reach for Grape at all.

Turn a recording into a searchable note

Record a lecture, call or meeting in the app and Grape writes the transcript into the note beside your own words.

Answer a question from notes the user already wrote

Ask the built in agent instead of searching. Every answer cites the note it came from, so the source is checkable.

Study from material the user owns

Generate flashcards, quizzes and mind maps out of existing notes rather than from generic web content.

Keep notes on a device rather than in a vendor database

Grape stores the library in a local database the user picks the location of. Sync is opt in and only on paid plans.

Read Grape product facts programmatically

Call the read only JSON API at https://grape.cool/api/v1 for plans, features, releases, help articles and blog posts. No key is needed.

When to reach for something else

Reading or writing a user note over HTTP. The notes API is private to the Grape apps and needs the account token from the app.
Team wikis with shared editing. Grape is a one person library that syncs across the devices that person owns.
Storing anything you would not put in a local database, such as regulated health or payment records.

The Spec Is One Fetch Away

Point your client at https://grape.cool/openapi.json and every operation, parameter and response shape comes with it.

Download free Compare the plans