recipe exchange
Back to Docs

Technical Integration Guide

This guide covers the technical details of integrating your existing recipe content with recipe.exchange through the AT Protocol. We support multiple integration paths, from completely automated publishing using our lexicons to hybrid approaches using our Schema.org compatibility.

Understanding the AT Protocol Recipe Lexicons

recipe.exchange extends the AT Protocol with custom lexicons for recipe sharing. Our lexicons are fully documented and available at:

Key Recipe Fields

{
  "$type": "exchange.recipe.recipe",
  "name": "Recipe Name",
  "text": "Recipe Description",
  "ingredients": ["array", "of", "ingredients"],
  "instructions": ["array", "of", "steps"],
  "prepTime": "PT30M",
  "cookTime": "PT1H",
  "totalTime": "PT1H30M",
  "recipeYield": "4 servings",
  "recipeCategory": "entree",
  "recipeCuisine": "italian",
  "cookingMethod": "exchange.recipe.defs#cookingMethodBaking",
  "nutrition": {
    "calories": 350,
    "fatContent": 12,
    "proteinContent": 28,
    "carbohydrateContent": 42
  },
  "suitableForDiet": [
    "exchange.recipe.defs#dietVegetarianDiet"
  ],
  "keywords": ["quick", "easy", "vegetarian"],
  "createdAt": "2024-01-15T00:00:00Z",
  "updatedAt": "2024-01-15T00:00:00Z"
}

Integration Options

1. Auto-Import Options

recipe.exchange offers multiple ways to automatically import your recipes:

Import from Website

The easiest way to import an existing recipe:

  1. Click “New Recipe” to start
  2. Select “Import from Website”
  3. Enter the URL of the recipe you want to import
  4. Our system will automatically detect and extract the recipe details using multiple methods:
    • Schema.org Recipe markup
    • Microdata or RDFa markup
    • General recipe content analysis

Import from Photo

Have a printed version of your recipe? You can import it using our photo import:

  1. Click “New Recipe” to start
  2. Select “Upload Photo”
  3. Take a photo or upload an existing image
  4. Our system will analyze the photo and extract the recipe details
    • For best results, ensure the photo is well-lit and the text is clearly visible
    • Supported formats: JPEG, PNG, GIF, WebP

2. Direct AT Protocol Integration

For automated publishing, you can interact directly with the AT Protocol.

Authentication

Before you can publish recipes programmatically, you’ll need to create an app password:

  1. Log into your Bluesky account at bsky.app
  2. Go to Settings → Privacy and Security → App Passwords
  3. Click “Create app password”
  4. Give your password a name (e.g., “recipe.exchange integration”)
  5. Copy the generated password immediately - you won’t be able to see it again

When using the AT Protocol client libraries, you’ll authenticate using your handle (e.g., yourdomain.com) and this app password instead of your main account password.

Integration Steps

  1. Authenticate with your AT Protocol credentials: handle & app password
  2. Create recipe records using our lexicon
  3. Publish to your personal data store (PDS)

Example Python script:

from atproto import Client, models

def publish_recipe(recipe_data):
    client = Client()

    # Authenticate the client with your Bluesky handle and app password
    client.login('handle.bsky.social', 'app-password')
    
    record = {
        '$type': 'exchange.recipe.recipe',
        'name': recipe_data['name'],
        'text': recipe_data['description'],
        'ingredients': recipe_data['ingredients'],
        'instructions': recipe_data['instructions'],
        # ... additional fields
    }
    
    response = client.com.atproto.repo.create_record(
        repo=client.me.did,
        collection='exchange.recipe.recipe',
        record=record
    )
    return response

# Usage example
recipe = {
    'name': 'Test Recipe',
    'description': 'A test recipe',
    'ingredients': ['Ingredient 1', 'Ingredient 2'],
    'instructions': ['Step 1', 'Step 2']
}
result = publish_recipe(recipe)

Data Validation

All recipes are validated against our lexicon schemas. Common requirements:

  • Recipe name: Required, max 255 characters
  • Description: Optional, max 1000 characters
  • Attribution: Must specify a valid attribution type and associated fields
  • Ingredients: At least one required
  • Instructions: At least one required
  • Durations: prep, cook, and total times use ISO 8601 duration format (e.g., “PT1H30M”)
  • URLs: Must be valid and accessible
  • Images: JPEG, PNG, or WebP, max 1MB per image

Need Help?

Additional Resources