Platform Concepts

Back to API Overview

This page collects shared platform behaviors that affect many unrelated endpoints.

Rate Limiting

The API uses rate limits that can surface in both headers and response envelopes. Clients should:

• treat rate-limit exhaustion as a recoverable state
• back off rather than retrying aggressively
• allow for negative requestsAvailable values when the system is accounting for in-flight usage

Some accounts may have a purchased just-in-time token allocation (JITTA) bucket associated with a user and the root realm of the asserted realm. JITTA is considered only after the normal endpoint bucket or shared global bucket is exhausted. JITTA is available only when all of the following are true:

• the request includes X-Ayode-JITTA: true
• the user is authorized for /rate-limiting/jitta in none scope at the root realm
• a current, active JITTA assignment exists for that user and root realm

If any condition is missing, the request follows the normal rate-limit exhaustion behavior.

Filtering

Filtering combines predicates rather than acting like a free-form search language. Clients should read endpoint-specific filter fields carefully and avoid assuming arbitrary predicate combinations are accepted. Three conventions recur across many list endpoints:

Enum status filters

An optional query parameter restricted to a documented set of enum values (for example status on GET /v2/terms, with values planned, active, completed, and archived). The match is exact against one of the documented values. Omitting the parameter returns rows regardless of status — the filter never applies an implicit default.

Case-insensitive search

An optional query parameter (conventionally named q) that performs a case-insensitive partial match against a small, specific set of documented fields for that endpoint — never a general full-text search across the whole resource. For example, q on GET /v2/terms matches against the term’s en_US display name or its termIndex, and nothing else.

Date-range filters

A paired <field>From/<field>To query parameter convention for restricting results to a date or timestamp range on a specific field. Both parameters share the same core semantics wherever they appear:

• Each bound is inclusive: <field>From returns rows on or after that date, <field>To returns rows on or before it.
• Each bound is independently optional. A caller may supply just one, both, or neither.
• The two bounds are composable: supplying both together expresses a range. There is no separate third “between” parameter — the pair is the range expression.
• Omitting both parameters returns rows across the full range (no implicit narrowing to a “current” period, unless an endpoint’s own documentation explicitly states otherwise).

Endpoints may still diverge on edge-case behavior not covered above — for example, whether an inverted range (<field>From later than <field>To) is rejected outright or simply yields an empty result. Consult the specific endpoint’s own documentation for that behavior.

This convention originates with startedTimestampFrom/ startedTimestampTo on the shell/browser diagnostic session listing endpoints, and is also used as startDateFrom/startDateTo on GET /v2/terms and GET /v2/users/~/sections.

ĀYŌDÈ URN Rules

Several APIs use structured URNs and external identifiers.

Important namespaces include:

• user
• realm
• role
• privilege
• standard
• resource

Clients should preserve URN strings exactly and should not attempt to rebuild them from guessed substrings.

Access-Control Architecture

The platform’s access-control model is realm-centric:

• realms define administrative boundaries
• subrealms inherit within the documented hierarchy
• roles aggregate privileges
• policies evaluate privileges within a scope and asserted realm

This model is stricter than simple role-label checks. The same user can be authorized differently depending on the asserted realm and target resource.

ĀYŌDÈ File System (AFS)

The file APIs expose a client-facing storage model with:

• zones and scopes
• direct reads for small payloads
• multi-step upload and download flows for larger payloads
• versioned asset behavior

Client guidance:

• Use endpoint-specific file flows rather than assuming every file operation is single-request.
• Expect separate handling for directory browsing, file reads, and large transfer workflows.

API Lifecycle Policy

Deprecated endpoints remain documented until termination and include lifecycle metadata such as:

• deprecation time
• sunset time
• termination time
• recommended replacement when available

Clients should plan migrations before sunset rather than waiting for hard termination.

Endpoint Symbol Key

Endpoint summaries use a compact icon vocabulary to signal subject area and operation type. Common patterns include:

• topic icon + view icon for reads
• topic icon + create icon for creates
• topic icon + update icon for edits
• topic icon + delete icon for removals

These symbols are descriptive only; the actual contract remains the operation definition in the sidebar.

Where To Go Next

• Security and Authorization for envelopes, headers, and privilege evaluation.
• AI, Jobs, and Integrations for orchestration and integration-specific workflows.