Documentation

REST API reference

Laravel JSON API for the Fikra Shariqa Innovation Challenge. Base URL:

/api

Send Accept: application/json on every request.
Public routes need no token. Admin routes need Sanctum Bearer auth.
Allowed dropdown values come from GET /options.

Authentication

Call POST /login, then send the token on protected endpoints:

Authorization: Bearer 1|your-token

Default local admin: admin@shams.ae / Shams@2026

Errors

Validation failures return HTTP 422:

{
  "message": "The email field is required. (and 1 more error)",
  "errors": {
    "email": ["The email field is required."],
    "password": ["The password field is required."]
  }
}

401 unauthenticated · 404 missing record or file · 201 created on register.

Public

GET/optionsPublic

Form dropdown values

Returns bilingual (EN/AR) option lists used by the registration form: nationalities, roles, skillsets, themes, statuses, and more.

cURL

curl /api/options

Response

{
  "age_groups": [{ "value": "18-24", "en": "18–24", "ar": "18–24" }],
  "genders": [{ "value": "female", "en": "Female", "ar": "أنثى" }],
  "nationalities": [{ "value": "AE", "en": "Emirati", "ar": "إماراتي" }],
  "current_roles": [...],
  "skillsets": [...],
  "challenge_themes": [...],
  "starting_points": [...],
  "application_types": [...],
  "weekend_commitments": [...],
  "hear_about": [...],
  "statuses": [...]
}

POST/registerPublic

Submit a registration

Public application endpoint. Send JSON, or multipart/form-data when uploading a pitch deck or prototype. skillsets may be sent as skillsets[] or a JSON array string. Email must be unique.

Body fields

Field	Type	Required	Notes
locale	en \| ar	No	UI language used to submit
full_name	string	Yes	Max 150
email	email	Yes	Unique
mobile_number	string	Yes	Include country code, e.g. +9715...
nationality	string	Yes	Value from /options nationalities
city_emirate	string	Yes	Max 120
age_group	string	No	Optional. 18-24 \| 25-34 \| 35-44 \| 45-54 \| 55+
gender	string	Yes	female \| male \| prefer_not_to_say
linkedin_url	url	No	Optional
current_role	string	Yes	Value from /options current_roles
organization_name	string	Yes	Company, newsroom, or university
field_of_study	string	Yes	Industry or field of study
skillsets	string[]	Yes	At least one value from /options skillsets
challenge_theme	string	Yes	Value from /options challenge_themes
starting_point	string	Yes	build_new \| early_idea \| prototype_mvp \| existing_product
idea_description	string	No	Optional one-liner. Hidden in UI when starting_point is build_new
application_type	string	Yes	solo \| partial_team \| full_team \| organization
teammates	string	No	Optional names/emails for team or org applications
motivation	string	Yes	Max 300 words
weekend_commitment	string	Yes	yes \| no \| not_sure
hear_about	string	Yes	Value from /options hear_about
confirm_accurate	boolean	Yes	Must be accepted (true / 1)
agree_terms	boolean	Yes	Must be accepted (true / 1)
receive_updates	boolean	No	Optional SHAMS marketing opt-in

Files

Field	Type	Required	Notes
pitch_deck	file	No	Optional. pdf, ppt, pptx, doc, docx, key. Max 20MB (PHP upload limit may be lower)
prototype	file	No	Optional. pdf, ppt, pptx, doc, docx, zip, mp4, mov, png, jpg, jpeg, webm. Max 50MB

cURL

curl -X POST /api/register \
  -H "Accept: application/json" \
  -F "locale=en" \
  -F "full_name=Aisha Al Qasimi" \
  -F "email=aisha@example.com" \
  -F "mobile_number=+971501234567" \
  -F "nationality=AE" \
  -F "city_emirate=Sharjah" \
  -F "gender=female" \
  -F "current_role=content_creator" \
  -F "organization_name=SHAMS Studio" \
  -F "field_of_study=Media" \
  -F "skillsets[]=content_creation" \
  -F "skillsets[]=ai_ml" \
  -F "challenge_theme=media_trust" \
  -F "starting_point=early_idea" \
  -F "idea_description=A trust layer for newsrooms" \
  -F "application_type=solo" \
  -F "motivation=I want to build responsible media tools for Sharjah." \
  -F "weekend_commitment=yes" \
  -F "hear_about=shams_network" \
  -F "confirm_accurate=1" \
  -F "agree_terms=1"

Response

{
  "message": "Registration submitted successfully.",
  "reference": "a99e09a0-18b3-407a-b03b-76d5af0974bc"
}

POST/loginPublic

Admin login

Returns a Sanctum personal access token. Send it as Authorization: Bearer {token} on protected routes. Existing tokens for the user are revoked.

Body fields

Field	Type	Required	Notes
email	email	Yes	Admin email
password	string	Yes	Admin password

cURL

curl -X POST /api/login \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@shams.ae","password":"Shams@2026"}'

Response

{
  "token": "1|xxxxxxxx",
  "user": { "id": 1, "name": "SHAMS Admin", "email": "admin@shams.ae" }
}

Admin

POST/logoutBearer token

Admin logout

Deletes the current access token.

cURL

