Desarrolladores

API de Grape y documentación para desarrolladores

La API pública de Grape, la especificación OpenAPI, la negociación de contenido en markdown y el archivo de instrucciones para agentes, en una sola página. Sin clave y sin registro.

Empieza aquí

Una URL base, sin clave

Todos los endpoints de abajo parten de https://grape.cool/api/v1 y responden a GET y a POST con el mismo resultado.

Leer los planes

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

Responder una pregunta sobre cómo hacer algo

curl -s "https://grape.cool/api/v1/help-search?q=lock+a+note"

Obtener el cuerpo de un artículo de ayuda

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

Leer cualquier página en markdown

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

O pedir directamente la URL en markdown

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

Hacer la misma llamada con POST en lugar de GET

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

Endpoints

Toda la superficie

Dieciséis endpoints de lectura. Cada uno tiene un operation id, parámetros tipados y un esquema de respuesta en el documento OpenAPI.

Endpoint	Operation id	Qué devuelve	Parámetros
`/app`	`getApp`	La identidad del producto, quién lo publica, las versiones actuales para computadora y celular, las plataformas y cuándo conviene usar Grape.	Ninguno
`/downloads`	`listDownloads`	Enlaces de descarga directa por plataforma y arquitectura.	`kind=desktop\|mobile`
`/plans`	`listPlans`	Gratis, Sync, Plus, Pro y De por vida, con sus precios y la lista completa de funciones de cada uno.	Ninguno
`/features`	`listFeatures`	Cada función que tiene la app hoy, con una descripción de cada una.	Ninguno
`/products`	`listProducts`	Las partes de la app que tienen nombre: el agente, la búsqueda, las notas de voz, el lienzo y las demás.	Ninguno
`/products/{slug}`	`getProduct`	Un área del producto con sus beneficios y puntos destacados.	Ninguno
`/solutions`	`listSolutions`	Los veintiún públicos para los que Grape publica una página a medida.	`group`
`/solutions/{slug}`	`getSolution`	Un público con sus resultados, casos de uso y preguntas.	Ninguno
`/faqs`	`listFaqs`	Las preguntas que hace la gente antes de descargar, con las respuestas publicadas.	Ninguno
`/changelog`	`listChangelog`	Las versiones para computadora y celular, con los cambios de cada una.	`platform=desktop\|mobile`
`/help-categories`	`listHelpCategories`	Las categorías del centro de ayuda y cuántos artículos tiene cada una.	Ninguno
`/help-articles`	`listHelpArticles`	Los títulos, las descripciones y los tiempos de lectura de los artículos de ayuda.	`category`
`/help-articles/{slug}`	`getHelpArticle`	Un artículo de ayuda con su cuerpo completo en markdown.	Ninguno
`/blog-posts`	`listBlogPosts`	Las entradas publicadas, de la más reciente a la más antigua.	`limit`
`/blog-posts/{slug}`	`getBlogPost`	Una entrada con su cuerpo completo en markdown.	Ninguno
`/search`	`searchContent`	Un término buscado en artículos de ayuda, entradas, funciones, productos, públicos y preguntas.	`q (obligatorio), limit`
`/help-search`	`searchHelp`	Una pregunta respondida desde el centro de ayuda, con las mejores guías completas.	`q (obligatorio), limit`

Autenticación

Qué está abierto y qué no

La API pública no necesita nada

Todos los endpoints bajo /api/v1 son abiertos. No hay clave que pedir, ni encabezado que configurar, ni registro. Las solicitudes están limitadas a 1000 por hora por dirección IP.

Las notas pasan por el servidor MCP

Las notas nunca viajan por la API pública. Una app de IA lee y escribe las notas de una cuenta con la sesión iniciada a través del servidor MCP en https://mcp.grape.cool, después de que el titular de la cuenta aprueba la conexión con OAuth, en el plan Pro. La API de sincronización que usan las apps de Grape es privada y no forma parte de esta especificación.

Endpoints de escritura

El formulario de contacto envía a /api/contact y la lista de correo, a /api/waitlist. Los dos tienen límite de solicitudes y los dos responden con la misma estructura de error. Para cualquier otra cosa, escríbenos desde la página de contacto en https://grape.cool/contact.

Errores

Los fallos vuelven como JSON

Nunca como una página HTML. Decide según el código, muestra el mensaje y sigue la pista.

{
    "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

Faltaba un parámetro o tenía un valor fuera de los permitidos.

`not_found` 404

Ningún registro coincide con el slug de la ruta.

`not_acceptable` 406

El encabezado Accept descartó tanto HTML como markdown.

`rate_limited` 429

Llegaron más de 1000 solicitudes desde esta dirección IP en una hora.

`internal_error` 500

No se pudo completar la solicitud. Reintenta una vez y, si vuelve a fallar, escríbenos.

Recetas

Sin CLI, sin SDK, sin capas intermedias

No hay ninguna CLI que instalar ni ningún SDK que importar. Cada endpoint es HTTP y JSON sin más, así que curl, httpie, fetch o el cliente HTTP de tu lenguaje funcionan sin ninguna capa intermedia.

Encontrar la respuesta a una pregunta sobre cómo hacer algo

La búsqueda abarca todos los tipos de contenido, así que quédate con un artículo de ayuda antes de pedir su cuerpo.

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'

Comprobar si salió una versión nueva

La versión actual de cada app y lo que cambió en ella.

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[] | "  - \(.)")'

Responder una pregunta sobre precios

Cada plan, su precio y lo que incluye, en una sola llamada.

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

