PitchGhost API

The PitchGhost API provides programmatic access to our lead generation and social media automation platform.

Authentication

All API endpoints require authentication using a combined Company ID and API key. The authentication value is formed by combining your Company ID with your API token, separated by a colon:

{companyId}:{apiKey}

For example:

e5903eb5-006a-4d3f-a34d-71b9d8929f2e:7baa8145694a4cb8b68a7fc178c27d80

Getting Your Company ID

You can find your Company ID in the PitchGhost app URL when logged in:

https://app.pitchghost.com/org/{YOUR-COMPANY-ID}/dashboard

For example, if your dashboard URL is:

https://app.pitchghost.com/org/a971dk12-05a5-46e3-akq6-cd11nbac3594/dashboard

Then your Company ID is: a971dk12-05a5-46e3-akq6-cd11nbac3594

Authentication Methods

You can provide your combined authentication string in one of two ways:

1. X-API-Key Header:

X-API-Key: e5903eb5-006a-4d3f-a34d-71b9d8929f2e:7baa8145694a4cb8b68a7fc178c27d80

2. Bearer Token:

Authorization: Bearer e5903eb5-006a-4d3f-a34d-71b9d8929f2e:7baa8145694a4cb8b68a7fc178c27d80

Rate Limits

The API implements rate limiting to ensure fair usage and system stability. All authenticated endpoints are subject to rate limits.

Global Rate Limit (Basic API)

All API requests are subject to a global rate limit of 200 requests per 10 minutes per company. This limit applies across all API keys for your company.

• Limit: 200 requests per 10-minute window
• Scope: Per company (all API keys combined)
• Window: Rolling 10-minute window

Rate Limit Headers

Every API response includes rate limit information in the following headers:

• X-RateLimit-Limit: Maximum requests allowed in the current window
• X-RateLimit-Remaining: Number of requests remaining in the current window
• X-RateLimit-Reset: Unix timestamp (in milliseconds) when the window resets
• X-RateLimit-Type: Type of rate limit applied ('global', 'action', or 'none')

When rate limited, you'll receive:

• 429 Too Many Requests status code
• Retry-After header indicating seconds to wait before retrying

Response Format

All responses are returned in JSON format. Successful responses will have appropriate HTTP status codes (2xx range).

Error Handling

Errors are returned with appropriate HTTP status codes and a JSON body containing a message field describing the error.

Common error codes:

• 401: Authentication required or invalid API key
• 403: Insufficient permissions for the requested resource
• 429: Rate limit exceeded (see Rate Limits section)
• 500: Internal server error