FlavorShare API Documentation

Overview #

The FlavorShare API follows RESTful conventions and returns JSON-encoded responses. All endpoints are served over HTTPS. The base URL for all API requests is:

Base URL

https://api.flavorshare.com/v1

Supports standard HTTP methods: GET, POST, PUT, DELETE. Pagination is cursor-based for large datasets. All timestamps are in ISO 8601 format.

Authentication #

FlavorShare uses Bearer token authentication. Include your API key in the Authorization header for all requests.

Header

Authorization: Bearer YOUR_API_KEY

Generate keys from your FlavorShare Dashboard. Keys are scoped to specific environments and permissions. Keep them secure and never expose them in client-side code.

Endpoints #

Core recipe management endpoints for reading, creating, updating, and deleting culinary content.

GET /recipes

List recipes with filtering & pagination

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of results (1-100). Default: 20
`offset`	integer	Cursor for pagination
`category`	string	Filter by category: `dessert`, `main-course`, `appetizer`
`tags`	string[]	Comma-separated tags: `vegetarian,quick,dairy-free`
`sort`	string	Sort by: `created_at`, `popularity`, `rating`

Response (200)

JSON

{
  "data": [
    {
      "id": "rcp_8x92k4m1",
      "title": "Nonna's Classic Carbonara",
      "author": {
        "id": "usr_4a21",
        "username": "marco_rossi"
      },
      "prep_time_min": 25,
      "rating": 4.9,
      "tags": ["italian", "pasta", "comfort-food"]
    }
  ],
  "pagination": {
    "next_offset": "eyJpZCI6MTAwfQ",
    "has_more": true
  }
}

POST /recipes

Create a new recipe

Request Body

JSON

{
  "title": "Spicy Miso Ramen", // required
  "description": "Rich, creamy broth with tender chashu...", // required
  "category": "main-course",
  "ingredients": [
    { "name": "miso paste", "quantity": "3 tbsp" },
    { "name": "tonkotsu broth", "quantity": "1L" }
  ], // required
  "instructions": ["Boil broth...", "Add miso..."], // required
  "prep_time_min": 45,
  "tags": ["japanese", "spicy", "ramen"],
  "images": ["https://cdn.../img1.jpg"]
}

Response (201)

Returns the created recipe object with assigned id and created_at timestamp.

GET /recipes/:id

Get single recipe details

Retrieves full recipe data including ingredients, steps, nutritional info, and author details.

PUT /recipes/:id

Update recipe

Partially or fully updates a recipe. Requires ownership or admin permissions. Returns updated object.

DELETE /recipes/:id

Delete recipe

Permanently removes a recipe and associated media. Returns 204 No Content on success.

Status Codes #

FlavorShare uses standard HTTP response codes to indicate request outcomes.

200

Success. The request was completed successfully.

201

Created. The recipe or resource was successfully created.

400

Bad Request. Invalid parameters or malformed JSON payload.

401

Unauthorized. Missing or invalid API key.

403

Forbidden. Insufficient permissions for the requested action.

404

Not Found. The requested resource does not exist.

429

Too Many Requests. Rate limit exceeded. Retry after Retry-After header.

500

Internal Server Error. Something went wrong on our end. Please try again.

Error Handling #

Errors are returned in a consistent JSON format with a machine-readable code and human-friendly message.

Error Response

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Missing required field: title",
    "details": [
      { "field": "ingredients", "issue": "Must contain at least 1 item" }
    ],
    "request_id": "req_92f8a1b3"
  }
}

API Reference