NTBC API Docs

📖

NTBC REST API

National TB Conference — Conference Management API

Base URL

https://api.nationaltbconference.org/api

Version

1.0

Framework

Laravel 12

Auth

Sanctum Bearer

Format

JSON

Environment

production

Base URL All endpoints are relative to https://api.nationaltbconference.org/api. Include Content-Type: application/json on every request.

🔑

Authentication

This API uses Laravel Sanctum Bearer token authentication. Tokens are returned from /api/login and must be included in the Authorization header on all protected routes.

# Include this header on every protected request Authorization: Bearer {your_token}

Storage The frontend stores tokens in localStorage under the key auth_token. Tokens do not expire by time — they are revoked on logout.

Roles

Role	Access Level
user	Authenticated authors — submit and manage own abstracts
reviewer	Review assigned abstracts, submit scores
board	View all approved abstracts and rankings
admin	Full access to all endpoints

⚠️

Error Responses

Code	Meaning
200 OK	Success
201 Created	Resource created
401 Unauthorized	Missing or invalid Bearer token
403 Forbidden	Valid token but insufficient role
422 Unprocessable	Validation failed — check `errors` object
404 Not Found	Resource does not exist
500 Server Error	Check `storage/logs/laravel.log`

// 422 Validation error shape { "message": "The given data was invalid.", "errors": { "email": ["The email field is required."] } }

🌐

Public Endpoints

No authentication required

GET /api/health API health check ›

⬤ No auth required

Returns the current status of the API. Useful for uptime monitoring and deployment verification.

Response

200 OK

{ "status": "ok", "api": "NationalTBConference", "version": "1.0", "env": "production", "time": "2026-04-27T10:00:00+00:00" }

POST /api/register Author self-registration ›

⬤ No auth required

Registers a new author account. The account is assigned the user role by default.

Body

Response

Field	Type	Required	Description
name	string	required	Full name
email	string	required	Unique email address
password	string	required	Min 8 characters
password_confirmation	string	required	Must match password

{ "name": "Jane Doe", "email": "jane@example.com", "password": "secret123", "password_confirmation": "secret123" }

201 Created

{ "message": "User created successfully", "user": { "id": 42, "name": "Jane Doe", "email": "jane@example.com", "role": "user" } }

POST /api/login Obtain bearer token ›

⬤ No auth required

Authenticates a user and returns a Sanctum bearer token along with user details.

Body

Response

Field	Type	Required	Description
email	string	required	Registered email
password	string	required	Account password

{ "email": "jane@example.com", "password": "secret123" }

POST /api/participant Register as participant ›

⬤ No auth required

Registers a conference participant (non-author). No account is created — the record is stored for attendance tracking.

Body

Response

{ "name": "John Smith", "email": "john@example.com", "institution": "University of Nairobi", "phone": "+254712345678" }

201 Created

{ "message": "Participant registered successfully" }

POST /api/password/email Send password reset link ›

⬤ No auth required

Sends a password reset link to the provided email address if an account exists.

Body

{ "email": "jane@example.com" }

🔐

Authenticated Endpoints

All roles — requires Bearer token

POST /api/logout Revoke current token ›

🔒 Bearer token

Revokes the current Sanctum token. No request body required.

Response

200 OK

{ "message": "Logged out successfully" }

GET /api/user-profile Current user profile ›

🔒 Bearer token

Returns the authenticated user's full profile.

Response

200 OK

{ "id": 42, "name": "Jane Doe", "email": "jane@example.com", "role": "user", "institution": "University of Nairobi", "status": "active", "created_at": "2026-01-15T08:00:00Z" }

GET /api/notifications List notifications ›

🔒 Bearer token

Returns all notifications for the authenticated user. Related actions: PUT /notifications/read-all, PUT /notifications/{id}/read, DELETE /notifications/{id}.

Response

200 OK

[ { "id": 7, "message": "Your abstract has been approved.", "read": false, "created_at": "2026-04-20T12:00:00Z" } ]

GET /api/thematics List thematic areas ›

🔒 Bearer token

Returns all thematic areas available for abstract submission.

Response

200 OK

[ { "id": 1, "name": "TB Diagnosis" }, { "id": 2, "name": "Drug Resistance" } ]

✍️

Abstract Submission

Roles: user · admin

POST /api/store-abstract Submit a new abstract ›

🎭 user · admin

Submits a new abstract for review. Returns the created abstract with its generated abstract ID.

Body

Response

Field	Type	Required	Description
title	string	required	Abstract title
authors	string	required	Author names
thematic_id	integer	required	Thematic area ID
abstract	string	required	Abstract body text (max 300 words)
presentation_type	string	optional	oral / poster

{ "title": "TB Drug Resistance in Eastern Africa", "authors": "Jane Doe, John Smith", "thematic_id": 2, "abstract": "Background: Drug-resistant TB remains...", "presentation_type": "oral" }

201 Created

{ "message": "Abstract submitted successfully", "abstract_id": "NTBC-2026-001", "id": 15 }

GET /api/author_abstracts My abstracts (paginated) ›

🎭 user · admin

Returns paginated abstracts submitted by the authenticated user.

