diff --git a/app/Http/Controllers/Apis/Protected/Main/OAuth2ElectionsApiController.php b/app/Http/Controllers/Apis/Protected/Main/OAuth2ElectionsApiController.php
index e42e97351..ed79dcd04 100644
--- a/app/Http/Controllers/Apis/Protected/Main/OAuth2ElectionsApiController.php
+++ b/app/Http/Controllers/Apis/Protected/Main/OAuth2ElectionsApiController.php
@@ -15,12 +15,15 @@
 use App\Models\Foundation\Elections\Election;
 use App\Models\Foundation\Elections\IElectionsRepository;
 use App\ModelSerializers\SerializerUtils;
+use App\Security\ElectionScopes;
 use App\Services\Model\IElectionService;
 use libs\utils\HTMLCleaner;
 use models\oauth2\IResourceServerContext;
 use ModelSerializers\SerializerRegistry;
 use utils\Filter;
 use utils\PagingInfo;
+use OpenApi\Attributes as OA;
+use Symfony\Component\HttpFoundation\Response;
 
 /**
  * Class OAuth2ElectionsApiController
@@ -50,9 +53,60 @@ public function __construct
         $this->service = $service;
     }
 
-    /**
-     * @return mixed
-     */
+    #[OA\Get(
+        path: "/api/v1/elections",
+        operationId: "getAllElections",
+        description: "Get all elections with pagination and filtering",
+        tags: ["Elections"],
+        security: [['election_oauth2' => [ElectionScopes::ReadAllElections]]],
+        parameters: [
+            new OA\Parameter(
+                name: "page",
+                in: "query",
+                required: false,
+                schema: new OA\Schema(type: "integer", default: 1),
+                description: "Page number"
+            ),
+            new OA\Parameter(
+                name: "per_page",
+                in: "query",
+                required: false,
+                schema: new OA\Schema(type: "integer", default: 20),
+                description: "Items per page"
+            ),
+            new OA\Parameter(
+                name: "filter",
+                in: "query",
+                required: false,
+                schema: new OA\Schema(type: "string"),
+                description: "Filter by name, opens, or closes (epoch format). Example: name[]=Test&opens[from]=1634567890"
+            ),
+            new OA\Parameter(
+                name: "order",
+                in: "query",
+                required: false,
+                schema: new OA\Schema(type: "string"),
+                description: "Order by: name, id, opens, or closes. Example: name,-opens"
+            ),
+            new OA\Parameter(
+                name: "expand",
+                in: "query",
+                required: false,
+                schema: new OA\Schema(type: "string"),
+                description: "Expand relationships: "
+            ),
+        ],
+        responses: [
+            new OA\Response(
+                response: Response::HTTP_OK,
+                description: "Elections list retrieved successfully",
+                content: new OA\JsonContent(ref: "#/components/schemas/PaginatedElectionsResponse")
+            ),
+            new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
+            new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"),
+            new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
+        ]
+    )]
     public function getAll()
     {
         return $this->_getAll(
@@ -97,9 +151,30 @@ function ($page, $per_page, $filter, $order, $applyExtraFilters) {
         );
     }
 
-    /**
-     * @return \Illuminate\Http\JsonResponse|mixed
-     */
+    #[OA\Get(
+        path: "/api/public/v1/elections/current",
+        operationId: "getCurrentElection",
+        description: "Get the current active election",
+        tags: ["Elections (Public)"],
+        parameters: [
+            new OA\Parameter(
+                name: "expand",
+                in: "query",
+                required: false,
+                schema: new OA\Schema(type: "string"),
+                description: "Expand relationships"
+            ),
+        ],
+        responses: [
+            new OA\Response(
+                response: Response::HTTP_OK,
+                description: "Current election retrieved successfully",
+                content: new OA\JsonContent(ref: "#/components/schemas/Election")
+            ),
+            new OA\Response(response: Response::HTTP_NOT_FOUND, description: "No current election found"),
+            new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
+        ]
+    )]
     public function getCurrent()
     {
         return $this->processRequest(function () {
@@ -122,10 +197,38 @@ public function getCurrent()
         });
     }
 
