Paws Source API Docs

Welcome to the Paws Source API. Our RESTful API lets you integrate pet management, veterinary consultations, nutrition planning, grooming bookings, and order processing directly into your applications. Build powerful pet care solutions with our comprehensive, developer-friendly endpoints.

Base URL https://api.paws-source.com/v2

📌

Note: All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Authentication

Paws Source uses API keys to authenticate requests. You can manage your API keys from the Dashboard. Keep your API keys secret and do not share them in publicly accessible areas.

HTTP

Authorization
Bearer ps_live_sk_a1b2c3d4e5f6g7h8i9j0

Content-Type
application/json
                        

API Key Types

Key Type	Prefix	Environment	Description
Live Key	ps_live_	Production	For live transactions and real data
Test Key	ps_test_	Sandbox	For testing — no real charges
Publishable Key	ps_pub_	Frontend	Safe for client-side use only

⚠️

Security Warning: Never expose your ps_live_ keys in client-side code or public repositories. Use ps_pub_ keys for frontend integrations only.

SDK Quick Start

Node.js / JavaScript

npm

npm install @paws-source/sdk

// Initialize
const paws = require('@paws-source/sdk')(
  'ps_live_sk_...'
);

// List pets
const pets = await paws.pets.list();
                        

Python

pip

pip install paws-source

# Initialize
import paws_source

paws = paws_source.Client(
    api_key="ps_live_sk_..."
)

# List pets
pets = paws.pets.list()
                        

Rate Limiting

API requests are rate limited to ensure fair usage and platform stability. Rate limit headers are included in every API response.

100

Requests / Minute

1,000

Requests / Hour

10,000

Requests / Day

Rate Limit Headers

Header	Description
X-RateLimit-Limit	Maximum requests allowed in the current window
X-RateLimit-Remaining	Number of requests remaining in the current window
X-RateLimit-Reset	Unix timestamp when the rate limit window resets

🚫

Exceeding Limits: When rate limits are exceeded, you'll receive a 429 Too Many Requests response. Implement exponential backoff in your retry logic.

Errors & Status Codes

Paws Source uses conventional HTTP status codes to indicate the success or failure of API requests. Errors are returned as JSON objects with a error key.

HTTP Status Codes

Code	Meaning	Common Causes
200	Success	Request processed successfully
201	Created	New resource created successfully
204	No Content	Resource deleted successfully
400	Bad Request	Malformed JSON, missing required fields
401	Unauthorized	Invalid or missing API key
403	Forbidden	Insufficient permissions for resource
404	Not Found	Resource does not exist
422	Unprocessable	Validation errors in request body
429	Too Many Requests	Rate limit exceeded
500	Server Error	Internal server error — retry with backoff

Error Response Format

                            JSON
                            
{

  "error": {

    "code": "invalid_request_error",

    "message": "Pet ID 'ps_123' not found.",

    "type": "not_found",

    "param": "id",

    "docs_url": "https://docs.paws-source.com/errors/404"

  }

}

Error Codes

Code	Description
invalid_request_error	The request was malformed or missing required parameters
authentication_error	API key is invalid, expired, or revoked
permission_error	API key lacks permission for this resource
not_found	The requested resource does not exist
rate_limit_error	Rate limit has been exceeded
validation_error	One or more fields failed validation
conflict_error	Resource conflict (e.g., duplicate booking)

Pagination

Most list endpoints support cursor-based pagination for efficient data retrieval. When requesting large datasets, use the limit and cursor parameters.

HTTP Request

GET /v2/pets?limit=20&cursor=ps_cursor_abc123

Pagination Parameters

Parameter	Type	Required	Description
limit	integer	Optional	Number of items to return (1–100, default: 20)
cursor	string	Optional	Cursor from previous response for next page
sort	string	Optional	Sort field: `created_at` or `name`

Pagination Response

                            JSON
                            
{

  "data": [ ... ],

  "has_more": true,

  "next_cursor": "ps_cursor_def456",

  "prev_cursor": "ps_cursor_ghi789"

}

🐾 Pets API

