REST API

Body

Field	Type	Required	Limit
title	string	✓	120자 — 넘으면 잘립니다
summary	string	✓	300자 — 넘으면 잘립니다
content	string	✓	16,000자 — 넘으면 거절됩니다

셋 다 비어 있으면 안 됩니다. 빈 값은 임의로 채우지 않고 거절합니다.

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 와 stored_bytes 는 저장 후의 총량입니다. 읽지 못했을 때는 0 이 아니라 필드 자체가 빠집니다.

문서에 기록되는 출처는 키 이름입니다. 요청으로 지정할 수 없습니다.

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 }

여기서 읽어도 times_opened 는 바뀌지 않습니다 — 그 숫자는 스크립트가 동기화한 것이 아니라 사람이 열어본 것을 셉니다.

status 는 ready·pending·failed 중 하나입니다 — ready 인 항목만 검색으로 찾힙니다.

group_id 는 업로드한 파일에서 나온 항목에만 있고, 아니면 null 입니다. 없는 id 는 404 로 답합니다.

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 은 파일 자체의 제목입니다 — 첫 조각에서 조각 번호를 뗀 것이고, 네 개의 개수는 items 를 훑지 않고도 바로 얻으라고 있습니다.

조각은 id 순으로 오고 본문은 들어 있지 않습니다 — 조각의 content 가 필요하면 위 단건 조회를 부릅니다.

group_id 는 위 단건 조회 응답에서 얻습니다. 해당 항목이 없는 라벨은 404 로 답합니다.

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 }

전부 아니면 전무입니다 — 그 라벨을 단 조각이 한 트랜잭션에서 함께 사라지므로, 도중에 끊겨도 파일이 반쯤 지워진 채 남지 않습니다.

위의 두 삭제와 달리 not_found 배열이 없습니다. 여기는 id 목록이 아니라 라벨 하나를 받으므로, 해당 항목이 없는 라벨은 위 조회와 같이 404 로 답합니다.

Query

파라미터	타입	필수	설명
cursor	정수		이어받을 지점 — 직전 응답의 커서입니다.
since	RFC 3339		시작 시점입니다. 예: 2026-09-01T13:00:00+09:00. 오프셋은 반드시 붙입니다. 첫 호출에만 씁니다.
limit	정수		1–100. 기본값 50.

since 로 시작하거나 아무것도 주지 않고 시작한 뒤, 이후에는 커서를 따라갑니다. 둘을 함께 주면 오류입니다.

요청

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

응답 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 는 남은 것이 있다는 뜻이라 바로 다시 요청합니다. poll_cursor 는 따라잡았다는 뜻이라 저장해 두고 다음에 확인합니다. 둘 중 정확히 하나만 담깁니다.

오래된 것부터 오므로 커서는 앞으로만 가고, 오래 쉬었더라도 건너뛰는 항목이 없습니다. 본문은 담기지 않습니다 — 필요하면 단건 조회로 읽습니다.

since 는 필터가 아니라 시작점이라 조금 더 오래된 항목이 몇 건 함께 올 수 있습니다. status 가 pending 일 수 있습니다 — 저장돼 읽히지만 아직 검색되지는 않습니다. 삭제와 이후의 상태 변화는 여기 나오지 않습니다.

Request

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

Body

Field	Type	Required	Limit
ids	number[]	✓	한 번에 50개 — 넘으면 거절됩니다

대량 임포트를 되돌리는 경로가 이것입니다.

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]}'