API Reference
You can download your own API reference by going to your instance's host and accessing it via /docs/openapi/json . example: https://canary.novel.dev/docs/openapi/json
Auth
Callback called by an authentication strategy available to the application.
Authentication successful. Redirecting to next step...
GET /auth/{strategy}/callback HTTP/1.1
Host:
Accept: */*
Authentication successful. Redirecting to next step...
No content
Start a reset password attempt.
Forget password attempt created.
POST /auth/forgot HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 26
{
"email": "[email protected]"
}Forget password attempt created.
No content
Proceed to the application after a successful MFA attempt.
Authentication successful. Redirecting to next step...
POST /auth/{strategy}/mfa HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 14
{
"otp": "text"
}Authentication successful. Redirecting to next step...
No content
Authenticate by passwordless strategy available to the application.
Authentication successful. Redirecting to next step...
GET /auth/passwordless/verify HTTP/1.1
Host:
Accept: */*
Authentication successful. Redirecting to next step...
No content
Create a payment intent to be used for upfront payment collection.
POST /signup/intent HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 31
{
"plan": "text",
"org_id": "text"
}Payment intent creation successful.
{
"intent": {
"client_secret": "text"
}
}Final step in resetting a user's password.
POST /auth/reset HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 59
{
"email": "[email protected]",
"password": "text",
"token": "text"
}Reset successful. Redirecting to next step...
{
"redirect_to": "text"
}Start the sign up process.
POST /signup HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 134
{
"email": "[email protected]",
"password": "text",
"intent": "text",
"interval": "month",
"plan": "text",
"method": "text",
"invitation_code": "text"
}Sign up successful. Redirecting to next step...
{
"redirect_to": "text"
}Authenticate by strategy available to the application.
POST /auth/{strategy} HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 44
{
"email": "[email protected]",
"password": "text"
}{
"redirect_to": "text"
}Authenticate by strategy available to the application.
GET /auth/{strategy} HTTP/1.1
Host:
Accept: */*
{
"redirect_to": "text"
}Application
List the plans available to a user.
GET /api/v1/plans HTTP/1.1
Host:
Accept: */*
Default Response
{
"plans": [
{
"id": "text",
"name": "text",
"monthly": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"yearly": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"trial": 1
}
]
}Get the important details required when accessing an authenticated screen.
GET /api/v1/session HTTP/1.1
Host:
Accept: */*
Default Response
{
"session": {
"live": true,
"flags": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"organizations": [
{
"id": "text",
"name": "text",
"type": "text"
}
],
"organization": {
"id": "text",
"name": "text",
"type": "text"
},
"subscribed": true,
"subscription": {
"name": "text",
"status": "text",
"subscription_id": "text"
},
"user": {
"id": "text",
"email": "[email protected]",
"display_name": "text",
"picture": "text"
},
"settings": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"role": "text",
"permissions": [
{
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"version": "text",
"fetched": "2025-07-30T10:28:23.714Z"
}
}Switch organization of the current session.
Switched organization successfully.
POST /api/v1/session/switch HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 17
{
"org_id": "text"
}Switched organization successfully.
No content
Accounts
Search list of events relate to user actions triggered by logger.account or a record in the AccountEvents model.
GET /api/v1/account/events HTTP/1.1
Host:
Accept: */*
Default Response
{
"events": [
{
"required": null,
"subscription_id": "text",
"metric": "text",
"value": 1,
"timestamp": "2025-07-30T10:28:23.714Z",
"reported_at": "2025-07-30T10:28:23.714Z"
}
]
}Returns the available profile data for the currently logged in user.
GET /api/v1/account HTTP/1.1
Host:
Accept: */*
Default Response
{
"profile": {
"id": "text",
"email": "[email protected]",
"display_name": "text",
"picture": "https://example.com",
"url": "https://example.com",
"verified": true,
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
},
"settings": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}Update the currently logged in account's profile.
User profile updated successfully.
PATCH /api/v1/account HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 83
{
"display_name": "text",
"picture": "https://example.com",
"url": "https://example.com"
}User profile updated successfully.
No content
Returns the available security data for the currently logged in user.
GET /api/v1/account/security HTTP/1.1
Host:
Accept: */*
Default Response
{
"profile": {
"id": "text",
"email": "[email protected]",
"password": true,
"verified": true,
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
},
"mfa": null,
"sessions": [
{
"ANY_ADDITIONAL_PROPERTY": "anything"
}
]
}Revoke a session related to the currently logged in user.
Session revoked successfully.
DELETE /api/v1/account/sessions HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 21
{
"session_id": "text"
}Session revoked successfully.
No content
Update the currently logged in account's settings.
User configuration updated successfully.
PATCH /api/v1/account/settings HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 87
{
"theme": "text",
"timezone": "text",
"language": "text",
"marketing": true,
"newsletter": true
}User configuration updated successfully.
No content
Update the currently logged in account's password.
User password updated successfully.
POST /api/v1/account/password HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 41
{
"password": "text",
"new_password": "text"
}User password updated successfully.
No content
Deactivate an active account.
Account has been deactivated.
POST /api/v1/account/deactivate HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 24
{
"sudo_password": "text"
}Account has been deactivated.
No content
Generates a QR and a secret that can be used by the user to register an authenticator.
GET /api/v1/account/mfa HTTP/1.1
Host:
Accept: */*
Default Response
{
"mfa": {
"qr": "text",
"secret": "text",
"remaining": 1,
"expires_at": "2025-07-30T10:28:23.714Z"
}
}Attach a TOTP secret to a user for use with MFA during login.
MFA secret registered successfully.
PUT /api/v1/account/mfa HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 32
{
"token": "text",
"secret": "text"
}MFA secret registered successfully.
No content
Revoke registered secret so a user can register a new one. It is possible to register and overwrite an existing mfa secret.
MFA secret revoked successfully.
DELETE /api/v1/account/mfa HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 24
{
"sudo_password": "text"
}MFA secret revoked successfully.
No content
Organizations
Details of the organization.
GET /api/v1/organization HTTP/1.1
Host:
Accept: */*
Default Response
{
"organization": {
"id": "text",
"name": "text",
"type": "text",
"email": "[email protected]",
"quotas": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"settings": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
}Deactivate an organization tied to the currently logged in session.
Organization has been deactivated.
DELETE /api/v1/organization HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 40
{
"sudo_password": "text",
"org_id": "text"
}Organization has been deactivated.
No content
Create a new organization tied to the user making the request.
POST /api/v1/organization HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 56
{
"name": "text",
"email": "[email protected]",
"personal": true
}Organization has been created.
{
"id": "text"
}Update the detail of the current organization.
Updated organization successfully.
PATCH /api/v1/organization HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 40
{
"name": "text",
"email": "[email protected]"
}Updated organization successfully.
No content
Events that have happened within the organization.
GET /api/v1/organization/events HTTP/1.1
Host:
Accept: */*
Default Response
{
"events": [
{
"request_id": "text",
"event_id": "text",
"timestamp": "text",
"action": "text",
"message": "text",
"context": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
]
}Invite a particular user/email to the organization.
Invite sent successfully.
POST /api/v1/organization/invite HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 57
{
"invites": [
{
"email": "[email protected]",
"roles": [
"text"
]
}
]
}Invite sent successfully.
No content
Revoke the invitation sent by the currently logged in user from an organization.
Invitations revoked successfully.
DELETE /api/v1/organization/invite HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 40
{
"invites": [
{
"email": "[email protected]"
}
]
}Invitations revoked successfully.
No content
Accept an invitation coming from an organization.
Invite accepted successfully.
POST /api/v1/organization/invite/accept HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 26
{
"invitation_code": "text"
}Invite accepted successfully.
No content
Reject an invitation coming from an organization.
Invite rejected successfully.
DELETE /api/v1/organization/invite/reject HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 26
{
"invitation_code": "text"
}Invite rejected successfully.
No content
List of organizations belonging to the currently logged in user.
GET /api/v1/organizations HTTP/1.1
Host:
Accept: */*
Default Response
{
"organizations": [
{
"id": "text",
"name": "text",
"type": "text",
"email": "[email protected]"
}
]
}List the members of the current organization in the session.
GET /api/v1/organization/members HTTP/1.1
Host:
Accept: */*
Default Response
{
"members": [
{
"id": "text",
"role": "text",
"email": "[email protected]",
"display_name": "text",
"picture": "text",
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"status": "text",
"mfa": true
}
]
}Remove a member of an organization.
Member removed successfully.
DELETE /api/v1/organization/members HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 21
{
"account_id": "text"
}Member removed successfully.
No content
Promote a member of an organization.
Member promoted successfully.
POST /api/v1/organization/promote HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 38
{
"account_id": "text",
"roles": [
"text"
]
}Member promoted successfully.
No content
Subscription
Return the current subscription the organization has active at the time of request.
GET /api/v1/subscription HTTP/1.1
Host:
Accept: */*
Default Response
{
"subscribed": true,
"organization": {
"id": "text",
"name": "text",
"type": "text",
"email": "[email protected]"
},
"subscription": null,
"quotas": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"payment_methods": [
{
"id": "text",
"type": "text",
"card": {
"brand": "text",
"last4": "text",
"expiry_month": "text",
"expiry_year": "text"
}
}
],
"charges": [
{
"number": "text",
"invoice": "text",
"invoice_pdf": "text",
"status": "text",
"amount": "text",
"currency": "text",
"payment_method": "text",
"email": "[email protected]",
"paid_at": "2025-07-30T10:28:23.714Z"
}
]
}Cancel the subscription currently applied to the organization.
Subscription cancelled successfully.
POST /api/v1/subscription/cancel HTTP/1.1
Host:
Accept: */*
Subscription cancelled successfully.
No content
Return the payment methods available to the organization has active at the time of request.
GET /api/v1/subscription/cards HTTP/1.1
Host:
Accept: */*
Default Response
{
"payment_methods": [
{
"id": "text",
"type": "text",
"card": {
"brand": "text",
"last4": "text",
"expiry_month": "text",
"expiry_year": "text"
}
}
]
}Add the payment method related to a user.
Payment method added successfully.
POST /api/v1/subscription/methods HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 47
{
"payment_method": "text",
"setup_intent": "text"
}Payment method added successfully.
No content
Remove the payment method related to a user.
Payment method removed successfully.
DELETE /api/v1/subscription/methods HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 28
{
"payment_method_id": "text"
}Payment method removed successfully.
No content
Subscribe to an available plan.
Subscription created successfully.
POST /api/v1/subscription/upgrade HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 65
{
"plan": "text",
"intent": "text",
"method": "text",
"interval": "text"
}Subscription created successfully.
No content
API Keys
Revoke the api key related to the currently logged in user.
API key revoked successfully.
DELETE /api/v1/api-keys HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 20
{
"access_id": "text"
}API key revoked successfully.
No content
List the keys available to the currently logged in session.
GET /api/v1/api-keys HTTP/1.1
Host:
Accept: */*
Default Response
{
"keys": [
{
"access_id": "text",
"secret_key": "text",
"label": "text",
"scope": "text",
"expiry": "text",
"expired": true,
"created_at": "text",
"expires_at": "text",
"last_used": "text"
}
]
}Generate an API key attached to the currently logged in user.
POST /api/v1/api-keys HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 79
{
"label": "text",
"scope": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"expiry": "text"
}Key generated successfully.
{
"key": {
"access_id": "text",
"secret_key": "text",
"label": "text",
"scope": "text",
"expiry": "text",
"expired": true,
"created_at": "text",
"expires_at": "text",
"last_used": "text"
}
}List the events related to a key.
GET /api/v1/api-keys/events HTTP/1.1
Host:
Accept: */*
Default Response
{
"events": [
{
"request_id": "text",
"access_id": "text",
"timestamp": "text",
"method": "text",
"url": "text",
"status": "text",
"ip": "text",
"origin": "text"
}
]
}Files
Presign the file to be used and return a signed url.
PUT /api/v1/files/presign HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 28
{
"key": "text",
"type": "text"
}Pre signed URL
{
"file": {
"presigned_url": "text",
"public": true,
"type": "text",
"original": "text",
"key": "text",
"asset_url": "text"
}
}If using local driver for file system. Accept file uploads.
File has been uploaded successfully.
PUT /files{*} HTTP/1.1
Host:
Content-Type: multipart/form-data
Accept: */*
Content-Length: 8
"binary"File has been uploaded successfully.
No content
Notifications
Mark notifications as archived.
Notification archived successfully.
POST /api/v1/notifications/archive HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 18
{
"items": [
"text"
]
}Notification archived successfully.
No content
Deregister the push token related to the user.
Token deregistered successfully.
DELETE /api/v1/notifications/register HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 19
{
"endpoint": "text"
}Token deregistered successfully.
No content
Register the push token related to the user.
Push token registered successfully.
POST /api/v1/notifications/register HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 46
{
"endpoint": "text",
"auth": "text",
"key": "text"
}Push token registered successfully.
No content
List all notifications available to the currently logged in user.
GET /api/v1/notifications HTTP/1.1
Host:
Accept: */*
Default Response
{
"notifications": [
{
"id": "text",
"author_id": "text",
"received_at": "text",
"read": true,
"title": "text",
"body": "text",
"icon": "text",
"level": "text",
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
],
"invites": [
{
"invitation_code": "text",
"organization": {
"id": "text",
"name": "text"
},
"created_at": "text",
"expires_at": "text",
"expired": true
}
]
}Mark notifications as read.
Notification marked as read successfully.
POST /api/v1/notifications/read HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 18
{
"items": [
"text"
]
}Notification marked as read successfully.
No content
Changelog
2024-12-20 - Initial Documentation
Last updated
Was this helpful?