API Reference

Complete reference for the Raily REST API

Overview

The Raily API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Base URL

All API requests are made to:

https://api.raily.ai/v1

Authentication

The Raily API uses API keys to authenticate requests. You can view and manage your API keys in the Dashboard.

Include your API key in the Authorization header:

Authorization: Bearer raily_sk_xxxxxxxxxxxxx

Your API key carries significant privileges. Keep it secure and never share it in publicly accessible areas such as GitHub, client-side code, or browser requests.

API Key Types

Type	Prefix	Use Case
Secret Key	raily_sk_	Server-side requests
Public Key	raily_pk_	Client-side (read-only)

---

Request Format

All requests should include:

Content-Type: application/json
Authorization: Bearer raily_sk_xxxxxxxxxxxxx

Example Request

curl https://api.raily.ai/v1/content \
  -H "Authorization: Bearer raily_sk_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "article-123",
    "title": "My Article",
    "type": "article",
    "source": "https://example.com/article"
  }'

---

Response Format

All responses are JSON with a consistent structure:

Success Response

{
  "id": "cnt_abc123xyz",
  "object": "content",
  "created": "2024-01-15T10:30:00Z",
  "externalId": "article-123",
  "title": "My Article",
  "type": "article",
  "source": "https://example.com/article"
}

List Response

{
  "object": "list",
  "data": [
    { "id": "cnt_abc123", ... },
    { "id": "cnt_def456", ... }
  ],
  "hasMore": true,
  "totalCount": 150
}

Error Response

{
  "error": {
    "code": "invalid_request",
    "message": "The 'title' field is required",
    "param": "title",
    "type": "validation_error"
  }
}

---

HTTP Status Codes

Code	Description
200	Success
201	Created
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn’t exist
409	Conflict - Resource already exists
422	Unprocessable Entity - Validation error
429	Too Many Requests - Rate limit exceeded
500	Server Error

---

Rate Limits

API requests are rate limited based on your plan:

Plan	Requests/minute	Requests/day
Starter	60	10,000
Professional	300	100,000
Enterprise	Custom	Custom

Rate limit information is included in response headers:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 295
X-RateLimit-Reset: 1705320000

When rate limited, you’ll receive a 429 response:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 60 seconds.",
    "retryAfter": 60
  }
}

---

Pagination

List endpoints support pagination with limit and cursor parameters:

GET /v1/content?limit=20&cursor=cnt_abc123

Parameter	Description	Default
limit	Number of items (1-100)	20
cursor	Pagination cursor	-

Response

{
  "object": "list",
  "data": [...],
  "hasMore": true,
  "nextCursor": "cnt_xyz789"
}

Pagination Example

async function getAllContent() {
  const allContent = [];
  let cursor = null;

  do {
    const response = await raily.content.list({
      limit: 100,
      cursor
    });

    allContent.push(...response.data);
    cursor = response.hasMore ? response.nextCursor : null;
  } while (cursor);

  return allContent;
}

---

Filtering

Many list endpoints support filtering:

GET /v1/content?type=article&created[gte]=2024-01-01

Filter Operators

Operator	Description	Example
eq	Equal (default)	type=article
ne	Not equal	type[ne]=draft
gt	Greater than	created[gt]=2024-01-01
gte	Greater or equal	requests[gte]=100
lt	Less than	created[lt]=2024-12-31
lte	Less or equal	requests[lte]=1000
in	In array	type[in]=article,report

---

Expanding Objects

Some endpoints support expanding related objects:

GET /v1/content/cnt_abc123?expand=policy

{
  "id": "cnt_abc123",
  "title": "My Article",
  "policyId": "pol_xyz789",
  "policy": {
    "id": "pol_xyz789",
    "name": "Premium Policy",
    "rules": [...]
  }
}

---

Idempotency

For POST requests, you can include an Idempotency-Key header to safely retry requests:

curl https://api.raily.ai/v1/content \
  -H "Authorization: Bearer raily_sk_xxx" \
  -H "Idempotency-Key: unique-request-id-123" \
  -d '{...}'

Idempotency keys expire after 24 hours.

---

Versioning

The API version is included in the URL path (/v1/). We maintain backwards compatibility within a version.

Breaking changes result in a new version. You’ll receive advance notice before deprecating old versions.

---

SDKs

Official SDKs handle authentication, retries, and error handling:

JavaScript/TypeScript

npm install @raily/sdk

Python

pip install raily

---

Quick Reference

Content Endpoints

Method	Endpoint	Description
GET	/v1/content	List all content
POST	/v1/content	Create content
GET	/v1/content/:id	Get content
PATCH	/v1/content/:id	Update content
DELETE	/v1/content/:id	Delete content

Policy Endpoints

Method	Endpoint	Description
GET	/v1/policies	List policies
POST	/v1/policies	Create policy
PATCH	/v1/policies/:id	Update policy
DELETE	/v1/policies/:id	Delete policy

Access Endpoints

Method	Endpoint	Description
POST	/v1/access/check	Check access

Analytics Endpoints

Method	Endpoint	Description
GET	/v1/analytics/usage	Usage analytics
GET	/v1/analytics/revenue	Revenue analytics

---

Next Steps

Authentication

Learn about API key management

Content API

Start managing content