Skip to main content

​
Notes Endpoints

Manage personal notes on verses. All endpoints require authentication.

​
GET /api/notes

Retrieve notes for the authenticated user. Can fetch a specific note or all notes.

​
Authentication

Requires Clerk authentication.

​
Query Parameters

​
chapter
integer
Chapter number (1-18). If provided with verse, fetches a specific note.
​
verse
integer
Verse number. If provided with chapter, fetches a specific note.

​
Behavior

  • With chapter and verse: Returns a single note object or null if no note exists
  • Without parameters: Returns all notes for the user as an array

​
Response - Single Note

​
id
integer
Unique note ID
​
user_id
string
User’s unique identifier
​
chapter
integer
Chapter number (1-18)
​
verse
integer
Verse number
​
note_text
string
The note content (trimmed)
​
created_at
string
ISO 8601 timestamp when the note was created
​
updated_at
string
ISO 8601 timestamp when the note was last updated

​
Response Example - Single Note

{
  "id": 789,
  "user_id": "user_abc123",
  "chapter": 2,
  "verse": 47,
  "note_text": "This verse reminds me to focus on my work without worrying about outcomes. Very applicable to my current project.",
  "created_at": "2024-03-10T12:34:56.789Z",
  "updated_at": "2024-03-10T14:20:30.123Z"
}

​
Response Example - All Notes

[
  {
    "id": 789,
    "user_id": "user_abc123",
    "chapter": 2,
    "verse": 47,
    "note_text": "Focus on actions, not results.",
    "created_at": "2024-03-10T12:34:56.789Z",
    "updated_at": "2024-03-10T14:20:30.123Z"
  },
  {
    "id": 790,
    "user_id": "user_abc123",
    "chapter": 6,
    "verse": 5,
    "note_text": "Self-control is key to spiritual growth.",
    "created_at": "2024-03-09T10:15:00.000Z",
    "updated_at": "2024-03-09T10:15:00.000Z"
  }
]

​
Error Responses

Status CodeDescription
400Invalid chapter or verse
401Unauthorized
500Failed to fetch notes
503Database not configured

​
POST /api/notes

Create a new note or update an existing note for a verse (upsert operation).

​
Authentication

Requires Clerk authentication.

​
Request

​
chapter
integer
required
Chapter number (1-18)
​
verse
integer
required
Verse number (must be valid for the chapter)
​
note_text
string
required
The note content. Maximum 5,000 characters (trimmed).

​
Request Body Example

{
  "chapter": 2,
  "verse": 47,
  "note_text": "This verse reminds me to focus on my work without worrying about outcomes."
}

​
Response

Returns the created or updated note object. 
{
  "id": 789,
  "user_id": "user_abc123",
  "chapter": 2,
  "verse": 47,
  "note_text": "This verse reminds me to focus on my work without worrying about outcomes.",
  "created_at": "2024-03-10T12:34:56.789Z",
  "updated_at": "2024-03-10T12:34:56.789Z"
}

​
Error Responses

Status CodeDescription
400Missing required fields, invalid chapter/verse, or note text too long
401Unauthorized
500Failed to save note
503Database not configured

​
DELETE /api/notes

Delete a note for a specific verse.

​
Authentication

Requires Clerk authentication.

​
Query Parameters

​
chapter
integer
required
Chapter number (1-18)
​
verse
integer
required
Verse number

​
Response

{
  "success": true
}

​
Error Responses

Status CodeDescription
400Invalid chapter or verse
401Unauthorized
500Failed to delete note
503Database not configured

​
Code Examples

curl -X GET "https://gitachat.org/api/notes?chapter=2&verse=47" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Notes

  • Notes are unique per user, chapter, and verse combination
  • Creating a note for an existing verse will update the existing note (upsert)
  • Note text is automatically trimmed of leading/trailing whitespace
  • Maximum note length: 5,000 characters
  • Notes are sorted by updated_at when fetching all notes (newest first)
  • Empty or whitespace-only notes cannot be saved

Build docs developers (and LLMs) love

Get started for freeTalk to us