Response

200 OK

{ "data": [ { "id": 15, "abstract_id": "NTBC-2026-001", "title": "TB Drug Resistance in Eastern Africa", "status": "pending", "created_at": "2026-04-01T09:00:00Z" } ], "current_page": 1, "last_page": 3, "total": 12 }

GET /api/abstract/{id} View own abstract ›

🎭 user · admin

Returns the full detail of a single abstract owned by the authenticated user. Returns 403 if the abstract belongs to another user.

PUT /api/abstract/{id} Update abstract ›

🎭 user · admin

Updates a draft or pending abstract. Same fields as POST /store-abstract. Cannot edit once status is approved.

DELETE /api/delete-abstract/{id} Delete abstract ›

🎭 user · admin

Permanently deletes an abstract owned by the authenticated user.

Response

200 OK

{ "message": "Abstract deleted successfully" }

🔎

Reviewer Endpoints

Roles: reviewer · admin

GET /api/get-assignedabstracts My assigned abstracts ›

🎭 reviewer · admin

Returns all abstracts assigned to the authenticated reviewer for review.

POST /api/update-abstract/{id} Update review status ›

🎭 reviewer · admin

Updates the review status of an assigned abstract.

Body

{ "status": "approved", // approved | rejected | pending "comments": "Well structured and relevant." }

POST /api/submit-score/{id} Submit abstract score ›

🎭 reviewer · admin

Submits a numeric score for the given abstract. Scores feed into the ranked list used by board members.

Body

Response

{ "score": 85, // 0–100 "remarks": "Excellent methodology." }

201 Created

{ "message": "Score submitted", "score": 85 }

📋

Board Member Endpoints

Roles: board · admin

GET /api/all-approved-abstracts All approved abstracts ›

🎭 board · admin

Returns all abstracts with an approved status across all reviewers.

GET /api/ranked-abstracts Abstracts ranked by score ›

🎭 board · admin

Returns approved abstracts sorted by average reviewer score (highest first).

Response

200 OK

[ { "id": 15, "abstract_id": "NTBC-2026-001", "title": "TB Drug Resistance in Eastern Africa", "avg_score": 88.5, "rank": 1 } ]

👥

Admin — User Management

Role: admin only

GET /api/view-authors List all authors ›

🛡 Admin only

Returns all users with the user role. See also GET /view-reviewers, GET /assing-reviewers.

POST /api/reg-user Create user (admin) ›

🛡 Admin only

Creates a new user with a specified role. Unlike /register, this allows setting any role.

Body

{ "name": "Dr. Alice", "email": "alice@example.com", "password": "secret123", "role": "reviewer" // user | reviewer | board | admin }

PUT /api/update-user/{id} Update user ›

🛡 Admin only

Updates user details or role. All fields are optional.

DELETE /api/delete-user/{id} Delete user ›

🛡 Admin only

Permanently deletes a user account.

PATCH /api/users/{id}/deactivate Deactivate / reactivate user ›

🛡 Admin only

Toggles a user's active status. Deactivated users cannot log in.

📄

Admin — Abstract Management

Role: admin only

GET /api/view-abstracts All abstracts ›

🛡 Admin only

Returns every abstract in the system regardless of status or author.

POST /api/store-assignabstract Assign abstract to reviewer ›

🛡 Admin only

Assigns an abstract to a reviewer for evaluation.

Body

{ "abstract_id": 15, "reviewer_id": 8 }

GET /api/abstract-pdf/{id} Download abstract PDF ›

🛡 Admin only

Generates and returns a PDF for the given abstract. Response Content-Type is application/pdf.

📊

Admin — Reports & Exports

Role: admin only

GET /api/summary-stats Summary statistics ›

🛡 Admin only

Returns dashboard aggregate counts: users, abstracts by status, participants, reviewers.

Response

200 OK

{ "total_users": 120, "total_abstracts": 85, "pending_abstracts": 20, "approved_abstracts": 55, "rejected_abstracts": 10, "total_participants": 340, "total_reviewers": 15 }

GET /api/export/abstracts Export abstracts CSV ›

🛡 Admin only

Downloads all abstracts as a CSV file. Related: GET /export/ranked, GET /export/participants, GET /export/reviewer-report.

POST /api/broadcast-email Send broadcast email ›

🛡 Admin only

Sends a bulk email to all users or a specific group.

Body

{ "subject": "Conference Reminder", "message": "The conference opens on 15 May 2026...", "target": "all" // all | authors | reviewers }

⚙️

Admin — Portal Settings

Role: admin only

GET /api/settings Get all settings ›

🛡 Admin only

Returns all portal settings as a key-value map.

Response

200 OK

{ "submission_open": "true", "conference_date": "2026-05-15", "max_word_count": "300" }

PUT /api/settings Bulk update settings ›

🛡 Admin only

Updates multiple settings in a single request.

Body

{ "settings": [ { "key": "submission_open", "value": "false" }, { "key": "conference_date", "value": "2026-05-20" } ] }

PUT /api/settings/{key} Update single setting ›

🛡 Admin only

Updates a single setting by its key. Creates the key if it does not exist.

Body

{ "value": "true" }