Manage pet profiles, including personal details, breeds, health records, and preferences.

GET /v2/pets Stable List all pets

Retrieves a paginated list of pets belonging to the authenticated account.

Query Parameters

Parameter	Type	Required	Description
type	string	Optional	Filter by type: `dog`, `cat`, `bird`, `rabbit`
status	string	Optional	Filter by status: `active`, `inactive`, `pending`
limit	integer	Optional	Number of items (default: 20, max: 100)
cursor	string	Optional	Pagination cursor

Example Request

cURL

curl https://api.paws-source.com/v2/pets?limit=10&type=dog

  -H "Authorization: Bearer ps_live_sk_..."

  -H "Content-Type: application/json"

Example Response

                                    JSON (200 OK)
                                    
                                

{
  "data": [
    {
      "id": "ps_pet_01JK3X4A5B6C7D8E9F",
      "name": "Buster",
      "type": "dog",
      "breed": "Golden Retriever",
      "age": 4,
      "weight_kg": 32.5,
      "gender": "male",
      "status": "active",
      "microchip_id": "985112004536789",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2025-03-10T14:22:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "ps_cursor_xyz789"
}
                                

POST /v2/pets Stable Create a pet

Creates a new pet profile in your account.

Request Body

Field	Type	Required	Description
name	string	Required	Pet's name (max 64 characters)
type	string	Required	Pet type: `dog`, `cat`, `bird`, `rabbit`, `hamster`
breed	string	Optional	Breed name
age	integer	Optional	Age in years
weight_kg	float	Optional	Weight in kilograms
gender	string	Optional	`male` or `female`
microchip_id	string	Optional	ISO 11784 compliant microchip ID
notes	string	Optional	Additional notes about the pet

Example Request

cURL

curl https://api.paws-source.com/v2/pets

  -X "POST"

  -H "Authorization: Bearer ps_live_sk_..."

  -H "Content-Type: application/json"

  -d '{
    "name": "Whiskers",
    "type": "cat",
    "breed": "Siamese",
    "age": 3,
    "weight_kg": 4.2,
    "gender": "female",
    "notes": "Indoor cat, allergic to chicken"
  }'
                                

Example Response (201 Created)

                                    JSON
                                    
                                

{
  "id": "ps_pet_02MN4Y5B6C7D8E9F0G",
  "name": "Whiskers",
  "type": "cat",
  "breed": "Siamese",
  "age": 3,
  "weight_kg": 4.2,
  "gender": "female",
  "status": "active",
  "created_at": "2025-06-15T10:00:00Z",
  "updated_at": "2025-06-15T10:00:00Z",
  "_links": {
    "self": "https://api.paws-source.com/v2/pets/ps_pet_02MN4Y5B6C7D8E9F0G",
    "nutrition_plan": "https://api.paws-source.com/v2/nutrition/plans?pet_id=ps_pet_02MN4Y5B6C7D8E9F0G",
    "vet_consults": "https://api.paws-source.com/v2/vet/consults?pet_id=ps_pet_02MN4Y5B6C7D8E9F0G"
  }
}
                                

GET /v2/pets/:id Stable Retrieve a pet

Retrieves the details of an existing pet profile.

Path Parameters

Parameter	Type	Required	Description
id	string	Required	The unique pet identifier (e.g., `ps_pet_01JK3X4A5B6C7D8E9F`)

💡

Tip: Use the expand query parameter to include nested objects: ?expand=nutrition_plan,vet_history

PATCH /v2/pets/:id Stable Update a pet

Updates a pet profile. Only the fields that are modified will be updated.

cURL

curl https://api.paws-source.com/v2/pets/ps_pet_02MN4Y5B6C7D8E9F0G

  -X "PATCH"

  -H "Authorization: Bearer ps_live_sk_..."

  -H "Content-Type: application/json"

  -d '{"weight_kg": 4.5, "status": "active"}'

Response: Returns the updated pet object (200 OK).

DELETE /v2/pets/:id Deprecated Delete a pet

Permanently deletes a pet profile. This action is irreversible and will also remove all associated records (nutrition plans, prescriptions, bookings).

⚠️

Destructive Action: Use with caution. For soft-delete behavior, update the pet's status field to inactive instead.

Response: 204 No Content on success.

🍖 Nutrition API

Create, manage, and retrieve personalized nutrition plans for pets.

POST /v2/nutrition/plans Stable Create nutrition plan

Generates a personalized nutrition plan based on the pet's profile, dietary restrictions, and health goals.

Request Body

Field	Type	Required	Description
pet_id	string	Required	The pet's unique identifier
dietary_preferences	string[]	Optional	Dietary needs: `grain-free`, `high-protein`, `weight_management`, `senior`
allergies	string[]	Optional	Known allergies: `chicken`, `beef`, `fish`, `dairy`
meal_frequency	string	Optional	Meals per day: `1`, `2`, `3` (default: `2`)
budget_max	float	Optional	Maximum monthly budget in USD

POST /v2/nutrition/suggest Beta AI-powered food suggestions

Uses AI to recommend specific food products based on the pet's profile and current health data.

✨

Beta Feature: This endpoint is in beta. We collect feedback to improve recommendations. Response format may change.

🩺 Veterinary API

Schedule and manage veterinary consultations and prescriptions.

POST /v2/vet/consult Stable Schedule consultation

Creates a new veterinary consultation request. You can choose between text, video, or phone consultation types.

Request Body

Field	Type	Required	Description
pet_id	string	Required	The pet's unique identifier
consult_type	string	Required	Type: `text`, `video`, `phone`
urgency	string	Optional	`routine`, `urgent`, `emergency` (default: `routine`)
symptoms	string	Optional	Description of symptoms or concerns
scheduled_at	datetime	Optional	Preferred appointment datetime (ISO 8601)

cURL

curl https://api.paws-source.com/v2/vet/consult

  -X "POST"

  -H "Authorization: Bearer ps_live_sk_..."

  -H "Content-Type: application/json"

  -d '{
    "pet_id": "ps_pet_02MN4Y5B6C7D8E9F0G",
    "consult_type": "video",
    "urgency": "urgent",
    "symptoms": "Vomiting for the past 24 hours, reduced appetite"
  }'
                                

