REST API overview

The Raytha REST API lets a script, a static site generator or another application read and manage everything the admin can: content items, content types, media, users, templates, themes, menus and functions. This page shows the first call, the URL layout and the conventions every endpoint shares.

Make your first call

Create an API key as described in Authentication, then call the Ping endpoint. It returns the version and the site name when the URL and key are right.

export RAYTHA_URL="https://example.com"
export RAYTHA_API_KEY="your-api-key"

curl -s "$RAYTHA_URL/raytha/api/v1/Ping" \
  -H "X-API-KEY: $RAYTHA_API_KEY"

A successful response looks like this:

{
  "success": true,
  "version": "2.0.0",
  "organizationName": "Example Site"
}

Now list the first page of a content type. Replace posts with the developer name of one of yours.

curl -s "$RAYTHA_URL/raytha/api/v1/ContentItems/posts?pageSize=2" \
  -H "X-API-KEY: $RAYTHA_API_KEY" | jq '.result.items[] | {id, primaryField, routePath, isPublished}'

URLs and tools

URL	What it is
/raytha/api/v1/{Resource}	All v1 endpoints. The resource name is the controller name, such as ContentItems or MediaItems.
/raytha/api	Interactive reference (Scalar). Open it in a browser to see every endpoint and body schema on your own version.
/raytha/api/v1/swagger.json	The OpenAPI document. Use it to generate a client.

If you run Raytha under a path prefix, put the prefix before /raytha. See Running behind a proxy.

Resources

Resource	Use it to	Permission the key needs
ContentItems	List, read, create, edit, unpublish, trash and restore items. Batch create. Look up an item by route path.	Read, edit or config on the content type
ContentTypes	Create, delete, export and import content types and whole schemas.	content_types
contenttypes/{type}/fields, …/views	Edit one content type's fields and views.	Config on that content type
MediaItems	Upload, list, delete and resolve files.	media_items to list and delete, upload permission to upload
SitePages	Create and edit site pages and their widgets.	site_pages
Themes, WebTemplates, WidgetTemplates	Read and change themes and templates.	templates
Menus	Edit navigation menus and menu items.	content_types
Users, UserGroups	Manage public users and groups.	users
Functions	Create and revise Raytha Functions.	system_settings
BackgroundTasks	Poll a long-running job, such as a batch create.	Any admin key
Ping	Check the URL and the key.	Any admin key

This documentation covers content items, media, filtering and errors in detail. The other groups follow the same conventions, and their bodies are in the interactive reference.

Conventions

• JSON in, JSON out. Send Content-Type: application/json with a body. Property names are camelCase.
• Envelope. Most responses are {"result": …, "error": "", "success": true}. A list result is {"items": […], "totalCount": 42}. Commands such as create and edit return the id of the item as result.
• Ids are 22-character strings such as h5anxM6u4UW80v09zzQjXg. Pass them as-is in URLs and bodies. A malformed id returns 422.
• Dates are ISO 8601 in UTC, for example 2026-01-14T09:30:00Z.
• Paging uses pageNumber (from 1) and pageSize (default 50). totalCount is the number of matches, not the size of the page.
• Status codes. 200 for reads and edits, 201 for a create, 202 for a batch that runs in the background, 400 and 422 for bad input, 401 for key and permission problems, 404 when something does not exist. See Errors.
• Media URLs in responses are absolute, built from the Website URL setting of your site.

Gotchas

• Call the API from a server, not from a browser page. Raytha sends no CORS headers for the API, and an API key in page source is public. Fetch at build time or from a backend.
• The key acts as an administrator. It has every permission its admin has. Create a dedicated admin with a narrow role for each integration.
• Lists include drafts and unpublished items. Add IsPublished eq 'true' to the filter when you build a public site. See Filtering.
• Field values come back wrapped. A text field is {"value": "Hello", "text": "Hello", "hasValue": true}. Requests take plain values. See Content items.
• No rate limit on v1. Raytha limits only sign-in paths. If your host or proxy enforces limits, back off when it answers 429.

Next steps

• Authentication: create a key and understand what it can do.
• Content items: create, read, edit and delete.
• Recipes: pagination, static builds and uploads.
• Raytha Functions: run server-side JavaScript on your site instead.