curl -X POST /api/logout \
  -H "Accept: application/json" \
  -H "Authorization: Bearer TOKEN"

Response

{ "message": "Logged out." }

GET/meBearer token

Current admin user

Returns the authenticated dashboard user.

cURL

curl /api/me \
  -H "Accept: application/json" \
  -H "Authorization: Bearer TOKEN"

Response

{ "id": 1, "name": "SHAMS Admin", "email": "admin@shams.ae" }

GET/statsBearer token

Dashboard totals

Aggregate counts by status, theme, role, application type, and how applicants heard about the challenge, plus the six most recent registrations.

cURL

curl /api/stats \
  -H "Accept: application/json" \
  -H "Authorization: Bearer TOKEN"

Response

{
  "total": 26,
  "pending": 8,
  "shortlisted": 5,
  "accepted": 3,
  "waitlisted": 4,
  "rejected": 6,
  "with_pitch_deck": 0,
  "with_prototype": 0,
  "solo": 8,
  "teams": 13,
  "organizations": 5,
  "by_status": { "pending": 8, "shortlisted": 5 },
  "by_theme": { "media_trust": 6 },
  "by_role": { "journalist": 3 },
  "by_application_type": { "solo": 8 },
  "by_hear_about": { "shams_network": 4 },
  "recent": [ { "id": 26, "full_name": "...", "...": "..." } ]
}

GET/registrationsBearer token

List registrations

Paginated Laravel resource collection. Search matches name, email, organization, and city.

Query parameters

Field	Type	Required	Notes
q	string	No	Search name, email, organization, city
status	string	No	pending \| shortlisted \| accepted \| waitlisted \| rejected
challenge_theme	string	No	Theme key from /options
current_role	string	No	Role key from /options
application_type	string	No	solo \| partial_team \| full_team \| organization
hear_about	string	No	Source key from /options
page	integer	No	Page number
per_page	integer	No	Default 15

cURL

curl "/api/registrations?q=noura&status=pending&page=1" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer TOKEN"

Response

{
  "data": [ { "id": 26, "full_name": "نورة الشامسي", "status": "pending", "...": "..." } ],
  "links": { "first": "...", "last": "...", "prev": null, "next": "..." },
  "meta": { "current_page": 1, "last_page": 2, "per_page": 15, "total": 26 }
}

GET/registrations/{id}Bearer token

Registration detail

Full application record, including bilingual labels and file flags. Wrapped in a data key.

Path parameters

Field	Type	Required	Notes
id	path	Yes	Numeric registration id

cURL

curl /api/registrations/26 \
  -H "Accept: application/json" \
  -H "Authorization: Bearer TOKEN"

Response

{
  "data": {
    "id": 26,
    "uuid": "48a65841-9569-4849-9659-3b5915af7636",
    "full_name": "نورة الشامسي",
    "email": "noura.fikra@example.com",
    "status": "shortlisted",
    "labels": { "gender": "أنثى", "current_role": "طالب", "skillsets": ["صناعة المحتوى"] },
    "has_pitch_deck": false,
    "has_prototype": false,
    "admin_notes": "Strong campus applicant."
  }
}

PATCH/registrations/{id}Bearer token

Update status or notes

Admin review. Status must be one of pending, shortlisted, accepted, waitlisted, rejected.

Path parameters

Field	Type	Required	Notes
id	path	Yes	Numeric registration id

Body fields

Field	Type	Required	Notes
status	string	No	pending \| shortlisted \| accepted \| waitlisted \| rejected
admin_notes	string	No	Optional. Max 5000 characters

cURL

curl -X PATCH /api/registrations/26 \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{"status":"shortlisted","admin_notes":"Strong campus applicant."}'

Response

{
  "data": { "id": 26, "status": "shortlisted", "admin_notes": "Strong campus applicant." }
}

GET/registrations/exportBearer token

Export CSV

UTF-8 CSV download of all registrations. Use the Bearer token; the browser dashboard fetches this as a blob.

cURL

curl /api/registrations/export \
  -H "Authorization: Bearer TOKEN" \
  -o fikra-shariqa-registrations.csv

Response

fikra-shariqa-registrations-YYYYMMDD-HHMMSS.csv

GET/registrations/{id}/files/{type}Bearer token

Download pitch deck or prototype

type must be pitch-deck or prototype. Returns 404 if that file was not uploaded.

Path parameters

Field	Type	Required	Notes
id	path	Yes	Numeric registration id
type	path	Yes	pitch-deck \| prototype

cURL

curl /api/registrations/26/files/pitch-deck \
  -H "Authorization: Bearer TOKEN" \
  -o pitch-deck.pdf

Response

Binary file download

Registration object

List, detail, stats.recent, and update responses use this shape. Detail and update wrap it in data.

iduuidlocalefull_nameemailmobile_numbernationalitycity_emirateage_groupgenderlinkedin_urlcurrent_roleorganization_namefield_of_studyskillsetschallenge_themestarting_pointidea_descriptionapplication_typeteammateshas_pitch_deckpitch_deck_namehas_prototypeprototype_namemotivationweekend_commitmenthear_aboutconfirm_accurateagree_termsreceive_updatesstatusadmin_noteslabelscreated_atupdated_at