# Webshop Scraper API Documentation

Generated automatically from registered endpoints.

### Health

GET /health

#### Health check endpoint

Returns the health status of the application and queue statistics

##### Responses

- 200 - Application health status

### Jobs

POST /api/jobs 🔒 Auth Required

#### Create a new scraping job

Creates a new job to scrape a webshop. If database is available, creates or finds the shop record.

##### Request Body

    {
      "type": "object",
      "properties": {
        "url": {
          "type": "string",
          "format": "url",
          "description": "The URL of the webshop to scrape"
        },
        "custom_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
          "description": "Optional custom UUID for the shop"
        }
      },
      "required": [
        "url"
      ]
    }

##### Responses

- 201 - Job created successfully
- 400 - Invalid request data
- 409 - Custom ID already in use

GET /api/jobs/:id 🔒 Auth Required

#### Get job status and result

Retrieves the status and result of a specific job

##### Parameters

- id (path: string) * - Job ID

##### Responses

- 200 - Job details
- 404 - Job not found

GET /api/jobs 🔒 Auth Required

#### List all jobs

Retrieves a list of all jobs with their current status and queue statistics

##### Responses

- 200 - List of jobs

### Shops

GET /api/shops 🔒 Auth Required

#### List all shops

Retrieves a list of all shops with their analytics

##### Responses

- 200 - List of shops with analytics
- 503 - Database not available

GET /api/shops/:id 🔒 Auth Required

#### Get detailed shop information

Retrieves detailed information about a specific shop including analytics, content metadata, scrape history, and scheduled jobs

##### Parameters

- id (path: string) * - Shop ID (internal UUID or custom UUID)

##### Responses

- 200 - Detailed shop information
- 404 - Shop not found

GET /api/shops/:id/results 🔒 Auth Required

#### Get shop results with full content

Retrieves scraped content for a shop with optional filtering

##### Parameters

- id (path: string) * - Shop ID (internal UUID or custom UUID)
- limit (query: number) - Maximum number of results to return
- date_from (query: string) - Filter results from this date (ISO format)
- date_to (query: string) - Filter results up to this date (ISO format)
- content_type (query: string) - Filter by content type: shipping, contacts, terms, faq

##### Responses

- 200 - Shop results with content
- 404 - Shop not found

PATCH /api/shops/:id/schedule 🔒 Auth Required

#### Enable or disable scheduled scraping

Updates the scheduling status for a shop

##### Parameters

- id (path: string) * - Shop ID

##### Request Body

    {
      "type": "object",
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "Whether to enable or disable scheduling"
        }
      },
      "required": [
        "enabled"
      ]
    }

##### Responses

- 200 - Schedule status updated
- 404 - Shop not found

PATCH /api/shops/:id/custom-id 🔒 Auth Required

#### Set or update custom ID for a shop

Updates the custom UUID identifier for a shop

##### Parameters

- id (path: string) * - Shop ID (internal UUID or current custom UUID)

##### Request Body

    {
      "type": "object",
      "properties": {
        "custom_id": {
          "type": "string",
          "nullable": true,
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
          "description": "Custom UUID or null to remove"
        }
      },
      "required": [
        "custom_id"
      ]
    }

##### Responses

- 200 - Custom ID updated
- 400 - Invalid custom ID format
- 404 - Shop not found
- 409 - Custom ID already in use

DELETE /api/shops/:id 🔒 Auth Required

#### Delete a shop and all related data

Permanently removes a shop and all associated data including scrape history, scheduled jobs, and content

##### Parameters

- id (path: string) * - Shop ID (internal UUID or custom UUID)

##### Responses

- 200 - Shop deleted successfully
- 404 - Shop not found

### Webhooks

POST /api/shops/:id/webhooks 🔒 Auth Required

#### Create or replace webhook for a shop

Creates a new webhook or updates an existing one for the specified shop

##### Parameters

- id (path: string) * - Shop ID

