Skip to content
Chomp Shopper home
Sign in

API documentation

Use Chomp Shopper's public REST API to read your recipes, make shopping lists and send them to Instacart.

Getting started

Everything you need to start using the Chomp Shopper API

Base URL

https://chompshopper.com/api/v1

Authentication

All API requests require authentication using an API key. Include your key in theX-API-Key header:

curl -H "X-API-Key: cs_live_your_key_here" \
  https://chompshopper.com/api/v1/me

Rate limiting

Free
100 requests/hour
Premium
1,000 requests/hour

Limits apply per API key.

Response format

All responses are returned in JSON format. Successful responses include the requested data, while errors include an error field.

// Success response
{
  "id": "abc123",
  "title": "Recipe Name",
  ...
}

// Error response
{
  "error": "Rate limit exceeded. Try again later."
}
GET
/api/v1/me
Get your account information and rate limit status

Example:

curl -H "X-API-Key: cs_live_xxx" https://chompshopper.com/api/v1/me

Response:

{
  "id": 123,
  "email": "user@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "tier": "free",
  "isPremium": false,
  "rateLimit": 100,
  "requestsThisHour": 5
}
GET
/api/v1/recipes/favorites
List your favorite recipes with pagination

Query Parameters:

limit (max 100), offset

Example:

curl -H "X-API-Key: cs_live_xxx" "https://chompshopper.com/api/v1/recipes/favorites?limit=10&offset=0"

Response:

{
  "recipes": [
    {
      "id": "abc123",
      "title": "Chicken Parmesan",
      "url": "https://example.com/recipe",
      "source": "example.com",
      "servings": 4,
      "cookTime": "45 minutes",
      "ingredients": ["1 lb chicken breast", "1 cup breadcrumbs"],
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 25,
    "limit": 10,
    "offset": 0,
    "hasMore": true
  }
}
GET
/api/v1/recipes/:id
Get a single recipe by ID

Example:

curl -H "X-API-Key: cs_live_xxx" https://chompshopper.com/api/v1/recipes/abc123

Response:

{
  "id": "abc123",
  "title": "Chicken Parmesan",
  "url": "https://example.com/recipe",
  "source": "example.com",
  "servings": 4,
  "cookTime": "45 minutes",
  "ingredients": ["1 lb chicken breast", "1 cup breadcrumbs"],
  "createdAt": "2024-01-15T10:30:00Z"
}
PUT
/api/v1/recipes/:id
Update a recipe (title, servings, cookTime, ingredients)

Example:

curl -X PUT -H "X-API-Key: cs_live_xxx" -H "Content-Type: application/json" \
  -d '{"title": "Updated Title", "servings": 6}' \
  https://chompshopper.com/api/v1/recipes/abc123

Response:

{
  "id": "abc123",
  "title": "Updated Title",
  "servings": 6,
  "message": "Recipe updated successfully"
}
GET
/api/v1/shopping-lists
List your shopping lists with pagination

Query Parameters:

limit (max 50), offset

Example:

curl -H "X-API-Key: cs_live_xxx" "https://chompshopper.com/api/v1/shopping-lists?limit=20"

Response:

{
  "lists": [
    {
      "id": "list123",
      "name": "Weekly Groceries",
      "recipeIds": ["abc123", "def456"],
      "ingredients": {
        "Produce": [{"id": "ing1", "name": "Tomatoes", "amount": "4", "category": "Produce"}]
      },
      "source": "web",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 15,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}
GET
/api/v1/shopping-lists/:id
Get a single shopping list by ID

Example:

curl -H "X-API-Key: cs_live_xxx" https://chompshopper.com/api/v1/shopping-lists/list123

Response:

{
  "id": "list123",
  "name": "Weekly Groceries",
  "recipeIds": ["abc123"],
  "ingredients": {...},
  "source": "web",
  "createdAt": "2024-01-15T10:30:00Z"
}
POST
/api/v1/shopping-lists/generate
Create a shopping list from recipe IDs

Request Body:

{ "recipeIds": ["abc123", "def456"], "name": "My List" }

Example:

curl -X POST -H "X-API-Key: cs_live_xxx" -H "Content-Type: application/json" \
  -d '{"recipeIds": ["abc123", "def456"], "name": "Weekend Cooking"}' \
  https://chompshopper.com/api/v1/shopping-lists/generate

Response:

{
  "id": "newlist789",
  "name": "Weekend Cooking",
  "recipeIds": ["abc123", "def456"],
  "ingredients": {...},
  "createdAt": "2024-01-15T10:30:00Z"
}
POST
/api/v1/instacart/push
Push a shopping list to Instacart (async job)

Request Body:

{ "shoppingListId": "list123", "postalCode": "10001" }

Example:

curl -X POST -H "X-API-Key: cs_live_xxx" -H "Content-Type: application/json" \
  -d '{"shoppingListId": "list123", "postalCode": "10001"}' \
  https://chompshopper.com/api/v1/instacart/push

Response:

{
  "jobId": "job_abc123",
  "status": "pending",
  "message": "Instacart push job created. Poll /api/v1/instacart/jobs/:jobId for status.",
  "statusUrl": "/api/v1/instacart/jobs/job_abc123"
}
GET
/api/v1/instacart/jobs/:jobId
Check status of an Instacart push job

Example:

curl -H "X-API-Key: cs_live_xxx" https://chompshopper.com/api/v1/instacart/jobs/job_abc123

Response:

{
  "id": "job_abc123",
  "status": "completed",
  "jobType": "instacart_push",
  "createdAt": "2024-01-15T10:30:00Z",
  "completedAt": "2024-01-15T10:30:05Z",
  "result": {
    "instacartUrl": "https://instacart.com/store/checkout/...",
    "itemCount": 12
  }
}

Sign in to manage API keys

Create an account or sign in to generate and manage your API keys

Sign In

JavaScript / Node.js

const API_KEY = 'cs_live_your_key_here';
const BASE_URL = 'https://chompshopper.com/api/v1';

// Fetch favorite recipes
async function getFavorites() {
  const response = await fetch(`${BASE_URL}/recipes/favorites`, {
    headers: {
      'X-API-Key': API_KEY
    }
  });
  return response.json();
}

// Generate a shopping list from recipes
async function createShoppingList(recipeIds, name) {
  const response = await fetch(`${BASE_URL}/shopping-lists/generate`, {
    method: 'POST',
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ recipeIds, name })
  });
  return response.json();
}

// Push to Instacart and wait for result
async function pushToInstacart(shoppingListId, postalCode) {
  // Start the job
  const jobResponse = await fetch(`${BASE_URL}/instacart/push`, {
    method: 'POST',
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ shoppingListId, postalCode })
  });
  const { jobId } = await jobResponse.json();
  
  // Poll for completion
  while (true) {
    const statusResponse = await fetch(`${BASE_URL}/instacart/jobs/${jobId}`, {
      headers: { 'X-API-Key': API_KEY }
    });
    const job = await statusResponse.json();
    
    if (job.status === 'completed') {
      return job.result;
    } else if (job.status === 'failed') {
      throw new Error(job.error);
    }
    
    // Wait before polling again
    await new Promise(resolve => setTimeout(resolve, 1000));
  }
}

