# Formies API Documentation (v1)

This document provides instructions on how to use the Formies API to access your forms and submission data programmatically.

## Authentication

All API requests must be authenticated using an API Key.

1.  **Generate an API Key**: You can generate and manage your API keys from your user dashboard under the "API Keys" section.
2.  **Pass the API Key**: The API key must be included in the `Authorization` header of your HTTP requests, using the `Bearer` scheme.

    Example:

    ```
    Authorization: Bearer YOUR_FULL_API_KEY_HERE
    ```

    Replace `YOUR_FULL_API_KEY_HERE` with the actual API key you generated (e.g., `fsk_xxxxxxxxxxxx_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy`).

If authentication fails (e.g., missing key, invalid key, expired key), the API will respond with a `401 Unauthorized` or `403 Forbidden` status code and a JSON error message.

## Endpoints

All API endpoints are prefixed with `/api/v1`.

### 1. List Your Forms

- **Endpoint**: `GET /api/v1/forms`
- **Method**: `GET`
- **Authentication**: Required (Bearer Token)
- **Description**: Retrieves a list of all forms owned by the authenticated user.
- **Successful Response (200 OK)**:
  ```json
  {
  	"success": true,
  	"forms": [
  		{
  			"uuid": "form-uuid-123",
  			"name": "My Contact Form",
  			"created_at": "2023-10-26T10:00:00.000Z",
  			"is_archived": false,
  			"submission_count": 150
  		}
  		// ... other forms
  	]
  }
  ```
- **Error Responses**:
  - `401 Unauthorized`: Authentication failed.
  - `500 Internal Server Error`: If there was an issue fetching the forms.

### 2. List Submissions for a Form

- **Endpoint**: `GET /api/v1/forms/:formUuid/submissions`
- **Method**: `GET`
- **Authentication**: Required (Bearer Token)
- **Path Parameters**:
  - `formUuid` (string, required): The UUID of the form for which to retrieve submissions.
- **Query Parameters (for pagination)**:
  - `page` (integer, optional, default: `1`): The page number of submissions to retrieve.
  - `limit` (integer, optional, default: `25`): The number of submissions to retrieve per page.
- **Description**: Retrieves a paginated list of submissions for a specific form owned by the authenticated user.
- **Successful Response (200 OK)**:
  ```json
  {
  	"success": true,
  	"formName": "My Contact Form",
  	"formUuid": "form-uuid-123",
  	"pagination": {
  		"currentPage": 1,
  		"totalPages": 3,
  		"totalSubmissions": 65,
  		"limit": 25,
  		"perPage": 25,
  		"count": 25
  	},
  	"submissions": [
  		{
  			"id": 1,
  			"data": { "email": "test@example.com", "message": "Hello!" },
  			"ip_address": "123.123.123.123",
  			"submitted_at": "2023-10-27T14:30:00.000Z"
  		}
  		// ... other submissions for the current page
  	]
  }
  ```
- **Error Responses**:
  - `401 Unauthorized`: Authentication failed.
  - `403 Forbidden`: If the authenticated user does not own the specified form.
  - `404 Not Found`: If the specified `formUuid` does not exist.
  - `500 Internal Server Error`: If there was an issue fetching the submissions.

## General Notes

- All API responses are in JSON format.
- Successful responses will generally include a `success: true` field.
- Error responses will include `success: false` and an `error` field (string or object) with details.