RailAI API

The RailAI API exposes the scoring models and Growth Graph that power the platform. Build integrations, publish agents, and access every feature programmatically.

Authentication

RailAI uses two auth modes. App resources (Growth Graph, predictions, CRM) take a Bearer JWT in the Authorization header. The public scoring endpoint takes an API key in the x-api-key header. Generate and manage API keys from the app (Developers → API keys).

POST /api/v1/api-economy/scores/content HTTP/1.1
Host: railai.cloud
x-api-key: rail_live_7Qz9KfA2mNbX4pR8sT1vW3yL
Content-Type: application/json

Quickstart

Score a piece of content in one call. Pass the platform, content type, and the title/body to evaluate; the response returns viral, engagement, and overall scores on a 0–100 scale.

curl https://railai.cloud/api/v1/api-economy/scores/content \
  -H "x-api-key: rail_live_••••" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "tiktok",
    "contentType": "short_video",
    "title": "POV: you automated your funnel",
    "body": "Here is exactly how we did it in 3 steps…"
  }'

{
  "viralScore": 41.2,
  "engagementScore": 38.6,
  "overallScore": 39.9,
  "platform": "tiktok",
  "contentType": "short_video"
}

Scores API

Score content on a 0–100 scale. The public endpoint is API-key authenticated; the full prediction engine is available to authenticated app sessions.

Public content scoring (x-api-key auth). Deterministic scoring over the supplied content features — the same input always yields the same scores. Usage is metered per key.

Full prediction-engine scoring for authenticated app sessions (Bearer JWT). Returns viral, engagement, and conversion predictions with feature breakdowns.

Growth Graph API

Query your organization’s growth graph and rank creators for a brand. Bearer JWT auth; all results are org-scoped.

Returns the nodes and relationships in your organization’s growth graph — brands, creators, communities, campaigns, and audiences.

Rank creators for a brand using graph proximity and historical performance signals.

Payments (USDC escrow)

Marketplace orders settle in USDC through a non-custodial on-chain escrow on Base. The platform never holds keys: the API returns theapprove andfund transactions for the buyer’s wallet to sign. On release the escrow splits 90% to the creator and a 10% platform fee.

Returns the escrow + USDC contract addresses, the derived on-chain order id, the amount (USDC minor units), the creator payout address, and ready-to-send approve / fund calldata. Bearer (JWT) auth, OWNER/ADMIN.

Submit the on-chain funding tx hash. The server reads the escrow contract (it never trusts the client) and advances the order to PROCESSING when the escrow is funded to the expected payee and amount. Idempotent on the tx hash.

Reconcile an order against on-chain state — Released → PAID, Refunded → REFUNDED.

Set the creator’s USDC payout wallet. Must be a wallet whose ownership was verified via the web3 SIWE challenge flow.

Non-secret status of the crypto rail: whether it is configured and the public chain + contract addresses. Returns { configured: false } when the rail is disabled.

Knowledge / RAG

The AI Knowledge Cloud turns your documents into a searchable AI brain. Create a knowledge base, ingest documents (they are chunked and embedded), then run hybrid semantic search or get grounded, cited answers. Bearer JWT auth; every knowledge base, document and chunk is org-scoped and never crosses tenants. Ingestion is asynchronous: an ingest call returns the document as PENDING and a background worker advances it to PROCESSING then INDEXED (or FAILED) — poll GET /knowledge/collections/:id/documents for status.

Create a knowledge base. The embedding model and vector dimension are pinned at creation so a base stays queryable even if the platform default changes.

Ingest a document. The text is normalized, chunked with overlap, embedded, and indexed into the vector store. Duplicate content (by hash) is rejected.

Ingest a public web page or resource by URL. The fetch is SSRF-guarded — private, loopback and cloud-metadata addresses are blocked, redirects are re-validated, and the response is size- and time-capped. HTML is reduced to readable text before indexing. Body: url (required, http/https) and an optional title.

