REFERENCE · HTTPS JSON

REST API reference

Base URL: https://zorqelio.xyz. Unless noted otherwise, endpoints accept and return JSON. Send workspace credentials in the Authorization: Bearer header. Treat all one-time tokens as secrets.

Account authentication

POST /api/v1/auth/register accepts email, password (12–128 characters), and workspaceName. It creates an account and workspace, then returns a 14-day sessionToken plus a one-time workspaceToken. POST /api/v1/auth/login accepts email and password and returns a new 14-day session token. Send either a valid workspace API token or an unexpired session token as Authorization: Bearer … to workspace API routes. GET /api/v1/auth/me checks a session, and POST /api/v1/auth/logout revokes it. An authenticated account can rotate its one-time workspace API token with POST /api/v1/workspace/api-token/rotate; this immediately invalidates the previous API token but leaves active account sessions working. Passwords are salted and hashed with PBKDF2-SHA-256; raw passwords and session tokens are not stored.

Public endpoints

MethodPathPurpose
GET/healthService health status.
GET/api/v1/catalogPublic service metadata, MCP endpoint and tool catalogue.
POST/api/v1/workspacesCreate a workspace and return its one-time workspace token.

Workspace-authenticated endpoints

MethodPathPurpose
GET/api/v1/workspaceWorkspace profile, contracts, monitors, usage, validation history and API Data Health evidence score.
POST/api/v1/contractsCreate a contract from {name, schema}; schema is a JSON Schema object.
POST/api/v1/workspace/validateValidate a payload against a workspace-owned contract.
POST/api/v1/monitorsCreate a push or scheduled API monitor.
GET/POST/api/v1/webhooksList or create signed incident webhook endpoints and delivery history.
DELETE/api/v1/webhooks/{endpointId}Disable a webhook endpoint.
POST/api/v1/webhook-deliveries/{deliveryId}/retryRetry a failed webhook delivery.
PUT/api/v1/workspace/notificationsSave notification preferences.
POST/api/v1/workspace/notifications/emailRequest an email verification code; currently unavailable until production email sender configuration exists.
POST/api/v1/workspace/notifications/email/verifyVerify an email address; requires email sending to be configured.

API Data Health

The authenticated GET /api/v1/workspace response includes a health object. Its estimated reliability score is calculated from active monitor states (50% weight), the latest 50 schema-validation results (30%), and incident history (20%). Factors without evidence are excluded and the remaining weights are normalized. The incident factor is omitted until at least one incident has been recorded; no incident history is not treated as proof of perfect health.

{
  "health": {
    "score": 98,
    "grade": "Excellent",
    "confidence": "moderate",
    "factors": [
      { "key": "monitoring", "label": "Monitor health", "score": 100, "weight": 50, "observations": 2 },
      { "key": "validation", "label": "Schema compliance", "score": 100, "weight": 30, "observations": 8 },
      { "key": "incidents", "label": "Incident status", "score": 90, "weight": 20, "observations": 1 }
    ],
    "sampleSize": { "monitors": 2, "validations": 8, "activeIncidents": 1 },
    "methodologyVersion": "1.0",
    "caveat": "Estimated indicator; not an uptime guarantee."
  }
}

score is null and grade is Collecting data until at least one monitor or validation event provides evidence. Confidence is based on monitor and validation sample size. This is a directional workspace indicator, not an external uptime measurement or SLA.

Validation reliability trend

The authenticated workspace response also includes reliabilityTrend, a daily aggregation of validation events from the last 14 calendar days. Each entry includes the UTC date, total validations, passed validations, blocked validations and rounded pass rate. Days without validation activity are omitted.

"reliabilityTrend": [
  { "date": "2026-11-11", "total": 20, "passed": 19, "blocked": 1, "passRate": 95 }
]

Incident automation webhooks

Create up to five HTTPS webhook destinations per workspace. Zorqelio queues incident lifecycle events and sends signed JSON POST requests. Supported events are incident.created, incident.acknowledged and incident.resolved.

curl -X POST https://zorqelio.xyz/api/v1/webhooks \
  -H "Authorization: Bearer $ZORQELIO_WORKSPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"n8n incident workflow","url":"https://automation.example/webhook/zorqelio"}'

Use GET /api/v1/webhooks to list endpoints and the latest 30 delivery attempts. Disable a destination with DELETE /api/v1/webhooks/{endpointId}. Retry a permanently failed delivery with POST /api/v1/webhook-deliveries/{deliveryId}/retry.