Example Response (201 Created)

                                    JSON
                                    
                                

{
  "id": "ps_consult_03PQ5R6S7T8U9V0W1X",
  "pet_id": "ps_pet_02MN4Y5B6C7D8E9F0G",
  "consult_type": "video",
  "urgency": "urgent",
  "status": "assigned",
  "assigned_vet": {
    "id": "ps_vet_04AB1C2D3E4F5G6H7I",
    "name": "Dr. Sarah Johnson",
    "specialty": "Small Animal Medicine",
    "avatar_url": "https://cdn.paws-source.com/vets/dr-johnson.jpg"
  },
  "meeting_link": "https://meet.paws-source.com/consult/abc123",
  "scheduled_at": "2025-06-15T14:00:00Z",
  "created_at": "2025-06-15T10:30:00Z"
}
                                

GET /v2/vet/consult/:id Stable Get consultation status

Retrieves the current status and details of a veterinary consultation.

Status values: pending → assigned → in_progress → completed → cancelled

GET /v2/vet/prescriptions Stable List prescriptions

Returns all active and past prescriptions for the authenticated account's pets.

Query Parameters

Parameter	Type	Required	Description
pet_id	string	Optional	Filter by pet
status	string	Optional	`active`, `completed`, `expired`

✂️ Grooming & 🏠 Boarding API

POST /v2/grooming/bookings Stable Book grooming

Request Body

Field	Type	Required	Description
pet_id	string	Required	The pet's unique identifier
package_id	string	Required	Grooming package: `basic`, `premium`, `spa`
preferred_date	datetime	Optional	Preferred appointment date (ISO 8601)
notes	string	Optional	Special instructions

POST /v2/boarding/bookings Stable Book boarding

Request Body

