API reference

The wede API is a JSON REST API. You use it to send events, sync operations captured without connectivity, receive webhooks and read the connectivity of your zones.

Base URL

https://api.wede.pt

Every endpoint lives under /v1. Send request bodies as JSON with Content-Type: application/json. Every response body is JSON, except 204 No Content responses, which have no body. Timestamps are ISO 8601 strings in UTC. wede is hosted in the European Union by default. Where local regulation requires in-country data residency, a dedicated regional instance is available by agreement.

Authentication

wede accepts two credentials. Use the one that matches where your code runs.

API key

Header x-wede-api-key. For your servers and backend jobs. Never put it in a browser, a mobile app or any bundle you ship to users.

Session token

Header Authorization: Bearer <token>. Returned by POST /v1/auth/login. For people signing in to your apps and to the wede dashboard.

API key

curl https://api.wede.pt/v1/events \
  -H "x-wede-api-key: wede_live_YOUR_KEY"

Prefix	Environment
`wede_live_` followed by 32 hex characters	Production
`wede_test_` followed by 32 hex characters	Sandbox

An API key is the credential for your integration. It can:

Area	Endpoints
Events	`POST /v1/events`, `GET /v1/events`, `GET /v1/events/:event_id`
Offline sync	`POST /v1/sync/batch`, `GET /v1/sync/status`
Webhooks	`GET /v1/webhooks`, `POST /v1/webhooks`, `DELETE /v1/webhooks/:webhook_id`, `POST /v1/webhooks/:webhook_id/test`
Event types	`GET /v1/catalog`, `GET /v1/catalog/equipment`
Connectivity	`GET /v1/connectivity/status`, `POST /v1/connectivity/report`
Zones (read)	`GET /v1/tenant/zones`, `GET /v1/tenant/zones/:zone_code`
Account	`GET /v1/tenant/me`, `GET /v1/tenant/usage`, `GET /v1/tenant/billing`
Sandbox	`POST /v1/sandbox/simulate-connectivity` (sandbox keys only)

Managing zones, teams, dispatch, missions, users, API keys and your event type catalog requires a session token of a user whose role grants it. An API key calling those endpoints receives 403 forbidden. wede stores only a SHA-256 hash of each key, so a key is shown in full only once, when it is created or rotated. A user with the api_keys:manage permission rotates a key with POST /v1/tenant/api-keys/rotate: the new key works immediately and the previous one keeps working for a grace period (24 hours unless grace_hours is set), so you can roll it out without downtime.

Session token

curl https://api.wede.pt/v1/events \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

A session token is valid for 8 hours. What it can do depends on the user’s role. See Login and Session tokens. If a request carries both headers, wede uses the session token.

Calling the API from a browser

The API accepts cross-origin requests from any origin. It authenticates only with the x-wede-api-key and Authorization headers, never with cookies, so a web app can call it directly with the signed-in user’s session token. Never put an API key in a browser: keep keys on your servers.

Environments

Each API key belongs to one environment, and everything it creates is stored with that environment.

	Production (`wede_live_`)	Sandbox (`wede_test_`)
Delivery	Real channels, following your continuity mode and channel cascade	Simulated. The same channel decision as production, but no message ever leaves wede
Zone connectivity	Real state of each zone	Simulated state per zone, `online` unless you change it
Usage and billing	Counted	Never counted
Visible to	Production credentials	Sandbox keys, and sessions that pass `environment=sandbox`

An API key reads only its own environment. A session reads production by default and can pass environment=sandbox on GET /v1/events, GET /v1/events/:event_id and GET /v1/sync/status.
The same idempotency_key can exist once in production and once in sandbox.
Sandbox results are recorded on the event and in its lifecycle. Lifecycle notes of simulated steps start with sandbox:.
Webhook deliveries carry "environment": "sandbox" or "environment": "production", so one endpoint can tell them apart.
With a sandbox key you can change a zone’s simulated state with POST /v1/sandbox/simulate-connectivity or POST /v1/connectivity/report. The real state of the zone is never touched.

Errors

Errors use standard HTTP status codes and a JSON body:

{
  "error": "unknown_event_type",
  "message": "Event type 'cardiac_arest' is not an active type of this tenant's catalog for vertical 'healthcare'.",
  "known_types": ["cardiac_arrest", "obstetric_emergency", "other_medical", "respiratory_failure", "stroke", "trauma"],
  "request_id": "req-4f1"
}

