Every capability.
One consistent language.
The Rheole API Reference is the definitive technical catalogue of every platform capability, designed for precision, consistency and speed.
Why API References Exist
A robust Developer Platform requires distinct types of documentation. Tutorials teach you how to build a specific app. Quick Starts get you running in five minutes. Migration Guides help you upgrade.
API Referencesserve a fundamentally different purpose. They are the exhaustive, objective encyclopaedia of the platform. They exist so that when you ask, "What exact parameters does the Places endpoint accept?" you receive an immediate, unambiguous answer.
The API Ecosystem
Every capability belongs to one unified platform architecture.
Resource Catalog
The Rheole API is resource-oriented. Rather than a chaotic list of actions, the API is organized around logical entities.
Accounts
The root of the identity model. Accounts represent the billing entity and legal ownership of all subordinate Projects and Organizations.
Projects
The primary container for resources. Every API request must be scoped to a specific Project, ensuring strict boundary isolation.
Organizations
Multi-tenant grouping structures that allow multiple users to collaborate securely across shared Projects.
Users
Individual human identities or service accounts that interact with the platform, defined by strict role-based access controls.
Places
The foundational spatial entity. Represents a physical location, enriched with geometric boundaries, metadata, and dynamic status.
Businesses
Commercial entities mapped to Places. Includes operational hours, category metadata, and real-time activity metrics.
Events
Temporal occurrences tied to physical Places. Events have strict start and end times, influencing local Context and Mobility.
Routes
Polyline representations of movement between two or more Places, optimized for various modes (walking, transit, cycling).
Communities
Aggregated representations of social groups operating within specific geographic bounds or shared interests.
Intent
The semantic representation of a user's goal (e.g., 'Find coffee quickly'), separated from their literal query string.
Context
The multi-dimensional state (time, weather, location, history) used to evaluate Intent and modify Recommendations.
Weather
Real-time and forecasted environmental conditions. Often used as a primary modifier for the Context and Route engines.
Transit
Formal public transportation schedules, delays, and real-time vehicle positioning.
Traffic
Real-time congestion and historical flow metrics affecting specific polylines or bounding boxes.
Notifications
Asynchronous, multi-channel messaging (push, email, SMS) triggered by spatial thresholds or temporal events.
Search
The discovery engine. Accepts Intent and Context to return relevance-ranked Places, Events, or Businesses.
Analytics
Aggregated, privacy-preserving metrics regarding API usage, spatial queries, and resource engagement.
Permissions
Granular access control policies dictating exactly which Users or Keys can perform specific operations on Resources.
Sessions
Temporary cryptographic tokens representing an active, authenticated connection between a User and the API.
Developer Keys
Long-lived, scoped credentials used for server-to-server authentication. Never to be exposed in client applications.
Webhooks
HTTP callbacks triggered by asynchronous state changes within the platform, enabling event-driven architectures.
Realtime Streams
WebSocket or Server-Sent Events connections for subscribing to high-frequency updates, such as live Transit locations.
Reference Structure
Every endpoint page follows one identical, consistent format. Once you learn how to read one endpoint, you can read them all.
- Overview & Purpose
- Authentication Requirements
- Parameters (Path, Query, Body)
- Response Schemas
- Code Examples (cURL, SDKs)
- Possible Errors
- Rate Limits
- Related Resources
- Best Practices
Common Design Patterns
Platform-wide conventions ensure predictable developer experiences. We standardize filtering, sorting, pagination, relationship expansion, and idempotency across the entire ecosystem.
Error Model & Versioning
Error Philosophy
Errors should be actionable. Every error response includes a predictable code, a human-readable message, and specific validation details to help you recover immediately.
Version Lifecycle
APIs evolve, but they should never break your code unexpectedly. We guarantee strict backward compatibility, clear deprecation policies, and minimum 24-month long-term support for superseded versions.
Authentication Model
API Keys
The simplest form of authentication. Long-lived strings used for server-to-server communication. Must be kept strictly confidential and passed via the Authorization header.
OAuth 2.0
The standard for delegating access. Used when an application needs to act on behalf of a Rheole User without handling their passwords directly.
Service Accounts
Special accounts representing applications or virtual machines, rather than human users. Used for automated, background processing tasks.
Project Scopes
Every Developer Key is bound to a specific Project. A key created for the 'Staging' project physically cannot access data in the 'Production' project.
Permission Scopes
Granular string arrays (e.g., 'places:read', 'events:write') that strictly define what operations a token is permitted to execute.
Session Tokens
Short-lived JWTs (JSON Web Tokens) generated upon user login, used primarily for client-side applications authenticating directly to the platform.
Proprietary Reference Concepts
Unified Reference™
Every API follows one predictable structure regardless of product line.
Living References™
Reference documentation evolves with the platform while maintaining complete version history.
Semantic API Discovery™
Developers search by intent, concept or use case rather than memorizing endpoint names.
Reference Graph™
Every endpoint, resource and guide is interconnected, allowing natural navigation.
Intelligent Cross-Links™
Documentation automatically surfaces related resources, guides and SDK equivalents.
Best Practices
Building robust integrations requires more than just correct syntax. These practices ensure performance, security, and maintainability across the platform.
Idempotency
Always include an 'Idempotency-Key' header for POST requests. This ensures that if a network failure occurs and you retry the request, the operation is not duplicated on our servers.
Pagination
List endpoints return a maximum of 100 resources. Always implement cursor-based pagination using the 'next_cursor' provided in the response metadata rather than offset/limit.
Expansion
Avoid 'N+1' query problems. Use the 'expand' query parameter to fetch related resources in a single API call (e.g., '?expand=business.reviews').
Exponential Backoff
When encountering 429 (Rate Limit) or 503 (Service Unavailable) errors, implement retry logic with exponential backoff and random jitter to avoid thundering herd problems.
Version Headers
Explicitly pin your API version using the 'Rheole-Version' header (e.g., '2025-10-15'). Do not rely on the account default, as this makes your codebase fragile during upgrades.
Caching
Respect the 'Cache-Control' headers returned by the API. High-frequency changing data (like Traffic) has short TTLs, while static metadata (like Place details) can be cached aggressively.
Reference Paradigms
Traditional API References
Endpoint lists. Documentation is merely an alphabetical dump of available URLs.
Minimal context. Explains 'how' to call the endpoint, but rarely explains 'why' or 'when'.
Static navigation. Developers must manually search through massive, monolithic pages.
Technical terminology. Written exclusively for backend engineers.
Limited relationships. Endpoints are treated as isolated silos.
Rheole API References
Resource-first. Documentation is structured around logical entities (Places, Events) and their relationships.
Context-rich. Provides architectural reasoning, best practices, and common pitfalls for every resource.
Intelligent discovery. Semantic search and interconnected reference graphs make discovery instant.
Developer-centred. Written with exceptional clarity, understandable by product managers and engineers alike.
Connected knowledge. Documentation actively surfaces related SDK methods, guides, and related REST APIs.
Frequently Asked Questions
API References are more than technical documentation. They are a shared language between developers and the platform.
A well-designed reference reduces friction, encourages exploration and enables innovation. This isn't just an API reference. It's a beautifully organised technical atlas of Ambient Spatial Intelligence that makes every capability easy to discover, understand and use.
Explore Spatial Computing