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.

No hay API de lectura. La búsqueda y la recuperación siguen estando en MCP y en tu panel.

Primeros pasos

  1. 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.
  2. La clave se muestra una sola vez, justo después de crearla. Cópiala en ese momento: no se puede volver a mostrar.
  3. 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

FieldTypeRequiredLimit
titlestring✓120 caracteres; lo que sobra se recorta
summarystring✓300 caracteres; lo que sobra se recorta
contentstring✓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.

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

FieldTypeRequiredLimit
idsnumber[]✓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.

Divide tú los documentos largos

El límite de contenido es de 16,000 caracteres por guardado. Nada se divide por ti: lo que pase de ahí se rechaza con content_too_long. Corta el documento en partes con sentido propio y guarda cada una con su título y su resumen: tú conoces el nombre del archivo y los títulos de sección, y eso hace que esas partes sean mucho más fáciles de recuperar después.

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_id
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
429 Reintenta la misma petición en un momento embedding_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

Conviene saber