Field	Description
`error`	Stable, machine-readable code. Branch on this value
`message`	Human-readable explanation. Its wording can change; do not parse it
`request_id`	Identifier of the request. Include it when you contact support. Present on most errors
`details`	Validation errors only: the list of fields that failed and why
`docs_url`	Some errors: a link to the relevant documentation

Codes you will meet across the API:

Status	Code	Meaning
400	`invalid_payload`	The body is not valid JSON or does not match the schema
401	`unauthorized`	Credential missing, malformed, revoked or expired
403	`forbidden`	Your credential does not have the permission this endpoint requires
404	`not_found`	The resource does not exist in your tenant and environment
409	`duplicate_event`	An event with this `idempotency_key` already exists in this environment
429	`rate_limited`	Your tenant exceeded its API key request limit for the current minute
422	`invalid_payload`	`POST /v1/events` only: the event body does not match the schema
422	`unknown_vertical`, `unknown_event_type`	The vertical or event type is not active
500	`internal_error`	Unexpected error. Safe to retry with the same `idempotency_key`
503	`service_unavailable`	wede could not validate the request right now. Retry with backoff

Each endpoint page lists every status and code that endpoint returns.

Retries and rate limiting

Retry 5xx responses and network errors with exponential backoff. For events and sync batches, always resend the same idempotency_key: a request that already reached wede returns 409 duplicate_event (or duplicate in a batch) instead of creating a second event. Requests made with an API key are limited per tenant and per minute. The limit is the one set for your tenant or, if none is set, the one of your plan; the default is 500 requests per minute. All the keys of your tenant share it. Every API key response carries:

Header	Meaning
`x-ratelimit-limit`	Requests allowed per minute
`x-ratelimit-remaining`	Requests left in the current minute
`x-ratelimit-reset`	When the current minute ends, in Unix seconds

Above the limit, wede answers 429 with a Retry-After header (seconds) and this body:

{
  "error": "rate_limited",
  "message": "Rate limit exceeded: 500 requests per minute.",
  "limit": 500,
  "retry_after_seconds": 23,
  "request_id": "req-9c2"
}

Wait retry_after_seconds before retrying, and resend the same idempotency_key. For bursts of offline operations, send them in one sync batch of up to 500 events: a batch counts as one request. POST /v1/auth/login returns 429 account_locked after repeated failed sign-ins.

Idempotency

POST /v1/events and every event in POST /v1/sync/batch require an idempotency_key (1 to 128 characters). wede stores each key once per tenant and environment:

The same key on POST /v1/events returns 409 duplicate_event.
The same key in a sync batch returns result: "duplicate" with the event_id of the event already stored, whether that event arrived online or in an earlier batch.

Use a key that identifies the operation itself (for example your transaction or order ID), not the HTTP request. That way the same operation sent online and later in an offline batch is stored once. Webhook deliveries carry X-Wede-Delivery, which stays the same across retries of one delivery. Use it to discard deliveries you have already processed.

Pagination

GET /v1/events uses cursor pagination:

Call it with an optional limit (default 50, maximum 200).
If the response has a non-null next_cursor, pass it as cursor to get the next page.
Stop when next_cursor is null.

Events are returned newest first. total_count is the number of events that match your filters across all pages. Keep the same filters while you page. Cursors are opaque: do not build or change them. Other list endpoints (GET /v1/webhooks, GET /v1/catalog, GET /v1/catalog/equipment, GET /v1/connectivity/status) return every item in one response.

SDKs

The wede SDKs wrap this API for JavaScript and TypeScript, React Native, Python, Swift and Android, and add the offline layer. They are available to customers under agreement. See SDKs.

Overview

Authentication

Events

Teams & Dispatch

Missions

Zones

Billing

Tenant

Webhooks

Sync

Connectivity

Sandbox

Parsers

Onboarding

Base URL

Authentication

API key

Session token

API key

Session token

Calling the API from a browser

Environments

Errors

Retries and rate limiting

Idempotency

SDKs

​Base URL

​Authentication

API key

Session token

​API key

​Session token

​Calling the API from a browser

​Environments

​Errors

​Retries and rate limiting

​Idempotency

​Pagination

​SDKs

Base URL

Authentication

API key

Session token

Calling the API from a browser

Environments

Errors

Retries and rate limiting

Idempotency

Pagination

SDKs