Skip to main content
This page lists the customer-facing REST API. For internal admin endpoints, see the platform’s MIGRATION_RUNBOOK.md. The MCP server (@rayify-ai/mcp) is a higher-level slim-8 surface layered over these endpoints.
Auto-generated OpenAPI: a full openapi.json will be generated from the platform backend once the v2 spec stabilizes. Until then, this page lists the customer-facing endpoints by hand.

Base URL

Override with RAYIFY_API_URL for self-hosted / staging.

Authentication

All endpoints require a Bearer token:
Provision keys via Settings → API Keys on rayify.ai. Per-user keys are recommended - actions are recorded under the key’s owner in the audit log.

Projects

List projects

Query params: status (active / completed / archived), kind (research / survey / audience / simulation), limit (default 50, max 200).

Get a project

Returns the full project state: questions, agent reasonings, DecisionPacket, status. Use this when you need to drag full context into your AI client.

Get project status (lightweight)

Returns { id, status, last_updated_at, question_count, reasoning_count }. Use this for polling without the body weight of full state.

Create a research project

The brief should be 50-2000 chars. audience tunes the Reasoning fleet’s specialist composition.

Create a survey

questions accepts string arrays only. For richer question types (matrix / likert / star_rating), use the web app.

Questions

Add a question

CP1 (Defender checkpoint 1) validates the question shape at submit time per the framing-rules registry. Invalid shapes return 400 with a structured error.

Sources

Attach a source

Sources are pulled into the project’s evidence pack and made available to the Reasoning fleet.

Findings

Search findings

Semantic search across the workspace’s project corpus. Returns ranked findings with citation provenance.

Error responses

All endpoints return JSON errors:
Status codes:
  • 400 - validation error
  • 401 - missing / invalid API key
  • 403 - insufficient permissions (admin route, wrong workspace)
  • 404 - resource not found
  • 429 - rate limited
  • 500 - platform error (report to support@rayify.ai)

Rate limits

Default: 100 requests/minute per API key. Enterprise tier raises this. 429 responses include a Retry-After header.

Webhooks

Webhook configuration lives on the web app: Settings → Webhooks. Subscribed events include project.created / project.completed / decision_packet.published. Payloads are signed with HMAC-SHA256; verify against the secret you provisioned at subscription time.

What’s next

  • SDK Setup - Python + TypeScript wrappers over this API
  • MCP Setup - slim-8 surface for AI clients