Build an integration

API basics

Understand how Asteri authenticates requests, returns records, and handles retries.

On this page

Base URL and version

Public API routes start with /api/public/v1 on your Asteri app origin. For example, a local server exposes customers at http://localhost:3000/api/public/v1/customers.

Use the host for the company you are connecting to. The public API has its own versioned request and response contract.

Browse the API referenceFind the live routes, required fields, and response examples.Open the OpenAPI documentUse the same contract in your own development tools.

Authentication and company access

Send a scoped API key in the Authorization header on every request. The key belongs to one company and selects that company automatically; no organization header is needed.

Request header

Authorization: Bearer ast_live_your_key

Create and manage keys under Security & access → Developer. The full key is shown once. Give each integration a separate key, only the scopes it needs, an expiry, and suitable request limits.

Common read scopes

Customers: read:customers
Appointments: read:appointments
Invoices: read:invoices
Payments: read:payments
Estimates: read:estimates
Services: read:servicesservices:read
Files: read:files
Availability: availability:read
Bookings: bookings:read
Promo codes: promo_codes:read

Each endpoint lists its exact scopes in the API reference. Keep keys in server-side secrets, outside browser bundles and mobile apps.

Read a page at a time

Collection responses return a data array and pagination details. Endpoints that support pagination accept limit and an opaque cursor; their reference entry lists the allowed page size.

An empty customer page

{
  "data": [],
  "pagination": {
    "count": 0,
    "limit": 25,
    "next_cursor": null
  }
}

When pagination.next_cursor has a value, pass it unchanged as the next request’s cursor. Stop when it is null. The SDK pagination helpers can walk the pages for you.

Retry writes safely

Some create operations require an Idempotency-Key header. Generate a unique value for each intended action, save it before the first request, and reuse the same value when retrying that action.

Use a different value for a new action. Check the endpoint’s required headers before sending a write; the generated SDK requires the key for operations that need it.

Errors and rate limits

Use the response status and message to decide what to do next. The SDK exposes these as AsteriApiError.

Status	Meaning	Next step
401	The key is missing, invalid, inactive, or expired.	Check the full bearer key and its expiry.
403	The request is outside the key’s access.	Check the plan, scopes, and IP allowlist.
429	A request limit was reached.	Wait for Retry-After, then reduce request frequency.
5xx	Asteri could not complete the request.	Retry with backoff; keep the same idempotency key for the same write.

Keys can have per-minute and per-day limits. Respect Retry-After and avoid immediate retry loops. Webhooks can reduce the need to poll for changes.

Choose what to build next

Find an endpointWork with customers, jobs, estimates, invoices, photos, and more.Listen for changesReceive signed events when CRM records change.