Documentation

Getting Started

Everything you need to integrate with or build on the Waste Warriors platform.

Overview

The Waste Warriors REST API allows you to manage pickups, process payments, and track recyclers programmatically. All endpoints return JSON and use Laravel Sanctum for authentication.

Base URL: https://api.wastewarrior.co.ke/api

Authentication

All protected endpoints require a Bearer token in the Authorization header. Obtain a token by calling the login endpoint.

POST /api/auth/login
{
  "phone": "07xxxxxxxxx",
  "password": "yourpassword"
}
Response
{
  "token": "1|abc123...",
  "user": { "id": 1, "name": "James", "role": "producer" }
}

Pass the token on every subsequent request: Authorization: Bearer 1|abc123...

Pickups

GET /producer/pickups
POST /producer/pickups
GET /producer/pickups/{id}
POST /producer/pickups/{id}/cancel
GET /recycler/pickups
POST /recycler/pickups/{id}/accept
POST /recycler/pickups/{id}/complete

Payments

Payments use M-Pesa STK Push (initiate + poll for status) and B2C for payouts. An in-app wallet is also available for both producers and recyclers.

POST /mpesa/stk/topup
GET /mpesa/stk/{checkoutId}/status
POST /mpesa/withdraw
GET /wallet/balance
GET /wallet/transactions

Live Tracking

Recyclers push their GPS position; producers poll for the current location. No WebSocket required.

POST /pickups/{id}/location
GET /pickups/{id}/location/current
GET /pickups/{id}/location/trail

Error Codes

Code Meaning
400 Validation error — check the message field for details
401 Unauthenticated — missing or invalid Bearer token
403 Forbidden — insufficient role or payment permission disabled
404 Resource not found
422 Business logic error (e.g. pickup already accepted)
500 Server error — contact support with the request ID