English Product Guides

EarthCoop API — Versioned Native Contract & Legacy Boundaries

EarthCoop now has a real versioned /api/v1 contract used for the first-party/native delivery boundary. This is materially different from the older unversioned /api surface, which still contains application routes, legacy compatibility paths, and domain endpoints that are not automatically part of the v1 contract.

Current /api/v1 scope

The current application mounts the versioned route set at:

/api/v1

At the current application baseline, that contract includes first-party/native endpoints for:

• authentication login/logout;
• bootstrap and current-member data;
• notifications and unread counts;
• marking notifications as read;
• device push subscription/unsubscription;
• basic geography lookups used by the native client;
• NajmHoda messaging;
• media URL delivery.

The exact route/controller implementation is the source of truth for payload details and authorization.

Authentication

The current v1 authentication flow includes a password-based login endpoint that can issue a bearer token after validating the account and required agreement state. Protected v1 routes use the current bearer/Sanctum authorization boundary, and logout revokes the current token.

See Authentication for the verified current contract and limitations.

Legacy and internal /api routes

EarthCoop still has unversioned /api routes used by the web application, compatibility layers, or domains not yet promoted into v1. Those paths can be real and useful without being part of the durable v1 native contract.

Use this distinction:

/api/v1 route = current versioned native/client contract
unversioned /api route = inspect its own current implementation/status
route existence ≠ universal third-party support promise

Authorization and domain rules

Authentication establishes requester identity. It does not bypass domain authorization. A protected operation can still require ownership, role, policy, governance topology, monetary state, or other business rules.

For NajmHoda and other action-capable flows, browser/client context cannot grant mutation authority. Trusted server-side policy and domain services remain responsible for permission and execution.

Response contracts

Do not assume one universal JSON envelope for every EarthCoop API domain. The current v1 controllers define their own validated request/response contract, while legacy/internal routes can retain different shapes.

For client work, bind only to endpoints explicitly present in the current versioned contract and verify their current tests/controller behavior.

API sections

Public/third-party integration status

The current v1 boundary is evidence of a durable versioned first-party/native contract. It should not be broadened by documentation into an unrestricted public developer platform without an explicit product/API policy. Third-party consumers should use only contracts that EarthCoop explicitly designates for that purpose.