-    /**
-     * @param $election_id
-     * @return mixed
-     */
+    #[OA\Get(
+        path: "/api/v1/elections/{election_id}",
+        operationId: "getElectionById",
+        description: "Get election by ID",
+        tags: ["Elections"],
+        security: [['election_oauth2' => [ElectionScopes::ReadAllElections]]],
+        parameters: [
+            new OA\Parameter(
+                name: "election_id",
+                in: "path",
+                required: true,
+                schema: new OA\Schema(type: "integer", format: "int64"),
+                description: "Election ID"
+            ),
+            new OA\Parameter(
+                name: "expand",
+                in: "query",
+                required: false,
+                schema: new OA\Schema(type: "string"),
+                description: "Expand relationships"
+            ),
+        ],
+        responses: [
+            new OA\Response(
+                response: Response::HTTP_OK,
+                description: "Election retrieved successfully",
+                content: new OA\JsonContent(ref: "#/components/schemas/Election")
+            ),
+            new OA\Response(response: Response::HTTP_NOT_FOUND, description: "Election not found"),
+            new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
+        ]
+    )]
     public function getById($election_id)
     {
         return $this->processRequest(function () use ($election_id) {
@@ -148,9 +251,58 @@ public function getById($election_id)
         });
     }
 
-    /**
-     * @return \Illuminate\Http\JsonResponse|mixed
-     */
+    #[OA\Get(
+        path: "/api/public/v1/elections/current/candidates",
+        operationId: "getCurrentElectionCandidates",
+        description: "Get all accepted candidates for the current election. Supports expand parameter to include member and/or election objects",
+        tags: ["Elections (Public)"],
+        parameters: [
+            new OA\Parameter(
+                name: "page",
+                in: "query",
+                required: false,
+                schema: new OA\Schema(type: "integer", default: 1),
+                description: "Page number"
+            ),
+            new OA\Parameter(
+                name: "per_page",
+                in: "query",
+                required: false,
+                schema: new OA\Schema(type: "integer", default: 20),
+                description: "Items per page"
+            ),
+            new OA\Parameter(
+                name: "filter",
+                in: "query",
+                required: false,
+                schema: new OA\Schema(type: "string"),
+                description: "Filter by first_name, last_name, or full_name"
+            ),
+            new OA\Parameter(
+                name: "order",
+                in: "query",
+                required: false,
+                schema: new OA\Schema(type: "string"),
+                description: "Order by first_name or last_name"
+            ),
+            new OA\Parameter(
+                name: "expand",
+                in: "query",
+                required: false,
+                schema: new OA\Schema(type: "string"),
+                description: "Expand relationships: member, election (comma-separated)"
+            ),
+        ],
+        responses: [
+            new OA\Response(
+                response: Response::HTTP_OK,
+                description: "Current election candidates retrieved successfully",
+                content: new OA\JsonContent(ref: "#/components/schemas/PaginatedCandidatesResponse")
+            ),
+            new OA\Response(response: Response::HTTP_NOT_FOUND, description: "No current election found"),
+            new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
+        ]
+    )]
     public function getCurrentCandidates()
     {
 
@@ -199,10 +351,67 @@ function ($page, $per_page, $filter, $order, $applyExtraFilters) use ($election)
         );
     }
 
-    /**
-     * @return \Illuminate\Http\JsonResponse|mixed
-     */
-    public function getElectionCandidates($election_id)
+    #[OA\Get(
+        path: "/api/v1/elections/{election_id}/candidates",
+        operationId: "getElectionCandidates",
+        description: "Get all accepted candidates for a specific election. Supports expand parameter to include member and/or election objects",
+        tags: ["Elections"],
+        security: [['election_oauth2' => [ElectionScopes::ReadAllElections]]],
+        parameters: [
+            new OA\Parameter(
+                name: "election_id",
+                in: "path",
+                required: true,
+                schema: new OA\Schema(type: "integer", format: "int64"),
+                description: "Election ID"
+            ),
+            new OA\Parameter(
+                name: "page",
+                in: "query",
+                required: false,
+                schema: new OA\Schema(type: "integer", default: 1),
+                description: "Page number"
+            ),
+            new OA\Parameter(
+                name: "per_page",
+                in: "query",
+                required: false,
+                schema: new OA\Schema(type: "integer", default: 20),
+                description: "Items per page"
+            ),
+            new OA\Parameter(
+                name: "filter",
+                in: "query",
+                required: false,
+                schema: new OA\Schema(type: "string"),
+                description: "Filter by first_name, last_name, or full_name"
+            ),
+            new OA\Parameter(
+                name: "order",
+                in: "query",
+                required: false,
+                schema: new OA\Schema(type: "string"),
+                description: "Order by first_name or last_name"
+            ),
+            new OA\Parameter(
+                name: "expand",
+                in: "query",
+                required: false,
+                schema: new OA\Schema(type: "string"),
+                description: "Expand relationships: member, election (comma-separated)"
+            ),
+        ],
+        responses: [
+            new OA\Response(
+                response: Response::HTTP_OK,
+                description: "Election candidates retrieved successfully",
+                content: new OA\JsonContent(ref: "#/components/schemas/PaginatedCandidatesResponse")
+            ),
+            new OA\Response(response: Response::HTTP_NOT_FOUND, description: "Election not found"),
+            new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
+        ]
+    )]
+    public function getElectionCandidates(int $election_id)
     {
 
         $election = $this->repository->getById(intval($election_id));
@@ -250,9 +459,58 @@ function ($page, $per_page, $filter, $order, $applyExtraFilters) use ($election)
         );
     }
 
