Message Ops

Use the HTTPS Web origin for the /api/v1 routes. The stock Web deployment does not forward the legacy /oauth/token route; see the integration limitation below. URL-encode environment, VPN, queue and identifier path segments. Swagger is disabled outside development/test; do not expect /api/docs on a production installation.

Authentication and permission model

Use a sop_ token for integrations through the public Web origin. Service Accounts require their own scoped roles and an existing matching service policy for broker operations; v1.7.1 has no customer UI/API to provision that policy. Personal tokens require administrator-enabled API access and use manual assignments only, never SSO-derived grants. A manual Queue Viewer/Queue Operator assignment supplies human queue access; see queue access and policy limits. Both use Authorization: Bearer sop_...; tokens are shown once, expire after the configured period (default 90 days) and are invalidated by regeneration. A valid token does not bypass environment/queue policies, content permissions, license limits or safety controls.

Browser sign-in uses Secure/HttpOnly session cookies in production. Explicit Bearer credentials take precedence over cookies. Sensitive administrative operations require a human session with recent MFA; possession of a long-lived token alone cannot satisfy interactive step-up. Cookie-authenticated writes are subject to origin/CSRF checks.

The API contains a legacy POST /oauth/token endpoint, but it is unavailable through the stock public Web route. The API backend is internal, and there is no /api/v1/oauth/token alias. Do not expose the entire API to make this route reachable. Legacy client credentials also lack environment role assignments, so their scopes alone cannot authorize broker operations. Public integrations should use the token paths and policy prerequisites above.

Search and inspect messages

For broker examples, use a personal token with manual queue assignments or a service account whose required persisted policy has already been provisioned and verified. For the shell examples, set WEB_URL to your public HTTPS origin without a trailing slash and supply TOKEN from your approved credential store. Examples use illustrative environment production, VPN default and queue DMQ.EXAMPLE; substitute a scope your account may access. Do not paste token values into shared scripts or logs.

curl --fail-with-body --silent --show-error "$WEB_URL/api/v1/environments" \
  -H "Authorization: Bearer $TOKEN"
curl --fail-with-body --silent --show-error \
  "$WEB_URL/api/v1/environments/production/vpns/default/queues?includeStats=true" \
  -H "Authorization: Bearer $TOKEN"

Search has a flat JSON body. A metadata-only example avoids assuming content-read permission:

curl --fail-with-body --silent --show-error -X POST "$WEB_URL/api/v1/messages/search" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  --data '{
    "environmentId": "production",
    "vpnName": "default",
    "queueName": "DMQ.EXAMPLE",
    "searchTerm": "order-123",
    "searchFields": ["messageId", "correlationId"],
    "maxMessagesToScan": 1000,
    "maxResults": 25,
    "includePayloadPreview": false
  }'

HTTP 202 returns {"searchId":"...","status":"accepted"}. Set SEARCH_ID from that response and poll at a reasonable interval until completed or failed:

curl --fail-with-body --silent --show-error "$WEB_URL/api/v1/messages/searches/$SEARCH_ID" \
  -H "Authorization: Bearer $TOKEN"
curl --fail-with-body --silent --show-error "$WEB_URL/api/v1/messages/searches/$SEARCH_ID/results" \
  -H "Authorization: Bearer $TOKEN"

Results contain searchId, status and results. Use a returned messageRef with GET /api/v1/messages/{messageRef}; full payload is GET /api/v1/messages/{messageRef}/payload with payload permission. Search resources are distinct from operation jobs.

Content-bearing unified searches, including omitted searchFields, require source-queue content-read permission. Stored content searches remain protected on later status/result reads. A 256 MiB aggregate browse-buffer bound can stop a search before its requested count. Unknown search fields are rejected. See Queues and Messages for masking and reference expiry.

Submit an operation and read its outcome

POST /api/v1/resubmissions, /moves and /deletions accept explicit environmentId and a selection. Use either selection.messageRefs or selection.criteria with vpnName and queueName, plus search predicates. Reference selections must resolve to the expected scope. Criteria are resolved against the live queue and the bulk limit applies; no matches produce CRITERIA_NO_MATCHES.

