API REST

Guarda y borra documentos de cientos o miles de páginas desde tus propios scripts. Sin ninguna IA de por medio.

En lugar de meter un PDF, una hoja de cálculo o un informe uno a uno a mano, un script hace todo el recorrido: extraes y divides el texto tú y envías el resultado.

Lo que guardas aquí es idéntico a lo guardado desde una IA conectada: la misma base de conocimiento, y tu IA lo recupera igual.

La lectura es por id, no por búsqueda. La recuperación semántica sigue estando en MCP y en tu panel.

Primeros pasos

Crea una clave en la tarjeta REST API, en tu página de cuenta. Su nombre se registra como el origen de todo lo guardado con ella: ponle uno que reconozcas después, como Import script o pdf-importer.
La clave se muestra una sola vez, justo después de crearla. Cópiala en ese momento: no se puede volver a mostrar.
Crea tantas claves como quieras y borra cualquiera de ellas cuando quieras.

Autenticación

Base URLhttps://contextick.ai

Authorization: Bearer api_xxxxxxxx

Aquí solo funcionan las claves que empiezan por api_. Una clave MCP o un token OAuth reciben 401 en esta API, y una clave de la API REST recibe 401 en el endpoint MCP: son superficies separadas, así que puedes revocar una sin tocar la otra.

Endpoints

POST `/api/v1/notes`

Guarda un elemento.

Body

Field	Type	Required	Limit
title	string	✓	120 caracteres; lo que sobra se recorta
summary	string	✓	300 caracteres; lo que sobra se recorta
content	string	✓	16,000 caracteres; por encima se rechaza

Ninguno de los tres puede ir vacío: un valor en blanco se rechaza en lugar de rellenarse a ojo.

Request

curl -X POST https://contextick.ai/api/v1/notes \
  -H "Authorization: Bearer api_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"title":"Q3 report","summary":"Revenue and headcount for Q3.","content":"…"}'

Response 201

{ "id": 42, "saved_items": 118, "stored_bytes": 1048576 }

saved_items y stored_bytes son tus totales después de guardar. Si no se pudieron leer, los campos se omiten en lugar de valer cero.

El origen que se registra en el elemento es el nombre de la clave. No se puede fijar desde la petición.

GET `/api/v1/notes/{id}`

Lee un elemento completo.

Request

curl https://contextick.ai/api/v1/notes/42 \
  -H "Authorization: Bearer api_xxxxxxxx"

Response 200

{ "id": 42, "title": "Q3 report", "summary": "…", "content": "…",
  "author": "you@example.com", "origin": "Import script", "created_at": "…",
  "status": "ready", "group_id": null, "times_opened": 3 }

Leer aquí no cambia times_opened: esa cuenta refleja lo que abres tú, no lo que sincroniza un script.

status es ready, pending o failed; solo un elemento ready aparece en la búsqueda.

group_id solo aparece si el elemento vino de un archivo subido; en caso contrario es null. Un id que no existe responde 404.

GET `/api/v1/notes/group/{group_id}`

Lista las partes en las que se dividió un archivo subido.

Request

curl https://contextick.ai/api/v1/notes/group/6f1c2a94 \
  -H "Authorization: Bearer api_xxxxxxxx"

Response 200

{ "group_id": "6f1c2a94", "title": "Q3 report",
  "part_count": 13, "ready": 11, "pending": 2, "failed": 0,
  "items": [
    { "id": 42, "title": "Q3 report (1/13)", "status": "ready" },
    { "id": 43, "title": "Q3 report (2/13)", "status": "pending" } ] }

title es el título del archivo, tomado de su primera parte y sin la numeración, y los cuatro recuentos te ahorran recorrer items para obtenerlos.

Las partes llegan en orden de id y sin su texto: para el content de una parte, usa la lectura de arriba.

El group_id viene de la lectura de arriba. Una etiqueta sin elementos responde 404.

DELETE `/api/v1/notes/group/{group_id}`

Elimina todas las partes de un archivo subido.

Request

curl -X DELETE https://contextick.ai/api/v1/notes/group/6f1c2a94 \
  -H "Authorization: Bearer api_xxxxxxxx"

Response 200

{ "group_id": "6f1c2a94", "deleted": [42, 43, 44],
  "saved_items": 117, "stored_bytes": 1040000 }

Todo el archivo o nada: cada parte con esa etiqueta se va en una sola transacción, así que una llamada interrumpida no puede dejar el archivo a medio borrar.

A diferencia de los dos borrados de arriba no hay array not_found: esto recibe una etiqueta, no una lista de ids, así que una etiqueta sin elementos responde 404 igual que la lectura de arriba.

GET `/api/v1/notes/changes`

Trae los elementos añadidos desde tu última consulta, del más antiguo al más reciente.

Query

