Developer API v1
Use a workspace credential to read granted resources. Availability depends on your published plan and the operational rollout switch.
Credential creation and rotation require a current MFA or backup code. Owners can restrict a key or webhook to selected 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 confirm a higher-risk grant for all current and future clients. Optional exact-IP key restrictions require a verified edge client IP and fail closed 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
View granted businesses
Lists active businesses granted to the credential.
- Effects
- Read only; no messages are sent and no quota is charged beyond the API call itself.
- 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 it appears; it cannot be retrieved 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 a cursor. List responses use 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 with 50 calls per minute, 500 per UTC day, and 3,000 total calls. Successful responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. A 429 response also includes Retry-After. Authentication failures return 401; revoked workspace, plan, grant, or scope access returns 403; unknown granted resources return 404.
Webhooks
Subscribed events are REVIEW_CREATED, REVIEW_REPLIED, and LOCAL_RANK_SCAN_COMPLETED. Endpoints have explicit business grants. Delivery is HTTPS only, with no redirects and up to six attempts. The signed body is JSON with event, occurredAt, and data. The X-Uprity-Delivery header 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 against the exact raw request body before parsing JSON. For each retry, verify its own header.
Data and version policy
v1 returns selected customer resource fields. It excludes credentials, provider tokens, billing changes, internal AI diagnostics, and unrestricted customer exports. Names and review or feedback text can contain personal data; store and share them according to your own access policy. Breaking changes require a new API version. Additive fields may appear in v1; clients should ignore unknown response fields. Deprecation notices will appear here and in the changelog before a version is retired.
Contact support for integration incidents or access questions.