Upload a file as multipart/form-data (field file, optional title) to extract and index it. Supported: PDF, DOCX, HTML, Markdown, CSV, JSON and plain text, up to 25 MB. Scanned/image-only PDFs are rejected (OCR is not yet supported).

Retrieve the most relevant chunks and generate a grounded answer with inline citations, a confidence score, and the source chunks. Uses a real LLM when configured, otherwise a deterministic extractive answer over your corpus.

curl -X POST https://railai.cloud/api/v1/knowledge/collections/KB_ID/answer \
  -H "Authorization: Bearer $RAILAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is the best time to post short-form video?",
    "limit": 8,
    "alpha": 0.6,
    "diversity": 0.3
  }'

{
  "knowledgeBaseId": "KB_ID",
  "query": "What is the best time to post short-form video?",
  "answer": "Evening posts perform best for creators [1] ...",
  "confidence": 0.82,
  "grounded": true,
  "model": "railai-rag",
  "citations": [
    {
      "documentId": "…",
      "documentTitle": "Posting Playbook",
      "chunkId": "…",
      "ordinal": 3,
      "snippet": "Short form video performs best when posted in the evening…",
      "score": 0.914
    }
  ]
}

Hybrid retrieval only (no generation): dense embeddings fused with a BM25 lexical score, reranked with MMR for diversity. Tune alpha (dense vs lexical weight) and diversity (0–1). Returns scored chunks with document titles and snippets.

Pass useGraph: true on search or answer to enable graph-before-vector retrieval: entities in your query are matched in the knowledge graph and traversed to related documents, which pre-filter the vector search. Requires Neo4j; when it is unavailable retrieval proceeds normally.

Knowledge endpoints are rate-limited per organization (default 120 requests/minute, 5,000/day) and every ingest/search/answer call is metered. Exceeding a window returns 429 Too Many Requests with a Retry-After hint.

Streaming answers (WebSocket)

For token-by-token answers, connect a Socket.IO client to the /knowledge namespace at path /api/socket.io, authenticating with your JWT via auth: { token }. Emit answer:stream with { knowledgeBaseId, query } and receive answer:token events as the answer streams, then a final answer:done (citations, confidence, model) — or answer:error.

import { io } from 'socket.io-client';

const socket = io('https://railai.cloud/knowledge', {
  path: '/api/socket.io',
  auth: { token: RAILAI_JWT },
  transports: ['websocket'],
});

socket.emit('answer:stream', { knowledgeBaseId: 'KB_ID', query: 'How do we onboard?' });
socket.on('answer:token', ({ token }) => process.stdout.write(token));
socket.on('answer:done', ({ citations, confidence, model }) => socket.disconnect());
socket.on('answer:error', ({ message }) => console.error(message));

Rate limits

Each API key carries a per-minute and per-day request limit. When a window is exceeded the request is rejected with 429 Too Many Requests and a retry-after hint; rejected calls are not metered against usage. New keys default to 60 req/min and 1,000 req/day.

Errors

RailAI uses conventional HTTP status codes. 2xx for success, 4xx for client errors, 5xx for server errors.

Webhooks

RailAI receives provider webhooks for commerce and marketplace integrations — Stripe, Shopify, and WooCommerce — at signature-verified endpoints. These are configured per connection inside the app (Commerce & Marketplace settings), not called directly.

Outbound event subscriptions (so your systems can react to scores and campaign matches) are on the roadmap.

SDKs

There is no official SDK yet — the API is plain JSON over HTTPS, so any HTTP client works. Official libraries are on the roadmap.

const res = await fetch(
  "https://railai.cloud/api/v1/api-economy/scores/content",
  {
    method: "POST",
    headers: {
      "x-api-key": process.env.RAILAI_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      platform: "tiktok",
      contentType: "short_video",
      title: "POV: you automated your funnel",
    }),
  },
);
const { viralScore } = await res.json();