Copy page

Getting Started

Getting Started with Open Paws API

Welcome to the Open Paws API! This guide will help you start using our platform for animal advocacy research and campaign management.

What You Can Do

The Open Paws API provides access to:

• Search - Search campaigns, actions, public figures, organizations, content, and AI-generated suggestions
• OSINT - Generate intelligence profiles on individuals and companies for advocacy research
• Content Generation - Create advocacy content for social media, email, press, and education
• Chat - Conversational AI assistant with animal advocacy knowledge
• Legal Guidance - Legal information for advocacy activities (async, delivered via email)
• Issue Tracking - Monitor advocacy issues and topics (async, delivered via email)

Authentication

All API requests require an API key sent in the Authorization header.

What is an API key? An API key is a unique string that identifies your application. It's like a password for your app — keep it secret and never share it in public code repositories.

What does "Bearer" mean? Bearer is the authentication scheme name. It tells the API that the string following it is your API key. You must include this prefix.

Get your free API key:

Your API key will be created and ready to use. Include it in every request using the Authorization header:

Code
Authorization: Bearer YOUR_API_KEY

Example with curl:

Code
curl -X POST https://api.openpaws.ai/v1/search/campaigns \
  -H "Authorization: Bearer zpka_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"query": "factory farming", "search_type": "text", "limit": 10}'

Example with Python:

Code
import requests

API_KEY = "zpka_your_key_here"

response = requests.post(
    "https://api.openpaws.ai/v1/search/campaigns",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "query": "factory farming",
        "search_type": "text",
        "limit": 10
    }
)

data = response.json()
print(f"Found {data['total']} campaigns")
for campaign in data['results']:
    print(f"  - {campaign['title']}")

Example with JavaScript (Node.js / browser):

Code
const API_KEY = "zpka_your_key_here";

const response = await fetch("https://api.openpaws.ai/v1/search/campaigns", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    query: "factory farming",
    search_type: "text",
    limit: 10
  })
});

const data = await response.json();
console.log(`Found ${data.total} campaigns`);
data.results.forEach(c => console.log(`  - ${c.title}`));

API Versioning

All API endpoints are versioned with a /v1/ prefix. The health endpoint (/health) is the only unversioned route.

When we release breaking changes, they will go into a new version (/v2/). We will maintain at least two major versions simultaneously, with a minimum 6-month overlap period. See API Stability for full details.

Your First Request

Let's search for animal welfare campaigns. Click the button below to try it in the API Playground:

Example response:

Code
{
  "table": "campaigns",
  "search_type": "text",
  "query": "factory farming",
  "total": 25,
  "limit": 10,
  "offset": 0,
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "End Factory Farming Act",
      "description": "Campaign to pass federal legislation...",
      "goal": "Pass HR 1234 by end of 2025",
      "status": "active",
      "cause_areas": ["animal_welfare", "environment"],
      "country_codes": ["US"]
    }
  ]
}

Common Errors

Status	Meaning	How to Fix
401 Unauthorized	Missing or invalid API key	Check that your Authorization header includes Bearer followed by your key
400 Bad Request	Invalid request body	Check the error response detail field for what's wrong
429 Too Many Requests	Rate limit or quota exceeded	Wait and retry with exponential backoff. Check the Retry-After header if present

Error response format (RFC 7807 Problem Details):

Code
{
  "type": "https://httpproblems.com/http-status/401",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authorization Failed",
  "instance": "/v1/search/campaigns",
  "trace": {
    "timestamp": "2026-03-17T10:12:45.976Z",
    "requestId": "fa517881-fc1b-4b5b-af6d-f301bb445c55",
    "buildId": "a825bb9b-2feb-42d7-a30b-353b0aa0e0f0",
    "rayId": "9ddb389a0858445a"
  }
}

Handling errors in your code:

Code
response = requests.post(url, headers=headers, json=body)
if not response.ok:
    error = response.json()
    print(f"Error {error['status']}: {error['title']} - {error['detail']}")

Code
const response = await fetch(url, { method: "POST", headers, body });
if (!response.ok) {
  const error = await response.json();
  console.error(`Error ${error.status}: ${error.title} - ${error.detail}`);
}

Search Types

Text Search (Default)

Fast keyword-based search across relevant fields. Best for specific terms and names.

Code
{
  "query": "cage-free eggs",
  "search_type": "text"
}

Semantic Search

AI-powered conceptual search using embeddings. Finds results based on meaning, not just keywords. Costs 5x more than text search.

Code
{
  "query": "improving conditions for farmed animals",
  "search_type": "semantic"
}

Searchable Tables

Table	Description	Example Filters
campaigns	Advocacy campaigns	status, cause_areas, country_codes
actions	User actions (emails, calls)	action_type, platform, target_type
public_figures	Politicians & influencers	party, country_code, figure_type
organizations	Companies & NGOs	industry, org_type, country_codes
content	Social media & articles	platform, stance, content_type
suggestions	AI-generated messages	tone, approach, audience

Using Filters

Narrow your search results with filters:

Code
{
  "query": "animal welfare",
  "search_type": "text",
  "filters": {
    "status": "active",
    "country_codes": ["US", "UK"]
  },
  "limit": 20
}

Search All Tables

Search across all tables at once with /v1/search/all:

Code
{
  "query": "animal testing cosmetics",
  "search_type": "text",
  "limit_per_table": 5
}

Rate Limits & Pricing

Plan	Rate Limit	Monthly Quota	Cost
Free	10 req/hour	5 requests	$0
Pay As You Go	50 req/hour	Unlimited	Usage-based

Complete Endpoint Pricing (Pay As You Go)

Endpoint	Cost per Request
/v1/search/{table} (text)	$0.05
/v1/search/{table} (semantic)	$0.25
/v1/search/all (text)	$0.15
/v1/search/all (semantic)	$0.75
/v1/chat/message	$0.25
/v1/chat/intent	$0.10
/v1/content/generate	$0.50
/v1/osint/personal-profile	$1.50
/v1/osint/company-profile	$1.50
/v1/legal/guidance	$1.00
/v1/tracking/issues	$0.25

See Pricing for plan details and nonprofit discounts.

Next Steps

• Explore the API Reference for complete endpoint documentation
• Read the API Stability page for versioning and compatibility policy
• Check the Changelog for recent updates
• Check out Pricing to upgrade your plan
• Manage your API Keys or Billing