Documentation

CloudApi acts as a neutral integration layer: callers send requests to a Relay URL, CloudApi applies mapping rules, then forwards the request to a target API endpoint and optionally maps the response back.

High-level flow

Create an Endpoint (target API): URL, method, auth, headers, timeouts.
Create an Integration: select endpoint, configure mapping, rate limits, logging, schemas.
Call the Relay URL that CloudApi generates for the integration (public key based).
Observe requests, latency, failures, and replay failed requests (when enabled by plan).

Quick start

Step 1 — Create an Endpoint

UI: Endpoints → Create (or create from API template library).

Set HTTP Method and URL.
Configure Authentication (Bearer/API key/Basic) and headers.
Save.

Step 2 — Create an Integration

UI: Integrations → Create

Select the target Endpoint.
Choose how to forward the request body (JSON to JSON / JSON to QueryString / No mapping).
Configure security + logging + schema options.
Save, then copy the Relay URL displayed in the integration details.

Step 3 — Call the Relay URL

Your callers send requests to the integration Relay URL (it contains a public key).

Tip: use Integrations → Try It to test the full flow without writing code.

Calling the Relay URL

Every integration has a public Relay URL that looks like:

https://<your-domain>/r/<integration_public_key>
https://<your-domain>/r/<integration_public_key>/optional/path

Supported methods

GET, POST, PUT are supported by default.
For POST/PUT, send JSON in the body with Content-Type: application/json.

Query string + path behavior

The optional path (everything after /r/<key>/) can be forwarded to the destination when your integration is configured to do so.
Inbound query string parameters are preserved and can be combined with JSON→QueryString mapping (depending on the integration mode).

Example cURL call

curl -X POST "https://<your-domain>/r/<key>" \
  -H "Content-Type: application/json" \
  -d '{"to":"9725XXXXXXXX","text":"Hello from Relay"}'

Body size is limited by server settings. If the request is too large you may get HTTP 413.

Endpoints

UI: Endpoints. Endpoints describe the target API CloudApi will call.

Key fields

HTTP Method and URL — the destination.
Authentication — bearer token / API key header / query token / basic auth.
Headers — default headers sent to the destination (e.g., Content-Type).
Timeouts — protect your relay from slow upstream services.

API template library

UI: Endpoints → Create from template. Templates pre-fill method, URL, and example schemas. You still need to set auth and any account-specific values.

Integrations

UI: Integrations. Integrations connect a Relay URL to a target Endpoint and apply rules.

What an integration controls

Relay URL — the public entry point that clients call.
Target Endpoint — where CloudApi forwards requests.
Request mapping — JSON-to-JSON mapping or JSON-to-QueryString mapping.
Response mapping — optional mapping of the upstream response back to your preferred schema.
Rate limiting — protect your relay from abuse.
Logging policy — store payloads, mask fields, retention settings (where available).

Try It (built-in tester)

UI: Integrations → open an integration → Try It. Paste a sample request and run it. You can inspect the mapped request/response and see logs in Observability.

Versions & rollback

UI: Integrations → open an integration → Versions. Use this to publish a new mapping safely and roll back quickly if something goes wrong.

Mapping

Mapping lets you translate between your callers’ payload format and the target API format.

JSON → JSON

UI: Integrations → Create/Edit → Mapping section
Use JSONPath-like selectors for source fields and define target paths.
Supports nested objects and arrays (including [*] for array mapping).

Tip: open Show mapping examples in the Integration form to see working examples.

JSON → QueryString

Use this when the target API expects URL query parameters (e.g., ?token=...) instead of a JSON body.

UI: Integrations → Create/Edit → QueryString mapping
Each mapping row maps a JSONPath source to a query parameter name.
Arrays can be serialized as JSON into a single parameter when required.

Schemas & validation

Schemas help you document expected request/response formats and catch invalid payloads early.

UI: Integrations → Create/Edit → Schemas
Define request schema (expected inbound JSON) and response schema (expected outbound JSON).
When enabled, CloudApi can fail-closed on invalid JSON and return an error instead of forwarding bad data.

Security controls

TOTP / Authenticator app

UI: Account / Manage → Enable Authenticator.

Terms of use & disclaimer acceptance

New users may be required to acknowledge Terms of use and Disclaimer once. UI: Account → Legal Acknowledge.

Integration-level controls

Rate limit (Requests/minute) — UI: Integrations → Create/Edit → Security.
IP allow list (if enabled in your build) — restrict Relay callers by IP.
Header forwarding — pass through selected inbound headers to the target endpoint when needed.
Masking — hide secrets/PII fields from stored logs.

Masking (recommended)

