Skip to content
Pidgr Docs

API Overview

Pidgr exposes a gRPC API built with Protocol Buffers. All services are available over native gRPC (for backend services) and the Connect protocol (for browsers and simple HTTP clients), including plain JSON-over-HTTP.

Protocol

Section titled “Protocol”
  • Package: pidgr.v1
  • Proto syntax: proto3
  • Transport: gRPC (HTTP/2) and Connect (HTTP/1.1 + HTTP/2)
  • Serialization: Protocol Buffers (binary) or JSON

The proto definitions are open source and published as generated packages for Go, Rust, and TypeScript.

Base URL

Section titled “Base URL”
Environment URL
Production https://api.pidgr.com

Authentication

Section titled “Authentication”

All API requests require authentication via one of:

JWT Bearer Token

Section titled “JWT Bearer Token”

Issued after passwordless sign-in (passkey or email one-time code) or SSO at auth.pidgr.com. Include in the Authorization header:

Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

Requests are scoped to your active organization — org_id is resolved server-side and never appears in request messages. Users who belong to multiple organizations select the active organization in the client.

API Key

Section titled “API Key”

For programmatic access (MCP server, CI/CD, service integrations):

Authorization: Bearer pidgr_<key>

API keys are scoped: each key carries an explicit set of permissions and an optional expiry, and can be revoked at any time. The full key is only shown once at creation; afterwards only its prefix (e.g. pidgr_k_abc12345) is displayed. See ApiKeyService.

OAuth 2.1

Section titled “OAuth 2.1”

Third-party integrations and MCP clients can authenticate users through Pidgr’s OAuth 2.1 authorization server, requesting scoped access instead of holding long-lived credentials. The effective permissions of an OAuth token are the intersection of the granted scopes and the user’s role.

Connect Usage

Section titled “Connect Usage”

For browser and React Native clients, use Connect-Web:

import { createConnectTransport } from "@connectrpc/connect-web";
import { createClient } from "@connectrpc/connect";
import { CampaignService } from "@pidgr/proto/pidgr/v1/campaign_connect";


const transport = createConnectTransport({
  baseUrl: "https://api.pidgr.com",
});


const client = createClient(CampaignService, transport);


const response = await client.listCampaigns({
  pagination: { pageSize: 10 },
});

Because the Connect protocol supports JSON, any HTTP client works too — POST a JSON body to /pidgr.v1.<Service>/<Method> with Content-Type: application/json.

gRPC Usage

Section titled “gRPC Usage”

For Go backend services:

conn, err := grpc.NewClient("api.pidgr.com:443",
    grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{})),
)


client := pidgrv1.NewCampaignServiceClient(conn)


resp, err := client.ListCampaigns(ctx, &pidgrv1.ListCampaignsRequest{
    Pagination: &pidgrv1.Pagination{PageSize: 10},
})

Pagination

Section titled “Pagination”

List endpoints use cursor-based pagination:

// First page
const page1 = await client.listCampaigns({
  pagination: { pageSize: 20 },
});


// Next page
const page2 = await client.listCampaigns({
  pagination: { pageSize: 20, pageToken: page1.pagination.nextPageToken },
});

Response includes PaginationMeta with nextPageToken (empty when no more pages) and totalCount.

Error Handling

Section titled “Error Handling”

The API returns standard gRPC status codes:

Code Meaning
OK (0) Success
INVALID_ARGUMENT (3) Invalid request fields
NOT_FOUND (5) Resource doesn’t exist
ALREADY_EXISTS (6) Duplicate resource
PERMISSION_DENIED (7) Insufficient permissions
FAILED_PRECONDITION (9) Request is valid but the resource is not in a state that allows it
RESOURCE_EXHAUSTED (8) Rate limit exceeded
UNAUTHENTICATED (16) Missing or invalid credentials
INTERNAL (13) Server error

Error details are sanitized in production — internal error messages are never exposed to clients.

Rate Limiting

Section titled “Rate Limiting”

API requests are rate-limited per organization:

  • Default: 100 requests/second per organization
  • Burst: 200 requests

When rate-limited, the API returns RESOURCE_EXHAUSTED with a Retry-After header.

Services

Section titled “Services”
Service Description
ActionService User action submission on delivered messages
ApiKeyService Scoped API key and SCIM token management
AuditService Audit trail queries and exports
AuthorizationService Effective permission resolution (internal, service-to-service)
CampaignService Campaign lifecycle, audiences, and deliveries
ChannelEventsService Third-party channel dispatch event recording (internal)
DeviceService Device registration and push tokens
GroupService Recipient group management
HeatmapService Touch event ingestion and heatmap queries
InboxService Mobile inbox sync and read tracking
InsightsService Cohort-level engagement insights and predictions
IntegrationsService Notification channel configuration, reachability, and dispatch
InviteLinkService Shareable invite links — create, list, revoke, redeem
MemberService Member invitations, profiles, roles, and settings
OrganizationService Organization CRUD, sandbox organizations, and privacy settings
OrgSecurityKeysService Per-organization key material (internal)
PrivacyService Data subject rights — export, erasure, rectification, restriction
RenderService Template rendering (internal)
ReplayService Session recording replay
RoleService Role and permission management
SSOService SSO identity provider management
TeamService Team management
TemplateService Message templates and translations
TokenService Deeplink token signing and validation

Services marked internal are part of the published proto contract but are only served inside the Pidgr platform boundary — they are not reachable with end-user or API-key credentials.