-    /**
-     * @return \Illuminate\Http\JsonResponse|mixed
-     */
+    #[OA\Get(
+        path: "/api/public/v1/elections/current/candidates/gold",
+        operationId: "getCurrentGoldCandidates",
+        description: "Get all gold (featured) candidates for the current election. Supports expand parameter to include member and/or election objects",
+        tags: ["Elections (Public)"],
+        parameters: [
+            new OA\Parameter(
+                name: "page",
+                in: "query",
+                required: false,
+                schema: new OA\Schema(type: "integer", default: 1),
+                description: "Page number"
+            ),
+            new OA\Parameter(
+                name: "per_page",
+                in: "query",
+                required: false,
+                schema: new OA\Schema(type: "integer", default: 20),
+                description: "Items per page"
+            ),
+            new OA\Parameter(
+                name: "filter",
+                in: "query",
+                required: false,
+                schema: new OA\Schema(type: "string"),
+                description: "Filter by first_name, last_name, or full_name"
+            ),
+            new OA\Parameter(
+                name: "order",
+                in: "query",
+                required: false,
+                schema: new OA\Schema(type: "string"),
+                description: "Order by first_name or last_name"
+            ),
+            new OA\Parameter(
+                name: "expand",
+                in: "query",
+                required: false,
+                schema: new OA\Schema(type: "string"),
+                description: "Expand relationships: member, election (comma-separated)"
+            ),
+        ],
+        responses: [
+            new OA\Response(
+                response: Response::HTTP_OK,
+                description: "Gold candidates retrieved successfully",
+                content: new OA\JsonContent(ref: "#/components/schemas/PaginatedCandidatesResponse")
+            ),
+            new OA\Response(response: Response::HTTP_NOT_FOUND, description: "No current election found"),
+            new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
+        ]
+    )]
     public function getCurrentGoldCandidates()
     {
 
@@ -301,6 +559,66 @@ function ($page, $per_page, $filter, $order, $applyExtraFilters) use ($election)
         );
     }
 
+    #[OA\Get(
+        path: "/api/v1/elections/{election_id}/candidates/gold",
+        operationId: "getElectionGoldCandidates",
+        description: "Get all gold (featured) candidates for a specific election. Supports expand parameter to include member and/or election objects",
+        tags: ["Elections"],
+        security: [['election_oauth2' => [ElectionScopes::ReadAllElections]]],
+        parameters: [
+            new OA\Parameter(
+                name: "election_id",
+                in: "path",
+                required: true,
+                schema: new OA\Schema(type: "integer", format: "int64"),
+                description: "Election ID"
+            ),
+            new OA\Parameter(
+                name: "page",
+                in: "query",
+                required: false,
+                schema: new OA\Schema(type: "integer", default: 1),
+                description: "Page number"
+            ),
+            new OA\Parameter(
+                name: "per_page",
+                in: "query",
+                required: false,
+                schema: new OA\Schema(type: "integer", default: 20),
+                description: "Items per page"
+            ),
+            new OA\Parameter(
+                name: "filter",
+                in: "query",
+                required: false,
+                schema: new OA\Schema(type: "string"),
+                description: "Filter by first_name, last_name, or full_name"
+            ),
+            new OA\Parameter(
+                name: "order",
+                in: "query",
+                required: false,
+                schema: new OA\Schema(type: "string"),
+                description: "Order by first_name or last_name"
+            ),
+            new OA\Parameter(
+                name: "expand",
+                in: "query",
+                required: false,
+                schema: new OA\Schema(type: "string"),
+                description: "Expand relationships: member, election (comma-separated)"
+            ),
+        ],
+        responses: [
+            new OA\Response(
+                response: Response::HTTP_OK,
+                description: "Gold candidates retrieved successfully",
+                content: new OA\JsonContent(ref: "#/components/schemas/PaginatedCandidatesResponse")
+            ),
+            new OA\Response(response: Response::HTTP_NOT_FOUND, description: "Election not found"),
+            new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
+        ]
+    )]
     public function getElectionGoldCandidates($election_id)
     {
 
@@ -349,11 +667,29 @@ function ($page, $per_page, $filter, $order, $applyExtraFilters) use ($election)
         );
     }
 
