Sous Worker API Documentation

This API provides endpoints for recipe-related operations for the Sous recipe app.

Authentication

All endpoints require authentication using a JWT token. Include the token in the Authorization header:

Authorization: Bearer <your_token>

Endpoints

POST /api/v1/recipes/generate-from-image

Generate a recipe from an image.

Request

Content-Type: multipart/form-data or application/json

For multipart/form-data:

{
  "image": [binary image data]
}

For application/json:

{
  "imageUrl": "https://example.com/image.jpg"
}

Response

{
  "title": "Generated Recipe Name",
  "description": "Description of the recipe",
  "ingredients": [
    "Ingredient 1",
    "Ingredient 2",
    "..."
  ],
  "instructions": [
    "Step 1",
    "Step 2",
    "..."
  ],
  "prepTime": 15,
  "cookTime": 30,
  "servings": 4,
  "tags": ["tag1", "tag2"]
}

GET /api/v1/recipes/search

Search through a list of provided recipes.

Query Parameters

Parameter Type Description
q string Search query string
tags string Comma-separated list of tags to filter by
page number Page number for pagination (default: 1)
limit number Number of results per page (default: 10)

Response

{
  "items": [
    {
      "id": "recipe-id-1",
      "title": "Recipe 1",
      "description": "Description of recipe 1",
      "ingredients": ["Ingredient 1", "Ingredient 2"],
      "instructions": ["Step 1", "Step 2"],
      "prepTime": 15,
      "cookTime": 30,
      "servings": 4,
      "tags": ["tag1", "tag2"],
      "imageUrl": "https://example.com/image1.jpg"
    },
    {
      "id": "recipe-id-2",
      "title": "Recipe 2",
      "description": "Description of recipe 2",
      "ingredients": ["Ingredient 1", "Ingredient 2"],
      "instructions": ["Step 1", "Step 2"],
      "prepTime": 10,
      "cookTime": 20,
      "servings": 2,
      "tags": ["tag2", "tag3"],
      "imageUrl": "https://example.com/image2.jpg"
    }
  ],
  "total": 100,
  "page": 1,
  "limit": 10,
  "totalPages": 10
}

GET /api/v1/recipes/web-search

Search the web for recipes.

Query Parameters

Parameter Type Description
q string Search query string
page number Page number for pagination (default: 1)
limit number Number of results per page (default: 10)

Response

{
  "items": [
    {
      "title": "Web Recipe 1",
      "url": "https://example.com/recipe1",
      "description": "Description of web recipe 1",
      "imageUrl": "https://example.com/image1.jpg",
      "source": "Example Recipe Site"
    },
    {
      "title": "Web Recipe 2",
      "url": "https://example.com/recipe2",
      "description": "Description of web recipe 2",
      "imageUrl": "https://example.com/image2.jpg",
      "source": "Another Recipe Site"
    }
  ],
  "total": 100,
  "page": 1,
  "limit": 10,
  "totalPages": 10
}

POST /api/v1/recipes/markup

Generate a marked-up recipe from raw text.

Request

{
  "recipe": "Raw recipe text here. For example:\n\nChocolate Chip Cookies\n\nIngredients:\n- 2 1/4 cups all-purpose flour\n- 1 tsp baking soda\n- 1 tsp salt\n- 1 cup butter, softened\n- 3/4 cup granulated sugar\n- 3/4 cup packed brown sugar\n- 2 large eggs\n- 2 tsp vanilla extract\n- 2 cups chocolate chips\n\nInstructions:\n1. Preheat oven to 375°F.\n2. Mix flour, baking soda, and salt in a small bowl.\n3. Beat butter, granulated sugar, and brown sugar in a large mixer bowl.\n4. Add eggs and vanilla; beat well.\n5. Gradually beat in flour mixture.\n6. Stir in chocolate chips.\n7. Drop by rounded tablespoon onto ungreased baking sheets.\n8. Bake for 9 to 11 minutes or until golden brown.\n9. Cool on baking sheets for 2 minutes; remove to wire racks to cool completely."
}

Response

{
  "title": "Chocolate Chip Cookies",
  "ingredients": [
    "2 1/4 cups all-purpose flour",
    "1 tsp baking soda",
    "1 tsp salt",
    "1 cup butter, softened",
    "3/4 cup granulated sugar",
    "3/4 cup packed brown sugar",
    "2 large eggs",
    "2 tsp vanilla extract",
    "2 cups chocolate chips"
  ],
  "instructions": [
    "Preheat oven to 375°F.",
    "Mix flour, baking soda, and salt in a small bowl.",
    "Beat butter, granulated sugar, and brown sugar in a large mixer bowl.",
    "Add eggs and vanilla; beat well.",
    "Gradually beat in flour mixture.",
    "Stir in chocolate chips.",
    "Drop by rounded tablespoon onto ungreased baking sheets.",
    "Bake for 9 to 11 minutes or until golden brown.",
    "Cool on baking sheets for 2 minutes; remove to wire racks to cool completely."
  ],
  "prepTime": 15,
  "cookTime": 11,
  "servings": 24,
  "tags": ["dessert", "cookies", "chocolate"]
}

Error Responses

All endpoints return standard HTTP status codes:

Error responses will have the following format:

{
  "error": "Error type",
  "message": "Detailed error message"
}