filing-cabinet-api/API.md

API contract (agent reference)

Base URL: http://localhost:${PORT}. Use Authorization: Bearer <token> or HttpOnly fc_session_token cookie on every endpoint except register/login. JSON uses Content-Type: application/json; upload routes use multipart/form-data.

Method + path	Auth	Input	Result / policy
POST /auth/register	no	JSON: name, username, email, password	201 {id}; strict fields; see password policy below
POST /auth/login	no	JSON: email, password	200 {id,token,expires_at}; sets fc_session_token HttpOnly cookie; 401 is generic
GET /auth/me	yes	no body/query	200 {id,name,username,email} session user profile
GET /auth/verify	yes	no body/query	200 {id,name,username,email} session verification endpoint
GET /profiles/me	yes	no body/query	200 {id,name,username,profile_link} for the token user
PUT /profiles/me	yes	multipart: optional name, username, email, password, current_password, file image, remove_image=true|false	200 {id,name,username,profile_link}; registration-style rules on changed text fields; upload replaces picture; remove_image=true clears it; image + remove is invalid
DELETE /profiles/me	yes	JSON: password	200 {message}; removes posts/images, profile picture, SQL row, graph node; clears session cookie; 401 if password is wrong
GET /profiles/:id	yes	no body/query	200 {id,name,username,profile_link}; email/password are never exposed
GET /profiles/image/:filename	yes	no body/query	Authenticated profile picture download
GET /posts	yes	no body/query	200 all posts; ownership does not limit viewing
GET /posts/me	yes	no body/query	200 only posts with author_id = token.user_id; each includes author_username
GET /posts/image/:filename	yes	no body/query	Authenticated image download
POST /posts/create	yes	multipart fields: title, text; optional file image	201 post; author_id always comes from token
PUT /posts/edit?id=<id>	yes + owner	multipart: optional title, text, image, remove_image=true|false	200 updated post; upload replaces image; remove_image=true clears it; image + remove is invalid
DELETE /posts/delete?id=<id>	yes + owner	query: id only	200; deletes only matching id AND author_id and removes stored image
POST /create_relationship?me=<id>&them=<id>	yes	query: me, them only	200; me must equal token user ID

Post objects include author_username and created_at (the database creation timestamp), joined from people.username; the join is left-sided so an orphaned post is not silently omitted.

Input rules

• Any undocumented body or query field returns 400; do not send author_id to create posts.
• Registration: name 1–100 chars; username 1–50, no whitespace; email 1–254, trimmed/lowercased, valid format, no whitespace, not disposable; password 1–128 and at least 12 chars with lower/upper/number/special, no username/email-local-part, common password, triple repeat, or obvious sequence.
• Profile update accepts only name, username, email, password, current_password, and remove_image, plus optional file field image; at least one profile field or picture change is required; changing password requires the current password and re-applies the registration password rules against the resulting username/email.
• Account deletion accepts only password (whitespace preserved, not trimmed); failures use 401 Invalid password.
• Login accepts only email and password; email is trimmed/lowercased; password is not trimmed or otherwise transformed (ordinary whitespace is significant).
• Passwords, hashes, salts, JWTs, and database details must never be logged or exposed.

Uploads

curl -X POST http://localhost:3000/posts/create \
  -H "Authorization: Bearer $TOKEN" \
  -F title='Hello' -F text='Body' -F image=@photo.png

To edit text/title, replace the image, or remove it:

curl -X PUT "http://localhost:3000/posts/edit?id=12" \
  -H "Authorization: Bearer $TOKEN" \
  -F text='Updated body' -F remove_image=true

Omit image and remove_image to keep the current image. Stored image URLs require the same Bearer token.

Profile picture (same file rules as post images):

curl -X PUT http://localhost:3000/profiles/me \
  -H "Authorization: Bearer $TOKEN" \
  -F image=@avatar.png

curl -X PUT http://localhost:3000/profiles/me \
  -H "Authorization: Bearer $TOKEN" \
  -F remove_image=true