Vigilar tu propio límite

Los campos del límite de solicitudes llegan en cada respuesta, incluida esta.

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

Leer una página en markdown en lugar de HTML

Funciona con cualquier URL del sitio, con o sin encabezado Accept.

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

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

Traer todo el sitio de una sola vez

Todas las páginas concatenadas, pensado para una ventana de contexto más que para un rastreador.

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

Límites de uso

Cada respuesta te dice cuánto te queda

Lee los encabezados y baja el ritmo antes de que te rechacen, no después. El límite es por dirección IP.

`RateLimit-Limit`

Cuántas solicitudes permite la ventana. Siempre 1000.

`RateLimit-Remaining`

Cuántas quedan en la ventana para tu dirección IP.

`RateLimit-Reset`

Los segundos que faltan para que se renueve el límite.

`RateLimit-Policy`

La cuota y la ventana en un solo campo: "public";q=1000;w=3600.

`RateLimit`

El mismo estado en la forma combinada que adoptó el borrador de la IETF.

`Retry-After`

Solo se envía con un 429. Los segundos que hay que esperar antes de volver a intentarlo.

Versiones

Lo que no va a cambiar sin avisarte

La versión va en la ruta. v1 es estable, y nada de aquí está obsoleto.

Lo que prometemos dentro de una versión

Dentro de una versión, a una respuesta solo se le agregan campos: nunca se quita uno ni se cambia su tipo.
Una respuesta puede traer un valor de enum nuevo, así que trata uno desconocido como no reconocido y no como un error.
Un cambio incompatible significa una versión nueva en una ruta nueva, no una modificación de esta.

Cómo se anuncia un retiro

Un encabezado `Deprecation` con la fecha en que la versión quedó obsoleta.
Un encabezado `Sunset` con la fecha en que deja de responder.
Un encabezado `Link` con rel="successor-version" que apunta a la versión que la reemplaza.
Un objeto `deprecation` en el índice de /api/v1 y en esta página.

Una versión obsoleta sigue respondiendo al menos 12 meses después de que aparece el encabezado Deprecation por primera vez, y el encabezado Sunset indica exactamente cuándo deja de responder.

Para máquinas

Archivos escritos para agentes

Especificación OpenAPI

OpenAPI 3.1, un operation id por endpoint, parámetros tipados y esquemas de respuesta. También se sirve como YAML en /openapi.yaml.

Instrucciones para agentes

llms.txt con las tareas para las que Grape sirve, las que no, y un enlace a cada página que vale la pena leer. La versión larga está en /llms-full.txt.

Índice de la API

La lista de endpoints en JSON, para que un cliente descubra lo que ofrece la API sin leer esta página.

Servidor MCP

El endpoint del Model Context Protocol para ChatGPT, Claude y otros clientes de IA: las carpetas y las notas de una cuenta, detrás de OAuth 2.1 y del plan Pro. Sus metadatos de recurso están en https://mcp.grape.cool/.well-known/oauth-protected-resource y los metadatos del servidor de autorización, en https://grape.cool/.well-known/oauth-authorization-server.

Markdown desde cualquier página del sitio

Envía Accept: text/markdown a la URL de cualquier página y el mismo contenido vuelve como markdown con Vary: Accept configurado, o agrega .md a la ruta si tu cliente no puede enviar encabezados. Una solicitud que descarta tanto HTML como markdown recibe un 406.

Cuándo usar Grape

Los trabajos para los que es la herramienta correcta

Escrito para un agente que decide si recurrir a Grape o no.

Convertir una grabación en una nota en la que se puede buscar

Graba una clase, una llamada o una reunión en la app y Grape escribe la transcripción en la nota, junto a tus propias palabras.

Responder una pregunta a partir de notas que el usuario ya escribió

Pregúntale al agente integrado en lugar de buscar. Cada respuesta cita la nota de la que salió, así que la fuente se puede comprobar.

Estudiar con material propio del usuario

Genera tarjetas de memoria, cuestionarios y mapas mentales a partir de notas existentes en lugar de contenido genérico de la web, o escríbelos tú mismo en cualquier plan.

Guardar las notas en un dispositivo y no en la base de datos de un proveedor

Grape guarda la biblioteca en una base de datos local cuya ubicación elige el usuario. La sincronización es opcional: con Grape Cloud en los planes Sync, Plus y Pro, o con el propio Dropbox o Google Drive del usuario en el plan De por vida, que Grape nunca ve.

Leer datos del producto Grape desde código

Llama a la API JSON de solo lectura en https://grape.cool/api/v1 para obtener planes, funciones, versiones, artículos de ayuda y entradas del blog. No hace falta ninguna clave.

Cuándo recurrir a otra cosa

Leer o escribir una nota de un usuario por HTTP. La API de notas es privada de las apps de Grape y necesita el token de la cuenta que da la app.
Una wiki de equipo o un espacio de trabajo en el que trabaja toda una empresa. Grape es una biblioteca para una sola persona, sincronizada entre sus propios dispositivos; una carpeta o una nota se puede compartir con otras personas en el plan Sync, Plus o Pro, y escribir en ella a la vez y en vivo en Pro, pero no hay cuentas de equipo ni enlaces públicos.
Guardar cualquier cosa que no pondrías en una base de datos local, como registros de salud regulados o datos de pago.

La especificación está a una solicitud

Apunta tu cliente a https://grape.cool/openapi.json y con ella llegan cada operación, cada parámetro y la forma de cada respuesta.

Descargar gratis Comparar los planes