Parámetro	Tipo	Notas
cursor	entero	Donde lo dejaste: el cursor de la respuesta anterior.
since	RFC 3339	Un momento concreto, p. ej. `2026-09-01T13:00:00+09:00`. El desplazamiento es obligatorio. Solo en la primera llamada.
limit	entero	1–100. Por defecto, 50.

Empieza con since (o sin nada) y luego sigue el cursor. Enviar ambos es un error.

Petición

curl "https://contextick.ai/api/v1/notes/changes?since=2026-09-01T04:00:00Z&limit=50" \
  -H "Authorization: Bearer api_xxxxxxxx"

Respuesta 200

{ "data": [
    { "id": 41, "title": "Q3 report", "summary": "…", "created_at": "2026-09-01T04:00:12Z",
      "origin": "Import script", "status": "ready", "group_id": null } ],
  "pagination": { "limit": 50, "poll_cursor": "41" } }

next_cursor significa que queda más: pide otra página enseguida. poll_cursor significa que estás al día: guárdalo y vuelve más tarde. Solo aparece uno de los dos.

Los elementos llegan del más antiguo al más reciente, así que el cursor solo avanza y no se salta nada, por mucho tiempo que hayas estado fuera. El texto no viene incluido: léelo elemento a elemento cuando lo necesites.

since es un punto de partida, no un filtro: pueden colarse unos pocos elementos algo más antiguos. status puede ser pending: guardado y legible, pero aún no buscable. Las eliminaciones y los cambios de estado posteriores no aparecen aquí.

DELETE `/api/v1/notes/{id}`

Borra un elemento.

Request

curl -X DELETE https://contextick.ai/api/v1/notes/42 \
  -H "Authorization: Bearer api_xxxxxxxx"

POST `/api/v1/notes/delete`

Borra varios de una vez.

Body

Field	Type	Required	Limit
ids	number[]	✓	50 ids por llamada; por encima se rechaza

Es la forma de deshacer una importación masiva.

Request

curl -X POST https://contextick.ai/api/v1/notes/delete \
  -H "Authorization: Bearer api_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"ids":[42,43]}'

Delete response 200

{ "deleted": [42], "not_found": [43], "saved_items": 117, "stored_bytes": 1040000 }

Los dos borrados responden con la misma forma. Un id que no existe se informa en not_found, no se trata como error. Borrar es permanente y no se puede deshacer.

Errores

Todos los fallos usan una sola forma:

{ "error": { "code": "quota_exceeded", "message": "…" } }

Ramifica según code. El message es prosa para una persona y puede cambiar en cualquier momento.

400 Corrige la petición y reintenta empty_titleempty_summaryempty_contentcontent_too_longtoo_many_idsinvalid_bodyinvalid_idinvalid_query

401 Revisa la clave api_ unauthorized

402 Resuelve el estado de pago; mientras tanto la recuperación sigue funcionando payment_past_duesubscription_pausedsubscription_canceledrefund_pending

404 Ese id, grupo o ruta no existe not_foundendpoint_not_found

405 Usa un método de la cabecera Allow method_not_allowed

415 Envía Content-Type: application/json unsupported_media_type

429 Reintenta la misma petición en un momento rate_limitedembedding_rate_limited

507 Libera espacio o pasa a un plan mayor; no reintentes tal cual quota_exceeded

503 500 Temporal o del servidor: reintenta en un momento

Recibir webhooks

Que los guardados, los borrados y los elementos que pasan a ser buscables lleguen a tu propio extremo ya tiene página propia: las cabeceras, los cuatro tipos de evento, la verificación de la firma y los reintentos están en la documentación de webhooks.

Conviene saber

Cuánto puedes guardar depende de tu plan: mira precios.
Las llamadas tienen un tope por hora y por día, y un 429 incluye Retry-After. Los topes quedan muy por encima del uso normal de un script; para importar de golpe un documento largo, súbelo desde tu panel: eso se cuenta por archivo, no por parte.
¿Algo no queda claro o no funciona? Escríbenos: una persona real lee cada mensaje.

API REST

Primeros pasos

Autenticación

Endpoints

POST /api/v1/notes

Body

Request

Response 201

GET /api/v1/notes/{id}

Request

Response 200

GET /api/v1/notes/group/{group_id}

Request

Response 200

DELETE /api/v1/notes/group/{group_id}

Request

Response 200

GET /api/v1/notes/changes

Query

Petición

Respuesta 200

DELETE /api/v1/notes/{id}

Request

POST /api/v1/notes/delete

Body

Request

Delete response 200

Errores

Recibir webhooks

Conviene saber

POST `/api/v1/notes`

GET `/api/v1/notes/{id}`

GET `/api/v1/notes/group/{group_id}`

DELETE `/api/v1/notes/group/{group_id}`

GET `/api/v1/notes/changes`

DELETE `/api/v1/notes/{id}`

POST `/api/v1/notes/delete`