Field	Type	Required	Description
pet_id	string	Required	The pet's unique identifier
check_in	datetime	Required	Check-in date/time (ISO 8601)
check_out	datetime	Required	Check-out date/time (ISO 8601)
room_type	string	Optional	`standard`, `deluxe`, `premium_suite`
special_needs	string	Optional	Medical or dietary needs during boarding

📦 Orders API

Create and manage orders for pet products, food, and services.

GET /v2/orders Stable List orders

Parameter	Type	Required	Description
status	string	Optional	`pending`, `processing`, `shipped`, `delivered`, `cancelled`
from	datetime	Optional	Filter orders from this date
to	datetime	Optional	Filter orders to this date

POST /v2/orders Stable Create order

Field	Type	Required	Description
items	object[]	Required	Array of items: `product_id`, `quantity`, `price`
shipping_address	object	Required	Full shipping address object
payment_method	string	Required	Payment method token from `/v2/payments`
gift_wrap	boolean	Optional	Enable gift wrapping (+$4.99)
promo_code	string	Optional	Discount promo code

POST /v2/orders/:id/cancel Stable Cancel order

Cancel an order if it hasn't been shipped yet. Full refund is processed within 5–7 business days.

📌

Note: Orders with status shipped or delivered cannot be cancelled via API. Use the Returns endpoint instead.

🔔 Webhooks

Paws Source sends HTTP POST notifications to your configured webhook endpoints when events occur. Configure webhook endpoints from your Dashboard → Webhooks.

                            HTTP Request
                            
                        

POST https://your-app.com/webhooks/paws-source

Content-Type: application/json

X-PawsSource-Signature: ts=1623847200,v1=a1b2c3d4e5f6...

X-PawsSource-Event: pet.profile_updated


{
  "id": "ps_evt_01JK3X4A5B6C7D8E9F",
  "type": "pet.profile_updated",
  "created_at": "2025-06-15T10:30:00Z",
  "data": {
    "id": "ps_pet_02MN4Y5B6C7D8E9F0G",
    "object_type": "pet",
    "changes": {
      "weight_kg": { "old": 4.2, "new": 4.5 }
    }
  }
}
                        

Webhook Signature Verification

Always verify the X-PawsSource-Signature header to ensure the request originated from Paws Source:

Node.js

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const [timestamp, signed] = signature.split(',');
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${payload}`)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signed),
    Buffer.from(expected)
  );
}
                        

Available Webhook Events

pet.created pet.updated pet.deleted nutrition.plan_created nutrition.plan_updated vet.consult.scheduled vet.consult.completed vet.prescription_issued grooming.booking_confirmed grooming.booking_cancelled boarding.booking_confirmed boarding.check_in boarding.check_out order.created order.paid order.shipped order.delivered order.cancelled order.refund_processed payment.failed

📚 SDKs & Libraries

Official SDKs are available for popular languages. Third-party community libraries are also supported.

Language	Package	Version	Status
JavaScript / Node.js	`@paws-source/sdk`	v3.2.0	Stable
Python	`paws-source`	v2.8.1	Stable
Ruby	`paws-source`	v1.14.0	Stable
Go	`github.com/paws-source/paws-go`	v2.1.0	Stable
PHP	`paws-source/paws-php`	v3.0.2	Stable
Java	`com.paws-source:java`	v2.5.0	Beta
Swift	`PawsSource`	v1.0.0	Beta

📝 Changelog

v2.1.0 Latest

June 10, 2025

Added AI-powered nutrition suggestions endpoint (/v2/nutrition/suggest)
New grooming booking endpoint with package tiers
Added expand parameter support for nested resource loading
Improved webhook signature verification with timestamp tolerance

v2.0.0

March 1, 2025

Breaking: API version moved to /v2/ — legacy v1 endpoints deprecated
Added boarding booking API
Cursor-based pagination replaces offset-based
New error response format with docs_url links
Added X-RateLimit-* headers to all responses

v1.4.2

November 15, 2024

Bug fix: Fixed pet profile update returning stale data
Added microchip_id field to pet responses
Performance improvements for list endpoints

Ready to Build?

Start integrating Paws Source API today. Get your API keys from the dashboard and explore our interactive playground.

Get API Keys → API Playground