Python

import requests
import time

API_KEY = 'cs_live_your_key_here'
BASE_URL = 'https://chompshopper.com/api/v1'
HEADERS = {'X-API-Key': API_KEY}

def get_favorites():
    response = requests.get(f'{BASE_URL}/recipes/favorites', headers=HEADERS)
    return response.json()

def create_shopping_list(recipe_ids, name):
    response = requests.post(
        f'{BASE_URL}/shopping-lists/generate',
        headers={**HEADERS, 'Content-Type': 'application/json'},
        json={'recipeIds': recipe_ids, 'name': name}
    )
    return response.json()

def push_to_instacart(shopping_list_id, postal_code):
    # Start the job
    response = requests.post(
        f'{BASE_URL}/instacart/push',
        headers={**HEADERS, 'Content-Type': 'application/json'},
        json={'shoppingListId': shopping_list_id, 'postalCode': postal_code}
    )
    job_id = response.json()['jobId']
    
    # Poll for completion
    while True:
        status_response = requests.get(
            f'{BASE_URL}/instacart/jobs/{job_id}',
            headers=HEADERS
        )
        job = status_response.json()
        
        if job['status'] == 'completed':
            return job['result']
        elif job['status'] == 'failed':
            raise Exception(job['error'])
        
        time.sleep(1)

# Example usage
favorites = get_favorites()
print(f"Found {len(favorites['recipes'])} favorite recipes")

recipe_ids = [r['id'] for r in favorites['recipes'][:3]]
shopping_list = create_shopping_list(recipe_ids, "Weekend Cooking")
print(f"Created shopping list: {shopping_list['name']}")

cURL

# Get your account info
curl -H "X-API-Key: cs_live_xxx" https://chompshopper.com/api/v1/me

# List favorite recipes
curl -H "X-API-Key: cs_live_xxx" \
  "https://chompshopper.com/api/v1/recipes/favorites?limit=10"

# Create a shopping list
curl -X POST \
  -H "X-API-Key: cs_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"recipeIds": ["abc123", "def456"], "name": "My List"}' \
  https://chompshopper.com/api/v1/shopping-lists/generate

# Push to Instacart
curl -X POST \
  -H "X-API-Key: cs_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"shoppingListId": "list123", "postalCode": "10001"}' \
  https://chompshopper.com/api/v1/instacart/push

# Check job status
curl -H "X-API-Key: cs_live_xxx" \
  https://chompshopper.com/api/v1/instacart/jobs/job_abc123