{"openapi":"3.1.0","info":{"title":"Sithmini API","version":"1.0.0","description":"Public search plus the versioned /api/v1 JSON API used by the Sithmini mobile apps. v1 responses use a `{ data }` / `{ error: { code, message } }` envelope."},"servers":[{"url":"http://www.sithmini.com"}],"components":{"securitySchemes":{"sessionCookie":{"type":"apiKey","in":"cookie","name":"better-auth.session_token","description":"Web session cookie set by /api/auth/*."},"bearerToken":{"type":"http","scheme":"bearer","description":"Session token for native clients — returned in the `set-auth-token` header on sign-in via /api/auth/*."}},"schemas":{"ApiError":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","BAD_REQUEST","UNAUTHENTICATED","FORBIDDEN","NOT_FOUND","METHOD_NOT_ALLOWED","CONFLICT"]},"message":{"type":"string"}}}}}}},"paths":{"/api/v1/me":{"get":{"operationId":"v1GetMe","summary":"Current user and a summary of their matrimony profiles","security":[{"sessionCookie":[]},{"bearerToken":[]}],"responses":{"200":{"description":"User + matrimony profile summaries","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object"}}}}}},"401":{"description":"Sign in required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/matrimony/profiles":{"get":{"operationId":"v1BrowseMatrimonyProfiles","summary":"Browse ACTIVE matrimony profiles","description":"Same filters and visibility rules as /matrimony/browse. Signed-in callers never see their own profiles and receive match scores + saved ids.","security":[{},{"sessionCookie":[]},{"bearerToken":[]}],"parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Free-text query; recognised keywords become filters, the rest is full-text searched."},{"name":"gender","in":"query","required":false,"schema":{"type":"string"},"description":"MALE | FEMALE. Defaults to the opposite of the caller's active profile."},{"name":"religion","in":"query","required":false,"schema":{"type":"string"},"description":"Religion code"},{"name":"ethnicity","in":"query","required":false,"schema":{"type":"string"},"description":"Ethnicity code"},{"name":"civilStatus","in":"query","required":false,"schema":{"type":"string"},"description":"Civil status code"},{"name":"education","in":"query","required":false,"schema":{"type":"string"},"description":"Education level code"},{"name":"district","in":"query","required":false,"schema":{"type":"string"},"description":"Sri Lankan district"},{"name":"country","in":"query","required":false,"schema":{"type":"string"},"description":"Country of residence, or `overseas` for anything outside Sri Lanka"},{"name":"minAge","in":"query","required":false,"schema":{"type":"integer"},"description":"Minimum age"},{"name":"maxAge","in":"query","required":false,"schema":{"type":"integer"},"description":"Maximum age"},{"name":"foodPreference","in":"query","required":false,"schema":{"type":"string"},"description":"Food preference code"},{"name":"drinking","in":"query","required":false,"schema":{"type":"string"},"description":"Drinking habit code"},{"name":"smoking","in":"query","required":false,"schema":{"type":"string"},"description":"Smoking habit code"},{"name":"nakshatra","in":"query","required":false,"schema":{"type":"string"},"description":"Birth star"},{"name":"rashi","in":"query","required":false,"schema":{"type":"string"},"description":"Moon sign"},{"name":"hasHoroscope","in":"query","required":false,"schema":{"type":"string","enum":["1"]},"description":"`1` to require a horoscope"},{"name":"verified","in":"query","required":false,"schema":{"type":"string","enum":["1"]},"description":"`1` to require a verified profile"},{"name":"postedBy","in":"query","required":false,"schema":{"type":"string"},"description":"Posted-by code (SELF, PARENT, ...)"},{"name":"profile","in":"query","required":false,"schema":{"type":"string"},"description":"Which of the caller's own profiles to act as. Defaults to the first eligible one."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":60,"default":30},"description":"Page size"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0},"description":"Page offset"}],"responses":{"200":{"description":"Profiles, applied filters, match scores and paging","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/matrimony/profiles/{id}":{"get":{"operationId":"v1GetMatrimonyProfile","summary":"Profile detail","description":"Same rules as /matrimony/listing/:id: only ACTIVE profiles; contact and photos reveal per owner settings or mutual acceptance; similar profiles exclude the caller's own.","security":[{},{"sessionCookie":[]},{"bearerToken":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Profile id"}],"responses":{"200":{"description":"Profile, similar profiles and the caller's interest state","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/matrimony/suggestions":{"get":{"operationId":"v1GetMatrimonySuggestions","summary":"Top matches for one of the caller's active profiles","security":[{"sessionCookie":[]},{"bearerToken":[]}],"parameters":[{"name":"profile","in":"query","required":false,"schema":{"type":"string"},"description":"Which of the caller's own profiles to act as. Defaults to the first eligible one."}],"responses":{"200":{"description":"Suggestions + the profile they were computed for","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object"}}}}}},"401":{"description":"Sign in required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/matrimony/my-profiles":{"get":{"operationId":"v1GetMyMatrimonyProfiles","summary":"The caller's own profiles (or the active org's)","security":[{"sessionCookie":[]},{"bearerToken":[]}],"responses":{"200":{"description":"Profiles, new outside-proposal count, org name","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object"}}}}}},"401":{"description":"Sign in required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/matrimony/interests":{"get":{"operationId":"v1GetMatrimonyInterests","summary":"Received and sent interests for one of the caller's profiles","security":[{"sessionCookie":[]},{"bearerToken":[]}],"parameters":[{"name":"profile","in":"query","required":false,"schema":{"type":"string"},"description":"Which of the caller's own profiles to act as. Defaults to the first eligible one."}],"responses":{"200":{"description":"received[], sent[], profiles[], activeProfileId","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object"}}}}}},"401":{"description":"Sign in required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"operationId":"v1MutateMatrimonyInterest","summary":"Send, accept/decline or withdraw an interest","security":[{"sessionCookie":[]},{"bearerToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["intent","fromProfileId","toProfileId"],"properties":{"intent":{"const":"express"},"fromProfileId":{"type":"string"},"toProfileId":{"type":"string"},"message":{"type":"string","maxLength":2000}}},{"type":"object","required":["intent","interestId","status"],"properties":{"intent":{"const":"respond"},"interestId":{"type":"string"},"status":{"type":"string","enum":["ACCEPTED","DECLINED"]}}},{"type":"object","required":["intent","interestId"],"properties":{"intent":{"const":"withdraw"},"interestId":{"type":"string"}}}]}}}},"responses":{"200":{"description":"Responded / withdrawn","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object"}}}}}},"201":{"description":"Interest sent (with compatibility when both have horoscopes)","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Sign in required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/matrimony/chat/threads":{"get":{"operationId":"v1GetMatrimonyChatThreads","summary":"The caller's matrimony chat threads","security":[{"sessionCookie":[]},{"bearerToken":[]}],"responses":{"200":{"description":"threads[] with other party + unread count","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object"}}}}}},"401":{"description":"Sign in required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/matrimony/chat/threads/{id}/messages":{"get":{"operationId":"v1GetMatrimonyChatMessages","summary":"Messages in a thread the caller participates in","security":[{"sessionCookie":[]},{"bearerToken":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Thread id"},{"name":"before","in":"query","required":false,"schema":{"type":"string"},"description":"Cursor: messages older than this message id"},{"name":"after","in":"query","required":false,"schema":{"type":"string"},"description":"Cursor: messages newer than this message id"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Page size"}],"responses":{"200":{"description":"messages[]","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Sign in required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"operationId":"v1SendMatrimonyChatMessage","summary":"Send a message","security":[{"sessionCookie":[]},{"bearerToken":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Thread id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["body"],"properties":{"body":{"type":"string","minLength":1,"maxLength":5000}}}}}},"responses":{"201":{"description":"messageId, createdAt","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Sign in required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/search":{"get":{"operationId":"searchTakListings","summary":"Search public tak.lk listings","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"Search terms, such as 'Toyota Corolla Colombo'."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20}}],"responses":{"200":{"description":"Structured search results","headers":{"Cache-Control":{"description":"Public cache policy for agent-heavy read traffic.","schema":{"type":"string"}},"ETag":{"description":"Weak validator based on query, limit, origin, result IDs, verticals, and timestamps.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["query","total","results"],"properties":{"query":{"type":"string"},"total":{"type":"integer"},"results":{"type":"array","items":{"type":"object","required":["id","title","vertical","verticalLabel","url","postedAt"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"vertical":{"type":"string"},"verticalLabel":{"type":"string"},"price":{"type":["integer","null"]},"priceSuffix":{"type":["string","null"]},"currency":{"type":["string","null"],"enum":["LKR",null]},"district":{"type":"string"},"city":{"type":"string"},"category":{"type":["string","null"]},"thumbnail":{"type":["string","null"],"format":"uri"},"url":{"type":"string","format":"uri"},"postedAt":{"type":"string","format":"date-time"}}}}}}}}},"304":{"description":"Search results are unchanged for the supplied If-None-Match validator.","headers":{"Cache-Control":{"schema":{"type":"string"}},"ETag":{"schema":{"type":"string"}}}},"400":{"description":"Missing or invalid query"}}}}}}