API Documentation

Welcome to the API documentation. This API allows you to programmatically access your data and perform CRUD (Create, Read, Update, Delete) operations.

Authentication

Every request to the API must be authenticated. This is done via an API Key.

1. Generate API Key: Each user can generate, copy, or delete a personal API key in their profile under My Profile > REST API.

2. Use API Key: The key must be sent with every request in the Authorization header as a "Bearer Token".

   Header Format:

   Authorization: Bearer <YOUR_API_KEY>

   Replace <YOUR_API_KEY> with the key from your user profile.

Endpoints

All endpoints are accessible via the URL .../api/v1.php. The specific action is controlled by the action parameter in the URL.

1. List Records

Reads a list of records from a specific table, with support for filtering, searching, sorting, and pagination.

• Method: GET
• URL: /api/v1.php?action=list_records&table_id=<TABLE_ID>
• Permission: can_view for the target table is required.

URL Parameters

Example Request (cURL)

curl -X GET "https://your-domain.com/api/v1.php?action=list_records&table_id=11&search=important&filter[status]=open&sort_col=priority&sort_dir=DESC&page=1&limit=10" \
     -H "Authorization: Bearer <YOUR_API_KEY>"

Success Response (200 OK)

Returns a JSON object with pagination info and a list of found records.

{
    "pagination": {
        "total_records": 25,
        "total_pages": 3,
        "current_page": 1,
        "limit": 10
    },
    "data": [
        {
            "id": 123,
            "status": "open",
            "priority": "high",
            "title": "Very important task"
        }
    ]
}

2. Read Single Record

Reads a single record from a specific table.

• Method: GET
• URL: /api/v1.php?action=get_record&table_id=<TABLE_ID>&id=<RECORD_ID>
• Permission: can_view for the target table is required.

URL Parameters

Example Request (cURL)

curl -X GET "https://your-domain.com/api/v1.php?action=get_record&table_id=11&id=123" \
     -H "Authorization: Bearer <YOUR_API_KEY>"

Success Response (200 OK)

Returns a JSON object containing all fields of the record.

{
    "id": 123,
    "created_at": "2023-10-27 10:00:00",
    "updated_at": "2023-10-27 10:05:00",
    "created_by_user_id": 5,
    "version": 1,
    "field_name_1": "Value 1",
    "field_name_2": 42
}

Error Responses

• 400 Bad Request: If table_id or id are missing.
• 403 Forbidden: If you do not have can_view permission for this table.
• 404 Not Found: If the record does not exist.

3. Create Record

Creates a new record in a specific table.

• Method: POST
• URL: /api/v1.php?action=create_record&table_id=<TABLE_ID>
• Permission: can_add for the target table is required.

URL Parameters

Request Body

The body of the request must contain a JSON object with the field names (technical names) and their corresponding values as key-value pairs.

{
    "field_name_1": "New Value",
    "field_name_2": 123.45,
    "checkbox_field": 1
}

Example Request (cURL)

curl -X POST "https://your-domain.com/api/v1.php?action=create_record&table_id=11" \
     -H "Authorization: Bearer <YOUR_API_KEY>" \
     -H "Content-Type: application/json" \
     -d '{"field_name_1": "New Value", "field_name_2": 123.45}'

Success Response (201 Created)

Returns the ID of the newly created record.

{
    "success": true,
    "message": "Record created successfully.",
    "id": 124
}

Error Responses

• 400 Bad Request: If table_id or a valid JSON body is missing.
• 403 Forbidden: If you do not have can_add permission for this table.
• 500 Internal Server Error: If the database insert fails.

4. Update Record

Updates one or more fields of an existing record.

• Method: POST
• URL: /api/v1.php?action=update_record&table_id=<TABLE_ID>&id=<RECORD_ID>
• Permission: can_edit for the target table is required.

URL Parameters

Request Body

The body of the request must contain a JSON object with only the fields to be changed and their new values.

{
    "field_name_1": "Updated Value",
    "status_field": "Done"
}

Example Request (cURL)

curl -X POST "https://your-domain.com/api/v1.php?action=update_record&table_id=11&id=123" \
     -H "Authorization: Bearer <YOUR_API_KEY>" \
     -H "Content-Type: application/json" \
     -d '{"status_field": "Done"}'

Success Response (200 OK)

Returns a success message and the number of affected rows.

{
    "success": true,
    "message": "Record updated successfully.",
    "affected_rows": 1
}

Error Responses

• 400 Bad Request: If table_id, id, or a valid JSON body is missing.
• 403 Forbidden: If you do not have can_edit permission for this table.
• 500 Internal Server Error: If the database update fails.

5. Delete Record

Moves a record to the trash (soft-delete). The record is not permanently deleted.

• Method: POST
• URL: /api/v1.php?action=delete_record&table_id=<TABLE_ID>&id=<RECORD_ID>
• Permission: can_delete for the target table is required.

URL Parameters

Example Request (cURL)

curl -X POST "https://your-domain.com/api/v1.php?action=delete_record&table_id=11&id=123" \
     -H "Authorization: Bearer <YOUR_API_KEY>" \

Success Response (200 OK)

Returns a success message.

{
    "success": true,
    "message": "Record archived successfully."
}

Error Responses

• 403 Forbidden: If you do not have can_delete permission for this table.
• 500 Internal Server Error: If the record could not be archived (e.g., because it was already archived).