Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/OluwagbeminiyiA/agro_pulse-API/llms.txt

Use this file to discover all available pages before exploring further.

The Produce API powers the AgroPulse marketplace catalog. Farmers use it to list items for sale — specifying the crop category, price per unit, quantity on hand, and expected harvest date — while buyers and administrators use it to browse and filter the full catalog. Every listing is scoped to a FarmerProfile and exposes a live availability_status that reflects current stock. All endpoints require a valid JWT Bearer token.

​
Base path

/api/produces/

​
Authentication

All endpoints require a JWT Bearer token in the Authorization header.

​
Endpoints

MethodPathDescriptionAuth required
GET/api/produces/List produce listingsYes
POST/api/produces/Create a new produce listingYes
GET/api/produces/{id}/Retrieve a single listing by UUIDYes
PUT/api/produces/{id}/Full update of a produce listingYes
PATCH/api/produces/{id}/Partial update of a produce listingYes
DELETE/api/produces/{id}/Delete a produce listingYes

​
Create a produce listing

POST /api/produces/ Creates a new Produce listing owned by the specified farmer. The id, created_at, and updated_at fields are set automatically by the server and must not be included in the request body. availability_status defaults to AVAILABLE if omitted.
​
farmer
string
required
UUID of the FarmerProfile that owns this listing.
​
produce_name
string
required
Name of the produce item (max 255 characters). For example, "Roma Tomatoes".
​
category
string
required
Produce category. Must be one of: VEGETABLES, FRUITS, GRAINS, DAIRY, MEAT, OTHER.
​
unit_price
number
required
Price per unit in the platform currency. Decimal, up to 2 decimal places (e.g., 4.50).
​
quantity_available
integer
required
Number of units currently in stock.
​
harvest_date
string
required
Expected or actual harvest date in YYYY-MM-DD format.
​
availability_status
string
default:"AVAILABLE"
Stock status. Must be one of: AVAILABLE, LOW_STOCK, SOLD_OUT. Defaults to AVAILABLE.

​
Example request

curl --request POST \
  --url https://api.agropulse.example.com/api/produces/ \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "farmer": "b7d2e4f6-91c3-4a2b-8d0e-56f7a8b9c012",
    "produce_name": "Roma Tomatoes",
    "category": "VEGETABLES",
    "unit_price": "4.50",
    "quantity_available": 200,
    "harvest_date": "2026-06-01",
    "availability_status": "AVAILABLE"
  }'

​
Example response

{
  "id": "e1c4f2a7-33d9-4b8e-a5f0-72c1d3e9b405",
  "farmer": "b7d2e4f6-91c3-4a2b-8d0e-56f7a8b9c012",
  "farmer_farm_name": "Golden Harvest Farms",
  "farmer_user_full_name": "Amara Osei",
  "produce_name": "Roma Tomatoes",
  "category": "VEGETABLES",
  "unit_price": "4.50",
  "quantity_available": 200,
  "harvest_date": "2026-06-01",
  "availability_status": "AVAILABLE",
  "created_at": "2026-05-13T11:00:00.000000Z",
  "updated_at": "2026-05-13T11:00:00.000000Z"
}
Retrieving a single listing via GET /api/produces/{id}/ returns a farmer_details object in place of farmer_farm_name and farmer_user_full_name. The nested object includes farm_name, farm_location, farmer_name, farmer_email, and farmer_phone.

​
List produce

GET /api/produces/ Returns an array of produce listings ordered by created_at descending. Use the query parameters below to narrow results.

​
Query parameters

​
category
string
Filter by produce category. One of: VEGETABLES, FRUITS, GRAINS, DAIRY, MEAT, OTHER.
​
availability_status
string
Filter by stock status. One of: AVAILABLE, LOW_STOCK, SOLD_OUT.
​
farmer
string
Filter by farmer UUID. Returns only listings owned by the specified FarmerProfile.
​
search
string
Full-text search term matched against produce fields.
​
ordering
string
Sort results by a field name. Prefix with - for descending order (e.g., -unit_price, harvest_date).

​
Example request

curl --request GET \
  --url 'https://api.agropulse.example.com/api/produces/?category=VEGETABLES&availability_status=AVAILABLE&ordering=-created_at' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

​
Produce object

​
id
string
required
UUID primary key. Auto-generated on creation, never editable.
​
farmer
string
required
UUID of the FarmerProfile that owns this listing.
​
farmer_farm_name
string
required
Name of the farmer’s farm. Read-only, derived from the linked FarmerProfile.
​
farmer_user_full_name
string
required
Full name of the farmer. Read-only, derived from the linked User account.
​
produce_name
string
required
Name of the produce item.
​
category
string
required
Produce category. One of: VEGETABLES, FRUITS, GRAINS, DAIRY, MEAT, OTHER.
​
unit_price
string
required
Price per unit as a decimal string (e.g., "4.50").
​
quantity_available
integer
required
Number of units currently in stock.
​
harvest_date
string
required
Harvest date in YYYY-MM-DD format.
​
availability_status
string
required
Stock status. One of: AVAILABLE, LOW_STOCK, SOLD_OUT.
​
created_at
string
required
ISO 8601 timestamp of listing creation. Read-only.
​
updated_at
string
required
ISO 8601 timestamp of the last update. Read-only.

Build docs developers (and LLMs) love

Get started for freeTalk to us