SDK & API

The SDK & API Settings page is where you create, label, test, update, and revoke the API keys used for programmatic access to PawPlacer. This lets you keep each integration isolated instead of sharing one secret everywhere.

Accessing SDK & API

1. Open Settings
2. Make sure the settings sidebar is showing Organization Settings
3. Click SDK & API

Recommended path: For JavaScript and TypeScript projects, use the PawPlacer SDK. It wraps the full public API, adds typed responses and caching, and is the fastest way to integrate safely.

Overview

PawPlacer exposes an official JavaScript SDK for pets, adopters, fosters, adoption fees, contracts, and custom fields. The SDK is the preferred path for JavaScript/TypeScript projects. The older REST API remains online for existing integrations and non-JavaScript clients, but new work should start with the SDK.

The SDK and API key tools support these operations:

• Retrieve pet, adopter, and foster data for display on external websites
• Automate data synchronization with other systems
• Create new pet profiles or adopter/foster records from external forms
• Fetch adoption fee rules and terms & conditions for your own application forms
• Build custom integrations and workflows

API Key Management

Create Your First Keys

The API Keys panel shows active, read, and write key counts at the top, followed by a Create a new key form. Most teams should create at least two keys:

1. A Read only key for websites, dashboards, and public listings
2. A Write + read key only for trusted backend jobs that create pets or people

When you create a key:

1. Give it a specific name such as "Website sync" or "Nightly import"
2. Choose Read only or Write + read from the access level menu
3. Copy the full secret immediately
4. Store it in your password manager or server-side secret store

PawPlacer shows the full secret only once. After that, Settings shows only the preview and metadata for the key.

Read vs Write Access

• Read only keys can call all GET endpoints (pets, people, adoption fees, contracts, custom fields)
• Write + read keys can call POST endpoints (POST /api/pets, POST /api/people) plus all read endpoints
• Write keys should stay limited to trusted server-side workloads
• Public websites should almost always use Read only keys

API Key Security

Each API key grants server-side access to the public API for your organization. Treat every key like a password:

• Never share your API key publicly
• Don't commit it to version control systems
• Don't include it in client-side code
• Store it securely and limit access to trusted team members

Updating and Revoking Keys

If one integration is compromised or no longer needed:

1. Create a replacement key for that specific integration
2. Update the external system to use the new key
3. Revoke the old key in Settings

Because keys are scoped per integration, you do not need to rotate every other system at the same time.

You can also rename an active key or change its scope directly from the key row. Update the Name or Scope fields, then click Save. Revoked keys remain visible with their status but cannot be used or edited.

What You Can See in Settings

The Settings page shows:

• Active, read, and write key counts
• Key name
• Scope (Read only or Write + read)
• Status
• Secret preview
• Created time
• Last used time

Use this metadata to keep external systems documented and to identify keys that should be rotated or removed.

Testing Your Key

The SDK & API Settings page includes a built-in Test Your Key health check beside the API Keys panel. When you create a new key, the health check input is filled automatically. You can also paste an existing full key manually.

To use it:

1. Paste your full API key into the input field
2. Click Run Health Check

The tool runs through a series of tests grouped by category:

• Pets: pets.list(), pets.findMany(), pets.get(id), pets.search('dog'), pets.getByStatus('available'), pets.getCustomFields()
• People: people.list(adopter), people.list(foster), people.findMany(adopter), people.get(id, adopter), people.getCustomFields(adopter), people.getCustomFields(foster)
• Adoption Fees & Contracts: adoptionFees.get(), contracts.get('adopter'), contracts.get('foster'), contracts.get('volunteer')
• Write Access: creates temporary test records and deletes them immediately to confirm write permissions without leaving data behind
• Response Metadata: reads lastResponseMeta to verify request IDs, rate limit info, and API version are returned correctly

Each test shows a pass/fail status with response time in milliseconds. You can expand any row to inspect the raw response data or error message.

This is the only place where it is safe to enter your full API key in a browser. The key is held in memory only and is never sent to any server other than your own PawPlacer account, logged, or stored.

Prefer the SDK

The PawPlacer SDK should be your default choice for new development. The SDK tab includes install commands for Bun, npm, and Yarn, a copyable quick-start example, the available endpoint list with scope and rate-limit badges, and the main SDK advantages.

The SDK covers pets, people, adoption fees, contracts, and custom fields with typed responses, smart caching, automatic retries, and idempotency for safe create operations.

Continue to store your SDK credentials securely and rotate them on the same cadence as API keys.

Legacy REST API

The Legacy REST API tab explains that the public REST API is deprecated and remains online for legacy integrations until at least the end of 2026. Use it when you are maintaining an existing integration or when SDK usage is not possible, such as:

• Integrating from a non-JavaScript runtime
• Generating clients from the OpenAPI contract
• Building custom middleware, sync jobs, or partner tooling around raw HTTP

If you are already using the REST API successfully, you do not need to migrate immediately. For new JavaScript or TypeScript work, prefer the SDK.