Augur API Overview

The Augur API is a collection of REST microservices. Each service runs at its own subdomain of augur-api.com. Check the service directory for the current list.

Base URL Pattern

https://{service-name}.augur-api.com

Examples:

• https://items.augur-api.com — Product catalog
• https://customers.augur-api.com — Customer data
• https://orders.augur-api.com — Order management

Authentication

All requests require two credentials:

curl -H "Authorization: Bearer YOUR_TOKEN" \
     -H "x-site-id: YOUR_SITE_ID" \
     https://items.augur-api.com/inv-mast?limit=10

Token Types

Tokens are locked to specific sites. Contact SimpleApps to obtain credentials.

Credential Files

The SDK resolves credentials automatically in this order:

1. Environment variables — AUGUR_TOKEN + AUGUR_SITE_ID
2. Explicit file — AUGUR_CREDS_FILE env var pointing to JSON
3. Project file — <cwd>/.simpleapps/augur-api.json
4. Global file — ~/.simpleapps/augur-api.json

Single-site format:

{
  "siteId": "my-site",
  "jwt": "my-token"
}

Multi-site format:

{
  "site-a": { "jwt": "token-a" },
  "site-b": { "jwt": "token-b" }
}

Response Format

All endpoints return a standard JSON envelope:

{
  "status": 200,
  "message": "Ok",
  "data": [],
  "count": 10,
  "total": 10,
  "totalResults": 542,
  "options": {},
  "params": {}
}

Pagination

List endpoints accept limit and offset query parameters:

GET /inv-mast?limit=25&offset=50

API Conventions

• REST only — no GraphQL
• JSON only — no XML
• No breaking changes — new fields are added, old fields are never removed
• Standard HTTP status codes for errors
• No sandbox — test against your configured site
• No formal rate limits — abuse is mitigated at the Cloudflare edge
• Edge caching available — use edgeCache parameter on GET requests

Error Handling

Error responses use the same JSON envelope as successful responses. The status field reflects the HTTP status code and message provides a human-readable description.

{
  "status": 404,
  "message": "Not Found",
  "data": [],
  "count": 0,
  "total": 0,
  "totalResults": 0,
  "options": {},
  "params": {}
}

A 500 response may not return a valid JSON envelope — always check the content type before parsing.

Status Codes

Retry Strategy

Retry only on 5xx errors and timeouts. Do not retry 4xx errors — they indicate a problem with the request.

1. Wait 1 second after the first failure
2. Double the wait on each subsequent retry (1s, 2s, 4s, 8s)
3. Stop after 3–4 attempts
4. Set a client timeout of 30 seconds per request

Edge Caching

Any GET request can use Cloudflare edge caching via the edgeCache query parameter:

curl https://items.augur-api.com/inv-mast?limit=10&edgeCache=5m

Implement local caching where appropriate. While Cloudflare handles CDN caching, storing frequently accessed data locally (product catalogs, pricing tiers) reduces API calls and improves response times.

Keeping Data in Sync

There is no webhook or event subscription system currently. A real-time event system is in development with no committed timeframe. All data syncs from Prophet 21 run on 5–15 minute intervals, pulling recently created and modified records. The recommended pattern is polling with edge caching.

Recommended Cache Intervals

Polling Pattern

1. Set edgeCache to match the sync interval for your data type
2. Poll at or above the cache interval — polling faster returns cached responses with no extra cost
3. Use offset and limit for incremental fetches on large collections
4. For order submission flows, omit edgeCache so you always read the latest state

# Poll inventory every 5 minutes with edge caching
curl https://items.augur-api.com/inv-mast?limit=100&edgeCache=5m

# Read order status without cache after placing an order
curl https://orders.augur-api.com/oe-hdr?order_no=12345

Limits & Reliability

Rate Limits

There are no formal per-client rate limits. All traffic passes through Cloudflare, which provides edge-level protection against abuse and anomalous traffic patterns.

Microservices Resilience

Each service maintains its own data store and operates independently. Services like pricing, items, and customers do not make live queries to Prophet 21 — they work from synced data. This means most API operations continue normally even during P21 maintenance windows or upgrades.

P21 downtime affects two operations:

• Data sync — new or changed records in P21 won't propagate until sync resumes
• Order submission — orders queued for P21 will be held until connectivity is restored

Status Page

A public status page is planned (augur-sites#1). In the meantime, contact SimpleApps for service health inquiries.