Developer API

The PawPlacer public API gives you read and limited write access to public pet data so you can power listings, embeds, and partner workflows. Every request requires an API key created in Settings → API and must be issued from a trusted server-side environment.

Pick your integration path

• Use the official JavaScript SDK for typed helpers, caching, and retries.
• Synchronize adoptable pets to your website or mobile app directly via the public API.
• Embed filtered lists (featured pets, species-specific pages, adoption campaigns).
• Create new pet profiles from intake kiosks or partner systems.
• Populate forms with the same custom fields your staff uses internally.
• Run incremental sync jobs using GET /api/pets?updated_since=....

Available Endpoints

All endpoints respond with JSON. CORS is enabled so you can proxy requests through your own backend, but never expose your API key to untrusted clients.

Standard API Metadata

Every public pet endpoint includes:

• X-Request-Id for tracing support issues
• X-Api-Version and X-Generated-At for contract/timing visibility
• X-RateLimit-* headers to expose current limit window state

OpenAPI 3.1 Contract

Use the official OpenAPI contract for language-agnostic integrations, Postman imports, and client generation:

• Spec URL: https://pawplacer.com/openapi/public-api-v1.yaml

Authentication

Send your API key in the x-api-key header:

const response = await fetch('https://pawplacer.com/api/pets', {
  headers: { 'x-api-key': process.env.PAWPLACER_API_KEY }
});

Missing keys return 401 with { "error": "API key required", "code": "api_key_required", "request_id": "..." }, and invalid keys return 401 with { "error": "Invalid API key", "code": "invalid_api_key", "request_id": "..." }.

Handling Rate Limits

The API enforces per-organization rate limits. When a limit is hit you receive 429 and a descriptive JSON error. Best practices:

1. Cache responses for at least 5–10 minutes.
2. Batch frontend requests through your server.
3. Use background jobs to refresh data instead of polling from client devices.

Quick Start Workflow

1. Generate an API key in Settings → API.
2. Call GET /api/pets with the key to render public listings.
3. Fetch GET /api/pets/custom-fields to learn which field_key values you can send.
4. Create a pet via POST /api/pets when you need to push new data into PawPlacer.

Example Requests

// List adoptable dogs
const listResponse = await fetch('https://pawplacer.com/api/pets?species=dog&status=available&limit=8', {
  headers: { 'x-api-key': process.env.PAWPLACER_API_KEY }
});
const dogs = await listResponse.json();

// Fetch a single pet
const petResponse = await fetch(`https://pawplacer.com/api/pets/${dogs.pets[0].id}`, {
  headers: { 'x-api-key': process.env.PAWPLACER_API_KEY }
});
const pet = await petResponse.json();

// Create a new pet
const createResponse = await fetch('https://pawplacer.com/api/pets', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.PAWPLACER_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Max',
    species: 'dog',
    age_category: 'young',
    sex: 'male',
    size: 'medium',
    status: 'Available',
    health: 'good',
    show_public: true,
    breed: ['Labrador Retriever'],
    custom_field_data: {
      favorite_toy: 'Tennis ball'
    }
  })
});
const created = await createResponse.json();

Security Checklist

• Keep API keys in environment variables or secret managers.
• Proxy requests through your own backend when serving public sites.
• Rotate keys immediately if you suspect they were exposed.
• Respect rate limits and handle error responses gracefully.

Next Steps

• Follow the detailed GET guide for response formats and error handling.
• Review the POST guide to understand required fields and validation.
• Visit Settings → API to regenerate or revoke keys when needed.