API Overview

The Petal API provides programmatic access to subscription and license management.

Subscription Required

API access requires a Standard or Advanced subscription.

Base URL

https://petal.tech/api/v1

Authentication

Most endpoints require authentication via Bearer token:

Authorization: Bearer <access_token>

See Authentication for details on obtaining tokens.

Response Format

All responses are JSON:

{
  "data": { ... },
  "error": null
}

Error responses:

{
  "data": null,
  "error": "Error message",
  "code": "ERROR_CODE"
}

Available Endpoints

Authentication

Method	Endpoint	Description
POST	/auth/login	Sign in with email/password
POST	/auth/signup	Create new account
POST	/auth/refresh	Refresh access token

Subscription

Method	Endpoint	Description
GET	/subscription/status	Get subscription details

License

Method	Endpoint	Description
POST	/license/validate	Validate a license key
POST	/license/activate	Activate license on device

API Keys

Method	Endpoint	Description
POST	/metrics/api-key	Generate or retrieve API key
POST	/metrics/api-key/validate	Validate an API key

Utility

Method	Endpoint	Description
POST	/heartbeat	Device heartbeat (for session tracking)
GET	/binary-hash	Get installer file hashes

HTTP Status Codes

Code	Meaning
200	Success
400	Bad Request - Invalid parameters
401	Unauthorized - Missing or invalid auth
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn't exist
429	Too Many Requests - Rate limited
500	Server Error - Try again later

Rate Limiting

Requests are rate limited per IP:

Endpoint	Limit
Auth (login)	5 requests/minute
Auth (signup)	3 requests/minute
License endpoints	30 requests/minute
API key validation	120 requests/minute
General API	60 requests/minute

Rate limit headers are included in responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 55
X-RateLimit-Reset: 1706365900
Retry-After: 30

SDKs and Libraries

Currently, we don't provide official SDKs. The REST API can be used with any HTTP client:

• Python: requests, httpx
• JavaScript: fetch, axios
• Rust: reqwest
• Go: net/http

Example: Quick Start

import requests

# Login to get access token
response = requests.post('https://petal.tech/api/v1/auth/login', json={
    'email': 'your@email.com',
    'password': 'your-password'
})
token = response.json()['access_token']

# Get subscription status
response = requests.get(
    'https://petal.tech/api/v1/subscription/status',
    headers={'Authorization': f'Bearer {token}'}
)
subscription = response.json()
print(f"Plan: {subscription['subscription']['plan']}")

Next Steps

• Authentication - Learn about auth flows
• Endpoints - Full endpoint reference