• Home
  • FAQ
  • Features
  • Docs
  • About
  • Pricing
Log In
Log InJoin Now

JavaScript SDK

Use the official PawPlacer SDK for painless API access

Install the PawPlacer SDK from npm for the fastest path to our public API: https://www.npmjs.com/package/pawplacer-sdk.

The package is TypeScript-first—the client and every helper ship with rich typings so editors surface the exact payload shape returned by our Supabase functions. It wraps the public endpoints, handles retries, memoized caching, and validates required fields before sending create requests.

Security reminder: Instantiate the client on the server. The SDK throws if it detects a browser environment unless you explicitly pass allowBrowser: true (NEVER DO THIS outside local development).

Why use the SDK?

  • Typed responses – the Pet interface mirrors the get_public_pets response so you always know which fields are available.
  • Smart caching – in-memory memoization refreshes results on a schedule you choose while staying within rate limits.
  • Retry & error parsing – transient failures are retried automatically and JSON error payloads are attached to thrown errors as apiError.
  • Server guardrails – the client refuses to instantiate in a browser by default to protect your API keys.

Installation

npm install pawplacer-sdk
# or
yarn add pawplacer-sdk
# or
bun add pawplacer-sdk

No extra @types package is required—the SDK bundles its own declarations. Track release history in the packaged CHANGELOG.md file (also linked from the npm README).

Integration checklist

  1. Generate an API key in Settings -> API.
  2. Store it in server-only environment variables (never client-exposed values).
  3. Instantiate PawPlacerClient on the server.
  4. Use client.pets.list(...) / client.pets.getById(...) for reads.
  5. Use client.pets.getCustomFields() before sending custom_field_data during creates.

Quick start

import { PawPlacerClient } from "pawplacer-sdk";

const client = new PawPlacerClient({
  apiUrl: process.env.PAWPLACER_API_URL ?? "https://pawplacer.com",
  apiKey: process.env.PAWPLACER_API_KEY,
  cache: {
    enabled: true,
    refreshFrequency: 180, // minutes
  },
});

const pets = await client.pets.list({ status: "available", species: "dog", limit: 12 });
const fields = await client.pets.getCustomFields();

const created = await client.pets.create({
  name: "Max",
  species: "dog",
  age_category: "young",
  sex: "male",
  size: "medium",
  status: "available",
  health: "good",
  show_public: true,
  adoption_fee: 250,
  breed: ["Labrador Retriever"],
  good_with: ["families", "kids"],
  temperaments: ["playful", "social"],
});

cache.refreshFrequency is expressed in minutes. Leave it undefined to keep the 3-hour default.

Configuration options

OptionDescription
apiUrlBase URL of the PawPlacer API (defaults to production).
apiKeyServer-side API key. Required for all non-public operations.
timeoutRequest timeout in milliseconds (default 30000).
retryLimit / retryBackoffLimitControl ky's retry strategy for transient failures.
debugEnables verbose logging ([PawPlacer SDK] …).
allowBrowserOpt-in to browser usage. Leave false to protect credentials. NEVER DO THIS on production.
cacheToggle memoization and choose how often cached results refresh.

Available helpers

MethodSummary
client.pets.list(params?)Paginated list of public pets with optional filters.
client.pets.get(id) / client.pets.getById(id)Fetch a single public pet by ID.
client.pets.getCustomFields()Retrieve valid field_key values for custom_field_data.
client.pets.create(payload)Create a pet (validates required fields before calling the API).
client.pets.findMany(params?, limit?)Convenience helper that returns just the data array.

Endpoint mapping

SDK methodEndpoint
client.pets.list(...)GET /api/pets
client.pets.getById(...)GET /api/pets/{petId}
client.pets.getCustomFields()GET /api/pets/custom-fields
client.pets.create(...)POST /api/pets

The returned Pet type reflects the full public payload, including tags, custom_field_data, and resolved relationship names like primary_veterinarian. client.pets.list(...) also supports updated_since (ISO-8601) for incremental sync pulls.

Need something more advanced? Import RequestManager or CacheManager from pawplacer-sdk to build custom integrations while reusing the memoization layer.

Prefer another language/runtime? Use the OpenAPI contract at https://pawplacer.com/openapi/public-api-v1.yaml to generate clients outside JavaScript/TypeScript.

Examples

  • sdk/examples/basic-usage.ts – CLI script that demonstrates listing, fetching, creating, and searching pets
  • sdk/examples/full-app.tsx – Next.js App Router playground showing server actions wired to pawplacer-sdk

Copy whichever example fits your stack and adapt the filters or payloads to suit your workflow.

Related docs

  • Developer API overview
  • Get public pet data
  • Create a pet via API
PreviousPetLink Microchip RegistryNextManaging Clinics

PawPlacer

© Copyright 2026 PawPlacer. All Rights Reserved.

Contact
  • Email
About
  • About Us
  • Funding Philosophy
  • Careers
  • FAQ
  • Pricing
  • Changelog
Legal
  • Terms of Service
  • Privacy Policy
  • Cookie Policy