API endpoint reference
Look up messaging and resource endpoints and their required scopes.
Reviewed
These are the routes available to a Waaru Developer API key. Prefix each path with https://api.waaru.app. All require a key bound to a number. Scoped reads work in either inbound mode, including retained history after disconnection subject to lifecycle checks. Autonomous sends and workspace mutations retain their connected-number and Developer API write gates.
This reference lists 36 Developer API operations and 15 scopes, including workspace resources, read-only campaign results and webhook management. Separate OAuth integrations bring the total public operation inventory to 55; they use separate credentials and authority. Existing keys gain no scopes automatically. Workspace-prefixed scopes cover shared contacts, labels and static audiences. Other resources stay limited to the key's number or WABA. Use the matching deployed API release; source implementation does not establish live availability.
| Method and path | Required scope |
|---|---|
GET /v1/developer/instance | instance:read |
POST /v1/developer/labels | workspace:labels:manage |
PATCH /v1/developer/labels/:id | workspace:labels:manage |
POST /v1/developer/labels/:id/archive | workspace:labels:manage |
PATCH /v1/developer/segments/:id | workspace:segments:manage |
POST /v1/developer/segments/:id/archive | workspace:segments:manage |
POST /v1/messages | messages:send |
GET /v1/messages/changes | messages:read |
GET /v1/developer/campaigns | campaigns:read |
GET /v1/developer/campaigns/:id | campaigns:read |
GET /v1/developer/campaigns/:id/recipients | campaigns:read |
GET /v1/messages/:messageId | messages:read |
GET /v1/conversations | messages:read |
GET /v1/conversations/:conversationId/messages | messages:read |
GET /v1/media/:id | media:read |
GET /v1/developer/contacts | workspace:contacts:read |
POST /v1/developer/contacts | workspace:contacts:write |
GET /v1/developer/contacts/:id | workspace:contacts:read |
PATCH /v1/developer/contacts/:id | workspace:contacts:write |
GET /v1/developer/labels | workspace:contacts:read |
PUT /v1/developer/contacts/:id/labels/:labelId | workspace:contacts:write |
DELETE /v1/developer/contacts/:id/labels/:labelId | workspace:contacts:write |
GET /v1/developer/segments | workspace:segments:read |
POST /v1/developer/segments | workspace:segments:write |
GET /v1/developer/segments/:id | workspace:segments:read |
GET /v1/developer/segments/:id/members | workspace:segments:read |
PUT /v1/developer/segments/:id/members/:contactId | workspace:segments:write |
DELETE /v1/developer/segments/:id/members/:contactId | workspace:segments:write |
GET /v1/developer/templates | templates:read |
GET /v1/developer/templates/:id | templates:read |
GET /v1/developer/reports/activity | reports:read |
GET /v1/webhook | webhooks:read |
PUT /v1/webhook | webhooks:manage |
POST /v1/webhook/rotate | webhooks:manage |
POST /v1/webhook/test | webhooks:manage |
POST /v1/webhook/state | webhooks:manage |
Send returns 202 with messageId and status: "queued". Other successful requests return 200; media downloads return bytes. Lists return items and nextCursor. Message IDs are Waaru identifiers, not Meta identifiers. Webhook event IDs support deduplication; X-Waaru-Request-Id is for troubleshooting and does not prevent duplicate sends.
Message examples · Conversation filters and media · Signed callbacks · Errors and limits
Use workspace and number resources
Contacts, labels and static segments are shared workspace resources. Use their dedicated guides below for field bounds, lifecycle rules and payload examples. Resource lists accept limit from 1 to 100 (default 50) and the returned nextCursor as after. Keep filters unchanged while paging. These are live lists, not exports.
Consent restrictions and send-safety checks remain enforced. Template discovery is not permission to send. Webhook writes require the current revision; only creation and rotation return a signing secret. Store it immediately. See webhook management for revision and retry rules.
Manage other capabilities in the dashboard
Create keys and choose the inbound handler in Settings > Developer. Template authoring, broadcasts, dynamic audience rules, Logic Flow authoring, workspace administration, and uploads remain dashboard operations. Outbound API media uses public HTTPS links. A dashboard /v1 path is not automatically a public API.
Download the OpenAPI contract or Postman collection. Import the collection into your own development tools and supply secrets only in your local secret environment. These files describe REST operations and are separate from the published Node SDK beta. This site never asks for an API key or executes requests for you.
Next: Make your first authenticated request.
Find request and response payloads
- Number status and capabilities
- Contacts and labels
- Static segments
- Template discovery
- Activity reports
- Webhook management
Public API-key boundaries
The operations above are the supported API-key surface. The following are not public API-key operations; this is not a delivery roadmap. Some separate OAuth connectors support their own reviewed actions.
| Capability | Public API-key support |
|---|---|
| Bulk or scheduled sends; broadcast create/edit/cancel | No |
| Full-text message search or conversation assignment mutation | No |
| Contact delete, bulk import/export, field-definition or consent administration | No |
| Label hard deletion or restoration | No |
| Segment deletion/restoration or dynamic rules | No |
| Template/Form authoring or media upload | No |
| Standalone catalog/product interactive sends or catalog management | No |
| Logic Flow or Automation authoring/execution administration | No |
| Arbitrary-period, conversion or cost analytics | No |
| Multiple callbacks or arbitrary webhook replay | No |
| Workspace/member/key administration or inbound-handler changes | No |
Approved template sends can include supported carousels, product cards and eligible Form launches. See template discovery and launch rules; authoring and sending are separate capabilities.
Read campaign summaries and recipient results without gaining broadcast scheduling or send authority.
API errors and retries
Interpret Waaru Developer API error codes, rate-limit headers, admission failures, and uncertain send outcomes without duplicating customer messages.
Contacts and labels
Read shared workspace contacts, upsert and update profiles, and apply existing labels with scoped API requests.