-    use GetAndValidateJsonPayload;
-
-    /**
-     * @return \Illuminate\Http\JsonResponse|mixed
-     */
+    #[OA\Put(
+        path: "/api/v1/elections/current/candidates/me",
+        operationId: "updateMyCandidateProfile",
+        description: "Update current user's candidate profile for the current election",
+        tags: ["Elections"],
+        security: [['election_oauth2' => [ElectionScopes::WriteMyCandidateProfile]]],
+        requestBody: new OA\RequestBody(
+            required: true,
+            content: new OA\JsonContent(ref: "#/components/schemas/CandidateProfileUpdateRequest")
+        ),
+        responses: [
+            new OA\Response(
+                response: Response::HTTP_OK,
+                description: "Candidate profile updated successfully",
+                content: new OA\JsonContent(ref: "#/components/schemas/Member")
+            ),
+            new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
+            new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden - User not authenticated"),
+            new OA\Response(response: Response::HTTP_NOT_FOUND, description: "No current election found"),
+            new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"),
+            new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
+        ]
+    )]
     public function updateMyCandidateProfile()
     {
         return $this->processRequest(function () {
@@ -393,11 +729,46 @@ public function updateMyCandidateProfile()
         });
     }
 
-    /**
-     * @param $candidate_id
-     * @return \Illuminate\Http\JsonResponse|mixed
-     */
-    public function nominateCandidate($candidate_id)
+    #[OA\Post(
+        path: "/api/v1/elections/current/candidates/{candidate_id}",
+        operationId: "nominateCandidate",
+        description: "Nominate a candidate for the current election. Supports expand parameter to include related objects (election, candidate, nominator)",
+        tags: ["Elections"],
+        security: [['election_oauth2' => [ElectionScopes::NominatesCandidates]]],
+        parameters: [
+            new OA\Parameter(
+                name: "candidate_id",
+                in: "path",
+                required: true,
+                schema: new OA\Schema(type: "integer", format: "int64"),
+                description: "Candidate ID to nominate"
+            ),
+            new OA\Parameter(
+                name: "expand",
+                in: "query",
+                required: false,
+                schema: new OA\Schema(type: "string"),
+                description: "Expand relationships: election, candidate, nominator (comma-separated)"
+            ),
+        ],
+        requestBody: new OA\RequestBody(
+            required: false,
+            content: new OA\JsonContent(ref: "#/components/schemas/NominationRequest")
+        ),
+        responses: [
+            new OA\Response(
+                response: Response::HTTP_OK,
+                description: "Candidate nominated successfully",
+                content: new OA\JsonContent(ref: "#/components/schemas/Nomination")
+            ),
+            new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
+            new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden - User not authenticated"),
+            new OA\Response(response: Response::HTTP_NOT_FOUND, description: "Candidate or current election not found"),
+            new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"),
+            new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
+        ]
+    )]
+    public function nominateCandidate(int $candidate_id)
     {
         return $this->processRequest(function () use ($candidate_id) {
             $current_member = $this->resource_server_context->getCurrentUser();
@@ -420,4 +791,4 @@ public function nominateCandidate($candidate_id)
 
         });
     }
