All API requests (except /health) require authentication via an API key passed in the x-api-key request header.
Getting Your API Key
Navigate to settings
Go to Settings > API Keys in your PG:AI workspace.
Generate a key
Click Generate API Key, give it a descriptive name, and select the permission scopes it should have.
Copy and store securely
Copy the key immediately — it won’t be shown again. Store it in environment variables or a secrets manager.
Using Your API Key
Include the API key in the x-api-key header on every request:
curl -X GET "https://api.getpg.ai/public-api/v1/territories" \
-H "x-api-key: your_api_key" \
-H "Content-Type: application/json"
Never expose your API key in client-side code, public repositories, or browser requests. Always keep it server-side.
Base URL
All API endpoints use the following base URL:
https://api.getpg.ai/public-api/v1
Permissions & Scopes
API keys are scoped with granular permissions. Each endpoint requires a specific permission — requests made with a key that lacks the required scope will receive a 403 Forbidden response.
| Scope | Description |
|---|
accounts:read | Search and list accounts |
companies:read | Read company data (relevance, graph, search, jobs, canvas) |
contacts:read | Read contact data |
contacts:write | Create or enrich contacts |
insights:read | Read company intelligence, profiles, alerts, and technologies |
insights:write | Create or modify company enrichment data |
integrations:read | Read integration status |
jobs:read | Read job postings |
monitoring:read | Read monitoring events |
monitoring:write | Manage monitoring events |
org_settings:read | Read organization settings and credits |
sequences:read | Read sequences and templates |
sequences:write | Create or modify sequences |
tasks:read | Read tasks |
tasks:write | Create or modify tasks |
territories:read | Read territories and their companies |
workflows:read | Read workflows |
workflows:execute | Trigger workflow executions |
* | Full access (all permissions) |
insights:* grants both insights:read and insights:write.
Rate Limits
API requests are rate-limited based on your plan. If you exceed the limit, the API returns a 429 Too Many Requests response.
| Header | Description |
|---|
X-RateLimit-Limit | Maximum requests allowed per window |
X-RateLimit-Remaining | Requests remaining in current window |
X-RateLimit-Reset | Unix timestamp when the rate limit resets |
If you’re hitting rate limits, consider batching requests or adding short delays between calls.
Error Responses
All error responses follow a consistent structured format. Every error includes a type, a machine-readable code, and a human-readable message. Some errors include a details object with additional context.
{
"error": {
"type": "validation_error",
"code": "invalid_uuid",
"message": "Not a valid UUID.",
"details": {}
}
}
X-Request-Id header you can use when contacting support to identify the specific request.
| Status Code | Description |
|---|
400 | Bad Request — invalid parameters or missing required fields |
401 | Unauthorized — missing or invalid API key |
402 | Insufficient Credits — your organization has run out of credits for this operation |
403 | Forbidden — API key lacks the required permission scope |
404 | Not Found — the requested resource does not exist |
429 | Rate Limited — too many requests, slow down and retry |
500 | Internal Server Error — something went wrong on our end |
503 | Service Unavailable — a downstream service is temporarily unreachable |
