API Documentation

API Documentation

📖 Afaqy Knowledge Base / AVL / Resources / Events / API Documentation

Base URL:

https://api.afaqy.sa

Authentication:

All endpoints require a valid JWT Bearer token in the header:

Authorization: Bearer <your_jwt_token>

1. Create Event

Create a new event.

POST /events

Request Body:

{
  "title": "string",
  "description": "string",
  "start_date": "YYYY-MM-DD HH:mm:ss",
  "end_date": "YYYY-MM-DD HH:mm:ss",
  "location": "string",
  "metadata": {
    "...": "..."
  }
}

Success Response:

  • 201 Created
{
  "status": "success",
  "message": "Event created successfully",
  "data": {
    "event_id": "string"
  }
}

Errors:

  • 400 – Bad Request
  • 401 – Unauthorized
  • 422 – Validation Errors

2. Edit Event

Update details of an existing event.

PUT /events/{event_id}

Path Parameters:

Name
Type
Required
Description
event_id
string
Yes
The ID of the event to update

Request Body:

{
  "title": "string",
  "description": "string",
  "start_date": "YYYY-MM-DD HH:mm:ss",
  "end_date": "YYYY-MM-DD HH:mm:ss",
  "location": "string",
  "metadata": {
    "...": "..."
  }
}

Success Response:

  • 200 OK
{
  "status": "success",
  "message": "Event updated successfully",
  "data": null}

Errors:

  • 400 – Bad Request
  • 401 – Unauthorized
  • 404 – Event Not Found
  • 422 – Validation Errors

3. Delete Event

Remove an event by ID.

DELETE /events/{event_id}

Path Parameters:

Name
Type
Required
Description
event_id
string
Yes
ID of the event to delete

Success Response:

  • 204 No Content

Errors:

  • 401 – Unauthorized
  • 404 – Not Found

4. List Events

Get a list of events, with optional filtering & pagination.

GET /events

Query Parameters (Optional):

Name
Type
Description
page
int
Page number (default: 1)
limit
int
Items per page (default: 20)
start_date
string
Filter events starting after date
end_date
string
Filter events ending before date

Success Response:

  • 200 OK

Errors:

  • 401 – Unauthorized

5. View Event

Get details of a single event.

GET /events/{event_id}

Path Parameters:

Name
Type
Required
Description
event_id
string
Yes
ID of the event

Success Response:

  • 200 OK
{
  "status": "success",
  "data": {
    "event_id": "string",
    "title": "string",
    "description": "string",
    "start_date": "datetime",
    "end_date": "datetime",
    "location": "string",
    "metadata": { ... }
  }
}

Errors:

  • 401 – Unauthorized
  • 404 – Not Found

Response & Error Standards

All responses follow a common JSON structure:

Success Wrapper

{
  "status": "success",
  "data": { ... },
  "message": "Optional descriptive message"
}

Error Wrapper

{
  "status": "error",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

🔐 Headers Example

Accept: application/json
Content-Type: application/json
Authorization: Bearer <JWT_TOKEN>