-}
\ No newline at end of file
+}
diff --git a/app/Swagger/ElectionSchemas.php b/app/Swagger/ElectionSchemas.php
new file mode 100644
index 000000000..242774a75
--- /dev/null
+++ b/app/Swagger/ElectionSchemas.php
@@ -0,0 +1,69 @@
+<?php
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+
+
+
+#[OA\Schema(
+    schema: 'CandidateProfileUpdateRequest',
+    type: 'object',
+    properties: [
+        new OA\Property(property: 'bio', type: 'string', description: 'Candidate biography'),
+        new OA\Property(property: 'relationship_to_openstack', type: 'string', description: 'Relationship to OpenStack'),
+        new OA\Property(property: 'experience', type: 'string', description: 'Professional experience'),
+        new OA\Property(property: 'boards_role', type: 'string', description: 'Board role experience'),
+        new OA\Property(property: 'top_priority', type: 'string', description: 'Top priority if elected'),
+    ]
+)]
+class CandidateProfileUpdateRequestSchema {}
+
+#[OA\Schema(
+    schema: 'NominationRequest',
+    type: 'object',
+    properties: [
+        new OA\Property(property: 'comment', type: 'string', nullable: true, description: 'Optional comment for the nomination'),
+    ]
+)]
+class NominationRequestSchema {}
+
+
+#[OA\Schema(
+    schema: "PaginatedElectionsResponse",
+    allOf: [
+        new OA\Schema(ref: '#/components/schemas/PaginateDataSchemaResponse'),
+        new OA\Schema(
+            type: 'object',
+            properties: [
+                new OA\Property(
+                    property: "data",
+                    type: "array",
+                    items: new OA\Items(ref: "#/components/schemas/Election")
+                )
+            ]
+        )]
+)]
+class PaginatedElectionsResponseSchema
+{
+}
+
+
+#[OA\Schema(
+    schema: "PaginatedCandidatesResponse",
+    allOf: [
+        new OA\Schema(ref: '#/components/schemas/PaginateDataSchemaResponse'),
+        new OA\Schema(
+            type: 'object',
+            properties: [
+                new OA\Property(
+                    property: "data",
+                    type: "array",
+                    items: new OA\Items(ref: "#/components/schemas/Candidate")
+                )
+            ]
+        )]
+)]
+class PaginatedCandidatesResponseSchema
+{
+}
diff --git a/app/Swagger/ElectionsSchemas.php b/app/Swagger/ElectionsSchemas.php
deleted file mode 100644
index 6b3e2f895..000000000
--- a/app/Swagger/ElectionsSchemas.php
+++ /dev/null
@@ -1,7 +0,0 @@
-<?php
-
-namespace App\Swagger\schemas;
-
-use OpenApi\Attributes as OA;
-
-//
diff --git a/app/Swagger/Models/CandidateSchema.php b/app/Swagger/Models/CandidateSchema.php
new file mode 100644
index 000000000..5e73ce5aa
--- /dev/null
+++ b/app/Swagger/Models/CandidateSchema.php
@@ -0,0 +1,105 @@
+<?php
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+#[OA\Schema(
+    schema: "Candidate",
+    type: "object",
+    required: ["id", "member_id", "election_id"],
+    properties: [
+        new OA\Property(
+            property: "id",
+            type: "integer",
+            format: "int64",
+            description: "Candidate ID",
+            example: 1
+        ),
+        new OA\Property(
+            property: "member_id",
+            type: "integer",
+            format: "int64",
+            description: "Associated member ID",
+            example: 123
+        ),
+        new OA\Property(
+            property: "election_id",
+            type: "integer",
+            format: "int64",
+            description: "Associated election ID",
+            example: 1
+        ),
+        new OA\Property(
+            property: "has_accepted_nomination",
+            type: "boolean",
+            description: "Whether candidate has accepted nomination",
+            example: true
+        ),
+        new OA\Property(
+            property: "is_gold_member",
+            type: "boolean",
+            description: "Whether candidate is featured/gold",
+            example: false
+        ),
+        new OA\Property(
+            property: "relationship_to_openstack",
+            type: "string",
+            nullable: true,
+            description: "Relationship to OpenStack",
+            example: "Core contributor"
+        ),
+        new OA\Property(
+            property: "experience",
+            type: "string",
+            nullable: true,
+            description: "Professional experience",
+            example: "10 years in open source"
+        ),
+        new OA\Property(
+            property: "boards_role",
+            type: "string",
+            nullable: true,
+            description: "Board role experience",
+            example: "Board member for 3 years"
+        ),
+        new OA\Property(
+            property: "bio",
+            type: "string",
+            nullable: true,
+            description: "Candidate biography",
+            example: "Passionate OpenStack contributor"
+        ),
+        new OA\Property(
+            property: "top_priority",
+            type: "string",
+            nullable: true,
+            description: "Top priority if elected",
+            example: "Improve community engagement"
+        ),
+        new OA\Property(
+            property: "created_at",
+            type: "integer",
+            format: "int64",
+            description: "Creation timestamp (unix epoch)"
+        ),
+        new OA\Property(
+            property: "updated_at",
+            type: "integer",
+            format: "int64",
+            description: "Last update timestamp (unix epoch)"
+        ),
+        new OA\Property(
+            property: "member",
+            description: "Member details (only when expand=member)",
+            ref: "#/components/schemas/Member",
+            nullable: true
+        ),
+        new OA\Property(
+            property: "election",
+            description: "Election details (only when expand=election)",
+            ref: "#/components/schemas/Election",
+            nullable: true
+        ),
+    ]
+)]
+class CandidateSchema {}
\ No newline at end of file
diff --git a/app/Swagger/Models/ElectionSchema.php b/app/Swagger/Models/ElectionSchema.php
new file mode 100644
index 000000000..293fa1baa
--- /dev/null
+++ b/app/Swagger/Models/ElectionSchema.php
@@ -0,0 +1,102 @@
+<?php
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+#[OA\Schema(
+    schema: "Election",
+    type: "object",
+    required: ["id", "name"],
+    properties: [
+        new OA\Property(
+            property: "id",
+            type: "integer",
+            format: "int64",
+            example: 1
+        ),
+        new OA\Property(
+            property: "name",
+            type: "string",
+            example: "Board Election 2025"
+        ),
+        new OA\Property(
+            property: "status",
+            type: "string",
+            enum: ["open", "closed", "upcoming"],
+            example: "open"
+        ),
+        new OA\Property(
+            property: "opens",
+            type: "integer",
+            format: "int64",
+            description: "Unix timestamp when election opens",
+            example: 1634567890
+        ),
+        new OA\Property(
+            property: "closes",
+            type: "integer",
+            format: "int64",
+            description: "Unix timestamp when election closes",
+            example: 1634654290
+        ),
+        new OA\Property(
+            property: "nomination_opens",
+            type: "integer",
+            format: "int64",
+            description: "Unix timestamp when nominations open",
+            example: 1634481490
+        ),
+        new OA\Property(
+            property: "nomination_closes",
+            type: "integer",
+            format: "int64",
+            description: "Unix timestamp when nominations close",
+            example: 1634567890
+        ),
+        new OA\Property(
+            property: "nomination_application_deadline",
+            type: "integer",
+            format: "int64",
+            description: "Unix timestamp for nomination application deadline",
+            example: 1634567890
+        ),
+        new OA\Property(
+            property: "candidate_application_form_relationship_to_openstack_label",
+            type: "string",
+            example: "Relationship to OpenStack"
+        ),
+        new OA\Property(
+            property: "candidate_application_form_experience_label",
+            type: "string",
+            example: "Experience in OpenStack"
+        ),
+        new OA\Property(
+            property: "candidate_application_form_boards_role_label",
+            type: "string",
+            example: "Board Role Experience"
+        ),
+        new OA\Property(
+            property: "candidate_application_form_top_priority_label",
+            type: "string",
+            example: "Top Priorities"
+        ),
+        new OA\Property(
+            property: "nominations_limit",
+            type: "integer",
+            example: 10
+        ),
+        new OA\Property(
+            property: "created_at",
+            type: "integer",
+            format: "int64",
+            description: "Creation timestamp"
+        ),
+        new OA\Property(
+            property: "updated_at",
+            type: "integer",
+            format: "int64",
+            description: "Last update timestamp"
+        ),
+    ]
+)]
+class ElectionSchema {}
\ No newline at end of file
diff --git a/app/Swagger/NominationSchema.php b/app/Swagger/NominationSchema.php
new file mode 100644
index 000000000..41b77c7ec
--- /dev/null
+++ b/app/Swagger/NominationSchema.php
@@ -0,0 +1,79 @@
+<?php
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+
+#[OA\Schema(
+    schema: "Nomination",
+    type: "object",
+    required: ["id", "candidate_id", "nominator_id", "election_id"],
+    properties: [
+        new OA\Property(
+            property: "id",
+            type: "integer",
+            format: "int64",
+            description: "Nomination ID",
+            example: 1
+        ),
+        new OA\Property(
+            property: "election_id",
+            type: "integer",
+            format: "int64",
+            description: "Associated election ID",
+            example: 1
+        ),
+        new OA\Property(
+            property: "candidate_id",
+            type: "integer",
+            format: "int64",
+            description: "Nominated candidate ID",
+            example: 123
+        ),
+        new OA\Property(
+            property: "nominator_id",
+            type: "integer",
+            format: "int64",
+            description: "Member who made the nomination",
+            example: 456
+        ),
+        new OA\Property(
+            property: "comment",
+            type: "string",
+            nullable: true,
+            description: "Optional nomination comment",
+            example: "Great candidate for the board"
+        ),
+        new OA\Property(
+            property: "created_at",
+            type: "integer",
+            format: "int64",
+            description: "Creation timestamp (unix epoch)"
+        ),
+        new OA\Property(
+            property: "updated_at",
+            type: "integer",
+            format: "int64",
+            description: "Last update timestamp (unix epoch)"
+        ),
+        new OA\Property(
+            property: "election",
+            description: "Expanded election object (only with expand=election)",
+            ref: "#/components/schemas/Election",
+            nullable: true
+        ),
+        new OA\Property(
+            property: "candidate",
+            description: "Expanded candidate object (only with expand=candidate)",
+            ref: "#/components/schemas/Candidate",
+            nullable: true
+        ),
+        new OA\Property(
+            property: "nominator",
+            description: "Expanded nominator member object (only with expand=nominator)",
+            ref: "#/components/schemas/Member",
+            nullable: true
+        ),
+    ]
+)]
+class NominationSchema {}
\ No newline at end of file
diff --git a/app/Swagger/Security/ElectionOAuth2Schema.php b/app/Swagger/Security/ElectionOAuth2Schema.php
new file mode 100644
index 000000000..72ac5a376
--- /dev/null
+++ b/app/Swagger/Security/ElectionOAuth2Schema.php
@@ -0,0 +1,26 @@
+<?php
+
+namespace App\Swagger\security;
+
+use App\Security\ElectionScopes;
+use OpenApi\Attributes as OA;
+
+#[
+    OA\SecurityScheme(
+        type: 'oauth2',
+        securityScheme: 'election_oauth2',
+        flows: [
+            new OA\Flow(
+                authorizationUrl: L5_SWAGGER_CONST_AUTH_URL,
+                tokenUrl: L5_SWAGGER_CONST_TOKEN_URL,
+                flow: 'authorizationCode',
+                scopes: [
+                    ElectionScopes::ReadAllElections => 'Read All Elections',
+                    ElectionScopes::WriteMyCandidateProfile => 'Write My Candidate Profile',
+                    ElectionScopes::NominatesCandidates => 'Nominate Candidates',
+                ],
+            ),
+        ],
+    )
+]
+class ElectionOAuth2Schema {}
diff --git a/app/Swagger/security/SummitBookableRoomsAttributeTypeSecurity.php b/app/Swagger/Security/SummitBookableRoomsAttributeTypeSecurity.php
similarity index 95%
rename from app/Swagger/security/SummitBookableRoomsAttributeTypeSecurity.php
rename to app/Swagger/Security/SummitBookableRoomsAttributeTypeSecurity.php
index 8b3ad5e8c..18238d0da 100644
--- a/app/Swagger/security/SummitBookableRoomsAttributeTypeSecurity.php
+++ b/app/Swagger/Security/SummitBookableRoomsAttributeTypeSecurity.php
@@ -1,11 +1,10 @@
-<?php 
+<?php
 namespace App\Swagger\schemas;
 
 use App\Security\SummitScopes;
 use OpenApi\Attributes as OA;
 
-#[
-    OA\SecurityScheme(
+#[OA\SecurityScheme(
         type: 'oauth2',
         securityScheme: 'summit_bookable_rooms_attribute_oauth2',
         flows: [