Authentication

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"

import requests

headers = {
    "x-api-key": "your_api_key",
    "Content-Type": "application/json"
}

response = requests.get(
    "https://api.getpg.ai/public-api/v1/territories",
    headers=headers
)

data = response.json()

const response = await fetch("https://api.getpg.ai/public-api/v1/territories", {
  method: "GET",
  headers: {
    "x-api-key": "your_api_key",
    "Content-Type": "application/json"
  }
});

const data = await response.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)

Wildcard scopes are also supported. For example, 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": {}
  }
}

All responses (including errors) include an 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

Overview

Endpoint Guides

MCP Server

Getting Your API Key

Using Your API Key

Base URL

Permissions & Scopes

Rate Limits

Error Responses

​Getting Your API Key

​Using Your API Key

​Base URL

​Permissions & Scopes

​Rate Limits

​Error Responses

Getting Your API Key

Using Your API Key

Base URL

Permissions & Scopes

Rate Limits

Error Responses