Developer API v1
Use a workspace credential to read granted resources. Availability depends on your published plan and the operational rollout switch.
Creating or rotating credentials requires current MFA or a backup code. Owners can limit keys and webhooks to active locations. Records without a location ID and business-wide summaries require a full business grant. Agency keys exclude new clients by default; owners can explicitly grant all current and future clients. Exact-IP restrictions require a verified edge client IP and deny access when it is unavailable.
API explorer
Choose a guided task, enter its inputs, and inspect the request and response. Credentials stay in this page's memory and are cleared when context changes.
business:read
Granted active businesses
Lists active businesses granted to the credential.
- Effects
- Read only. No messages, scans, AI calls, replies, or exports are created. The API request itself may count toward quota.
- Pagination
- Single object; no pagination parameters.
curl 'https://uprity.com/api/v1/business' \
-H 'Authorization: Bearer YOUR_SECRET'Quickstart
Create a time-bounded key in Settings → Developer and select its business or agency clients. Copy the secret when shown; you cannot retrieve it later.
curl https://app.uprity.com/api/v1/business \ -H 'Authorization: Bearer lk_live_YOUR_SECRET'
Read resources
| GET /api/v1 | Scope | Returns |
|---|---|---|
| /business | business:read | Granted active businesses |
| /business/{id} | business:read | One granted business |
| /locations | locations:read | Active locations in granted businesses |
| /reviews | reviews:read | Reviews and reply status |
| /reviews/{id} | reviews:read | One granted review |
| /feedback | feedback:read | Private feedback |
| /review-requests | review_requests:read | Review request batch status |
| /rank-scans | rank:read | Completed local rank scans and grid results |
| /visibility | visibility:read | AI visibility scan summaries |
| /reports | reports:read | Published internal audit metadata |
| /usage | usage:read | API usage counters |
| /webhooks | webhooks:read | Webhook endpoints |
Lists accept businessId where applicable, limit (1–200; default 50), and cursor. Responses include data and pagination.nextCursor. For a completed report, POST /reports/[id]/export-link, then GET its five-minute downloadUrl with the same Bearer key.
Limits and errors
Published workspace allowances control minute and month quotas. The Agency trial is read only: 50 calls per minute, 500 per UTC day, and 3,000 total. Successful responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. A 429 response includes Retry-After. Authentication failures return 401; revoked workspace, plan, grant, or scope access returns 403; unknown granted resources return 404.
Webhooks
Events: REVIEW_CREATED, REVIEW_REPLIED, and LOCAL_RANK_SCAN_COMPLETED. Endpoints have explicit business grants. Delivery uses HTTPS, no redirects, and up to six attempts. Signed JSON includes event, occurredAt, and data. X-Uprity-Delivery identifies the delivery. Each attempt has a fresh X-Uprity-Signature header in t=milliseconds,v1=hex digest form.
import { createHmac, timingSafeEqual } from 'node:crypto'
const [timestamp, digest] = [/* parse t and v1 from X-Uprity-Signature */]
if (Math.abs(Date.now() - Number(timestamp)) > 300_000) throw Error('Stale delivery')
const expected = createHmac('sha256', secret).update(timestamp + '.' + rawBody).digest()
const actual = Buffer.from(digest, 'hex')
if (actual.length !== expected.length || !timingSafeEqual(actual, expected)) throw Error('Invalid signature')Verify each retry against its exact raw request body before parsing JSON.
Data and version policy
v1 returns selected customer fields. It excludes credentials, provider tokens, billing changes, internal AI diagnostics, and unrestricted customer exports. Names and review or feedback text may contain personal data; store and share them under your own access policy. Breaking changes require a new API version. Additive v1 fields may appear; clients should ignore unknown fields. Deprecation notices appear here and in the changelog before retirement.
Contact support for integration incidents or access questions.