API REFERENCE

API Reference

Complete REST API documentation for every Rymeda infrastructure layer.

https://api.rymeda.com/v1v1.0

Authentication

All API requests require authentication via OAuth2 bearer tokens or API keys. Tokens are scoped to specific permissions and expire after a configurable TTL.

OAuth2 Client Credentials Flow

Exchange your client ID and secret for a bearer token.

POST https://auth.rymeda.com/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&scope=care:read care:write revenue:read

Token Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "care:read care:write revenue:read"
}

Available Scopes

Scope	Description
`care:read`	Read care sessions, client profiles, progress notes
`care:write`	Create and update sessions, notes, care plans
`revenue:read`	Read claims, ERA/EOBs, payment data
`revenue:write`	Submit claims, manage billing workflows
`compliance:read`	Read audit trails, compliance artifacts
`compliance:write`	Upload artifacts, configure compliance rules
`intelligence:read`	Query ORIS, view predictions and insights
`intelligence:write`	Trigger workflows, run analysis
`network:read`	Read providers, organizations, credentials
`network:write`	Manage providers, create organizations
`commerce:read`	Read products, orders, inventory
`commerce:write`	Create orders, manage marketplace
`platform:admin`	Manage webhooks, API keys, org settings

Security note: Never expose your client secret or API keys in client-side code. Use server-side authentication and proxy requests through your backend.

Pagination

All list endpoints use cursor-based pagination for consistent, efficient traversal of large datasets.

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of items per page (1–100, default 25)
`cursor`	string	Opaque cursor from previous response
`sort`	string	Sort field (e.g., "createdAt", "-createdAt" for descending)

Example Response

{
  "data": [ ... ],
  "pagination": {
    "cursor": "eyJpZCI6ImNsYWltXzA1MCJ9",
    "hasMore": true,
    "limit": 25,
    "total": 142
  }
}

Error Codes

All errors return a consistent JSON structure with machine-readable codes and human-readable messages.

Error Response Shape

{
  "error": {
    "status": 422,
    "code": "VALIDATION_FAILED",
    "message": "Validation failed for 2 fields",
    "details": [
      { "field": "clientId", "message": "Client not found" },
      { "field": "cptCodes", "message": "At least one CPT code is required" }
    ],
    "requestId": "req_abc123xyz"
  }
}

HTTP Status Codes

Status	Title	Description
`400`	Bad Request	The request body is malformed or missing required fields.
`401`	Unauthorized	Missing or invalid authentication token.
`403`	Forbidden	Valid token but insufficient permissions for this resource.
`404`	Not Found	The requested resource does not exist.
`409`	Conflict	Resource state conflict (e.g., duplicate submission, stale update).
`422`	Unprocessable Entity	Validation failed — check field-level errors in response body.
`429`	Too Many Requests	Rate limit exceeded. Retry after the duration in the Retry-After header.
`500`	Internal Server Error	An unexpected error occurred. Contact support with the request ID.

Rate Limits

Rate limits are enforced per API key. Exceeding limits returns a 429 status with a Retry-After header.

Rate Limit Headers

Header	Description
`X-RateLimit-Limit`	Maximum requests per window
`X-RateLimit-Remaining`	Remaining requests in current window
`X-RateLimit-Reset`	Unix timestamp when the window resets
`Retry-After`	Seconds to wait before retrying (on 429 only)

Tier Limits

Tier	Requests	Burst	Description
Free	`100 / min`	`20 / sec`	Development and sandbox usage
Growth	`1,000 / min`	`100 / sec`	Production workloads
Enterprise	`10,000 / min`	`500 / sec`	High-volume integrations
Custom	`Unlimited`	`Custom`	Dedicated infrastructure

Care

Care delivery engine — sessions, clients, documentation, and progress notes.

POST/v1/care/sessions

Create a new care session for a client. Automatically validates service authorization and provider credentials.

Bearer token required

curl -X POST https://api.rymeda.com/v1/care/sessions \
  -H "Authorization: Bearer rym_test_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "client_123",
    "serviceType": "behavioral_health",
    "providerId": "prov_456",
    "startTime": "2025-01-15T09:00:00Z"
  }'

GET/v1/care/clients/{clientId}

Retrieve a client profile including demographics, active care plans, and service history.

Bearer token required

curl https://api.rymeda.com/v1/care/clients/client_123 \
  -H "Authorization: Bearer rym_test_your_api_key_here"

POST/v1/care/progress-notes

Create a progress note for a completed session. Supports structured fields and free-text narratives.

Bearer token required

{
  "sessionId": "session_789",
  "type": "soap",
  "subjective": "Client reports improved sleep patterns...",
  "objective": "Alert, oriented, cooperative...",
  "assessment": "Progress toward treatment goals...",
  "plan": "Continue current treatment plan..."
}

Revenue

Claims lifecycle, ERA/EOB processing, payer management, and revenue analytics.

POST/v1/revenue/claims

Submit a new insurance claim. Validates CPT/ICD codes, service authorizations, and payer requirements before submission.

Bearer token required

curl -X POST https://api.rymeda.com/v1/revenue/claims \
  -H "Authorization: Bearer rym_test_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "client_123",
    "sessionId": "session_789",
    "payerId": "payer_medicaid",
    "cptCodes": ["90837"],
    "amount": 245.00
  }'

GET/v1/revenue/claims

List all claims with filtering by status, payer, date range, and service type. Supports cursor-based pagination.

Bearer token required

curl "https://api.rymeda.com/v1/revenue/claims?status=submitted&limit=25" \
  -H "Authorization: Bearer rym_test_your_api_key_here"

