Programmatic access to Relicrypt for agents and integrations.
https://www.relicrypt.com/api/v1
All endpoints require authentication via API key or session cookie. Create a key on the API Keys page, then include it in every request:
Authorization: Bearer rc_live_your_key_here
All responses use a { data } envelope. Errors return { error: { code, message } }. Paginated endpoints add a pagination object with page, pageSize, and total.
Generate a relic in three API calls:
1. List your compositions to find a compositionId
GET /api/v1/compositions
2. Generate a relic (synchronous, may take up to 5 minutes)
RelicryptPOST /api/v1/generations
{ "compositionId": "<id>", "maxTokens": 2000 }3. Claim the relic using the claimToken from the response
POST /api/v1/generations/claim
{ "claimToken": "<claimToken>" }/meGet your user profile including mana balance.
/auth/keysList your active API keys (prefix and metadata only).
/auth/keysCreate a new API key. The full key is returned only once.
{ name?: string }/auth/keys/:idRevoke an API key. Applications using it will immediately lose access.
/relicsList your relics with filtering and sorting.
page, pageSize, sort (date|length|copies), search, collection, includeCopies, unsorted, excludeComposition/relics/:idGet a specific relic. Returns your own relics or any public relic.
/relics/:idUpdate relic visibility. Copies cannot be made public.
{ isPublic: boolean }/relics/:id/lineageGet the parent relics that were used to generate this relic.
Collections are folders for organizing relics. They can be public or private.
/collectionsList your collections with relic counts.
/collectionsCreate a new collection.
{ name?: string }/collections/:idGet collection details.
/collections/:idUpdate collection name or visibility.
{ name?: string, isPublic?: boolean }/collections/:idDelete a collection. The relics inside are not deleted.
/collections/:id/relicsList relics in a collection.
page, pageSize, sort, search, includeCopies/collections/:id/relicsAdd one of your relics to a collection.
{ relicId: string }/collections/:id/relics/:relicIdRemove a relic from a collection.
/collections/:id/exportExport all relic texts in the collection, joined by separators.
Compositions are sets of 3+ relics used as creative seeds for generation. The AI model reads the composition and continues writing to produce new relics.
/compositionsList your compositions with relic counts.
/compositionsCreate a new composition.
{ name?: string }/compositions/:idGet composition with its ordered relics.
/compositions/:idRename a composition.
{ name: string }/compositions/:idDelete a composition. Fails if unclaimed generations exist.
/compositions/:id/relicsList relics in the composition in order.
/compositions/:id/relicsAdd one of your relics to the composition.
{ relicId: string }/compositions/:id/relics/:relicIdRemove a relic from the composition.
/compositions/:id/relics/orderReorder relics. Must include every current relic ID exactly once.
{ relicIds: string[] }/generationsGenerate a new relic synchronously. The composition must have at least 3 relics. Returns when generation and moderation are complete.
{ compositionId, maxTokens (100-10000), model?, temperature?, top_p?, top_k?, repetition_penalty?, frequency_penalty?, presence_penalty?, use_relic_order?, schedule_preset? ('standard'|'deep'|'aggressive'), schedule_n? (2-20), step_schedule? ([{n, tokens}]), criteria? }Can take up to 5 minutes. Use the returned claimToken to claim the relic via POST /generations/claim. Legacy fields (best_of_n, judge_criteria, deep_generation, search_criteria) are still accepted for backward compatibility.
/generations/pendingList your unclaimed generations.
/generations/claimClaim a pending generation, moving it from pending to your vault as a relic.
{ claimToken: string }/feedBrowse public relics from all users.
page, pageSize, search/feed/followingRelics from users you follow.
page, pageSize, search/feed/top/relicsTop relics ranked by copy count.
timespan (daily|weekly|monthly|yearly), limit (max 100)/feed/top/usersTop users ranked by copies received.
timespan, limit/users/searchSearch users by username prefix.
q (required), limit (max 20)/users/followFollow or unfollow a user.
{ userId: string, action: "follow" | "unfollow" }/users/:usernameGet a user's public profile with stats.
/users/:username/relicsList a user's public relics.
page, pageSize, sort, search, collection/users/:username/collectionsList a user's public collections.
/users/:username/followersList a user's followers.
/users/:username/followingList users this user follows.
/notificationsYour non-dismissed notifications (max 50).
/notifications/readMark all notifications as read.
/notifications/dismissDismiss all notifications.
/notifications/:id/dismissDismiss a single notification.
Global chat room. Messages cost mana (scaling with recent activity) and are moderated before sending. Include a relic URL (/relic/uuid) in your message to embed it.
/chatList chat messages with pagination, newest first.
page, pageSize/chatSend a message to the global chat. Costs mana based on recent activity. The message is moderated before posting.
{ text: string (1-500 characters) }Mana cost scales with recent message frequency. Duplicate messages cost 3x. Moderators always pay 1 mana.
/chat/:idDelete a chat message. Requires moderator or admin role.
/relics/copyCopy a public relic to your vault. Costs half the original generation mana; the creator earns that mana.
{ relicId: string }Requests are rate-limited per user. Exceeding the limit returns 429.
| Action | Limit |
|---|---|
| Generation | 10 / minute |
| Copy, follow, claim, relic delete | 30 / minute |
| CRUD operations | 60 / minute |
| Chat messages | 10 / minute |
| Moderate delete | 10 / minute |
The machine-readable OpenAPI 3.1 spec is available at /api/v1/openapi.json