New endpoints use an endpoint-specific HMAC-SHA256 signing secret derived from the server-side WEBHOOK_SIGNING_KEY. The create response includes signature.signingSecret once; copy it to your automation's secret manager immediately because it is never returned again. Requests include X-Zorqelio-Event, X-Zorqelio-Delivery, X-Zorqelio-Timestamp and X-Zorqelio-Signature: v1=<hex>. Verify HMAC-SHA256 over timestamp + "." + raw_request_body using that endpoint's signing secret, compare signatures in constant time, and reject timestamps older than five minutes to reduce replay risk. The signing secret is not stored in the database and is independent of workspace API-token rotation. Older endpoints created before this change retain their legacy token-derived signature until replaced.

Deliveries retry with backoff up to eight attempts. Redirects are not followed. Only HTTPS endpoints on port 443 are accepted; local hostnames, IP literals, credentials, query strings, fragments and Zorqelio hostnames are rejected. Disabling an endpoint marks its queued deliveries failed and prevents retries on that endpoint. Keep webhook URLs private because their paths may contain credentials.

Create a workspace

curl -X POST https://zorqelio.xyz/api/v1/workspaces \
  -H "Content-Type: application/json" \
  -d '{"name":"My AI workflow"}'

Response includes workspace.id, workspace.name, workspaceToken and a warning that the token is shown once. Workspace creation is rate-limited to five creations per network per hour.

Create a JSON contract

curl -X POST https://zorqelio.xyz/api/v1/contracts \
  -H "Authorization: Bearer $ZORQELIO_WORKSPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order response",
    "schema": {
      "type": "object",
      "required": ["id", "status"],
      "properties": {
        "id": {"type":"string"},
        "status": {"type":"string","enum":["open","paid"]}
      },
      "additionalProperties": false
    }
  }'

Response includes a contract ID and one-time contract access token. The REST contract creation endpoint creates version 1; further publishing and comparison are available through MCP tools.

Validate a payload

curl -X POST https://zorqelio.xyz/api/v1/workspace/validate \
  -H "Authorization: Bearer $ZORQELIO_WORKSPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"contractId":"YOUR_CONTRACT_UUID","payload":{"id":"ord_7","status":"paid"}}'

Response includes valid, decision, contractVersion, issue details, event ID and timestamp. A valid payload is ALLOW; a schema violation is BLOCK. Validation history stores a bounded summary, not the raw payload.

Create a push monitor

curl -X POST https://zorqelio.xyz/api/v1/monitors \
  -H "Authorization: Bearer $ZORQELIO_WORKSPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"contractId":"YOUR_CONTRACT_UUID","label":"Orders feed","expectedIntervalMinutes":30}'

Response includes a monitor ID, push endpoint, one-time bearer token and mode: "push". Submit each new JSON result to the returned endpoint. See the monitoring guide.

Standard error shape

{
  "error": {
    "code": "WORKSPACE_AUTH_REQUIRED",
    "message": "Provide your workspace API token as a Bearer token."
  }
}

Common HTTP statuses: 400 invalid input, 401 missing/invalid credentials, 404 resource not found in workspace, 409 workspace resource limit, 413 request too large, 415 unsupported media type, 409 idempotency-key replay, 429 workspace quotas/rate limits (and signup rate limits), and 410 revoked monitor. Exact error codes are returned in the response body.

Workspace usage metering and plan entitlements

Authenticated workspace API operations and MCP tools can be attributed to the owning workspace. Usage is tracked in UTC calendar months, with separate API-request and MCP-invocation counters, per-minute limits, success/failure/rejection outcomes, and a separate billable-operation classification. Authentication failures and public health/catalogue requests are not assigned to a workspace or counted as billable usage. Stateless JSON utility tools can opt into workspace attribution by including the optional workspaceToken input.

curl https://zorqelio.xyz/api/v1/workspace/usage \
  -H "Authorization: Bearer $ZORQELIO_WORKSPACE_TOKEN"

The usage endpoint is workspace-scoped and returns the current UTC month, assigned plan limits, aggregate counters and up to 50 recent usage events. API clients may send an Idempotency-Key header; a repeated key for the same workspace is rejected with HTTP 409; no operation is executed twice. Commercial attempt budgets still count requests. Quota and rate-limit rejections return HTTP 429. MCP utility calls without a workspace token remain anonymous and are not assigned to a workspace.

Starter workspace limits are 10,000 combined authenticated API requests and workspace-attributed MCP invocations per UTC month, with 60 per minute for each category. These are workspace quotas, separate from x402 prices. All existing core features remain enabled on the Starter workspace plan. Starter costs $9/month through PayPal when configured. Verified payment is required for persistent automation; the combined operation allowance is 10,000 per UTC month. Overage is blocked and prepaid credits remain inactive.

Usage event records and monthly counters are workspace-scoped. Credit accounts and an append-only credit ledger are reserved for future purchases, allocations, consumption, refunds, adjustments and expirations; no credit balance can currently be purchased or spent. Payment verification and x402 remain separate and are not required for ordinary MCP access.

Limits and operational notes