Copy page

Guides

API Stability

API Stability & Versioning

Current Status

The Open Paws API is in v1, with route groups at mixed stability tiers. Stable routes will not receive breaking changes without advance notice; beta routes may change without notice. See the classification table below for per-group status, SLA, and guarantees. The public routes listed under "stable" (search, chat, content, OSINT) and the Stripe webhook are the production-ready surface. Agent proxy routes are beta (planned for first release).

Base URL: https://api.openpaws.ai

Route Stability Classifications

Route Group	Status	SLA	Notes
Public routes (/v1/search/*, /v1/chat/*, /v1/content/*, /v1/osint/*)	stable	99.9%	Production ready
Agent proxy (/v1/agent/completions, /v1/claude/messages)	beta	Best effort	Planned — not yet in production. Subject to change, requires API key
Stripe webhooks	stable	99.9%	Internal only

Backward Compatibility Promise

We will NOT make the following changes without at least 30 days notice in the Changelog:

• Remove an existing endpoint
• Remove or rename a field from a response body
• Change the type of an existing response field
• Add a new required field to a request body
• Change authentication requirements for an existing endpoint
• Change the meaning of an existing status code for an endpoint

What We MAY Change Without Notice

These changes are considered non-breaking and may happen at any time:

• Add new optional fields to request bodies
• Add new fields to response bodies
• Add new endpoints
• Add new enum values to existing fields
• Improve error messages (while keeping the same error structure)
• Change the order of fields in JSON responses
• Change internal implementation details that don't affect the API contract

Deprecation Process

When we need to make a breaking change:

1. Announcement — The change is documented in the Changelog with at least 30 days notice
2. Deprecation header — Deprecated endpoints return a Deprecation header with the sunset date
3. Migration guide — A migration guide is provided in the changelog entry
4. Sunset — The deprecated behavior is removed after the notice period

URL Versioning

All API endpoints use URL-based versioning with the /v1/ prefix (e.g., /v1/search/all, /v1/content/generate). The only exception is /health, which is unversioned.

• The current version is v1
• When a new major version is released, it will be available at /v2/...
• We will maintain at least 2 major versions simultaneously
• The previous version will receive security fixes for at least 6 months after a new major version is released

Response Format Patterns

The API uses three response patterns. Each endpoint's documentation specifies which pattern it uses:

Pattern	Used By	How It Works
Synchronous JSON	Search, Chat, Content, Intent	Request → JSON response immediately
Streaming NDJSON	OSINT Personal Profile	Request → streaming newline-delimited JSON events over 5-10 minutes
Async Task	Company Investigation, Legal Guidance, Issue Tracking	Request → immediate {taskId} confirmation, results delivered via email

Consuming Streaming NDJSON

The OSINT personal profile endpoint returns streaming NDJSON (newline-delimited JSON). Each line is a separate JSON object:

Code
// JavaScript example for consuming NDJSON stream
const response = await fetch('https://api.openpaws.ai/v1/osint/personal-profile', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    firstName: 'Jane',
    lastName: 'Doe',
    companyName: 'Acme Corp'
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();
let buffer = '';

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  buffer += decoder.decode(value, { stream: true });
  const lines = buffer.split('\n');
  buffer = lines.pop(); // Keep incomplete line in buffer

  for (const line of lines) {
    if (!line.trim()) continue;
    const event = JSON.parse(line);

    switch (event.type) {
      case 'begin':
        console.log(`Starting: ${event.metadata.nodeName}`);
        break;
      case 'item':
        console.log(`Content: ${event.content}`);
        break;
      case 'end':
        console.log(`Completed: ${event.metadata.nodeName}`);
        break;
      case 'error':
        console.error(`Error in: ${event.metadata.nodeName}`);
        break;
    }
  }
}

Code
# Python example for consuming NDJSON stream
import requests
import json

response = requests.post(
    'https://api.openpaws.ai/v1/osint/personal-profile',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'firstName': 'Jane',
        'lastName': 'Doe',
        'companyName': 'Acme Corp'
    },
    stream=True
)

for line in response.iter_lines():
    if not line:
        continue
    event = json.loads(line)

    if event['type'] == 'begin':
        print(f"Starting: {event['metadata']['nodeName']}")
    elif event['type'] == 'item':
        print(f"Content: {event['content']}")
    elif event['type'] == 'end':
        print(f"Completed: {event['metadata']['nodeName']}")
    elif event['type'] == 'error':
        print(f"Error in: {event['metadata']['nodeName']}")

Async Task Results

For async endpoints (company investigation, legal guidance, issue tracking), results are currently delivered via email to the address associated with your account. Programmatic result retrieval (polling or webhooks) is on our roadmap.

Questions?

If you have questions about API stability or need help planning your integration, contact [email protected].