UI: Integrations → Create/Edit → Logging
Enable Mask sensitive fields in stored payloads.
Set Mask keys (CSV) (example: password,token,authorization,secret).
Save. Stored request/response payloads will redact matching keys.

Reliability controls

Timeouts — avoid hanging requests on slow upstream providers (Endpoint settings).
Idempotency — protect against duplicates when callers retry (if enabled for your integration/provider).
Backoff / retries — if you enable retries, prefer idempotency and safe methods.
Integration versions — UI: Integrations → Versions to rollback quickly.

Integration versions

UI: Integrations → open an integration → Versions
Create a new version when you change mappings or endpoint settings.
If a change breaks production, rollback to a previous version.

Observability & logs

Observability dashboard

UI: Observability. View traffic, error rate, latency, and recent failures.

Integration Logs

UI: Integrations → open integration → Logs (or via Observability).

Filter by status code, date range, method, client IP, correlation id, and more.
Open a log to see request/response details (depending on logging settings and masking).

What is stored in logs?

You control which payloads are stored.

UI: Integrations → Create/Edit → Logging
Enable or disable: Store incoming request body, Store outgoing request body, and Store outgoing response body.
Use Masking to redact sensitive keys from stored payloads.

Correlation IDs

If your callers send X-Correlation-Id (or X-Request-Id), CloudApi stores it in logs and echoes it back as X-Correlation-Id in the response. This makes it easy to trace a single request across systems.

Replay

Replay lets you re-send a previously logged request to the target endpoint, useful for transient errors. Replay availability may depend on your plan.

UI: Integration Logs → open a log → Replay.
Replay All Failed replays up to a batch limit for currently filtered failures.
Replay requires that the system stored a replay snapshot for that request.

Alerts

UI: Alerts. Create rules to notify you about failures, spikes, or latency issues. Alerts may be plan-gated.

Create an alert rule per integration (or per tenant) with thresholds and time windows.
View triggered events and their context.

Audit log

UI: Audit Logs. Track important actions such as changes to endpoints, integrations, and billing operations. Availability may depend on plan.

Use it to answer: “Who changed what, and when?”
Useful for enterprise compliance and incident analysis.

Billing & plans

UI: Billing. Upgrade/downgrade your plan and see which features are enabled.

Some navigation tabs show Locked when your plan does not include a feature.
Plan features are also shown in the UI via badges and tooltips.

Invitations & team members

UI: Invitations. Invite users to your tenant and manage access.

Create an invite and send the invitation link to a teammate.
Invited users join your tenant but do not become the tenant owner.
Company setup steps may be enforced only for the tenant owner (depending on your onboarding settings).

Status & health

UI: Status. Use this page to validate that the web app and the Relay route are responding.

Use it for quick uptime checks and environment diagnostics.
When troubleshooting provider failures, Status helps you confirm the issue is not the CloudApi service itself.

Examples

Example — WhatsApp Cloud API (send text)

Create an Endpoint with URL: https://graph.facebook.com/v19.0/<phone_number_id>/messages
Auth: add header Authorization: Bearer <token>
Create an Integration, map inbound JSON to WhatsApp format

Inbound request (your callers)


    {
    "to": "9725XXXXXXXX",
    "text": "Hello from CloudApi"
    }

Target request body (WhatsApp)


    {
    "messaging_product": "whatsapp",
    "to": "9725XXXXXXXX",
    "type": "text",
    "text": {
    "preview_url": false,
    "body": "Hello from CloudApi"
    }
    }

Example — SendGrid (send email)

Endpoint URL: https://api.sendgrid.com/v3/mail/send

Auth header: Authorization: Bearer <SENDGRID_API_KEY>


    {
    "personalizations": [
    {
    "to": [{ "email": "[email protected]" }],
    "subject": "Hello"
    }
    ],
    "from": { "email": "[email protected]", "name": "CloudApi" },
    "content": [
    { "type": "text/plain", "value": "Hello" },
    { "type": "text/html", "value": "<p>Hello</p>" }
    ]
    }

Example — JSON → QueryString

Inbound JSON:

{
  "token": "abc",
  "page": 2,
  "filter": { "status": "open" }
}

QueryString mapping result:

?token=abc&page=2&filter=%7B%22status%22%3A%22open%22%7D

Troubleshooting

401/403 from target: check endpoint auth header and token scope.
429 rate limited: check Integration rate limit settings and client traffic patterns.
Invalid JSON: verify the caller sends valid JSON and the Integration schema/mapping rules match.
Replay not available: snapshot not stored, expired, or feature not included in plan.
Webhook-style providers: inbound webhooks must be configured in the provider dashboard; CloudApi handles outbound relays.