HTTP API reference

Every route below is relative to the Relay API base URL. The hosted pilot uses https://rpa.essedo.com. JSON is the request and response format except for 204 No Content. IDs in paths are Relay UUIDs unless a route says otherwise.

Authentication, scopes, and errors

Hosted requests need a named User-Agent, CF-Access-Client-Id, and CF-Access-Client-Secret. Every /v1/* request also needs Authorization: Bearer <workspace-api-key>. GET /healthz needs Cloudflare Access on the hosted pilot but no workspace API key. Keep all credentials in your application's secret store. Workspace keys are scoped; resources outside the key's workspace are unavailable.

GET /v1/connections HTTP/1.1
User-Agent: customer-app/1.0
CF-Access-Client-Id: <access-client-id>
CF-Access-Client-Secret: <access-client-secret>
Authorization: Bearer <workspace-api-key>

Required scopes are shown for each endpoint. Authentication and scope failures are 401 and 403; unknown or inaccessible IDs are 404; validation errors are usually 400 with field detail. Some service conflicts return {"code":"..."} and an HTTP 409; the compatibility invitation route uses {"error":{"code":"...","message":"...","details":{}}}. A successful operation POST only confirms acceptance; inspect the operation's eventual status, error_code, and result.

Shared response objects

Connection

LinkedIn responses include the last four fields. They do not return the account password.

Operation

outcome_unknown means an external write may have occurred. Inspect provider evidence before another send. The current LinkedIn adapter has no automatic evidence reconciler.

Subscription, event, and delivery

Subscription has id, connection_id, event_types, callback_url, active, and created_at. Creation alone adds secret, returned once. Detail alone adds delivery_counts for pending, sending, delivered, failed, and canceled.

Event list items have id, provider_event_id, type, and received_at. Event detail adds connection_id and data, the normalized provider event payload.

Delivery has id, subscription_id, event_id, status, attempt_count, replay_count, next_attempt_at, delivered_at, and last_error. Detail adds attempts[], each with id, sequence, outcome, status_code, error, started_at, and completed_at.

Service and connections

Durable operations

{"capability":"linkedin.people.search","input":{"keywords":"engineer","start":0,"count":25}}

Subscriptions, events, and deliveries

Selectable event types are message_received, message_sent, sponsored_inmail_received, custom_connection_request_accepted, connection.stream_degraded, and connection.stream_restored. The connection-request classification can be a fallback; inspect provider state before treating it as proof of acceptance.

Callback contract

Relay sends a JSON event callback with X-CS-Event-Id, X-CS-Delivery-Id, X-CS-Timestamp, and X-CS-Signature: v1=<hex>. The signature is HMAC-SHA256 using the subscription secret over the ASCII timestamp, a period, then the raw request body bytes. Compare in constant time and reject stale timestamps. Return 2xx promptly, then process asynchronously. Delivery is at least once; deduplicate by event ID. Non-2xx responses and timeouts retry up to five attempts with 1, 5, 30, and 120 second delays before failed; replay is explicit. Redirects are not followed. There is no automatic event retention timer yet. LinkedIn's stream has no verified replay cursor, so use conversation/message reads to investigate continuity gaps.

The callback JSON body is {id,type,connection_id,provider_event_id,received_at,data}. id is the Relay event UUID and matches X-CS-Event-Id; data is the normalized event payload. X-CS-Delivery-Id identifies this delivery attempt series and is different from the event ID.

Downloads

• Postman collection — all routes and 22 capability request examples.
• Hosted Postman environment — blank credential fields for local use.