Retrieve
Database list/read, or media list, metadata and download.
Log in
Protocol v1 · Beta source candidate
Shell API lets one ZeRaLD installation grant another access to named database and media capabilities. A managed website calls a local alias; the Panels handle the link, identity, permissions and provider route.
The central Website is the control plane: installation identity, linked relationships, the service catalogue and the authoritative grants. Panel-to-Panel HTTPS is the data plane: structured database requests and streamed media. The Website is not a media-file relay.
A connection does not grant service access. Providers publish capabilities, explicitly grant consumers Read and/or Write, and consumers bind an authorised service to an alias. The provider rechecks the current grant for every operation.
Shell API is optional. When a ZeRaLD owner has connected and bound a service, PHP applications can use the installed client without receiving the installation signing key or provider's address.
require_once '/var/www/zerald/client/php/ZeRaLDServiceClient.php';
$services = ZeRaLDServiceClient::fromManagedPanel();
// Only if the owner has bound the database alias "orders":
$orders = $services->list('orders');
// Only if the owner has bound the media alias "photos":
// $media = $services->uploadMedia('photos', '/absolute/path/photo.jpg');
Other languages can invoke the local CLI bridge using versioned JSON on standard input and output. ZeRaLD resolves the sole managed site's aliases and uses its existing installation identity. The application must still handle an absent or revoked grant. No linked service is mandatory for an ordinary project.
{"protocol_version":"1","alias":"orders","operation":"list","payload":{"filters":[],"sort":[],"limit":50,"offset":0}}
The command bridge is local to the managed Panel. This JSON example is not a public HTTP request or an authentication token.
Database list/read, or media list, metadata and download.
Database create/update/delete/bulk, or media upload, replace and delete.
Publication alone grants nothing. A linked installation may have no accessible services. Explicit unlinking suspends grants in both directions, and reconnecting does not automatically restore them. A saved alias may outlive a grant, but it becomes unavailable until access is restored.
Read and Write are independent: do not assume Write implies Read. A republished service retaining its name can preserve existing grants even if the underlying resource changes; owners should review scope when remapping.
Protocol version 1 and capability version 1 are independent of the Panel release version. Control-plane routes are served by ZeRaLD's Website; provider routes are served by the current linked Panel HTTPS address.
| Plane | Method | Path |
|---|---|---|
| Website | GET | /api/installations/{id}/shell/connections |
| Website | GET | /api/installations/{id}/shell/services |
| Website | POST | /api/installations/{id}/shell/database-services |
| Website | POST | /api/installations/{id}/shell/media-services |
| Website | POST | …/shell/{database-services|media-services}/{serviceId}/authorize |
| Provider | POST | /shell-database.php |
| Provider | POST / GET | /shell-media.php |
These routes use short-lived installation bearer tokens issued via the existing signed challenge/verify flow. Provider-to-Website authorisation routes check the consumer's token and the live grant; they are internal to that exchange and do not supply consumers with private service definitions. Do not issue application keys from these examples.
OpenAPI 3.1 provides operation IDs, request bodies, media types, error responses and the explicit Read/Write mapping for clients and future partner simulators.
POST a JSON envelope containing service_id, operation and payload to the authorised provider route. Resource/table definitions are selected and verified by the provider, never supplied by the remote consumer.
{"service_id":42,"operation":"list","payload":{"filters":[{"field":"status","operator":"eq","value":"open"}],"sort":[],"limit":50,"offset":0}}
Single-record read/update/delete require a provider-verified unique single-column identifier. Bulk operations are separate, explicitly named calls; their filters can deliberately be empty to select all published records. Filters support eq, ne, gt, gte, lt, lte and in.
Upload and replace use multipart/form-data with a binary file; download is an authorised GET returning streamed bytes. List, metadata and delete use JSON POST. Media returns stable, opaque references such as m_0123456789abcdef0123456789abcdef—not publicly accessible file URLs.
A replacement preserves the media reference. The provider owns the underlying persistent media store and checks current grants before access. An application may expose media through its own authorised routes where appropriate; Shell API does not create anonymous links.
Successful database/metadata calls return an ok: true JSON envelope with protocol_version: "1". Media downloads return binary content instead. Failures use an ok: false envelope and a structured error.code; examples include service_unavailable, token_invalid, installation_disconnected, resource_schema_changed and provider_unavailable.
Callers should handle a disconnected peer, revoked grant, unsupported capability, schema change or temporarily unavailable catalogue. A linked relationship is not proof the server is online. The exact provider endpoint can change without a managed site's application source changing.
This reference describes the implemented Panel-to-Panel Protocol v1 source candidate. It is designed to be language-neutral. However, third-party partner identities, independent registration and token issuance are not yet implemented; the existing installation-token model cannot be treated as a publicly available sign-up system. An independent Python provider/consumer simulator can exercise the documented v1 wire format locally without ZeRaLD source code. It uses a fixture-only token and simulated grant scopes. It does not register an official partner, issue a ZeRaLD credential or establish production interoperability.
This documentation is part of an unreleased development candidate. Real two-Panel HTTPS, native database engines, binary streaming and browser end-to-end acceptance remain required before the first Beta release.
Inspect Protocol v1 contract