API Documentation

Complete API reference for Hoofs & Paws platform

Base URL: https://alpha.hoofsandpaws.co/api/v1 Version: v1

Navigation

Authentication

Most endpoints require authentication using Laravel Sanctum. Include the token in the Authorization header:

Authorization: Bearer {token}

Register

POST
/auth/register

Request Body:

{
  "email": "user@example.com",
  "password": "password123",
  "password_confirmation": "password123",
  "role": "owner",
  "phone": "+1234567890",
  "first_name": "John",
  "last_name": "Doe"
}

Response (201):

{
  "message": "Registration successful",
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "role": "owner",
    "profile": {...}
  },
  "token": "sanctum_token",
  "token_type": "Bearer"
}

Login

POST
/auth/login

Request Body:

{
  "email": "user@example.com",
  "password": "password123"
}

Logout

POST
/auth/logout

Requires authentication token in header.

Users

Get Current User

GET
/user

Returns the authenticated user's profile and related data.

Response (200):

{
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "role": "owner",
    "profile": {...},
    "provider_profile": {...}
  }
}

Pets

List Pets

GET
/pets

Create Pet

POST
/pets

Request Body:

{
  "species_id": 1,
  "name": "Buddy",
  "breed": "Golden Retriever",
  "age_years": 3,
  "weight_pounds": 65.5,
  "gender": "male"
}

Get Pet

GET
/pets/{id}

Update Pet

PUT
/pets/{id}

Delete Pet

DELETE
/pets/{id}

Providers

List Providers

GET
/providers

Query params: tier

Get Provider

GET
/providers/{id}

Get Provider Profile

GET
/providers/profile

Update Provider Profile

PUT
/providers/profile

Services

List Services

GET
/services

Query params: type, species_id, provider_id, max_price

Get Service

GET
/services/{id}

Provider Service Management

List Provider Services GET
/providers/services
Create Service POST
/providers/services
Update Service PUT
/providers/services/{id}
Delete Service DELETE
/providers/services/{id}

Bookings

List Bookings

GET
/bookings

Returns bookings based on user role.

Create Booking

POST
/bookings

Request Body:

{
  "service_id": 1,
  "pet_ids": [1, 2],
  "start_time": "2025-01-20T10:00:00Z",
  "end_time": "2025-01-20T12:00:00Z",
  "special_instructions": "Please avoid other dogs",
  "service_location": {
    "address": "123 Main St",
    "city": "City",
    "state": "State",
    "zip_code": "12345"
  }
}

Response (201):

{
  "message": "Booking request created successfully",
  "data": {
    "id": 1,
    "status": "pending",
    "total_amount": 50.00,
    "platform_fee": 10.00,
    "provider_payout": 40.00
  }
}

Update Booking Status

PUT
/bookings/{id}

Valid statuses: accepted, declined, confirmed, in_progress, completed, cancelled

Request Body:

{
  "status": "accepted",
  "cancellation_reason": "Optional if cancelling"
}

Reviews

List Reviews

GET
/reviews

Query params: provider_id, service_id, booking_id

Create Review

POST
/reviews

Can only review completed bookings.

Request Body:

{
  "booking_id": 1,
  "rating": 5,
  "comment": "Excellent service!",
  "photos": ["https://example.com/photo.jpg"]
}

Messaging

List Conversations

GET
/conversations

Create/Get Conversation

POST
/conversations

Body: {"booking_id": 1}

Send Message

POST
/messages

Request Body:

{
  "conversation_id": 1,
  "content": "Hello, I have a question",
  "attachments": ["https://example.com/file.jpg"]
}

Onboarding

Provider Onboarding

POST /onboarding/provider/profile
GET /onboarding/provider/search-business
POST /onboarding/provider/create-business
POST /onboarding/provider/complete

Owner Onboarding

POST /onboarding/owner/profile
GET /onboarding/owner/pet-species
POST /onboarding/owner/add-pet
POST /onboarding/owner/complete

Error Responses

400 Bad Request

{
  "message": "Validation failed",
  "errors": {
    "email": ["The email field is required."]
  }
}

401 Unauthorized

{
  "message": "Unauthenticated."
}

403 Forbidden

{
  "message": "Unauthorized: You can only access your own resources"
}

404 Not Found

{
  "message": "Resource not found"
}

Rate Limiting

API requests are rate-limited to 60 requests per minute per user/IP for most endpoints.

Rate limit headers are included in responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59