☰ DiAstrologer API Docs

Users

8 endpoint(s).

Endpoint Method Summary Auth
/api/v1/users/ POST Create User
/api/v1/users/ GET List Users 🔒
/api/v1/users/by-email/{email} GET Get User By Email 🔒
/api/v1/users/search/ GET Search Users 🔒
/api/v1/users/{user_id} GET Get User 🔒
/api/v1/users/{user_id} PUT Update User 🔒
/api/v1/users/{user_id} DELETE Delete User 🔒
/api/v1/users/{user_id}/update-analysis-time POST Update Analysis Time 🔒

POST /api/v1/users/

Create User

Create a new user profile with birth place.

Rate-limited: 5 submissions per IP per hour to prevent abuse.

NOTE: Email verification is not yet implemented. New accounts are usable immediately. This is documented as a known gap (see CLAUDE.md).

Request body (application/json)

Field Type Required Description
name string yes User's name
email any no Email address
phone any no Phone number
birth_date string yes Birth date (YYYY-MM-DD)
birth_time string yes Birth time (HH:MM)
birth_place string yes Birth place name
birth_latitude number yes Birth place latitude
birth_longitude number yes Birth place longitude
birth_timezone string no Birth place timezone
current_place any no Current place name
current_latitude any no
current_longitude any no
current_timezone any no
preferred_language string no Preferred language (hi/en)

Response 200 — object

Example

curl -X POST 'https://api.example.com/api/v1/users/' \
  -H 'Authorization: Bearer <API_KEY>'

GET /api/v1/users/

List Users

List all users with pagination. ADMIN-ONLY (mass data enumeration prevented).

🔒 Authentication required — send Authorization: Bearer <API_KEY>

Param In Type Required Description
limit query integer no Number of users to return
offset query integer no Number of users to skip

Response 200 — object

Example

curl -X GET 'https://api.example.com/api/v1/users/' \
  -H 'Authorization: Bearer <API_KEY>'

GET /api/v1/users/by-email/{email}

Get User By Email

Get user profile by email. ADMIN-ONLY (email enumeration prevented).

🔒 Authentication required — send Authorization: Bearer <API_KEY>

Param In Type Required Description
email path string yes

Response 200 — object

Example

curl -X GET 'https://api.example.com/api/v1/users/by-email/${email}' \
  -H 'Authorization: Bearer <API_KEY>'

GET /api/v1/users/search/

Search Users

Search users by name, email, or birth place. ADMIN-ONLY (wildcard ILIKE enumeration prevented).

🔒 Authentication required — send Authorization: Bearer <API_KEY>

Param In Type Required Description
q query string yes Search query (name, email, or place)
limit query integer no

Response 200 — object

Example

curl -X GET 'https://api.example.com/api/v1/users/search/' \
  -H 'Authorization: Bearer <API_KEY>'

GET /api/v1/users/{user_id}

Get User

Get user profile by ID.

Auth required. Users can only view their own profile (admins may view any).

🔒 Authentication required — send Authorization: Bearer <API_KEY>

Param In Type Required Description
user_id path integer yes

Response 200 — object

Example

curl -X GET 'https://api.example.com/api/v1/users/${user_id}' \
  -H 'Authorization: Bearer <API_KEY>'

PUT /api/v1/users/{user_id}

Update User

Update user profile.

Auth required. Users can only update their own profile (admins may update any).

🔒 Authentication required — send Authorization: Bearer <API_KEY>

Param In Type Required Description
user_id path integer yes

Request body (application/json)

Field Type Required Description
name any no
email any no
phone any no
birth_date any no
birth_time any no
birth_place any no
birth_latitude any no
birth_longitude any no
birth_timezone any no
current_place any no
current_latitude any no
current_longitude any no
current_timezone any no
preferred_language any no

Response 200 — object

Example

curl -X PUT 'https://api.example.com/api/v1/users/${user_id}' \
  -H 'Authorization: Bearer <API_KEY>'

DELETE /api/v1/users/{user_id}

Delete User

Delete user profile.

Auth required. Users can only delete their own profile (admins may delete any).

🔒 Authentication required — send Authorization: Bearer <API_KEY>

Param In Type Required Description
user_id path integer yes

Response 200 — object

Example

curl -X DELETE 'https://api.example.com/api/v1/users/${user_id}' \
  -H 'Authorization: Bearer <API_KEY>'

POST /api/v1/users/{user_id}/update-analysis-time

Update Analysis Time

Update the last_analysis_at timestamp for a user. Called after each PDAE or Karma analysis.

Auth required. Users can only touch their own timestamp (admins may touch any).

🔒 Authentication required — send Authorization: Bearer <API_KEY>

Param In Type Required Description
user_id path integer yes

Response 200 — object

Example

curl -X POST 'https://api.example.com/api/v1/users/${user_id}/update-analysis-time' \
  -H 'Authorization: Bearer <API_KEY>'