Admin API Endpoints Documentation¶
This document describes all custom admin-facing API endpoints for the AzharStore Medusa v2 backend.
Base URL¶
Authentication¶
All admin endpoints require a valid Medusa admin JWT token. Include the token in the Authorization header:
Tokens are obtained by logging into the Medusa admin dashboard at /app.
Endpoints¶
Advertisement Endpoints¶
GET /admin/advertisements¶
Lists all advertisements.
Request
Response (200 OK)
{
"advertisements": [
{
"id": "string",
"title": "string | null",
"image_url": "string",
"link_url": "string | null",
"location": "string",
"display_order": number,
"is_active": boolean,
"created_at": "string (ISO 8601)"
}
],
"count": number
}
Error Response (401 Unauthorized)
Example
POST /admin/advertisements¶
Creates a new advertisement.
Request
Request Body
{
"title": "string | null",
"image_url": "string (required)",
"link_url": "string | null",
"location": "string (default: home_slider)",
"display_order": number (default: 0),
"is_active": boolean (default: true)
}
Response (201 Created)
{
"advertisement": {
"id": "string",
"title": "string | null",
"image_url": "string",
"link_url": "string | null",
"location": "string",
"display_order": number,
"is_active": boolean,
"created_at": "string (ISO 8601)"
}
}
Error Response (400 Bad Request)
Example
curl -X POST http://localhost:9000/admin/advertisements \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"title": "Summer Sale",
"image_url": "https://example.com/banner.jpg",
"link_url": "https://example.com/sale",
"location": "home_slider",
"display_order": 1,
"is_active": true
}'
PATCH /admin/advertisements/:id¶
Updates an existing advertisement.
Request
Request Body
{
"title": "string | null",
"image_url": "string",
"link_url": "string | null",
"location": "string",
"display_order": number,
"is_active": boolean
}
Response (200 OK)
{
"advertisement": {
"id": "string",
"title": "string | null",
"image_url": "string",
"link_url": "string | null",
"location": "string",
"display_order": number,
"is_active": boolean,
"created_at": "string (ISO 8601)"
}
}
Example
curl -X PATCH http://localhost:9000/admin/advertisements/ad_123 \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"is_active": false}'
DELETE /admin/advertisements/:id¶
Deletes an advertisement.
Request
Response (204 No Content)
Example
curl -X DELETE http://localhost:9000/admin/advertisements/ad_123 \
-H "Authorization: Bearer <token>"
Settings Endpoints¶
GET /admin/settings¶
Lists all settings.
Request
Response (200 OK)
{
"settings": {
"free_delivery_threshold": "string",
"pickup_message": "string | null",
"ceo_whatsapp": "string | null"
}
}
Example
PATCH /admin/settings¶
Bulk updates settings.
Request
Request Body
{
"settings": {
"free_delivery_threshold": "string",
"pickup_message": "string | null",
"ceo_whatsapp": "string | null"
}
}
Response (200 OK)
{
"settings": {
"free_delivery_threshold": "string",
"pickup_message": "string | null",
"ceo_whatsapp": "string | null"
}
}
Error Response (400 Bad Request)
Example
curl -X PATCH http://localhost:9000/admin/settings \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"settings": {
"free_delivery_threshold": "1500",
"pickup_message": "Ready in 30 minutes",
"ceo_whatsapp": "+97387654321"
}
}'
Translation Endpoints¶
GET /admin/translations¶
Lists all translations.
Request
Response (200 OK)
{
"translations": [
{
"id": "string",
"language_code": "string",
"key": "string",
"value": "string",
"section": "string | null"
}
]
}
Example
POST /admin/translations¶
Creates a new translation.
Request
Request Body
{
"language_code": "string (default: ar)",
"key": "string (required)",
"value": "string (required)",
"section": "string | null"
}
Response (201 Created)
{
"translation": {
"id": "string",
"language_code": "string",
"key": "string",
"value": "string",
"section": "string | null"
}
}
Error Response (400 Bad Request)
Example
curl -X POST http://localhost:9000/admin/translations \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"language_code": "ar",
"key": "add_to_cart",
"value": "أضف إلى السلة",
"section": "product"
}'
PATCH /admin/translations/:id¶
Updates an existing translation.
Request
Request Body
Response (200 OK)
{
"translation": {
"id": "string",
"language_code": "string",
"key": "string",
"value": "string",
"section": "string | null"
}
}
Example
curl -X PATCH http://localhost:9000/admin/translations/trans_123 \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"value": "أضف للسلة"}'
DELETE /admin/translations/:id¶
Deletes a translation.
Request
Response (204 No Content)
Example
curl -X DELETE http://localhost:9000/admin/translations/trans_123 \
-H "Authorization: Bearer <token>"
Error Handling¶
All admin endpoints follow consistent error handling:
- 200 OK: Successful request
- 201 Created: Successful creation (POST)
- 204 No Content: Successful deletion
- 400 Bad Request: Invalid input or validation error
- 401 Unauthorized: Missing or invalid authentication token
- 500 Internal Server Error: Server-side error
Error responses always include:
- error: Error code or type
- message: Human-readable error message
Authentication Details¶
Obtaining a Token¶
- Navigate to the Medusa admin dashboard at
http://localhost:9000/app - Log in with admin credentials (from
MEDUSA_ADMIN_EMAILandMEDUSA_ADMIN_PASSWORD) - The dashboard will handle token management automatically
- For API access, you may need to extract the token from browser storage or use the dashboard's API client
Token Format¶
Tokens are JWT (JSON Web Tokens) signed with the JWT_SECRET from environment variables.
Token Expiration¶
Tokens expire according to Medusa's default configuration. Re-authenticate when receiving 401 errors.
CORS¶
Admin endpoints are configured to accept requests from origins specified in the ADMIN_CORS environment variable.
Rate Limiting¶
No rate limiting is currently implemented. Consider adding rate limiting for admin operations in production.