API Documentation

# ConsentGuard.io API Documentation

## Base URL
```
https://consentguard.io/api/v1
```

## Authentication
All API endpoints require authentication using API tokens. Include your API token in the Authorization header:

```
Authorization: Bearer YOUR_API_TOKEN
```

## Content Type
All requests should include the appropriate Content-Type header:

```
Content-Type: application/json
```

---

## Endpoints

### Create Spot Check

Create a one-time validation check for a URL without adding it to your managed websites.

**Endpoint:** `POST /spot-check`

**Request Body:**
```json
{
"url": "https://example.com"
}
```

**Example Request:**
```bash
curl -X POST "https://consentguard.io/api/v1/spot-check" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com"
}'
```

**Success Response (201):**
```json
{
"success": true,
"data": {
"validation_request": "550e8400-e29b-41d4-a716-446655440000",
"url": "https://example.com"
}
}
```

**Validation Error (422):**
```json
{
"error": "Validation failed",
"details": {
"url": [
"The url field is required."
]
}
}
```

**Error Response (500):**
```json
{
"error": "Unable to create spot check"
}
```

---

### Add Website

Add a new website to your managed websites list.

Note: adding a website will not instantly trigger a validation check. Checks are scheduled once per day for all managed websites.
You can run checks later using the `/checks` endpoint.

**Endpoint:** `POST /websites`

**Request Body:**
```json
{
"url": "https://example.com",
"description": "Main company website"
}
```

