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

{
  "status": "success",
  "data": [
    {
      "event_id": "string",
      "title": "string",
      "start_date": "datetime",
      "end_date": "datetime",
      "location": "string"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 135
  }
}

Errors:

401 – Unauthorized

5. View Event

Get details of a single event.

GET /events/{event_id}

Path Parameters:

| --- | --- | --- | --- |

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>