GET/v1/revenue/era/{eraId}

Retrieve an Electronic Remittance Advice (ERA) by ID, including payment details and adjustment codes.

Bearer token required

Compliance

Audit trails, regulatory tracking, documentation enforcement, and compliance scoring.

GET/v1/compliance/audits

List audit trail entries with filtering by resource type, action, user, and date range.

Bearer token required

curl "https://api.rymeda.com/v1/compliance/audits?resourceType=care_session&limit=50" \
  -H "Authorization: Bearer rym_test_your_api_key_here"

POST/v1/compliance/artifacts

Upload a compliance artifact (policy document, training certificate, attestation) with metadata.

Bearer token required

{
  "type": "training_certificate",
  "title": "HIPAA Annual Training 2025",
  "userId": "user_100",
  "expiresAt": "2026-01-15T00:00:00Z",
  "fileUrl": "https://storage.rymeda.com/artifacts/cert_001.pdf"
}

Network

Multi-tenant provider management, credentialing, workforce, and scheduling.

GET/v1/network/providers

List providers with filtering by specialty, credential status, organization, and availability.

Bearer token required

curl "https://api.rymeda.com/v1/network/providers?specialty=behavioral_health" \
  -H "Authorization: Bearer rym_test_your_api_key_here"

POST/v1/network/organizations

Create a new organization in the network. Provisions isolated tenant with RBAC, data partitioning, and compliance defaults.

Bearer token required

{
  "name": "Crestview Health Services",
  "type": "behavioral_health_provider",
  "ein": "12-3456789",
  "primaryContact": {
    "email": "admin@crestview.com",
    "phone": "+1-555-0100"
  }
}

Commerce

Healthcare marketplace, supply chain, vendor management, and order processing.

GET/v1/commerce/products

List marketplace products with filtering by category, vendor, and availability.

Bearer token required

POST/v1/commerce/orders

Create a new order for healthcare products or supplies. Validates inventory, calculates shipping, and initiates fulfillment.

Bearer token required

{
  "organizationId": "org_100",
  "items": [
    {
      "productId": "prod_001",
      "quantity": 10
    }
  ],
  "shippingAddress": {
    "line1": "123 Health Ave",
    "city": "Austin",
    "state": "TX",
    "zip": "78701"
  }
}

Intelligence

ORIS-powered clinical reasoning, natural language queries, predictive analytics, and insights.

POST/v1/intelligence/query

Query the ORIS intelligence engine with natural language. Returns structured insights from clinical and operational data.

Bearer token required

curl -X POST https://api.rymeda.com/v1/intelligence/query \
  -H "Authorization: Bearer rym_test_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Show clients with overdue progress notes this week",
    "context": { "organizationId": "org_100" }
  }'

POST/v1/intelligence/predict

Generate predictive analytics for operational metrics — no-shows, revenue forecasts, compliance risk.

Bearer token required

{
  "model": "no_show_risk",
  "input": {
    "clientId": "client_123",
    "sessionDate": "2025-01-20",
    "serviceType": "behavioral_health"
  }
}

POST/v1/intelligence/analyze

Run deep analysis on clinical or operational data. Supports trend analysis, anomaly detection, and pattern recognition.

Bearer token required

{
  "analysisType": "trend",
  "metric": "claim_denial_rate",
  "timeRange": {
    "start": "2024-07-01",
    "end": "2025-01-15"
  },
  "groupBy": "payer"
}

Platform

Webhook management, API key lifecycle, and platform configuration.

GET/v1/platform/webhooks

List configured webhook endpoints with delivery status and event subscriptions.

Bearer token required

POST/v1/platform/api-keys

Create a new API key with scoped permissions and optional expiration.

Bearer token required

{
  "name": "Production Integration",
  "scopes": ["care:read", "care:write", "revenue:read"],
  "expiresAt": "2026-01-15T00:00:00Z"
}

Webhooks

Receive real-time notifications when events occur in Rymeda. Webhooks are signed, retried, and delivered in order.

Event Types

Event	Description
`session.created`	A new care session has been scheduled.
`session.completed`	A care session has been marked as completed.
`claim.submitted`	A new insurance claim has been submitted to the payer.
`claim.paid`	An insurance claim has been paid by the payer.
`claim.denied`	An insurance claim has been denied by the payer.
`compliance.artifact_expiring`	A compliance artifact is expiring within the configured notice period.
`provider.credential_updated`	A provider credential has been updated or re-verified.
`intelligence.workflow_completed`	An ORIS automation workflow has completed execution.

Signature Verification

Every webhook payload is signed with your webhook secret using HMAC-SHA256. Verify the signature before processing.

// Verify webhook signature (Node.js)
import crypto from 'crypto'

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  )
}

// Headers sent with each webhook:
// X-Rymeda-Signature: <HMAC-SHA256 hex digest>
// X-Rymeda-Timestamp: <Unix timestamp>
// X-Rymeda-Event: <event type>

Retry Policy

Attempts

Up to 5 retries with exponential backoff

Backoff

1s, 5s, 30s, 2m, 10m between retries

Timeout

30 second response timeout per attempt

Example Payload

{
  "event": "session.created",
  "data": {
    "sessionId": "session_789",
    "clientId": "client_123",
    "providerId": "prov_456",
    "startTime": "2025-01-15T09:00:00Z"
  },
  "timestamp": "2025-01-14T16:30:00Z"
}

Need help integrating?

Check out our integration guides or talk to our engineering team for hands-on support.

Integration Guides Talk to Engineering