**Fields:**
- `url` (required): Website URL (must start with http:// or https://)
- `description` (optional): Website description (max 1000 characters)

**Example Request:**
```bash
curl -X POST "https://consentguard.io/api/v1/websites" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com",
"description": "Main company website"
}'
```

**Success Response (201):**
```json
{
"success": true,
"data": {
"website_id": 123,
"url": "https://example.com",
"description": "Main company website",
"domain": "example.com",
"is_active": true,
"created_at": "2025-11-27T10:30:00.000000Z"
},
"message": "Website example.com has been added successfully."
}
```

**Validation Error (422):**
```json
{
"error": "Validation failed",
"details": {
"url": [
"The URL must start with http:// or https://"
]
}
}
```

**Domain Limit Error (403):**
```json
{
"error": "Domain limit reached",
"message": "You have reached your domain limit (5/5). Please upgrade your plan to add more websites."
}
```

**Domain Exists Error (409):**
```json
{
"error": "Domain already exists",
"message": "A website with domain 'example.com' already exists in this team."
}
```

---

### Get User Checks

Retrieve a paginated list of all validation checks (both website and spot checks) for the authenticated user.

**Endpoint:** `GET /checks`

**Query Parameters:**
- `limit` (optional): Number of results to return (max 100, default 50)
- `offset` (optional): Number of results to skip for pagination (default 0)

**Example Request:**
```bash
curl -X GET "https://consentguard.io/api/v1/checks?limit=20&offset=0" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json"
```

**Success Response (200):**
```json
{
"success": true,
"data": {
"checks": [
{
"check_id": 123,
"validation_request_uuid": "550e8400-e29b-41d4-a716-446655440000",
"type": "website",
"url": "https://example.com",
"website_id": 456,
"status": "completed",
"created_at": "2025-11-27T10:30:00.000000Z"
},
{
"check_id": 124,
"validation_request_uuid": "660e8400-e29b-41d4-a716-446655440001",
"type": "spot",
"url": "https://test.com",
"website_id": null,
"check_source": "API",
"status": "pending",
"created_at": "2025-11-27T09:15:00.000000Z"
}
],
"pagination": {
"limit": 20,
"offset": 0,
"count": 2
}
}
}
```

**Error Response (500):**
```json
{
"error": "Failed to retrieve checks",
"message": "An error occurred while retrieving your checks. Please try again."
}
```

---

### Get Validation Results

Retrieve the validation results for a specific check using its validation request UUID.

**Endpoint:** `GET /results/{validationResultUuid}`

**Path Parameters:**
- `validationResultUuid`: The UUID of the validation request

**Example Request:**
```bash
curl -X GET "https://consentguard.io/api/v1/results/550e8400-e29b-41d4-a716-446655440000" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json"
```

**Success Response (200) - Completed:**
```json
{
"status": "completed",
"data": {
"url": "https://example.com",
"domain": "example.com",
"scan_date": "2025-11-27T10:30:00Z",
"consent_mode_working": true,
"gdpr_compliant": true,
"compliance_score": 85.5,
"issues_found": 2,
"violations": [
{
"type": "CONSENT_MODE_NOT_IMPLEMENTED",
"severity": "high",
"message": "Consent Mode V2 not properly implemented",
"details": "Google Analytics found without proper consent signals"
}
],
"recommendations": [
"Implement Google Consent Mode V2",
"Update Google Analytics configuration"
]
}
}
```

**Success Response (200) - Pending:**
```json
{
"status": "pending"
}
```

**Error Response (404):**
```json
{
"error": "Result not found"
}
```

**Error Response (500):**
```json
{
"error": "Unable to retrieve results"
}
```

---


### Delete Website

Remove a website from your managed websites list.

**Endpoint:** `DELETE /websites/{website_id}`

**Path Parameters:**
- `website_id`: The ID of the website to delete

**Request Body:**
```json
{
"domain_confirmation": "example.com"
}
```

**Fields:**
- `domain_confirmation` (required): The exact domain name to confirm deletion

**Example Request:**
```bash
curl -X DELETE "https://consentguard.io/api/v1/websites/123" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"domain_confirmation": "example.com"
}'
```

**Success Response (200):**
```json
{
"success": true,
"message": "Website example.com has been deleted successfully."
}
```

**Validation Error (422):**
```json
{
"error": "Validation failed",
"details": {
"domain_confirmation": [
"The domain confirmation does not match the website domain."
]
}
}
```

**Authorization Error (403):**
```json
{
"message": "This action is unauthorized."
}
```

**Not Found Error (404):**
```json
{
"error": "Resource not found",
"message": "The requested resource was not found"
}
```

---

## Error Handling

### HTTP Status Codes

- `200` - OK: Request successful
- `201` - Created: Resource created successfully
- `400` - Bad Request: Invalid request data
- `401` - Unauthorized: Invalid or missing API token
- `403` - Forbidden: Insufficient permissions
- `404` - Not Found: Resource not found
- `409` - Conflict: Resource already exists
- `422` - Unprocessable Entity: Validation failed
- `500` - Internal Server Error: Server error

### Error Response Format

All error responses follow this format:

```json
{
"error": "Error Type",
"message": "Human-readable error message"
}
```

For validation errors (422), additional details are provided:

```json
{
"error": "Validation failed",
"details": {
"field_name": [
"Error message for this field"
]
}
}
```

### Authentication Errors

**Missing Token (401):**
```json
{
"error": "Unauthenticated",
"message": "Invalid or missing API token"
}
```

---

## Rate Limiting

API requests are subject to rate limiting. When you exceed the rate limit, you'll receive a `429 Too Many Requests` response.

## Data Types

### Check Types
- `website` - Validation check for a managed website
- `spot` - One-time validation check (spot check)

### Validation Statuses
- `pending` - Check is queued for processing
- `processing` - Check is currently being analyzed
- `completed` - Check completed successfully
- `failed` - Check failed due to an error

### Check Sources (for spot checks)
- `Web` - Created via web interface
- `API` - Created via API

---

## Getting Started

1. **Generate API Token**: Create an API token in your dashboard under Integrations > API Tokens
2. **Test Connection**: Make a GET request to `/checks` to verify your token works
3. **Create Spot Check**: Use POST `/spot-check` to validate a URL
4. **Get Results**: Use GET `/results/{uuid}` to retrieve validation results
5. **Manage Websites**: Use POST/DELETE `/websites` to manage your website list

## Support

For API support, please check the troubleshooting section in your dashboard or contact support through the web interface.