Surfaces

Interactive API Explorer: Explorer

The authoritative surface is the OpenAPI spec:

• /rbs/openapi.yaml

Additional surfaces are available: MCP (/rbs/mcp.html) and CLI (g3n rbs ...; see cli/README.md).

Surface Types (explicit)

API Gateway

• Status: Available.
• Base: https://api.g3nretailstack.com/rbs
• Notes: Primary tenant surface for subscription management and delivery tests.

Direct Lambda

• Status: Not offered.
• Notes: No direct Lambda surface is documented for RBS.

CLI

• Status: Available.
• Command: g3n rbs ... (API Gateway).
• Notes: See cli/README.md.

MCP

• Status: Available.
• Canonical protocol: https://mcp.g3nretailstack.com/rbs/PROTOCOL.md
• Mirror: https://doc.g3nretailstack.com/rbs/PROTOCOL.md

Auth + tenancy

• Auth headers: x-session-guid (user session) or x-api-key (org-bound service account) are required for all API Gateway calls, including /stat.
• Tenant endpoints require x-orgcode (health checks do not).
• Owner-only: non-owners receive 403 forbidden (anti-enumeration still applies).
• Header auth is canonical; body auth is accepted where documented. See /common/headers-identity.html.
• Optional cost attribution: x-cccode (or request field cccode) where supported; see OpenAPI.

Identifier policy

• Direct get/update/status calls require GUID/ID fields (*_id or legacy *_guid where that is the canonical field name). Code-based lookups are resolve/search only.
• Responses never include both *_id and *_guid for the same record (no dual-field output).
• Exceptions (email-based UAS, PVM resolve, MRS container+record_id) are listed in /common/ids-codes.html.

Request builder (API Gateway)

Headers (canonical)

-H "x-orgcode: $ORGCODE"
-H "x-session-guid: $SESSION_GUID" # or: -H "x-api-key: $API_KEY"
-H "content-type: application/json"

Template

curl -sS -X POST "https://api.g3nretailstack.com/rbs/<endpoint>" \
  -H "content-type: application/json" \
  -H "x-orgcode: $ORGCODE" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{"...": "..."}'

Notes

• Replace <endpoint> with a route from the OpenAPI inventory.
• Health checks may omit x-orgcode; tenant routes require it.
• Header auth is canonical; body session_guid / api_key is accepted where documented.

Error envelope example (canonical)

{
  "success": false,
  "error": {
    "error_code": "rbs.conflict_revision",
    "http_status": 409,
    "retryable": false,
    "request_id": "req-123",
    "trace_id": "trace-abc",
    "major": { "tag": "conflict", "message": { "en_US": "Expected revision does not match the current record." } },
    "details": { "expected_revision": "rev-3", "current_revision": "rev-4" },
    "conflict_snapshot": { "revision": "rev-4" }
  },
  "build": { "...": "..." },
  "stats": { "call": "example", "service": "rbs", "timestamp_utc": "2026-01-26T00:00:00Z", "request_id": "req-123" }
}

Subscription lifecycle

• POST /rbs/subscription/register — register a queue subscription and send verification.
• POST /rbs/subscription/verify — activate the subscription using a queue-delivered token.
• POST /rbs/subscription/status/set — pause/resume/revoke.
• POST /rbs/subscription/update — update filters or queue config (re-verifies if queue/credentials change).
• POST /rbs/subscription/unregister — revoke subscription.
• POST /rbs/subscription/get + /rbs/subscription/list — read your registry.
• POST /rbs/subscription/test — send a test delivery to the queue.

Delivery payloads

• Standard deliveries include delivery_id, subscription_id, delivered_at, delivery_reason, and event.
• delivery_reason: live (normal delivery), retry (automatic retry), test (manual test), or verify (subscription verification).
• Event payloads include their own reason (why the event occurred).

Delivery auth + queue verification

• Preferred auth: cross-account assume_role with external_id; static access keys are supported for legacy cases.
• RBS verifies queue ownership by calling GetQueueAttributes and matching QueueArn to the provided queue URL/account.
• Required permissions for the delivery principal: sqs:GetQueueAttributes + sqs:SendMessage on the target queue.
• For SSE-KMS queues, the key policy must allow the delivery principal to use the key (send requires KMS encrypt permissions).

Oversize payloads

If a delivery payload exceeds the SQS size limit, RBS stores the full delivery payload in S3 and sends a signed pointer instead. The S3 object content is the JSON payload that would have been delivered, and the signed URL expires based on RBS_PAYLOAD_PRESIGN_TTL_SECONDS (default 3600s).

Pointer message shape (example):

{
  "type": "rbs_payload_pointer",
  "delivery_id": "del-123",
  "delivered_at": "2026-01-26T00:00:00Z",
  "subscription_id": "sub-123",
  "delivery_reason": "live",
  "event_summary": {
    "event_id": "evt-123",
    "service": "pvm",
    "action": "variant-updated",
    "reason": "status-set"
  },
  "payload_pointer": {
    "storage": "s3",
    "bucket": "example-payload-bucket",
    "key": "rbs/oversize/ACME/sub-123/evt-123.json",
    "region": "us-east-1",
    "url": "https://signed-url",
    "expires_at": "2026-01-26T01:00:00Z",
    "content_type": "application/json",
    "size_bytes": 482931,
    "sha256": "..."
  }
}

Role requirements (by endpoint family)

• All RBS operations: owner-only (org owner session or owner API key).

Idempotency & retries

• Subscription register is not idempotent; use subscription_id to look up before retrying.
• Status updates require expected_revision when documented.

Common pitfalls

• Queue URL/region must match the target AWS account/region.
• Verification tokens expire; complete verification promptly.

Examples (core families)

Subscription register

{ "queue_url": "https://sqs.us-east-1.amazonaws.com/123456789012/g3n-events", "queue_region": "us-east-1", "filters": [{ "service": "scm", "action_prefix": "order-" }], "reason": "integration" }

Response (shape):

{ "success": true, "data": { "subscription_id": "SUB_ID" }, "build": { "...": "..." }, "stats": { "...": "..." } }

Subscription verify

{ "subscription_id": "SUB_ID", "verification_token": "TOKEN", "reason": "verify" }

Response (shape):

{ "success": true, "data": { "status": "active" }, "build": { "...": "..." }, "stats": { "...": "..." } }