Files
Django_TasksApp/main/API.md
T

5.1 KiB

TaskNest Food and Kitchen API v1

The API is intended for a future thin MCP adapter. It is available under /api/v1/; machine-readable OpenAPI 3.1 is at /api/v1/schema/. No MCP server or interactive production API UI is included.

Authentication and permissions

Create a personal token in Settings → API access. The full tn_... token is shown once. Send it as Authorization: Bearer <token>. A token identifies its owner; API requests do not accept a user identifier. Tokens can have food:read, food:write, inventory:read, and inventory:write. A missing, invalid, revoked, or expired token returns HTTP 401. A missing scope returns HTTP 403. The token management screen supports optional expiry and revocation. HTTPS is required in deployment to protect bearer tokens in transit.

Each resource lookup filters by the token owner. An unknown UUID and another user's UUID both return 404. The API does not use session authentication, and its bearer-token views are CSRF exempt. Default Django CORS policy does not grant cross-origin browser access. Do not log Authorization headers.

Endpoints

Method Route Scope Purpose
GET /food/today/ food:read User-local date, entries grouped by meal, seven daily totals, and existing goals
GET /food/products/?search=&limit=30&offset=0 food:read Own products, nutrition per 100, and portions; no raw_data
POST /food/log/ food:write Create from an owned product_id or manual snapshot
GET/PATCH/DELETE /food/log/{id}/ read/write Own log entry
POST /food/log/{id}/attachments/ food:write Multipart image upload to an owned entry
GET /food/attachments/{id}/file/ food:read Authenticated image retrieval
DELETE /food/attachments/{id}/ food:write Delete an owned image
GET/POST /kitchen/items/ read/write Search/list or create inventory item
GET/PATCH/DELETE /kitchen/items/{id}/ read/write Own inventory item

Collection responses use count, limit, offset, and results. The default limit is 30 and maximum is 100; offset is capped at 10,000. Product and inventory search checks name, brand, and barcode; inventory search also checks location and category. GET /food/today/ is naturally bounded by one day.

JSON decimal values are strings to preserve precision. For food creation, send meal, positive decimal amount, and unit (g or ml). With product_id, nutrition and name snapshots are calculated from that owned product using the same service as the web UI, and the unit must match its basis. Without a product, send product_name and optional brand, barcode, portion_label, and nutrition totals (calories_kcal, carbohydrates_g, protein_g, fat_g, fibre_g, sugars_g, salt_g). Manual entries are snapshot-only, so repeat estimates do not create duplicate products. date defaults to the user's saved local time zone date; an explicit ISO date and optional time can be supplied. API entries have created_via: api, separate from their nutrition source.

Inventory creation requires an owned product UUID, positive integer quantity, and a location name. Optional fields are category, notes, opened, and best_before. Location and category names reuse the application's owned lookup records. There is no invented inventory unit: the existing model counts whole items. DELETE removes the item, matching the API operation; the web inventory still has its separate archive behavior.

For attachment upload, send multipart image and optional caption. JPEG, PNG, and WebP are accepted after decoding and format/MIME checks. The file limit is 5 MiB and the pixel limit is 25 million. Images are stored under main/private_media/, which has no public media URL; download requires food:read and ownership of the parent entry. Filenames on disk are random. The original filename is metadata only.

POST creation routes accept an optional Idempotency-Key header. Repeating the same token, route, key, and body returns the stored result and creates no second record. Reusing a key with a different body or route returns 409. Keys are per token. JSON errors use {"error":{"code":"...","message":"..."}}; validation may include details. Common codes include invalid_token, expired_token, insufficient_scope, entry_not_found, product_not_found, inventory_item_not_found, image_too_large, and unsupported_image_type.

Example requests

TOKEN='<token-shown-once-in-settings>'
curl -H "Authorization: Bearer $TOKEN" https://example.com/api/v1/food/today/
curl -H "Authorization: Bearer $TOKEN" 'https://example.com/api/v1/food/products/?search=pasta'
curl -X POST https://example.com/api/v1/food/log/ \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: dinner-2026-10-07-1' \
  -d '{"meal":"dinner","product_name":"Homemade satay","amount":"1","unit":"g","calories_kcal":"850"}'
curl -X POST https://example.com/api/v1/food/log/ENTRY_UUID/attachments/ \
  -H "Authorization: Bearer $TOKEN" -F 'image=@meal.jpg;type=image/jpeg' -F 'caption=Dinner'