Resubmit/move also require target.type (queue or topic) and target.destination. Destination permissions are checked separately. Move also requires source-delete authority. Direct move/delete require reason and always require changeReference in production. The following dry-run move uses a live reference obtained from your search; replace msgref-from-your-search before submission:

{
  "environmentId": "production",
  "selection": {"messageRefs": ["msgref-from-your-search"]},
  "target": {"type": "queue", "destination": "RETRY.QUEUE"},
  "options": {"dryRun": true},
  "reason": "Verify retry selection",
  "changeReference": "CHG-12345",
  "idempotencyKey": "unique-key-for-this-dry-run"
}

Save the edited request as move-request.json and submit:

curl --fail-with-body --silent --show-error -X POST "$WEB_URL/api/v1/moves" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  --data-binary @move-request.json

The HTTP 202 response is a public job object with id and status. Follow GET /api/v1/jobs/{id}, /events and /report. Dry run does not mutate the broker and does not guarantee a later live result. Use a new idempotency key if changing from dry run to a real request.

For move and delete, idempotencyKey is an optional JSON body field. Reuse it with the same request to retrieve the existing job after an uncertain submission response; a different request with the same key conflicts. Keys are scoped to authenticated identity kind and ID, and normal access checks still apply. Do not rely on an Idempotency-Key HTTP header in v1.7.1; it is not read by these handlers. Resubmission does not cache idempotent responses. Check existing jobs before resubmitting a possibly accepted request.

Resubmit options include dryRun, preserveHeaders, preserveProperties and addResubmissionMetadata. The API accepts maxRatePerSecond, but the v1.7.1 Worker does not enforce it; do not use it as a rate limit. Move supports dry run and header/property preservation; delete supports dry run. Resubmit leaves the original in place; use move when source removal is intended. Broker acknowledgement is required before move removes the source. Cancellation is cooperative and does not undo completed items.

Schedule an operation

POST /api/v1/schedules accepts name, operation (resubmit, move, delete) and request_template, using the corresponding operation body. In production, every request_template must include changeReference, including resubmit; move/delete also require reason. For one-time work, set schedule_type: "once" and a future ISO 8601 run_at with year and UTC offset. For recurring work, set schedule_type: "cron" and a five-field UTC schedule_expression. Do not provide both timing fields.

This recurring dry-run example resolves a fresh bounded selection at 02:00 UTC daily:

{
  "name": "Daily retry review",
  "operation": "move",
  "schedule_type": "cron",
  "schedule_expression": "0 2 * * *",
  "request_template": {
    "environmentId": "production",
    "selection": {"criteria": {"vpnName": "default", "queueName": "DMQ.EXAMPLE", "maxResults": 25}},
    "target": {"type": "queue", "destination": "RETRY.QUEUE"},
    "options": {"dryRun": true},
    "reason": "Scheduled retry review",
    "changeReference": "CHG-12345"
  }
}

Review and disable/delete a test schedule after validation. Editing/enabling transfers execution ownership to the manager. Use criteria rather than expiring references for recurring work. Schedules explains timing, consumed one-time runs and recovery.

Errors

Most errors use an error object containing code, message, correlationId and details. Validation messages can be arrays. Server failures return a generic message; use the correlation ID with sanitized service logs. Typical HTTP outcomes are 400 invalid input, 401 missing/expired credentials, 403 policy/license/MFA denial, 404 missing resource, 409 state/idempotency conflict, 410 expired reference and 429 throttling.

The legacy OAuth route instead returns OAuth JSON such as {"error":"invalid_request"} (400), unsupported_grant_type (400) or invalid_client (401). An accepted job can fail later; HTTP submission status is not its terminal result. See Troubleshooting for recovery actions.

Endpoint directory

Paths below are complete HTTP paths. Every protected operation enforces its applicable permission, scope, license and MFA checks; the presence of a route does not grant access. Request bodies for operational workflows are described above; administrator task guides explain the corresponding settings and controls. For generated clients, obtain the release-matched OpenAPI contract from your supplier and validate these v1.7.1 limits and authentication requirements when integrating.

Authentication and profile

Broker operations and schedules

Administration and integrations