##### Request Body

    {
      "type": "object",
      "properties": {
        "url": {
          "type": "string",
          "format": "url",
          "description": "Webhook URL"
        },
        "secret": {
          "type": "string",
          "description": "Optional webhook secret for verification"
        }
      },
      "required": [
        "url"
      ]
    }

##### Responses

- 200 - Webhook updated
- 201 - Webhook created
- 400 - Invalid webhook URL
- 404 - Shop not found

GET /api/shops/:id/webhooks 🔒 Auth Required

#### Get webhook configuration for a shop

Retrieves webhook configuration and recent delivery history

##### Parameters

- id (path: string) * - Shop ID (internal UUID or custom UUID)

##### Responses

- 200 - Webhook configuration and delivery history
- 404 - Shop or webhook not found

PATCH /api/shops/:id/webhooks 🔒 Auth Required

#### Enable or disable webhook

Updates the enabled status of a webhook

##### Parameters

- id (path: string) * - Shop ID

##### Request Body

    {
      "type": "object",
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "Whether to enable or disable the webhook"
        }
      },
      "required": [
        "enabled"
      ]
    }

##### Responses

- 200 - Webhook status updated
- 404 - Shop or webhook not found

DELETE /api/shops/:id/webhooks 🔒 Auth Required

#### Delete webhook for a shop

Permanently removes the webhook configuration for a shop

##### Parameters

- id (path: string) * - Shop ID (internal UUID or custom UUID)

##### Responses

- 200 - Webhook deleted successfully
- 404 - Shop or webhook not found

### Custom URLs

POST /api/shops/:id/custom-urls 🔒 Auth Required

#### Add a custom URL to scrape for a shop

Adds a custom URL to be scraped for specific content type

##### Parameters

- id (path: string) * - Shop ID

##### Request Body

    {
      "type": "object",
      "properties": {
        "url": {
          "type": "string",
          "format": "url",
          "description": "URL to scrape (must belong to the same domain as the shop)"
        },
        "content_type": {
          "type": "string",
          "enum": [
            "shipping",
            "contacts",
            "terms",
            "faq"
          ],
          "description": "Type of content to scrape from this URL"
        }
      },
      "required": [
        "url",
        "content_type"
      ]
    }

##### Responses

- 201 - Custom URL added successfully
- 400 - Invalid request data or URL not in same domain
- 404 - Shop not found
- 409 - URL already exists or already scraped

GET /api/shops/:id/custom-urls 🔒 Auth Required

#### List all custom URLs for a shop

Retrieves all custom URLs configured for a shop

##### Parameters

- id (path: string) * - Shop ID (internal UUID or custom UUID)

##### Responses

- 200 - List of custom URLs
- 404 - Shop not found

PATCH /api/shops/:id/custom-urls/:customUrlId 🔒 Auth Required

#### Enable or disable a custom URL

Updates the enabled status of a custom URL

##### Parameters

- id (path: string) * - Shop ID
- customUrlId (path: string) * - Custom URL ID

##### Request Body

    {
      "type": "object",
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "Whether to enable or disable the custom URL"
        }
      },
      "required": [
        "enabled"
      ]
    }

##### Responses

- 200 - Custom URL status updated
- 403 - Custom URL does not belong to this shop
- 404 - Shop or custom URL not found

DELETE /api/shops/:id/custom-urls/:customUrlId 🔒 Auth Required

#### Delete a custom URL

Permanently removes a custom URL from the shop configuration

##### Parameters

- id (path: string) * - Shop ID
- customUrlId (path: string) * - Custom URL ID

##### Responses

- 200 - Custom URL deleted successfully
- 403 - Custom URL does not belong to this shop
- 404 - Shop or custom URL not found

### Documentation

GET /doc

#### Get API Documentation

Returns interactive HTML documentation for all registered API endpoints

##### Responses

- 200 - HTML documentation page

GET /doc/openapi

#### Get OpenAPI Specification

Returns the OpenAPI 3.0 specification for the API in JSON format

##### Responses

- 200 - OpenAPI specification

GET /doc/endpoints

#### List All Endpoints

Returns a JSON list of all registered endpoints with their metadata

##### Responses

- 200 - List of endpoints