QR Platform API V1
Interactive API Reference and Code Playground https://api.qr-platform.com/v1/docs
Version 0.1.0
Endpoints by Category
Auth
| Method | Path | Description | |
|---|---|---|---|
| POST | /auth/register | Register New User | |
| POST | /auth/register-verify | Verify Registration Code or Token | |
| POST | /auth/register-verify-resend | Resend Registration Verification Code and Token | |
| POST | /auth/sign-in | Sign In User | |
| POST | /auth/sign-in-verify | Verify Sign In Code or Token | |
| POST | /auth/email-verify-send | Send Email Verification Code and Token | |
| POST | /auth/email-verify | Verify Email Address | |
| GET | /auth/me | Get Current User | |
| GET | /auth/sign-out | Sign Out User |
Password Management
| Method | Path | Description | |
|---|---|---|---|
| POST | /auth/password/reset | Request Password Reset | |
| POST | /auth/password/reset-verify | Verify Password Reset | |
| POST | /auth/password/change | Change Password |
API Keys
| Method | Path | Description | |
|---|---|---|---|
| POST | /api-keys | Create API key | |
| GET | /api-keys | List API keys | |
| GET | /api-keys/{apiKeyId} | Get API key details | |
| PUT | /api-keys/{apiKeyId} | Update API key | |
| DELETE | /api-keys/{apiKeyId} | Delete API key | |
| PUT | /api-keys/{apiKeyId}/status | Change API key status |
Organizations
| Method | Path | Description | |
|---|---|---|---|
| GET | /orgs/current | Get current organization | |
| PUT | /orgs | Update current organization | |
| POST | /orgs/first | Create first organization | |
| POST | /orgs/current/{orgId} | Switch current organization |
Invitations
| Method | Path | Description | |
|---|---|---|---|
| POST | /invites | Create invitation | |
| GET | /invites | List organization invitations | |
| GET | /invites/me | List my invitations | |
| DELETE | /invites/{invitationId} | Delete invitation | |
| GET | /invites/{token}/accept | Accept invitation | |
| GET | /invites/{token}/decline | Decline invitation |
Members
| Method | Path | Description | |
|---|---|---|---|
| POST | /members | Add a member to organization | |
| GET | /members | List organization members | |
| DELETE | /members/{userId} | Remove member from organization | |
| GET | /members/{userId}/roles | Get member roles | |
| POST | /members/{userId}/role | Add role to member | |
| DELETE | /members/{userId}/role/{roleName} | Remove role from member |
Workspaces
| Method | Path | Description | |
|---|---|---|---|
| POST | /workspaces | Create a new workspace | |
| GET | /workspaces | List workspaces | |
| GET | /workspaces/{workspaceId} | Get workspace by ID | |
| PUT | /workspaces/{workspaceId} | Update workspace | |
| DELETE | /workspaces/{workspaceId} | Delete workspace | |
| GET | /workspaces/{workspaceId}/members/{userId}/role | Get user roles in workspace | |
| POST | /workspaces/{workspaceId}/members/{userId}/role | Add role to workspace member | |
| DELETE | /workspaces/{workspaceId}/members/{userId}/role | Remove role from workspace member | |
| GET | /workspaces/{workspaceId}/members | List workspace members |
Roles
| Method | Path | Description | |
|---|---|---|---|
| GET | /roles | List all roles |
Plans
| Method | Path | Description | |
|---|---|---|---|
| GET | /plans | List available plans | |
| GET | /plans/current | Get current plan |
Settings
| Method | Path | Description | |
|---|---|---|---|
| GET | /settings | Get all organization settings | |
| GET | /settings/custom | Get all custom settings | |
| POST | /settings/custom | Create custom setting | |
| GET | /settings/custom/{settingSlug} | Get custom setting by slug | |
| PUT | /settings/custom/{settingSlug} | Update custom setting | |
| DELETE | /settings/custom/{settingSlug} | Delete custom setting | |
| GET | /settings/custom/{settingSlug}/value | Get custom setting value | |
| GET | /settings/service | Get all service settings | |
| GET | /settings/service/{settingSlug} | Get service setting by slug | |
| PUT | /settings/service/{settingSlug} | Upsert service setting | |
| GET | /settings/service/{settingSlug}/value | Get service setting value |
Workspace Settings
QR Code Scans
| Method | Path | Description | |
|---|---|---|---|
| GET | /codes/{codeId}/scans | List QR Code Scans |
QR Code Router Rules
| Method | Path | Description | |
|---|---|---|---|
| GET | /codes/{codeId}/router-rules | List Router Rule Assignments | |
| POST | /codes/{codeId}/router-rules | Create Router Rule Assignment | |
| GET | /codes/{codeId}/router-rules/{routerRuleId} | Get Router Rule Assignment | |
| PUT | /codes/{codeId}/router-rules/{routerRuleId} | Update Router Rule Assignment | |
| DELETE | /codes/{codeId}/router-rules/{routerRuleId} | Delete Router Rule Assignment | |
| GET | /router-rules | List Organization Router Rules | |
| GET | /workspaces/{workspaceId}/router-rules | List Workspace Router Rule Assignments |
QR Codes
| Method | Path | Description | |
|---|---|---|---|
| GET | /codes/deleted | List Soft Deleted QR Codes | |
| GET | /codes/{codeId} | Get QR Code | |
| PUT | /codes/{codeId} | Update QR Code | |
| DELETE | /codes/{codeId} | Soft Delete QR Code | |
| GET | /codes | List QR Codes | |
| POST | /codes | Create QR Code | |
| DELETE | /codes | Bulk Soft Delete QR Codes | |
| PUT | /codes/{codeId}/options | Partially update QR Code Options | |
| DELETE | /codes/permanent | Bulk Permanent Delete QR Codes | |
| DELETE | /codes/{codeId}/permanent | Delete QR Code | |
| POST | /codes/{codeId}/restore | Restore QR Code | |
| POST | /codes/validate | Validate QR Code Options | |
| POST | /codes/{codeId}/validate | Validate Existing QR Code | |
| POST | /codes/links/refresh | Bulk Refresh QR Code Links |
QR Code Links
| Method | Path | Description | |
|---|---|---|---|
| GET | /codes/links | List QR Code Links | |
| POST | /codes/generate/{type} | Generate QR Code File Content | |
| GET | /codes/{codeId}/version/{version}/{type} | Get QR Code Version File Content | |
| GET | /codes/{codeId}/version/{version}/{type}/link | Get QR Code Version Link | |
| DELETE | /codes/{codeId}/versions/{version}/links | Delete QR Code version links | |
| DELETE | /codes/{codeId}/versions/{version}/links/{type} | Delete QR Code version link by Type | |
| DELETE | /codes/{codeId}/versions/links | Delete All QR Code Versions Links | |
| DELETE | /codes/{codeId}/versions/links/{type} | Delete All QR Code Versions Links by Type | |
| GET | /codes/{codeId}/{type} | Get QR Code File Content (SVG, PNG, PDF) | |
| GET | /codes/{codeId}/{type}/link | Get QR Code link | |
| DELETE | /codes/{codeId}/links | Delete QR Code links | |
| DELETE | /codes/{codeId}/links/{type} | Delete QR Code link by Type |
QR Code Versions
| Method | Path | Description | |
|---|---|---|---|
| GET | /codes/{codeId}/version/{version} | Get QR Code version | |
| GET | /codes/{codeId}/versions | List QR Code versions | |
| DELETE | /codes/{codeId}/versions | Delete All QR Code Versions | |
| POST | /codes/{codeId}/version/{version}/restore | Restore QR Code Version |
Templates
| Method | Path | Description | |
|---|---|---|---|
| POST | /templates | Create a new template | |
| GET | /templates | List all templates | |
| GET | /templates/base | List base templates | |
| GET | /templates/{templateId} | Get template by ID | |
| PUT | /templates/{templateId} | Update template by ID | |
| DELETE | /templates/{templateId} | Delete template by ID | |
| PUT | /templates/{templateId}/options | Partially update template options by ID | |
| GET | /templates/workspace/{workspaceId} | List templates for a workspace |
Styles
| Method | Path | Description | |
|---|---|---|---|
| POST | /styles | Create a new style | |
| GET | /styles | List all styles | |
| GET | /styles/base | List base styles | |
| GET | /styles/{styleId} | Get style by ID | |
| PUT | /styles/{styleId} | Update style by ID | |
| DELETE | /styles/{styleId} | Delete style by ID | |
| PUT | /styles/{styleId}/options | Partially update style options by ID | |
| GET | /styles/workspace/{workspaceId} | List styles for a workspace |
Texts
| Method | Path | Description | |
|---|---|---|---|
| POST | /texts | Create a new text | |
| GET | /texts | List all texts | |
| GET | /texts/base | List base texts | |
| GET | /texts/{textId} | Get text by ID | |
| PUT | /texts/{textId} | Update text by ID | |
| DELETE | /texts/{textId} | Delete text by ID | |
| PUT | /texts/{textId}/options | Partially update text options by ID | |
| GET | /texts/workspace/{workspaceId} | List texts for a workspace |
Borders
| Method | Path | Description | |
|---|---|---|---|
| POST | /borders | Create a new border | |
| GET | /borders | List all borders | |
| GET | /borders/base | List base borders | |
| GET | /borders/{borderId} | Get border by ID | |
| PUT | /borders/{borderId} | Update border by ID | |
| DELETE | /borders/{borderId} | Delete border by ID | |
| PUT | /borders/{borderId}/options | Partially update border options by ID | |
| GET | /borders/workspace/{workspaceId} | List borders for a workspace |
Country Codes
| Method | Path | Description | |
|---|---|---|---|
| GET | /country-codes | List All Country Codes |
Router Rule Templates
| Method | Path | Description | |
|---|---|---|---|
| POST | /router-rule-templates | Create Router Rule Template | |
| GET | /router-rule-templates | List Router Rule Templates | |
| GET | /router-rule-templates/{routerRuleTemplateId} | Get Router Rule Template | |
| PUT | /router-rule-templates/{routerRuleTemplateId} | Update Router Rule Template | |
| DELETE | /router-rule-templates/{routerRuleTemplateId} | Delete Router Rule Template | |
| POST | /workspaces/{workspaceId}/router-rule-templates | Create Workspace Router Rule Template |
Endpoints Details
Register New User
POST /auth/register
Registers a new user and organization. Sends a verification code and token via email
RequestBody
{
// User email address
email: string
// User password (optional for passwordless)
password?: string
// Name of the initial organization
organizationName?: string
// Description of the organization
organizationDescription?: string
// Redirect URL of the organization
organizationRedirectUrl?: string
}
Responses
- 200 Registration initiated. Check email for verification
{
// Indicates if passwordless registration was used
passwordless?: boolean
// Indicates if a verification email was sent
emailSent?: boolean
// Informational message
message?: string
// ID of the created organization
orgId?: string
// Name of the organization
organizationName?: string
// Redirect URL of the organization
organizationRedirectUrl?: string
// Description of the organization
organizationDescription?: string
}
- 400 Bad Request on registration
// Bad Request on registration
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"EmailAlreadyInUseMessage"},
{"$ref":"EmailSendFailureMessage"},
{"$ref":"OrganizationCreationFailureMessage"}
]
Schemas: ValidationErrorMessage EmailAlreadyInUseMessage EmailSendFailureMessage OrganizationCreationFailureMessage
Verify Registration Code or Token
POST /auth/register-verify
Verifies the 6-digit code or token sent via email after registration
RequestBody
{
// User email address (optional)
email?: string
// 6-digit verification code (for email/MFA)
code?: string
// Verification token (for email links)
token?: string
// User password (if setting during verification)
password?: string
}
Responses
- 200 Registration verification successful
{
// JWT access token upon successful registration verification
access_token?: string
}
- 400 Bad Request on registration verification
// Bad Request on registration verification
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"EmailAlreadyVerifiedMessage"}
]
Schemas: ValidationErrorMessage EmailAlreadyVerifiedMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 404 User or organization not found
// User or organization not found
anyOf: [
{"$ref":"UserNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: UserNotFoundMessage OrganizationNotFoundMessage
Resend Registration Verification Code and Token
POST /auth/register-verify-resend
Resends the 6-digit verification code or token to the user's email.
RequestBody
{
// User email address
email: string
// User password (optional for passwordless)
password?: string
// Name of the initial organization
organizationName?: string
// Description of the organization
organizationDescription?: string
// Redirect URL of the organization
organizationRedirectUrl?: string
}
Responses
- 200 Verification email resent successfully
{
// Indicates if the verification email was resent
emailSent?: boolean
}
- 400 Bad Request on resending registration verification
// Bad Request on resending registration verification
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"InvalidCredentialsForOperationMessage"},
{"$ref":"EmailAlreadyVerifiedMessage"},
{"$ref":"EmailSendFailureMessage"}
]
Schemas: ValidationErrorMessage InvalidCredentialsForOperationMessage EmailAlreadyVerifiedMessage EmailSendFailureMessage
- 404 User or organization not found
// User or organization not found
anyOf: [
{"$ref":"UserNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: UserNotFoundMessage OrganizationNotFoundMessage
Sign In User
POST /auth/sign-in
Initiates user sign-in. Returns an access token if password is provided and correct, otherwise indicates if passwordless verification is needed
RequestBody
{
// User email address
email: string
// User password (optional for passwordless)
password?: string
}
Responses
- 200 Sign-in successful or verification initiated
{
// JWT access token (if password provided)
access_token?: string
// Indicates if passwordless sign-in is required
passwordless?: boolean
// Indicates if a sign-in verification email was sent
emailSent?: boolean
// Details of the organization the user signed into
organization?: {
// Unique identifier for the organization
id: string
// Name of the organization
name?: string
}
}
- 400 Bad Request on sign-in
// Bad Request on sign-in
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"EmailSendFailureMessage"}
]
Schemas: ValidationErrorMessage EmailSendFailureMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 404 User or organization not found
// User or organization not found
anyOf: [
{"$ref":"UserNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: UserNotFoundMessage OrganizationNotFoundMessage
Verify Sign In Code or Token
POST /auth/sign-in-verify
Verifies the 6-digit code or token sent via email for passwordless sign-in
RequestBody
{
// User email address (optional)
email?: string
// 6-digit verification code (for email/MFA)
code?: string
// Verification token (for email links)
token?: string
// User password (if setting during verification)
password?: string
}
Responses
- 200 Sign-in verification successful
{
// JWT access token upon successful sign-in verification
access_token?: string
}
- 400 Bad Request on sign-in verification
// Error response for validation failures
{
message: string
errors?: []
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 404 User or organization not found
// User or organization not found
anyOf: [
{"$ref":"UserNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: UserNotFoundMessage OrganizationNotFoundMessage
Send Email Verification Code and Token
POST /auth/email-verify-send
Sends a verification code and token to the user's email if it's not already verified.
RequestBody
{
// User email address
email: string
// User password (optional for passwordless)
password?: string
// Name of the initial organization
organizationName?: string
// Description of the organization
organizationDescription?: string
// Redirect URL of the organization
organizationRedirectUrl?: string
}
Responses
- 200 Verification email sent successfully
{
// Indicates if the verification email was sent
emailSent?: boolean
}
- 400 Bad Request on sending email verification
// Bad Request on sending email verification
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"InvalidCredentialsForOperationMessage"},
{"$ref":"EmailAlreadyVerifiedMessage"},
{"$ref":"EmailSendFailureMessage"}
]
Schemas: ValidationErrorMessage InvalidCredentialsForOperationMessage EmailAlreadyVerifiedMessage EmailSendFailureMessage
- 404 User or organization not found
// User or organization not found
anyOf: [
{"$ref":"UserNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: UserNotFoundMessage OrganizationNotFoundMessage
Verify Email Address
POST /auth/email-verify
Verifies the user's email address using the provided code or token.
RequestBody
{
// User email address (optional)
email?: string
// 6-digit verification code (for email/MFA)
code?: string
// Verification token (for email links)
token?: string
// User password (if setting during verification)
password?: string
}
Responses
- 200 Email verification successful
{
// Indicates if the email was successfully verified
verified?: boolean
// JWT access token upon successful verification
access_token?: string
}
- 400 Bad Request on email verification
// Bad Request on email verification
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"EmailAlreadyVerifiedMessage"}
]
Schemas: ValidationErrorMessage EmailAlreadyVerifiedMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 404 User or organization not found
// User or organization not found
anyOf: [
{"$ref":"UserNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: UserNotFoundMessage OrganizationNotFoundMessage
Get Current User
GET /auth/me
Retrieves the details of the currently authenticated user
- Security: bearerAuth
Responses
- 200 Successfully retrieved user details
allOf: [
{"$ref":"UserResponseWithAudit"}
]
Schemas: UserResponseWithAudit
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 404 Member not found, Organization context not found, or Member has no organizations.
// Member not found, Organization context not found, or Member has no organizations.
anyOf: [
{"$ref":"UserNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: UserNotFoundMessage OrganizationNotFoundMessage
Sign Out User
GET /auth/sign-out
Signs out the current user by clearing relevant cookies/session data
Responses
- 200 Successfully signed out
{
// Confirmation message
message: string
}
- 400 Bad Request on sign-out
// Error response when the user is not signed in or session has expired
{
message: string
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
Request Password Reset
POST /auth/password/reset
Sends a password reset email with a verification token
RequestBody
{
// User email address
email: string
// User password (required for authentication)
password?: string
}
Responses
- 200 Password reset email sent
{
// Success message
message?: string
}
- 400 Invalid request to reset password.
// Invalid request to reset password.
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"EmailSendFailureMessage"}
]
Schemas: ValidationErrorMessage EmailSendFailureMessage
- 404 User or organization not found
// User or organization not found
anyOf: [
{"$ref":"UserNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: UserNotFoundMessage OrganizationNotFoundMessage
Verify Password Reset
POST /auth/password/reset-verify
Verifies the password reset token and sets a new password
RequestBody
{
// User email address
email: string
// Password reset token received via email
token: string
// New password to set
newPassword: string
}
Responses
- 200 Password reset successful
{
// Success message
message?: string
}
- 400 Invalid request to verify password reset.
// Invalid request to verify password reset.
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"PasswordChangeFailedMessage"}
]
Schemas: ValidationErrorMessage PasswordChangeFailedMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 404 User or organization not found
// User or organization not found
anyOf: [
{"$ref":"UserNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: UserNotFoundMessage OrganizationNotFoundMessage
Change Password
POST /auth/password/change
Changes the password for the authenticated user
- Security: bearerAuth
RequestBody
{
// Current user password
currentPassword: string
// New password to set
newPassword: string
}
Responses
- 200 Password changed successfully
{
// Success message
message?: string
}
- 400 Invalid request to change password.
// Invalid request to change password.
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"PasswordChangeFailedMessage"}
]
Schemas: ValidationErrorMessage PasswordChangeFailedMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 404 User or organization not found
// User or organization not found
anyOf: [
{"$ref":"UserNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: UserNotFoundMessage OrganizationNotFoundMessage
Create API key
POST /api-keys
Creates a new API key for the current organization.
RequestBody
// Data required to create a new API key
{
// Name of the role assigned to this API key
roleName: string
// Duration for which the key is valid (e.g., "30d", "1y")
lifetime?: string
// Descriptive name for the API key
name: string
}
Responses
- 201 API key created successfully
// Response after creating an API key, including the key value
allOf: [
{"$ref":"ApiKeyResponse"}
]
Schemas: ApiKeyResponse
- 400 Bad Request when creating API key
// Bad Request when creating API key
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"ApiKeyNameTakenMessage"},
{"$ref":"InvalidApiKeyRoleMessage"},
{"$ref":"InvalidApiKeyLifetimeFormatMessage"},
{"$ref":"LimitReachedMessage"}
]
Schemas: ValidationErrorMessage ApiKeyNameTakenMessage InvalidApiKeyRoleMessage InvalidApiKeyLifetimeFormatMessage LimitReachedMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization not found.
// Indicates that the organization context was not found or is invalid
{
// The specified organization could not be found or is not accessible
message: string
}
- 409 Conflict
// Conflict response message
{
message: string
}
- 429 You have reached the limit for limit-api-keys. Please upgrade your plan to continue
// Limit reached response message
{
message: string
}
List API keys
GET /api-keys
Retrieves all API keys for the current organization.
Responses
- 200 List of API keys
[]
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization not found or no API keys found for the organization.
// Organization not found or no API keys found for the organization.
anyOf: [
{"$ref":"EmptyArrayResponse"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: EmptyArrayResponse OrganizationNotFoundMessage
Get API key details
GET /api-keys/{apiKeyId}
Retrieves details of a specific API key by its ID.
Responses
- 200 API key details
// API key information with organization details
{
// Unique identifier for the API key
id: string
// ID of the organization this API key belongs to
orgId: string
// Name of the role assigned to this API key
roleName: string
// Descriptive name for the API key
name: string
// Current status of the API key
status: enum[active, deleted, disabled] //default: active
// Timestamp when the API key expires
expiresAt?: string | null
// Organization information
organization: {
// Name of the organization this API key belongs to
name?: string
}
// User who created the resource
createdByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// User who last updated the resource
updatedByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// API key used to create the resource
createdByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// API key used to last update the resource
updatedByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// When the resource was created
createdAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
// When the resource was last updated
updatedAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
}
Schemas: AuditInfoMember AuditInfoApiKey
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 API key not found or its organization not found.
// API key not found or its organization not found.
anyOf: [
{"$ref":"ApiKeyNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: ApiKeyNotFoundMessage OrganizationNotFoundMessage
Update API key
PUT /api-keys/{apiKeyId}
Updates an existing API key by its ID.
RequestBody
// Data for updating an API key
{
// New name for the API key
name: string
// New expiration date for the API key
expiresAt?: string | null
}
Responses
- 200 API key updated successfully
// API key information with organization details
{
// Unique identifier for the API key
id: string
// ID of the organization this API key belongs to
orgId: string
// Name of the role assigned to this API key
roleName: string
// Descriptive name for the API key
name: string
// Current status of the API key
status: enum[active, deleted, disabled] //default: active
// Timestamp when the API key expires
expiresAt?: string | null
// Organization information
organization: {
// Name of the organization this API key belongs to
name?: string
}
// User who created the resource
createdByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// User who last updated the resource
updatedByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// API key used to create the resource
createdByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// API key used to last update the resource
updatedByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// When the resource was created
createdAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
// When the resource was last updated
updatedAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
}
Schemas: AuditInfoMember AuditInfoApiKey
- 400 Bad Request when updating API key
// Bad Request when updating API key
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"ApiKeyNameTakenMessage"}
]
Schemas: ValidationErrorMessage ApiKeyNameTakenMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 API key to update not found or its organization not found.
// API key to update not found or its organization not found.
anyOf: [
{"$ref":"ApiKeyNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: ApiKeyNotFoundMessage OrganizationNotFoundMessage
Delete API key
DELETE /api-keys/{apiKeyId}
Deletes an API key by its ID.
Responses
- 200 API key deleted successfully
// Generic success response
{
// Success message
message: string
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 API key to delete not found or its organization not found.
// API key to delete not found or its organization not found.
anyOf: [
{"$ref":"ApiKeyNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: ApiKeyNotFoundMessage OrganizationNotFoundMessage
Change API key status
PUT /api-keys/{apiKeyId}/status
Changes the status of an API key (activate or disable).
RequestBody
// Data for changing the status of an API key
{
// New status for the API key
status: enum[active, disabled]
}
Responses
- 200 API key status changed successfully
// API key information with organization details
{
// Unique identifier for the API key
id: string
// ID of the organization this API key belongs to
orgId: string
// Name of the role assigned to this API key
roleName: string
// Descriptive name for the API key
name: string
// Current status of the API key
status: enum[active, deleted, disabled] //default: active
// Timestamp when the API key expires
expiresAt?: string | null
// Organization information
organization: {
// Name of the organization this API key belongs to
name?: string
}
// User who created the resource
createdByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// User who last updated the resource
updatedByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// API key used to create the resource
createdByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// API key used to last update the resource
updatedByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// When the resource was created
createdAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
// When the resource was last updated
updatedAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
}
Schemas: AuditInfoMember AuditInfoApiKey
- 400 Bad Request when changing API key status
// Bad Request when changing API key status
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"LimitReachedMessage"}
]
Schemas: ValidationErrorMessage LimitReachedMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 API key to change status not found or its organization not found.
// API key to change status not found or its organization not found.
anyOf: [
{"$ref":"ApiKeyNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: ApiKeyNotFoundMessage OrganizationNotFoundMessage
Get current organization
GET /orgs/current
Retrieves details of the current active organization for the authenticated user.
Responses
- 200 Current organization details
// Organization information with related details
{
// Unique identifier for the organization
id: string
// Name of the organization
name: string
// Current plan of the organization
planName?: string | null
// Description of the organization
description?: string | null
// Redirect URL of the organization
redirectUrl?: string | null
// Whether the organization is disabled
isDisabled?: boolean
// ID of the user or API key that disabled the organization
disabledBy?: string | null
// Timestamp when the organization was disabled
disabledAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
// Whether the organization is deleted
isDeleted?: boolean
// ID of the user or API key that deleted the organization
deletedBy?: string | null
// Timestamp when the organization was deleted
deletedAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
// Whether this is the current active organization for the user
isCurrent?: boolean
roles?: {
// Name of the role
name: string
scopes?: // Scope associated with the role
string[]
}[]
workspaces?: {
// Unique identifier for the workspace
id: string
// Name of the workspace
name: string
// Whether access to this workspace is isRestricted
isRestricted: boolean
roles?: {
// Name of the role
name: string
scopes?: // Scope associated with the role
string[]
}[]
}[]
// User who created the resource
createdByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// User who last updated the resource
updatedByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// API key used to create the resource
createdByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// API key used to last update the resource
updatedByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// When the resource was created
createdAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
// When the resource was last updated
updatedAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
}
Schemas: AuditInfoMember AuditInfoApiKey
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 404 The current organization was not found.
// Indicates that the organization context was not found or is invalid
{
// The specified organization could not be found or is not accessible
message: string
}
Update current organization
PUT /orgs
Updates the details of the current active organization.
RequestBody
// Data for updating an organization
{
// Name of the organization
name?: string
// Description of the organization
description?: string | null
// Redirect URL of the organization
redirectUrl?: string | null
}
Responses
- 200 Organization updated successfully
// Organization information with related details
{
// Unique identifier for the organization
id: string
// Name of the organization
name: string
// Current plan of the organization
planName?: string | null
// Description of the organization
description?: string | null
// Redirect URL of the organization
redirectUrl?: string | null
// Whether the organization is disabled
isDisabled?: boolean
// ID of the user or API key that disabled the organization
disabledBy?: string | null
// Timestamp when the organization was disabled
disabledAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
// Whether the organization is deleted
isDeleted?: boolean
// ID of the user or API key that deleted the organization
deletedBy?: string | null
// Timestamp when the organization was deleted
deletedAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
// Whether this is the current active organization for the user
isCurrent?: boolean
roles?: {
// Name of the role
name: string
scopes?: // Scope associated with the role
string[]
}[]
workspaces?: {
// Unique identifier for the workspace
id: string
// Name of the workspace
name: string
// Whether access to this workspace is isRestricted
isRestricted: boolean
roles?: {
// Name of the role
name: string
scopes?: // Scope associated with the role
string[]
}[]
}[]
// User who created the resource
createdByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// User who last updated the resource
updatedByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// API key used to create the resource
createdByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// API key used to last update the resource
updatedByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// When the resource was created
createdAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
// When the resource was last updated
updatedAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
}
Schemas: AuditInfoMember AuditInfoApiKey
- 400 Invalid request to update organization. Check data, permissions, or ensure at least one field is provided for update.
// Invalid request to update organization. Check data, permissions, or ensure at least one field is provided for update.
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"UpdateFieldRequiredMessage"}
]
Schemas: ValidationErrorMessage UpdateFieldRequiredMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 The organization to update was not found.
// Indicates that the organization context was not found or is invalid
{
// The specified organization could not be found or is not accessible
message: string
}
Create first organization
POST /orgs/first
Creates the first organization for a new user. Only works when the user has no organizations.
RequestBody
// Data required to create a new organization
{
// Name of the organization
name: string
// Description of the organization
description?: string
// Redirect URL of the organization
redirectUrl?: string | null
}
Responses
- 201 First organization created successfully
// Response after creating an organization
{
// Unique identifier for the organization
id: string
// Name of the organization
name: string
// Description of the organization
description?: string | null
// Redirect URL of the organization
redirectUrl?: string | null
}
- 400 Invalid request to create first organization.
// Error response for validation failures
{
message: string
errors?: []
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 409 Conflict
// Conflict response message
{
message: string
}
Switch current organization
POST /orgs/current/{orgId}
Switches the current active organization for the authenticated user.
Responses
- 200 Organization switched successfully
{
// JWT access token upon successful sign-in verification
access_token?: string
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 404 Target organization for switching not found or is disabled.
// Target organization for switching not found or is disabled.
anyOf: [
{"$ref":"OrganizationNotFoundMessage"},
{"$ref":"OrganizationNotFoundOrDisabledMessage"}
]
Schemas: OrganizationNotFoundMessage OrganizationNotFoundOrDisabledMessage
Create invitation
POST /invites
Creates a new invitation to join the organization with a specified role.
RequestBody
// Data required to create a new invitation
{
// Email address of the person to invite
email: string
// Role to assign to the invited user
roleName: string
// Optional workspace ID to invite user to a specific workspace
workspaceId?: string
// Optional personalized message to include in the invitation
message?: string | null
}
Responses
- 201 Invitation created successfully
// Invitation details with audit information
{
// Unique identifier for the invitation
id: string
// Email address of the invited user
email: string
// ID of the organization sending the invitation
orgId: string
// ID of the specific workspace (if applicable)
workspaceId?: string | null
// Role to be assigned upon acceptance
roleName: string
// Current status of the invitation
status: enum[pending, accepted, expired, declined]
// Personalized message included in the invitation
message?: string | null
// When the invitation expires
expiresAt: anyOf: [
{"type":"string"},
{"type":"string"}
]
// Organization information
organization: {
// Name of the organization sending the invitation
name: string
}
// Workspace information (if invitation is for a specific workspace)
workspace?: object | null
// User who created the resource
createdByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// User who last updated the resource
updatedByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// API key used to create the resource
createdByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// API key used to last update the resource
updatedByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// When the resource was created
createdAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
// When the resource was last updated
updatedAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
}
Schemas: AuditInfoMember AuditInfoApiKey
- 400 Invalid request to create invitation.
// Invalid request to create invitation.
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"UserAlreadyHasRoleInOrganizationMessage"}
]
Schemas: ValidationErrorMessage UserAlreadyHasRoleInOrganizationMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization not found.
// Indicates that the organization context was not found or is invalid
{
// The specified organization could not be found or is not accessible
message: string
}
- 409 Conflict
// Conflict response message
{
message: string
}
- 429 You have reached the limit for limit-members. Please upgrade your plan to continue
// Limit reached response message
{
message: string
}
List organization invitations
GET /invites
Retrieves all invitations for the current organization.
Responses
- 200 List of invitations
[]
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization context not found.
// Organization context not found.
anyOf: [
{"$ref":"EmptyArrayResponse"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: EmptyArrayResponse OrganizationNotFoundMessage
List my invitations
GET /invites/me
Retrieves all invitations sent by the current user.
Responses
- 200 List of invitations sent by the current user
// Invitation details with audit information
{
// Unique identifier for the invitation
id: string
// ID of the organization sending the invitation
orgId: string
// ID of the specific workspace (if applicable)
workspaceId?: string | null
// Role to be assigned upon acceptance
roleName: string
// Current status of the invitation
status: enum[pending, accepted, expired, declined]
// Personalized message included in the invitation
message?: string | null
// When the invitation expires
expiresAt: anyOf: [
{"type":"string"},
{"type":"string"}
]
// Organization information
organization: {
// Name of the organization sending the invitation
name: string
}
// Workspace information (if invitation is for a specific workspace)
workspace?: object | null
// User who created the resource
createdByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// User who last updated the resource
updatedByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// API key used to create the resource
createdByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// API key used to last update the resource
updatedByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// When the resource was created
createdAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
// When the resource was last updated
updatedAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
}[]
Schemas: AuditInfoMember AuditInfoApiKey
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 No invitations found for the current user, or the organization context is invalid.
// No invitations found for the current user, or the organization context is invalid.
anyOf: [
{"$ref":"EmptyArrayResponse"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: EmptyArrayResponse OrganizationNotFoundMessage
Delete invitation
DELETE /invites/{invitationId}
Deletes an invitation by its ID.
Responses
- 200 Invitation deleted successfully
// Success response message
{
message: string
}
- 400 Cannot delete invitation due to invalid parameters or business rules.
// Cannot delete invitation due to invalid parameters or business rules.
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"CannotDeleteAcceptedInvitationMessage"}
]
Schemas: ValidationErrorMessage CannotDeleteAcceptedInvitationMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Invitation to delete not found, or its organization not found.
// Invitation to delete not found, or its organization not found.
anyOf: [
{"$ref":"InvitationNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: InvitationNotFoundMessage OrganizationNotFoundMessage
Accept invitation
GET /invites/{token}/accept
Accepts an invitation using the provided token. Creates a user account if needed.
Responses
- 200 Invitation accepted successfully
// Response after accepting an invitation
{
// User ID of the newly registered or existing user
id: string
// Email address of the user
email: string
// Whether the email has been verified
isEmailVerified: boolean
// JWT access token for authentication
access_token: string
}
- 400 Cannot accept invitation due to invalid token, status, or parameters.
// Cannot accept invitation due to invalid token, status, or parameters.
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"InvitationExpiredMessage"},
{"$ref":"InvitationAlreadyAcceptedMessage"},
{"$ref":"InvitationAlreadyDeclinedMessage"}
]
Schemas: ValidationErrorMessage InvitationExpiredMessage InvitationAlreadyAcceptedMessage InvitationAlreadyDeclinedMessage
- 404 Invitation to accept not found or has an invalid status (e.g., already accepted/declined/expired).
// Indicates that the invitation was not found or is invalid
{
// The specified invitation could not be found or is invalid or the organization is disabled or deleted
message: string
}
Decline invitation
GET /invites/{token}/decline
Declines an invitation using the provided token.
Responses
- 200 Invitation declined successfully
// Success response message
{
message: string
}
- 400 Cannot decline invitation due to invalid token, status, or parameters.
// Cannot decline invitation due to invalid token, status, or parameters.
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"InvitationExpiredMessage"},
{"$ref":"InvitationAlreadyAcceptedMessage"},
{"$ref":"InvitationAlreadyDeclinedMessage"}
]
Schemas: ValidationErrorMessage InvitationExpiredMessage InvitationAlreadyAcceptedMessage InvitationAlreadyDeclinedMessage
- 404 Invitation to decline not found or has an invalid status (e.g., already accepted/declined/expired).
// Indicates that the invitation was not found or is invalid
{
// The specified invitation could not be found or is invalid or the organization is disabled or deleted
message: string
}
Add a member to organization
POST /members
Adds a new member to the current organization with the specified role.
RequestBody
// Data required to add a member to an organization
{
// Email address of the user to add
email: string
// Name of the role to assign to the member
roleName: string
// Whether to send an invitation email
sendInvitation?: boolean
}
Responses
- 201 Member added successfully
// Role information with organization details
{
// Name of the role
name: string
scopes?: string[]
// Organization the role is associated with
organization: {
// Unique identifier for the organization
id: string
// Name of the organization
name?: string
// Description of the organization
description?: string | null
}
}
- 400 Invalid request to add member.
// Invalid request to add member.
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"UserAlreadyHasRoleInOrganizationMessage"}
]
Schemas: ValidationErrorMessage UserAlreadyHasRoleInOrganizationMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Member to be added not found (and invitation not sent), or Organization not found.
// Member to be added not found (and invitation not sent), or Organization not found.
anyOf: [
{"$ref":"MemberNotFoundMessage"},
{"$ref":"MemberOrRoleNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: MemberNotFoundMessage MemberOrRoleNotFoundMessage OrganizationNotFoundMessage
- 409 Conflict
// Conflict response message
{
message: string
}
List organization members
GET /members
Retrieves all members of the current organization.
Responses
- 200 List of organization members
[]
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization not found, or no members in organization.
// Organization not found, or no members in organization.
anyOf: [
{"$ref":"EmptyArrayResponse"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: EmptyArrayResponse OrganizationNotFoundMessage
Remove member from organization
DELETE /members/{userId}
Removes a member from the current organization.
Responses
- 200 Member removed from organization successfully
// Success response message
{
message: string
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Member to remove not found in the organization, or Organization not found.
// Member to remove not found in the organization, or Organization not found.
anyOf: [
{"$ref":"MemberNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: MemberNotFoundMessage OrganizationNotFoundMessage
Get member roles
GET /members/{userId}/roles
Retrieves all roles assigned to a member in the current organization.
Responses
- 200 Member roles
// Grouped roles for a member
{
organizationRoles: // Role in the organization
{
// Name of the role
name: string
scopes?: string[]
// ID of the organization this role is associated with
orgId: string
}[]
workspaceRoles: // Role in a workspace
{
// Name of the role
name: string
scopes?: string[]
// ID of the workspace this role is associated with
workspaceId: string
}[]
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Member not found, Organization not found, or member found but has no roles in this context.
// Member not found, Organization not found, or member found but has no roles in this context.
anyOf: [
{"$ref":"EmptyRolesListResponse"},
{"$ref":"MemberNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: EmptyRolesListResponse MemberNotFoundMessage OrganizationNotFoundMessage
Add role to member
POST /members/{userId}/role
Assigns a new role to a member in the current organization.
RequestBody
// Data required to add a role to a member
{
// Name of the role to assign
roleName: string
}
Responses
- 200 Role added successfully
// Role information with organization details
{
// Name of the role
name: string
scopes?: string[]
// Organization the role is associated with
organization: {
// Unique identifier for the organization
id: string
// Name of the organization
name?: string
// Description of the organization
description?: string | null
}
}
- 400 Invalid request to add role to member.
// Invalid request to add role to member.
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"UserAlreadyHasRoleInOrganizationMessage"}
]
Schemas: ValidationErrorMessage UserAlreadyHasRoleInOrganizationMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Member, Role, or Organization not found.
// Member, Role, or Organization not found.
anyOf: [
{"$ref":"MemberNotFoundMessage"},
{"$ref":"MemberOrRoleNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: MemberNotFoundMessage MemberOrRoleNotFoundMessage OrganizationNotFoundMessage
Remove role from member
DELETE /members/{userId}/role/{roleName}
Removes a role from a member in the current organization.
Responses
- 200 Role removed from member successfully
// Success response message
{
message: string
}
- 400 Cannot remove member role due to business rules or invalid parameters.
// Cannot remove member role due to business rules or invalid parameters.
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"CannotRemoveOwnOwnerRoleMessage"}
]
Schemas: ValidationErrorMessage CannotRemoveOwnOwnerRoleMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Member, Role, or Organization not found.
// Member, Role, or Organization not found.
anyOf: [
{"$ref":"MemberNotFoundMessage"},
{"$ref":"MemberOrRoleNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: MemberNotFoundMessage MemberOrRoleNotFoundMessage OrganizationNotFoundMessage
Create a new workspace
POST /workspaces
Creates a new workspace in the current organization.
RequestBody
// Data required to create a new workspace
{
// Name of the workspace
name: string
// Description of the workspace
description?: string
// Whether access to this workspace is isRestricted
isRestricted?: boolean //default: true
}
Responses
- 201 Workspace created successfully
// Workspace information with audit details
{
// Unique identifier for the workspace
id: string
// Name of the workspace
name: string
// Description of the workspace
description?: string | null
// Whether access to this workspace is isRestricted
isRestricted: boolean
// ID of the organization this workspace belongs to
orgId: string
// User who created the resource
createdByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// User who last updated the resource
updatedByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// API key used to create the resource
createdByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// API key used to last update the resource
updatedByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// When the resource was created
createdAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
// When the resource was last updated
updatedAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
}
Schemas: AuditInfoMember AuditInfoApiKey
- 400 Invalid input for creating a workspace.
// Invalid input for creating a workspace.
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"WorkspaceNameTakenMessage"}
]
Schemas: ValidationErrorMessage WorkspaceNameTakenMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization not found.
// Indicates that the organization context was not found or is invalid
{
// The specified organization could not be found or is not accessible
message: string
}
- 429 You have reached the limit for limit-workspaces. Please upgrade your plan to continue
// Limit reached response message
{
message: string
}
List workspaces
GET /workspaces
Retrieves all workspaces for the current organization.
Responses
- 200 List of workspaces
[]
- 400 Invalid request for listing workspaces.
// Error response for validation failures
{
message: string
errors?: []
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization not found or no workspaces exist.
// Organization not found or no workspaces exist.
anyOf: [
{"$ref":"EmptyArrayResponse"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: EmptyArrayResponse OrganizationNotFoundMessage
Get workspace by ID
GET /workspaces/{workspaceId}
Retrieves a specific workspace by its unique identifier.
Responses
- 200 Workspace details
// Workspace information with audit details
{
// Unique identifier for the workspace
id: string
// Name of the workspace
name: string
// Description of the workspace
description?: string | null
// Whether access to this workspace is isRestricted
isRestricted: boolean
// ID of the organization this workspace belongs to
orgId: string
// User who created the resource
createdByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// User who last updated the resource
updatedByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// API key used to create the resource
createdByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// API key used to last update the resource
updatedByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// When the resource was created
createdAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
// When the resource was last updated
updatedAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
}
Schemas: AuditInfoMember AuditInfoApiKey
- 400 Invalid request for getting a workspace.
// Error response for validation failures
{
message: string
errors?: []
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Workspace or Organization not found.
// Workspace or Organization not found.
anyOf: [
{"$ref":"WorkspaceNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: WorkspaceNotFoundMessage OrganizationNotFoundMessage
Update workspace
PUT /workspaces/{workspaceId}
Updates an existing workspace by its unique identifier.
RequestBody
// Data for updating a workspace
{
// New name for the workspace
name?: string
// New description for the workspace
description?: string
// Whether access to this workspace is isRestricted
isRestricted?: boolean
}
Responses
- 200 Workspace updated successfully
// Workspace information with audit details
{
// Unique identifier for the workspace
id: string
// Name of the workspace
name: string
// Description of the workspace
description?: string | null
// Whether access to this workspace is isRestricted
isRestricted: boolean
// ID of the organization this workspace belongs to
orgId: string
// User who created the resource
createdByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// User who last updated the resource
updatedByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// API key used to create the resource
createdByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// API key used to last update the resource
updatedByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// When the resource was created
createdAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
// When the resource was last updated
updatedAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
}
Schemas: AuditInfoMember AuditInfoApiKey
- 400 Invalid input for updating a workspace.
// Invalid input for updating a workspace.
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"WorkspaceNameTakenMessage"}
]
Schemas: ValidationErrorMessage WorkspaceNameTakenMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Workspace or Organization not found.
// Workspace or Organization not found.
anyOf: [
{"$ref":"WorkspaceNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: WorkspaceNotFoundMessage OrganizationNotFoundMessage
Delete workspace
DELETE /workspaces/{workspaceId}
Deletes a workspace by its unique identifier.
Responses
- 200 Workspace deleted successfully
// Response after deleting a workspace
{
// Success message
message: string
}
- 400 Invalid request for deleting a workspace.
// Invalid request for deleting a workspace.
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"WorkspaceNotEmptyMessage"}
]
Schemas: ValidationErrorMessage WorkspaceNotEmptyMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Workspace or Organization not found.
// Workspace or Organization not found.
anyOf: [
{"$ref":"WorkspaceNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: WorkspaceNotFoundMessage OrganizationNotFoundMessage
Get user roles in workspace
GET /workspaces/{workspaceId}/members/{userId}/role
Retrieves the roles assigned to a specific user in a workspace.
Responses
- 200 User roles in the workspace
// Role assigned to a workspace member
{
// Name of the role
name: string
}[]
- 400 Invalid request for getting user roles in a workspace.
// Error response for validation failures
{
message: string
errors?: []
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Workspace, Member, or Organization not found.
// Workspace, Member, or Organization not found.
anyOf: [
{"$ref":"WorkspaceNotFoundMessage"},
{"$ref":"MemberNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: WorkspaceNotFoundMessage MemberNotFoundMessage OrganizationNotFoundMessage
Add role to workspace member
POST /workspaces/{workspaceId}/members/{userId}/role
Assigns a role to a user in a specific workspace.
RequestBody
// Role to assign to a workspace member
{
// Name of the role to assign
roleName: string
}
Responses
- 201 Role added successfully
// Result of assigning a role to a workspace member
{
// Name of the assigned role
name: string
}
- 400 Invalid input for adding a role to a workspace member.
// Invalid input for adding a role to a workspace member.
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"UserAlreadyHasRoleInWorkspaceMessage"}
]
Schemas: ValidationErrorMessage UserAlreadyHasRoleInWorkspaceMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Workspace, Member, Role or Organization not found.
// Workspace, Member, Role or Organization not found.
anyOf: [
{"$ref":"WorkspaceNotFoundMessage"},
{"$ref":"MemberNotFoundMessage"},
{"$ref":"RoleNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: WorkspaceNotFoundMessage MemberNotFoundMessage RoleNotFoundMessage OrganizationNotFoundMessage
Remove role from workspace member
DELETE /workspaces/{workspaceId}/members/{userId}/role
Removes a role from a user in a specific workspace.
Responses
- 200 Role removed from user in workspace successfully
// Success response message
{
message: string
}
- 400 Invalid input for removing a role from a workspace member.
// Error response for validation failures
{
message: string
errors?: []
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Workspace, Member, Role or Organization not found.
// Workspace, Member, Role or Organization not found.
anyOf: [
{"$ref":"WorkspaceNotFoundMessage"},
{"$ref":"MemberNotFoundMessage"},
{"$ref":"RoleNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: WorkspaceNotFoundMessage MemberNotFoundMessage RoleNotFoundMessage OrganizationNotFoundMessage
List workspace members
GET /workspaces/{workspaceId}/members
Retrieves all members in a specific workspace.
Responses
- 200 List of workspace members
[]
- 400 Invalid request for listing workspace members.
// Error response for validation failures
{
message: string
errors?: []
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Workspace or Organization not found, or workspace has no members.
// Workspace or Organization not found, or workspace has no members.
anyOf: [
{"$ref":"EmptyArrayResponse"},
{"$ref":"WorkspaceNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: EmptyArrayResponse WorkspaceNotFoundMessage OrganizationNotFoundMessage
List all roles
GET /roles
Retrieves all system roles with their associated permission scopes.
Parameters(Query)
// Whether to include detailed scope information
includeScopes?: boolean
Responses
- 200 List of roles with their scopes
[]
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization not found or no roles defined (system roles should always exist).
// Organization not found or no roles defined (system roles should always exist).
anyOf: [
{"$ref":"EmptyArrayResponse"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: EmptyArrayResponse OrganizationNotFoundMessage
List available plans
GET /plans
Retrieves all available plans. If authenticated, the current plan will be marked.
Responses
- 200 List of available plans
[]
- 404 No plans found globally (returns empty array if successful but no plans exist), or the organization context was not found if authenticated.
// No plans found globally (returns empty array if successful but no plans exist), or the organization context was not found if authenticated.
anyOf: [
{"$ref":"EmptyArrayResponse"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: EmptyArrayResponse OrganizationNotFoundMessage
Get current plan
GET /plans/current
Retrieves the current plan for the authenticated organization with usage details.
Responses
- 200 Current organization plan with usage details
// Plan with detailed usage information
{
// Unique identifier of the plan
name: enum[plan-free, plan-startup, plan-business, plan-enterprise]
// Detailed limits with current usage
limits: {
}
// Whether this is the current plan
isCurrent?: boolean
// When the next limit reset will occur
nextResetAt?: anyOf: [
{"type":"string"},
{"type":"string"}
]
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Plan for the current organization not found (this usually implies the organization itself was not found or has no plan).
// Plan for the current organization not found (this usually implies the organization itself was not found or has no plan).
anyOf: [
{"$ref":"PlanNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: PlanNotFoundMessage OrganizationNotFoundMessage
Get all organization settings
GET /settings
Retrieves all settings (custom and service) for the organization.
Responses
- 200 List of all settings with group information
[]
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization not found, or no settings available.
// Organization not found, or no settings available.
anyOf: [
{"$ref":"EmptyArrayResponse"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: EmptyArrayResponse OrganizationNotFoundMessage
Get all custom settings
GET /settings/custom
Retrieves all custom settings for the organization.
Responses
- 200 List of custom settings
[]
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization not found, or no custom settings available.
// Organization not found, or no custom settings available.
anyOf: [
{"$ref":"EmptyArrayResponse"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: EmptyArrayResponse OrganizationNotFoundMessage
Create custom setting
POST /settings/custom
Creates a new custom setting for the organization.
RequestBody
// Data required to create a new setting
{
// Name of the setting
name: string
// Description of what the setting does
description?: string | null
}
Responses
- 201 Custom setting created successfully
// Setting response data
{
// Name of the setting
name: string
// URL-friendly identifier for the setting
slug: string
// Description of what the setting does
description?: string | null
}
- 400 Bad Request when creating custom setting
// Bad Request when creating custom setting
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"SettingValueRequiredMessage"},
{"$ref":"SettingReservedNameMessage"},
{"$ref":"SettingNotWorkspaceOverridableMessageSchema"}
]
Schemas: ValidationErrorMessage SettingValueRequiredMessage SettingReservedNameMessage SettingNotWorkspaceOverridableMessageSchema
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization not found.
// Indicates that the organization context was not found or is invalid
{
// The specified organization could not be found or is not accessible
message: string
}
Get custom setting by slug
GET /settings/custom/{settingSlug}
Retrieves a specific custom setting by its slug.
Responses
- 200 Custom setting details
// Setting response data
{
// Name of the setting
name: string
// URL-friendly identifier for the setting
slug: string
// Description of what the setting does
description?: string | null
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization or Setting not found.
// Organization or Setting not found.
anyOf: [
{"$ref":"SettingNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: SettingNotFoundMessage OrganizationNotFoundMessage
Update custom setting
PUT /settings/custom/{settingSlug}
Updates an existing custom setting by its slug.
RequestBody
// Data required to update an existing setting
{
// Description of what the setting does
description?: string | null
}
Responses
- 200 Custom setting updated successfully
// Setting response data
{
// Name of the setting
name: string
// URL-friendly identifier for the setting
slug: string
// Description of what the setting does
description?: string | null
}
- 400 Bad Request when updating custom setting
// Bad Request when updating custom setting
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"SettingValueRequiredMessage"},
{"$ref":"SettingNotWorkspaceOverridableMessageSchema"}
]
Schemas: ValidationErrorMessage SettingValueRequiredMessage SettingNotWorkspaceOverridableMessageSchema
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization or Setting not found.
// Organization or Setting not found.
anyOf: [
{"$ref":"SettingNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: SettingNotFoundMessage OrganizationNotFoundMessage
Delete custom setting
DELETE /settings/custom/{settingSlug}
Deletes a custom setting by its slug.
Responses
- 200 Custom setting deleted successfully
// Generic success response
{
// Success message
message: string
}
- 400 Bad Request when deleting custom setting
// Error response when attempting to delete a non-deletable service setting
{
message: string
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization or Setting not found.
// Organization or Setting not found.
anyOf: [
{"$ref":"SettingNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: SettingNotFoundMessage OrganizationNotFoundMessage
Get custom setting value
GET /settings/custom/{settingSlug}/value
Retrieves only the value of a specific custom setting by its slug.
Responses
- 200 Custom setting value (any type)
{
"type": "string"
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization or Setting not found.
// Organization or Setting not found.
anyOf: [
{"$ref":"SettingNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: SettingNotFoundMessage OrganizationNotFoundMessage
Get all service settings
GET /settings/service
Retrieves all service settings for the organization.
Responses
- 200 List of service settings
[]
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization not found, or no service settings available.
// Organization not found, or no service settings available.
anyOf: [
{"$ref":"EmptyArrayResponse"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: EmptyArrayResponse OrganizationNotFoundMessage
Get service setting by slug
GET /settings/service/{settingSlug}
Retrieves a specific service setting by its slug.
Responses
- 200 Service setting details
// Setting response data
{
// Name of the setting
name: string
// URL-friendly identifier for the setting
slug: string
// Description of what the setting does
description?: string | null
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization or Service Setting not found.
// Organization or Service Setting not found.
anyOf: [
{"$ref":"SettingNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: SettingNotFoundMessage OrganizationNotFoundMessage
Upsert service setting
PUT /settings/service/{settingSlug}
Updates an existing service setting or creates it if it does not exist.
RequestBody
// Data required to update an existing setting
{
// Description of what the setting does
description?: string | null
}
Responses
- 200 Service setting updated successfully
// Setting response data
{
// Name of the setting
name: string
// URL-friendly identifier for the setting
slug: string
// Description of what the setting does
description?: string | null
}
- 400 Bad Request when upserting service setting
// Bad Request when upserting service setting
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"SettingValueRequiredMessage"},
{"$ref":"InvalidServiceSettingSlugMessage"},
{"$ref":"InvalidServiceSettingValueTypeMessage"},
{"$ref":"InvalidServiceSettingValueMessage"},
{"$ref":"CannotOverrideSettingAtWorkspaceLevelMessage"}
]
Schemas: ValidationErrorMessage SettingValueRequiredMessage InvalidServiceSettingSlugMessage InvalidServiceSettingValueTypeMessage InvalidServiceSettingValueMessage CannotOverrideSettingAtWorkspaceLevelMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization or Setting not found.
// Organization or Setting not found.
anyOf: [
{"$ref":"SettingNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: SettingNotFoundMessage OrganizationNotFoundMessage
Get service setting value
GET /settings/service/{settingSlug}/value
Retrieves only the value of a specific service setting by its slug.
Responses
- 200 Service setting value (any type)
{
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization or Service Setting not found.
// Organization or Service Setting not found.
anyOf: [
{"$ref":"SettingNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: SettingNotFoundMessage OrganizationNotFoundMessage
Get all workspace settings
GET /workspaces/{workspaceId}/settings
Retrieves all settings (custom and service) for the workspace.
Responses
- 200 List of all workspace settings with group information
[]
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization not found, or no workspace settings found for any workspace in the org.
// Organization not found, or no workspace settings found for any workspace in the org.
anyOf: [
{"$ref":"EmptyArrayResponse"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: EmptyArrayResponse OrganizationNotFoundMessage
Get all workspace custom settings
GET /workspaces/{workspaceId}/settings/custom
Retrieves all custom settings for the workspace.
Responses
- 200 List of workspace custom settings
[]
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization not found, or no custom settings available.
// Organization not found, or no custom settings available.
anyOf: [
{"$ref":"EmptyArrayResponse"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: EmptyArrayResponse OrganizationNotFoundMessage
Create workspace custom setting
POST /workspaces/{workspaceId}/settings/custom
Creates a new custom setting for the workspace.
RequestBody
// Data required to create a new setting
{
// Name of the setting
name: string
// Description of what the setting does
description?: string | null
}
Responses
- 201 Workspace custom setting created successfully
// Setting response data
{
// Name of the setting
name: string
// URL-friendly identifier for the setting
slug: string
// Description of what the setting does
description?: string | null
}
- 400 Bad Request when creating custom setting
// Bad Request when creating custom setting
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"SettingValueRequiredMessage"},
{"$ref":"SettingReservedNameMessage"}
]
Schemas: ValidationErrorMessage SettingValueRequiredMessage SettingReservedNameMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization or Workspace not found.
// Organization or Workspace not found.
anyOf: [
{"$ref":"WorkspaceNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: WorkspaceNotFoundMessage OrganizationNotFoundMessage
Get workspace custom setting by slug
GET /workspaces/{workspaceId}/settings/custom/{settingSlug}
Retrieves a specific workspace custom setting by its slug.
Responses
- 200 Workspace custom setting details
// Setting response data
{
// Name of the setting
name: string
// URL-friendly identifier for the setting
slug: string
// Description of what the setting does
description?: string | null
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization or Setting not found.
// Organization or Setting not found.
anyOf: [
{"$ref":"SettingNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: SettingNotFoundMessage OrganizationNotFoundMessage
Update workspace custom setting
PUT /workspaces/{workspaceId}/settings/custom/{settingSlug}
Updates an existing workspace custom setting by its slug.
RequestBody
// Data required to update an existing setting
{
// Description of what the setting does
description?: string | null
}
Responses
- 200 Workspace custom setting updated successfully
// Setting response data
{
// Name of the setting
name: string
// URL-friendly identifier for the setting
slug: string
// Description of what the setting does
description?: string | null
}
- 400 Bad Request when updating custom setting
// Bad Request when updating custom setting
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"SettingValueRequiredMessage"}
]
Schemas: ValidationErrorMessage SettingValueRequiredMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization, Workspace, or Setting not found.
// Organization, Workspace, or Setting not found.
anyOf: [
{"$ref":"SettingNotFoundMessage"},
{"$ref":"WorkspaceNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: SettingNotFoundMessage WorkspaceNotFoundMessage OrganizationNotFoundMessage
Delete workspace custom setting
DELETE /workspaces/{workspaceId}/settings/custom/{settingSlug}
Deletes a workspace custom setting by its slug.
Responses
- 200 Workspace custom setting deleted successfully
// Generic success response
{
// Success message
message: string
}
- 400 Bad Request when deleting custom setting
// Error response when attempting to delete a non-deletable service setting
{
message: string
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization, Workspace, or Setting not found.
// Organization, Workspace, or Setting not found.
anyOf: [
{"$ref":"SettingNotFoundMessage"},
{"$ref":"WorkspaceNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: SettingNotFoundMessage WorkspaceNotFoundMessage OrganizationNotFoundMessage
Get workspace custom setting value
GET /workspaces/{workspaceId}/settings/custom/{settingSlug}/value
Retrieves only the value of a specific workspace custom setting by its slug.
Responses
- 200 Workspace custom setting value (any type)
{
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization or Setting not found.
// Organization or Setting not found.
anyOf: [
{"$ref":"SettingNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: SettingNotFoundMessage OrganizationNotFoundMessage
Get all workspace service settings
GET /workspaces/{workspaceId}/settings/service
Retrieves all service settings for the workspace.
Responses
- 200 List of workspace service settings
[]
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization not found, or no service settings available.
// Organization not found, or no service settings available.
anyOf: [
{"$ref":"EmptyArrayResponse"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: EmptyArrayResponse OrganizationNotFoundMessage
Get workspace service setting by slug
GET /workspaces/{workspaceId}/settings/service/{settingSlug}
Retrieves a specific workspace service setting by its slug.
Responses
- 200 Workspace service setting details
// Setting response data
{
// Name of the setting
name: string
// URL-friendly identifier for the setting
slug: string
// Description of what the setting does
description?: string | null
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization, Workspace, or Service Setting not found.
// Organization, Workspace, or Service Setting not found.
anyOf: [
{"$ref":"SettingNotFoundMessage"},
{"$ref":"WorkspaceNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: SettingNotFoundMessage WorkspaceNotFoundMessage OrganizationNotFoundMessage
Upsert workspace service setting
PUT /workspaces/{workspaceId}/settings/service/{settingSlug}
Updates an existing workspace service setting or creates it if it does not exist.
RequestBody
// Data required to update an existing setting
{
// Description of what the setting does
description?: string | null
}
Responses
- 200 Workspace service setting updated successfully
// Setting response data
{
// Name of the setting
name: string
// URL-friendly identifier for the setting
slug: string
// Description of what the setting does
description?: string | null
}
- 400 Bad Request when upserting service setting
// Bad Request when upserting service setting
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"SettingValueRequiredMessage"},
{"$ref":"InvalidServiceSettingSlugMessage"},
{"$ref":"InvalidServiceSettingValueTypeMessage"},
{"$ref":"InvalidServiceSettingValueMessage"}
]
Schemas: ValidationErrorMessage SettingValueRequiredMessage InvalidServiceSettingSlugMessage InvalidServiceSettingValueTypeMessage InvalidServiceSettingValueMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization, Workspace, or Setting not found.
// Organization, Workspace, or Setting not found.
anyOf: [
{"$ref":"WorkspaceNotFoundMessage"},
{"$ref":"SettingNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: WorkspaceNotFoundMessage SettingNotFoundMessage OrganizationNotFoundMessage
Delete workspace service setting override
DELETE /workspaces/{workspaceId}/settings/service/{settingSlug}
Deletes a workspace-level override for a service setting, reverting to organization defaults.
Responses
- 200 Overridden workspace service setting deleted successfully
// Generic success response
{
// Success message
message: string
}
- 400 Bad Request when deleting overridden workspace service setting
// Bad Request when deleting overridden workspace service setting
anyOf: [
{"$ref":"WorkspaceIdRequiredMessageSchema"},
{"$ref":"InvalidServiceSettingSlugMessage"}
]
Schemas: WorkspaceIdRequiredMessageSchema InvalidServiceSettingSlugMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization, Workspace, or Setting not found.
// Organization, Workspace, or Setting not found.
anyOf: [
{"$ref":"WorkspaceNotFoundMessage"},
{"$ref":"SettingNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: WorkspaceNotFoundMessage SettingNotFoundMessage OrganizationNotFoundMessage
Get workspace service setting value
GET /workspaces/{workspaceId}/settings/service/{settingSlug}/value
Retrieves only the value of a specific workspace service setting by its slug.
Responses
- 200 Workspace service setting value (any type)
{
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization, Workspace, or Service Setting not found.
// Organization, Workspace, or Service Setting not found.
anyOf: [
{"$ref":"SettingNotFoundMessage"},
{"$ref":"WorkspaceNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: SettingNotFoundMessage WorkspaceNotFoundMessage OrganizationNotFoundMessage
List QR Code Scans
GET /codes/{codeId}/scans
Retrieves a paginated list of scans for a specific QR Code with optional filtering
- Security: bearerAuth
Parameters(Query)
page?: number
limit?: number
orderBy?: enum[scannedAt, browser, countryCode, status]
orderDirection?: enum[asc, desc]
// Filter by browser name
browser?: string
// Filter by operating system
os?: string
// Filter by country code (ISO 3166-1 alpha-2)
countryCode?: string
// Filter by city name
city?: string
// Filter by region/state name
region?: string
// Filter by continent
continent?: string
// Filter by AS organization
asOrganization?: string
// Filter by scan status (SUCCESS or LIMIT_REACHED)
status?: enum[success, limit_reached]
// Filter by scan date range
scannedAt?: {
}
Responses
- 200 A paginated list of QR Code Scans
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization, code, or scans not found.
// Organization, code, or scans not found.
anyOf: [
{"$ref":"EmptyResponseWithPagination"},
{"$ref":"CodeNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: EmptyResponseWithPagination CodeNotFoundMessage OrganizationNotFoundMessage
List Router Rule Assignments
GET /codes/{codeId}/router-rules
Retrieves all router rule assignments for a specific QR code with pagination and filtering options. Returns rules sorted by priority (highest first) with enriched template data.
- Security: bearerAuth
Parameters(Query)
page?: integer //default: 1
limit?: integer //default: 10
includeDisabled?: boolean
type?: enum[location, continent, geo, time, date, timezone, language, browser, os, deviceVendor, deviceModel, scanLimit]
priority?: integer
dataType?: enum[url, text, email, phone, sms, wifi, vcard, event]
Responses
- 200 A paginated list of Router Rule assignments with enriched template data
// Paginated list response
{
// Pagination metadata
pagination: {
// Total number of items matching the filter criteria
total: number
// Current page number
page: number
// Number of items per page
limit: number
// Total number of pages
totalPages: number
}
data: []
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 QR code not found
{
error?: string
}
Create Router Rule Assignment
POST /codes/{codeId}/router-rules
Assigns a router rule to a QR code. You can reference an existing template by ID/name or create an inline custom rule. Rules with the same priority are evaluated in creation order. Scan limits and loop functionality are supported.
- Security: bearerAuth
RequestBody
{}
Responses
- 201 Router Rule assignment created successfully
// Code router rule assignment response object
{
// Unique rule assignment identifier
id: string
// Parent QR code ID
codeId: string
// Template ID or null for inline
templateId: string | null
// Denormalized rule type for filtering
ruleType: string
// Resolved rule object
rule: {
// Template ID (only for template rules)
id?: string
// Rule name
name: string | null
// Rule description
description: string | null
// Rule type
type: string
// Rule conditions (null for scanLimit)
conditions: object | null
// Is global template
isGlobal?: boolean
// Organization ID
orgId?: string | null
// Workspace ID
workspaceId?: string | null
// Total template scans
totalScans?: integer
// Template creation date
createdAt?: string
// Template update date
updatedAt?: string
}
priority: integer
// The type of data the QR code contains. Only applies to dynamic codes. Determines how the QR code data is processed and what content type is returned when scanned. Available options: url (default, standard web redirect), wifi (WiFi configuration), vcard (contact card), text (plain text), email (mailto format), event (calendar event), json (custom JSON), file (file download).
dataType: enum[url, wifi, vcard, text, email, event, json, file]
dynamicData: {
}
maxScans: integer | null
loop: boolean
expiresAt: string | null
disabled: boolean
currentScans: integer
totalScans: integer
// User who created the resource
createdByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// User who last updated the resource
updatedByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// API key used to create the resource
createdByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// API key used to last update the resource
updatedByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// When the resource was created
createdAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
// When the resource was last updated
updatedAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
}
Schemas: AuditInfoMember AuditInfoApiKey
- 400 Invalid request data, priority conflict, or template not found
// Invalid request data, priority conflict, or template not found
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"RouterRulePriorityAlreadyExistsMessage"},
{"$ref":"RouterRuleInvalidConditionsMessage"},
{"$ref":"RouterRuleMaxScansRequiredMessage"},
{"$ref":"RouterRuleInvalidCountryCodeMessage"},
{"type":"object","properties":{"error":{"type":"string","const":"COMPOSITE_RULE_NESTING_DEPTH_EXCEEDED"},"message":{"type":"string"},"maxDepth":{"type":"number"},"actualDepth":{"type":"number"}},"required":["error","message","maxDepth","actualDepth"],"description":"Composite rule nesting depth exceeded maximum allowed depth","example":{"error":"COMPOSITE_RULE_NESTING_DEPTH_EXCEEDED","message":"Condition nesting depth exceeds maximum allowed depth of 5","maxDepth":5,"actualDepth":7}},
{"type":"object","properties":{"error":{"type":"string","const":"COMPOSITE_RULE_CONDITION_COUNT_EXCEEDED"},"message":{"type":"string"},"maxConditions":{"type":"number"},"actualConditions":{"type":"number"}},"required":["error","message","maxConditions","actualConditions"],"description":"Composite rule condition count exceeded maximum allowed","example":{"error":"COMPOSITE_RULE_CONDITION_COUNT_EXCEEDED","message":"Too many conditions (150). Maximum allowed is 100 for performance reasons.","maxConditions":100,"actualConditions":150}},
{"type":"object","properties":{"error":{"type":"string","const":"COMPOSITE_RULE_INVALID_LOGICAL_OPERATOR"},"message":{"type":"string"},"validOperators":{"type":"array","items":{"type":"string"}}},"required":["error","message","validOperators"],"description":"Invalid logical operator in composite rule","example":{"error":"COMPOSITE_RULE_INVALID_LOGICAL_OPERATOR","message":"Logical condition must have exactly one operator (AND, OR, oneOf, or noneOf)","validOperators":["AND","OR","oneOf","noneOf"]}},
{"type":"object","properties":{"error":{"type":"string","const":"COMPOSITE_RULE_CONDITIONS_REQUIRED"},"message":{"type":"string"},"ruleType":{"type":"string"}},"required":["error","message","ruleType"],"description":"Composite rules require enhanced conditions to be specified","example":{"error":"COMPOSITE_RULE_CONDITIONS_REQUIRED","message":"composite rules require enhanced conditions to be specified","ruleType":"composite"}},
{"type":"object","properties":{"error":{"type":"string","const":"RULE_MERGED_VALIDATION_ERROR"},"message":{"type":"string"},"field":{"type":"string"},"ruleType":{"type":"string"},"requiredAction":{"type":"string"}},"required":["error","message","field","ruleType","requiredAction"],"description":"Error when merged rule state validation fails","example":{"error":"RULE_MERGED_VALIDATION_ERROR","message":"scanLimit rules must have null conditions","field":"conditions","ruleType":"scanLimit","requiredAction":"Set conditions to null"}},
{"type":"object","properties":{"error":{"type":"string","const":"RULE_TYPE_CONDITION_MISMATCH_ERROR"},"message":{"type":"string"},"requestedType":{"type":"string"},"existingConditions":{"type":"boolean"},"requiredAction":{"type":"string"}},"required":["error","message","requestedType","existingConditions","requiredAction"],"description":"Error when rule type and condition format do not match","example":{"error":"RULE_TYPE_CONDITION_MISMATCH_ERROR","message":"Cannot change rule type to composite with standard format conditions","requestedType":"composite","existingConditions":true,"requiredAction":"Provide enhanced conditions"}}
]
Schemas: ValidationErrorMessage RouterRulePriorityAlreadyExistsMessage RouterRuleInvalidConditionsMessage RouterRuleMaxScansRequiredMessage RouterRuleInvalidCountryCodeMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 429 You have reached the limit for router rules per QR code. Please upgrade your plan to continue
// Limit reached response message
{
message: string
}
Get Router Rule Assignment
GET /codes/{codeId}/router-rules/{routerRuleId}
Retrieves a specific router rule assignment for a QR code. Returns the rule with enriched template data, usage statistics, and audit information.
- Security: bearerAuth
Responses
- 200 Router Rule assignment details with enriched template data
// Code router rule assignment response object
{
// Unique rule assignment identifier
id: string
// Parent QR code ID
codeId: string
// Template ID or null for inline
templateId: string | null
// Denormalized rule type for filtering
ruleType: string
// Resolved rule object
rule: {
// Template ID (only for template rules)
id?: string
// Rule name
name: string | null
// Rule description
description: string | null
// Rule type
type: string
// Rule conditions (null for scanLimit)
conditions: object | null
// Is global template
isGlobal?: boolean
// Organization ID
orgId?: string | null
// Workspace ID
workspaceId?: string | null
// Total template scans
totalScans?: integer
// Template creation date
createdAt?: string
// Template update date
updatedAt?: string
}
priority: integer
// The type of data the QR code contains. Only applies to dynamic codes. Determines how the QR code data is processed and what content type is returned when scanned. Available options: url (default, standard web redirect), wifi (WiFi configuration), vcard (contact card), text (plain text), email (mailto format), event (calendar event), json (custom JSON), file (file download).
dataType: enum[url, wifi, vcard, text, email, event, json, file]
dynamicData: {
}
maxScans: integer | null
loop: boolean
expiresAt: string | null
disabled: boolean
currentScans: integer
totalScans: integer
// User who created the resource
createdByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// User who last updated the resource
updatedByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// API key used to create the resource
createdByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// API key used to last update the resource
updatedByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// When the resource was created
createdAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
// When the resource was last updated
updatedAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
}
Schemas: AuditInfoMember AuditInfoApiKey
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Router rule or QR code not found
{
error?: string
}
Update Router Rule Assignment
PUT /codes/{codeId}/router-rules/{routerRuleId}
Updates a router rule assignment. You can change the rule source (template vs inline), priority, data configuration, and other settings. Validation is context-aware and will validate dynamicData against the existing or provided dataType. Priority conflicts are checked.
- Security: bearerAuth
RequestBody
{}
Responses
- 200 Router Rule assignment updated successfully
// Code router rule assignment response object
{
// Unique rule assignment identifier
id: string
// Parent QR code ID
codeId: string
// Template ID or null for inline
templateId: string | null
// Denormalized rule type for filtering
ruleType: string
// Resolved rule object
rule: {
// Template ID (only for template rules)
id?: string
// Rule name
name: string | null
// Rule description
description: string | null
// Rule type
type: string
// Rule conditions (null for scanLimit)
conditions: object | null
// Is global template
isGlobal?: boolean
// Organization ID
orgId?: string | null
// Workspace ID
workspaceId?: string | null
// Total template scans
totalScans?: integer
// Template creation date
createdAt?: string
// Template update date
updatedAt?: string
}
priority: integer
// The type of data the QR code contains. Only applies to dynamic codes. Determines how the QR code data is processed and what content type is returned when scanned. Available options: url (default, standard web redirect), wifi (WiFi configuration), vcard (contact card), text (plain text), email (mailto format), event (calendar event), json (custom JSON), file (file download).
dataType: enum[url, wifi, vcard, text, email, event, json, file]
dynamicData: {
}
maxScans: integer | null
loop: boolean
expiresAt: string | null
disabled: boolean
currentScans: integer
totalScans: integer
// User who created the resource
createdByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// User who last updated the resource
updatedByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// API key used to create the resource
createdByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// API key used to last update the resource
updatedByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// When the resource was created
createdAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
// When the resource was last updated
updatedAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
}
Schemas: AuditInfoMember AuditInfoApiKey
- 400 Invalid request data, priority conflict, or validation error
// Invalid request data, priority conflict, or validation error
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"RouterRulePriorityAlreadyExistsMessage"},
{"$ref":"RouterRuleInvalidConditionsMessage"},
{"$ref":"RouterRuleMaxScansRequiredMessage"},
{"$ref":"RouterRuleInvalidCountryCodeMessage"},
{"type":"object","properties":{"error":{"type":"string","const":"COMPOSITE_RULE_NESTING_DEPTH_EXCEEDED"},"message":{"type":"string"},"maxDepth":{"type":"number"},"actualDepth":{"type":"number"}},"required":["error","message","maxDepth","actualDepth"],"description":"Composite rule nesting depth exceeded maximum allowed depth","example":{"error":"COMPOSITE_RULE_NESTING_DEPTH_EXCEEDED","message":"Condition nesting depth exceeds maximum allowed depth of 5","maxDepth":5,"actualDepth":7}},
{"type":"object","properties":{"error":{"type":"string","const":"COMPOSITE_RULE_CONDITION_COUNT_EXCEEDED"},"message":{"type":"string"},"maxConditions":{"type":"number"},"actualConditions":{"type":"number"}},"required":["error","message","maxConditions","actualConditions"],"description":"Composite rule condition count exceeded maximum allowed","example":{"error":"COMPOSITE_RULE_CONDITION_COUNT_EXCEEDED","message":"Too many conditions (150). Maximum allowed is 100 for performance reasons.","maxConditions":100,"actualConditions":150}},
{"type":"object","properties":{"error":{"type":"string","const":"COMPOSITE_RULE_INVALID_LOGICAL_OPERATOR"},"message":{"type":"string"},"validOperators":{"type":"array","items":{"type":"string"}}},"required":["error","message","validOperators"],"description":"Invalid logical operator in composite rule","example":{"error":"COMPOSITE_RULE_INVALID_LOGICAL_OPERATOR","message":"Logical condition must have exactly one operator (AND, OR, oneOf, or noneOf)","validOperators":["AND","OR","oneOf","noneOf"]}},
{"type":"object","properties":{"error":{"type":"string","const":"COMPOSITE_RULE_CONDITIONS_REQUIRED"},"message":{"type":"string"},"ruleType":{"type":"string"}},"required":["error","message","ruleType"],"description":"Composite rules require enhanced conditions to be specified","example":{"error":"COMPOSITE_RULE_CONDITIONS_REQUIRED","message":"composite rules require enhanced conditions to be specified","ruleType":"composite"}},
{"type":"object","properties":{"error":{"type":"string","const":"RULE_MERGED_VALIDATION_ERROR"},"message":{"type":"string"},"field":{"type":"string"},"ruleType":{"type":"string"},"requiredAction":{"type":"string"}},"required":["error","message","field","ruleType","requiredAction"],"description":"Error when merged rule state validation fails","example":{"error":"RULE_MERGED_VALIDATION_ERROR","message":"scanLimit rules must have null conditions","field":"conditions","ruleType":"scanLimit","requiredAction":"Set conditions to null"}},
{"type":"object","properties":{"error":{"type":"string","const":"RULE_TYPE_CONDITION_MISMATCH_ERROR"},"message":{"type":"string"},"requestedType":{"type":"string"},"existingConditions":{"type":"boolean"},"requiredAction":{"type":"string"}},"required":["error","message","requestedType","existingConditions","requiredAction"],"description":"Error when rule type and condition format do not match","example":{"error":"RULE_TYPE_CONDITION_MISMATCH_ERROR","message":"Cannot change rule type to composite with standard format conditions","requestedType":"composite","existingConditions":true,"requiredAction":"Provide enhanced conditions"}}
]
Schemas: ValidationErrorMessage RouterRulePriorityAlreadyExistsMessage RouterRuleInvalidConditionsMessage RouterRuleMaxScansRequiredMessage RouterRuleInvalidCountryCodeMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Router rule assignment not found, or QR code/organization/workspace context not found.
// Router rule assignment not found, or QR code/organization/workspace context not found.
anyOf: [
{"$ref":"RouterRuleNotFoundMessage"},
{"$ref":"CodeNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"},
{"$ref":"WorkspaceNotFoundMessage"}
]
Schemas: RouterRuleNotFoundMessage CodeNotFoundMessage OrganizationNotFoundMessage WorkspaceNotFoundMessage
Delete Router Rule Assignment
DELETE /codes/{codeId}/router-rules/{routerRuleId}
Deletes a router rule assignment. Rules that have been used (totalScans > 0) cannot be deleted to preserve analytics data. Consider disabling the rule instead.
- Security: bearerAuth
Responses
- 200 Router Rule assignment deleted successfully
{
message?: string
}
- 400 Rule has been used and cannot be deleted
{
error?: string
details?: {
// Number of times this rule has been used
totalScans?: integer
}
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Router rule assignment not found, or QR code/organization/workspace context not found.
// Router rule assignment not found, or QR code/organization/workspace context not found.
anyOf: [
{"$ref":"RouterRuleNotFoundMessage"},
{"$ref":"CodeNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"},
{"$ref":"WorkspaceNotFoundMessage"}
]
Schemas: RouterRuleNotFoundMessage CodeNotFoundMessage OrganizationNotFoundMessage WorkspaceNotFoundMessage
List Soft Deleted QR Codes
GET /codes/deleted
Retrieves a paginated list of soft deleted QR Codes with optional filtering
- Security: bearerAuth
Parameters(Query)
page?: number
limit?: number
orderBy?: enum[createdAt, updatedAt, name]
orderDirection?: enum[asc, desc]
// Filter by QR code name
name?: string
// Filter by workspace ID
workspaceId?: string
// Filter by validation status
isValid?: enum[true, false, null]
// Filter by QR code data content
data?: string
// Filter by creation date range
createdAt?: {
}
// Filter by update date range
updatedAt?: {
}
Responses
- 200 A paginated list of soft deleted QR Codes
// Paginated list response
{
// Pagination metadata
pagination: {
// Total number of items matching the filter criteria
total: number
// Current page number
page: number
// Number of items per page
limit: number
// Total number of pages
totalPages: number
}
data: []
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization not found, or the list of codes is empty (returned as an empty paginated response).
// Organization not found, or the list of codes is empty (returned as an empty paginated response).
anyOf: [
{"$ref":"EmptyResponseWithPagination"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: EmptyResponseWithPagination OrganizationNotFoundMessage
List QR Code Links
GET /codes/links
Retrieves a paginated list of all QR Code links with optional filtering
- Security: bearerAuth
Parameters(Query)
page?: number
limit?: number
orderBy?: enum[createdAt, updatedAt, type]
orderDirection?: enum[asc, desc]
// Filter by QR code ID
codeId?: string
type?: enum[svg, png, pdf]
// Filter by QR code name
codeName?: string
// Filter by QR code version
codeVersion?: number
// Filter by QR code data content
codeData?: string
// Filter by QR code type
codeType?: string
// Filter by QR code validation status
codeIsValid?: enum[true, false, null]
// Filter by style name
styleName?: string
// Filter by template name
templateName?: string
// Filter by border name
borderName?: string
// Filter by whether this is the current version
isCurrentVersion?: enum[true, false]
// Filter by creator user ID
createdByUserId?: string
// Filter by creator API key ID
createdByApiKeyId?: string
// Filter by creation date range
createdAt?: {
}
// Filter by update date range
updatedAt?: {
}
// Filter by workspace ID
workspaceId?: string
Responses
- 200 A paginated list of QR Code links
// Paginated list response
{
// Pagination metadata
pagination: {
// Total number of items matching the filter criteria
total: number
// Current page number
page: number
// Number of items per page
limit: number
// Total number of pages
totalPages: number
}
data: []
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 QR Code links not found
// QR Code links not found
anyOf: [
{"$ref":"EmptyResponseWithPagination"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: EmptyResponseWithPagination OrganizationNotFoundMessage
Get QR Code
GET /codes/{codeId}
Retrieves a QR Code by its unique identifier
- Security: bearerAuth
Responses
- 200 The requested QR Code
// QR code response with audit information and file links
allOf: [
{"$ref":"BaseCodeResponseWithAudit"}
]
Schemas: BaseCodeResponseWithAudit
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization or code not found.
// Organization or code not found.
anyOf: [
{"$ref":"CodeNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: CodeNotFoundMessage OrganizationNotFoundMessage
Update QR Code
PUT /codes/{codeId}
Updates an existing QR Code with new data and options. Supports changing dataType for dynamic codes (e.g., from URL to WiFi configuration). When changing dataType, ensure metadata structure matches the new dataType requirements. This operation creates a new version of the QR code.
- Security: bearerAuth
RequestBody
{
// Type of QR code
type?: enum[static, dynamic]
// The type of data the QR code contains. Only applies to dynamic codes. Determines how the QR code data is processed and what content type is returned when scanned. Each dataType has specific content structure requirements.
dataType?: enum[url, wifi, vcard, text, email, event, json, file, ]
// Functional content for dynamic QR codes. Structure depends on dataType. url: {url}, wifi: {ssid, password?, security?, hidden?}, vcard: {fullName?, email?, phone?, organization?}, text: {text}, email: {to, subject?, body?}, event: {eventTitle, startDate, endDate?, location?}, file: {fileName, fileUrl, mimeType?}, json: any valid JSON.
dynamicData?: object | null
// Short alias for the QR code link (URL-safe characters only)
shortAlias?: string | null
// QR code data content
data?: string | null
// QR code generation options
options?: oneOf: [
{"$ref":"QRCodeOptionsWithOptionalData"},
{"type":"null"}
]
// Name of the QR code
name?: string
// Description for the QR code
description?: string
// Custom user metadata for the QR code as JSON object. This is separate from the dynamicData field and can store any additional information about the QR code that is not part of the functional content (e.g., campaign info, tags, internal references).
metadata?: object | null
// Style ID to apply to the QR code
styleId?: string | null
// Style object with options or style name string
style?: anyOf: [
{"type":"object","properties":{"id":{"type":["string","null"]},"name":{"type":["string","null"]},"options":{"oneOf":[{"$ref":"StyleOptions"},{"type":"null"}]}}},
{"type":"string"},
{"type":"null"}
]
// Template ID to apply to the QR code
templateId?: string | null
// Template object with options or template name string
template?: anyOf: [
{"type":"object","properties":{"id":{"type":["string","null"]},"name":{"type":["string","null"]},"options":{"oneOf":[{"$ref":"QRCodeOptionsWithOptionalData"},{"type":"null"}]}}},
{"type":"string"},
{"type":"null"}
]
// Border ID to apply to the QR code
borderId?: string | null
// Border object with options or border name string
border?: anyOf: [
{"type":"object","properties":{"id":{"type":["string","null"]},"name":{"type":["string","null"]},"options":{"oneOf":[{"$ref":"BorderOptions"},{"type":"null"}]}}},
{"type":"string"},
{"type":"null"}
]
// Text ID to apply to the QR code
textId?: string | null
// Text object with options or text name string
text?: anyOf: [
{"type":"object","properties":{"id":{"type":["string","null"]},"name":{"type":["string","null"]},"options":{"oneOf":[{"$ref":"TextOptions"},{"type":"null"}]}}},
{"type":"string"},
{"type":"null"}
]
// Format for the generated QR code link. Return existing link if generated before or create new link with provided format.
linkFormat?: enum[svg, png, pdf]
// Whether to validate the QR code during update
validate?: boolean
}
Schemas: QRCodeOptionsWithOptionalData
Responses
- 200 QR Code updated successfully
// QR code response with audit information and file links
allOf: [
{"$ref":"BaseCodeResponseWithAudit"}
]
Schemas: BaseCodeResponseWithAudit
- 400 Invalid request to update QR Code.
// Invalid request to update QR Code.
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"UpdateFieldRequiredMessage"},
{"$ref":"CodeIsInvalidMessage"},
{"$ref":"InvalidCodeTypeMessage"},
{"$ref":"CodeIsSoftDeletedMessage"},
{"$ref":"DynamicDataForStaticCodeMessage"},
{"$ref":"DynamicDataRequiredMessage"},
{"$ref":"ShortAliasAlreadyTakenMessage"},
{"$ref":"ShortAliasForDynamicToStaticCodeMessage"},
{"$ref":"InfiniteRedirectLoopDetectedMessage"},
{"$ref":"DataTypeForDynamicToStaticCodeMessage"},
{"$ref":"DataTypeForStaticCodeMessage"},
{"$ref":"DataForDynamicCodeMessage"}
]
Schemas: ValidationErrorMessage UpdateFieldRequiredMessage CodeIsInvalidMessage InvalidCodeTypeMessage CodeIsSoftDeletedMessage DynamicDataForStaticCodeMessage DynamicDataRequiredMessage ShortAliasAlreadyTakenMessage ShortAliasForDynamicToStaticCodeMessage InfiniteRedirectLoopDetectedMessage DataTypeForDynamicToStaticCodeMessage DataTypeForStaticCodeMessage DataForDynamicCodeMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Could not update code due to missing resources.
// Could not update code due to missing resources.
anyOf: [
{"$ref":"CodeNotFoundMessage"},
{"$ref":"StyleNotFoundMessage"},
{"$ref":"TemplateNotFoundMessage"},
{"$ref":"BorderNotFoundMessage"},
{"$ref":"TextNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: CodeNotFoundMessage StyleNotFoundMessage TemplateNotFoundMessage BorderNotFoundMessage TextNotFoundMessage OrganizationNotFoundMessage
- 409 QR Code with same name already exists
// Not found response message
{
message: string
}
Soft Delete QR Code
DELETE /codes/{codeId}
Marks a QR Code as deleted without permanently removing it from the system. Usage limits are not affected and the code can potentially be restored.
- Security: bearerAuth
Responses
- 200 QR Code soft deleted successfully.
{
// Confirmation message
message: string
}
- 400 QR Code is already deleted.
// Error response when a code is already deleted
{
message: string
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization or code not found.
// Organization or code not found.
anyOf: [
{"$ref":"CodeNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: CodeNotFoundMessage OrganizationNotFoundMessage
List QR Codes
GET /codes
Retrieves a paginated list of QR Codes with optional filtering
- Security: bearerAuth
Parameters(Query)
page?: number
limit?: number
orderBy?: enum[createdAt, updatedAt, name]
orderDirection?: enum[asc, desc]
// Filter by QR code name
name?: string
// Filter by workspace ID
workspaceId?: string
// Filter by validation status
isValid?: enum[true, false, null]
// Filter by QR code data content
data?: string
// Filter by creation date range
createdAt?: {
}
// Filter by update date range
updatedAt?: {
}
Responses
- 200 A paginated list of QR Codes
// Paginated list response
{
// Pagination metadata
pagination: {
// Total number of items matching the filter criteria
total: number
// Current page number
page: number
// Number of items per page
limit: number
// Total number of pages
totalPages: number
}
data: []
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization not found, or the list of codes is empty (returned as an empty paginated response).
// Organization not found, or the list of codes is empty (returned as an empty paginated response).
anyOf: [
{"$ref":"EmptyResponseWithPagination"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: EmptyResponseWithPagination OrganizationNotFoundMessage
Create QR Code
POST /codes
Creates a new QR Code with the specified data and options. Supports different dataTypes for dynamic codes including WiFi configuration, contact cards (vCard), plain text, email composition, calendar events, file downloads, and custom JSON data. Each dataType has specific metadata requirements that determine how the QR code is processed when scanned.
RequestBody
{
// Type of QR code
type?: enum[static, dynamic]
// The type of data the QR code contains. Only applies to dynamic codes. Defaults to "url" for dynamic codes. Each dataType has specific content structure requirements. url: {url}, wifi: {ssid, password?, security?, hidden?}, vcard: {fullName?, email?, phone?, organization?}, text: {text}, email: {to, subject?, body?}, event: {eventTitle, startDate, endDate?, location?}, file: {fileName, fileUrl, mimeType?}, json: any valid JSON.
dataType?: enum[url, wifi, vcard, text, email, event, json, file]
// Functional content for dynamic QR codes. Structure depends on dataType. url: {url}, wifi: {ssid, password?, security?, hidden?}, vcard: {fullName?, email?, phone?, organization?}, text: {text}, email: {to, subject?, body?}, event: {eventTitle, startDate, endDate?, location?}, file: {fileName, fileUrl, mimeType?}, json: any valid JSON.
dynamicData?: {
}
// Short alias for the QR code link (URL-safe characters only)
shortAlias?: string
// QR code data content
data?: string
// Name of the QR code
name: string
// Optional description for the QR code
description?: string
// Custom user metadata for the QR code as JSON object. This is separate from the dynamicData field and can store any additional information about the QR code that is not part of the functional content (e.g., campaign info, tags, internal references).
metadata?: object | null
// Format for the generated QR code link
linkFormat?: enum[svg, png, pdf]
// Whether to validate the QR code during creation
validate?: boolean
// QR code generation options
options?: oneOf: [
{"$ref":"QRCodeOptionsWithOptionalData"},
{"type":"null"}
]
// Style ID to apply to the QR code
styleId?: string | null
// Style object with options or style name string
style?: anyOf: [
{"type":["object","null"],"properties":{"id":{"type":["string","null"]},"options":{"oneOf":[{"$ref":"StyleOptions"},{"type":"null"}]}}},
{"type":"string"},
{"type":"null"}
]
// Template ID to apply to the QR code
templateId?: string | null
// Template object with options or template name string
template?: anyOf: [
{"type":["object","null"],"properties":{"id":{"type":["string","null"]},"options":{"oneOf":[{"$ref":"QRCodeOptionsWithOptionalData"},{"type":"null"}]}}},
{"type":"string"},
{"type":"null"}
]
// Border ID to apply to the QR code
borderId?: string | null
// Border object with options or border name string
border?: anyOf: [
{"type":["object","null"],"properties":{"id":{"type":["string","null"]},"options":{"oneOf":[{"$ref":"BorderOptions"},{"type":"null"}]}}},
{"type":"string"},
{"type":"null"}
]
// Text ID to apply to the QR code
textId?: string | null
// Text object with options or text name string
text?: anyOf: [
{"type":["object","null"],"properties":{"id":{"type":["string","null"]},"options":{"oneOf":[{"$ref":"TextOptions"},{"type":"null"}]}}},
{"type":"string"},
{"type":"null"}
]
}
Schemas: QRCodeOptionsWithOptionalData
Responses
- 200 QR Code created successfully
// QR code response with audit information and file links
allOf: [
{"$ref":"BaseCodeResponseWithAudit"}
]
Schemas: BaseCodeResponseWithAudit
- 400 Invalid request to create QR Code.
// Invalid request to create QR Code.
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"CodeDataRequiredMessage"},
{"$ref":"CodeIsInvalidMessage"},
{"$ref":"InvalidCodeTypeMessage"},
{"$ref":"DynamicDataForNewStaticCodeMessage"},
{"$ref":"DynamicDataRequiredMessage"},
{"$ref":"ShortAliasAlreadyTakenMessage"},
{"$ref":"ShortAliasForStaticCodeMessage"},
{"$ref":"InfiniteRedirectLoopDetectedMessage"},
{"$ref":"DataTypeForStaticCodeMessage"},
{"$ref":"DataTypeForDynamicToStaticCodeMessage"},
{"$ref":"DataForDynamicCodeMessage"}
]
Schemas: ValidationErrorMessage CodeDataRequiredMessage CodeIsInvalidMessage InvalidCodeTypeMessage DynamicDataForNewStaticCodeMessage DynamicDataRequiredMessage ShortAliasAlreadyTakenMessage ShortAliasForStaticCodeMessage InfiniteRedirectLoopDetectedMessage DataTypeForStaticCodeMessage DataTypeForDynamicToStaticCodeMessage DataForDynamicCodeMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Could not create code due to missing resources.
// Could not create code due to missing resources.
anyOf: [
{"$ref":"OrganizationNotFoundMessage"},
{"$ref":"WorkspaceNotFoundMessage"},
{"$ref":"StyleNotFoundMessage"},
{"$ref":"TemplateNotFoundMessage"},
{"$ref":"BorderNotFoundMessage"},
{"$ref":"TextNotFoundMessage"}
]
Schemas: OrganizationNotFoundMessage WorkspaceNotFoundMessage StyleNotFoundMessage TemplateNotFoundMessage BorderNotFoundMessage TextNotFoundMessage
- 409 QR Code with same name already exists
// Not found response message
{
message: string
}
- 429 You have reached the limit for limit-codes. Please upgrade your plan to continue
// Limit reached response message
{
message: string
}
Bulk Soft Delete QR Codes
DELETE /codes
Soft deletes multiple QR codes by their IDs. The codes are marked as deleted but not permanently removed from the system.
- Security: bearerAuth
Responses
- 200 Bulk soft delete completed with detailed results
{
// Success message for the bulk operation
message: string
// Detailed results categorized by outcome (only included when showDetails=true)
details?: {
deleted: string[]
alreadyDeleted: string[]
notFound: string[]
forbidden: string[]
failed: string[]
}
}
- 400 Invalid request for bulk soft delete.
// Error response for validation failures
{
message: string
errors?: []
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization not found.
// Indicates that the organization context was not found or is invalid
{
// The specified organization could not be found or is not accessible
message: string
}
Partially update QR Code Options
PUT /codes/{codeId}/options
Partially updates an existing QR Code's options using a deep merge. This will create a new version of the QR Code. Supports updating dataType for dynamic codes, which changes how the QR code content is processed when scanned (e.g., returning WiFi configuration instead of URL redirect).
- Security: bearerAuth
RequestBody
{
// The type of data the QR code contains. Only applies to dynamic codes. Determines how the QR code data is processed and what content type is returned when scanned.
dataType?: enum[url, wifi, vcard, text, email, event, json, file]
// Partial QR code generation options to update. All fields are optional. At least one option field must be provided.
options: {
// Data to encode in the QR code (required)
data?: string
// Shape of the QR code
shape?: enum[square, circle, ]
margin?: number | null
isResponsive?: boolean | null
scale?: number | null
offset?: number | null
verticalOffset?: number | null
horizontalOffset?: number | null
qrOptions?: object | null
dotsOptions?: object | null
cornersSquareOptions?: object | null
cornersDotOptions?: object | null
backgroundOptions?: anyOf: [
{"type":"object","properties":{"color":{"type":["string","null"],"description":"Background color in CSS format","example":"#ffffff"},"round":{"anyOf":[{"type":"number","minimum":0,"maximum":1},{"type":"string"},{"type":"null"}],"description":"Background corner rounding (0-1 or CSS value)","example":0.1},"gradient":{"oneOf":[{"$ref":"Gradient"},{"type":"null"}],"description":"Gradient for background"}},"required":["color"]},
{"type":"boolean","const":false}
]
image?: anyOf: [
{"type":"string"},
{},
{},
{"type":"null"}
]
imageOptions?: object | null
borderOptions?: object | null
}
// Format for the generated QR code link. Return existing link if generated before or create new link with provided format.
linkFormat?: enum[svg, png, pdf]
// Whether to validate the QR code after updating options.
validate?: boolean
}
Responses
- 200 QR Code options updated successfully, new version created.
// QR code response with audit information and file links
allOf: [
{"$ref":"BaseCodeResponseWithAudit"}
]
Schemas: BaseCodeResponseWithAudit
- 400 Invalid request to update QR Code Options.
// Invalid request to update QR Code Options.
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"UpdateFieldRequiredMessage"},
{"$ref":"UpdateOptionsFieldRequiredMessage"},
{"$ref":"CodeIsInvalidMessage"},
{"$ref":"InvalidCodeTypeMessage"},
{"$ref":"CodeIsSoftDeletedMessage"}
]
Schemas: ValidationErrorMessage UpdateFieldRequiredMessage UpdateOptionsFieldRequiredMessage CodeIsInvalidMessage InvalidCodeTypeMessage CodeIsSoftDeletedMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization or code not found.
// Organization or code not found.
anyOf: [
{"$ref":"CodeNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: CodeNotFoundMessage OrganizationNotFoundMessage
Bulk Permanent Delete QR Codes
DELETE /codes/permanent
Permanently deletes multiple QR codes by their IDs. This operation is irreversible and will remove all associated data including versions, files, and scans.
- Security: bearerAuth
Responses
- 200 Bulk permanent delete completed with detailed results
{
// Success message for the bulk permanent deletion operation
message: string
// Detailed results categorized by outcome (only included when showDetails=true)
details?: {
deleted: string[]
notFound: string[]
forbidden: string[]
failed: string[]
}
}
- 400 Invalid request for bulk permanent delete.
// Error response for validation failures
{
message: string
errors?: []
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization not found.
// Indicates that the organization context was not found or is invalid
{
// The specified organization could not be found or is not accessible
message: string
}
Delete QR Code
DELETE /codes/{codeId}/permanent
Deletes a QR Code by its unique identifier
- Security: bearerAuth
Responses
- 200 QR Code deleted successfully.
{
// Confirmation message
message: string
}
- 400 QR Code is not soft deleted.
// Error response when a code is not soft deleted
{
message: string
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization or code not found.
// Organization or code not found.
anyOf: [
{"$ref":"CodeNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: CodeNotFoundMessage OrganizationNotFoundMessage
Restore QR Code
POST /codes/{codeId}/restore
Restores a soft-deleted QR Code by setting its deleted status to false. The code becomes active again and accessible through regular endpoints.
- Security: bearerAuth
Responses
- 200 QR Code restored successfully.
// QR code response with audit information and file links
allOf: [
{"$ref":"BaseCodeResponseWithAudit"}
]
Schemas: BaseCodeResponseWithAudit
- 400 QR Code is not deleted.
// Error response when a code is not deleted
{
message: string
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization or code not found.
// Organization or code not found.
anyOf: [
{"$ref":"CodeNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: CodeNotFoundMessage OrganizationNotFoundMessage
Generate QR Code File Content
POST /codes/generate/{type}
Generates a file content for a QR Code
- Security: bearerAuth
RequestBody
{
// QR code data content
data?: string
// QR code generation options
options?: {
// Overall shape of the QR code
shape?: enum[square, circle, ]
// Margin around the QR code in pixels
margin?: number | null
// Whether QR code is responsive
isResponsive?: boolean | null
// Scale factor for QR code (0-1.5)
scale?: number | null
// General offset in pixels
offset?: number | null
// Vertical offset in pixels
verticalOffset?: number | null
// Horizontal offset in pixels
horizontalOffset?: number | null
// QR code specific options
qrOptions?: object | null
// Options for QR code dots
dotsOptions?: object | null
// Options for QR code corner squares
cornersSquareOptions?: object | null
// Options for QR code corner dots
cornersDotOptions?: object | null
// Options for QR code background or false to disable
backgroundOptions?: anyOf: [
{"type":"object","properties":{"color":{"type":["string","null"],"description":"Background color in CSS format","example":"#ffffff"},"round":{"anyOf":[{"type":"number","minimum":0,"maximum":1},{"type":"string"},{"type":"null"}],"description":"Background corner rounding (0-1 or CSS value)","example":0.1},"gradient":{"oneOf":[{"$ref":"Gradient"},{"type":"null"}],"description":"Gradient for background"}},"required":["color"]},
{"type":"boolean","const":false}
]
// Image to embed in the QR code (URL, Buffer, or Blob)
image?: anyOf: [
{"type":"string"},
{},
{},
{"type":"null"}
]
// Options for embedded image
imageOptions?: object | null
// Border configuration options
borderOptions?: object | null
// Data to encode in the QR code (optional in this context)
data?: string
}
// Style ID to apply to the QR code
styleId?: string | null
// Style object with options or style name string
style?: anyOf: [
{"type":["object","null"],"properties":{"options":{"oneOf":[{"$ref":"StyleOptions"},{"type":"null"}]}}},
{"type":"string"},
{"type":"null"}
]
// Template ID to apply to the QR code
templateId?: string | null
// Template object with options or template ID string
template?: anyOf: [
{"type":["object","null"],"properties":{"options":{"type":["object","null"],"properties":{"shape":{"type":["string","null"],"enum":["square","circle",null],"description":"Overall shape of the QR code","example":"square"},"margin":{"type":["number","null"],"description":"Margin around the QR code in pixels","example":10},"isResponsive":{"type":["boolean","null"],"description":"Whether QR code is responsive","example":true},"scale":{"type":["number","null"],"minimum":0,"maximum":1.5,"description":"Scale factor for QR code (0-1.5)","example":1},"offset":{"type":["number","null"],"description":"General offset in pixels","example":0},"verticalOffset":{"type":["number","null"],"description":"Vertical offset in pixels","example":0},"horizontalOffset":{"type":["number","null"],"description":"Horizontal offset in pixels","example":0},"qrOptions":{"type":["object","null"],"properties":{"typeNumber":{"type":["number","null"],"minimum":0,"maximum":40,"description":"QR code type number (0-40)","example":0},"mode":{"type":"string","enum":["numeric","alphanumeric","byte","kanji","unicode"],"description":"QR code encoding mode","example":"byte"},"errorCorrectionLevel":{"type":["string","null"],"enum":["L","M","Q","H",null],"description":"Error correction level","example":"M"}},"description":"QR code specific options"},"dotsOptions":{"type":["object","null"],"properties":{"type":{"type":["string","null"],"enum":["dot","square","rounded","extra-rounded","classy","classy-rounded","vertical-line","horizontal-line","random-dot","small-square","tiny-square","star","plus","diamond",null],"description":"Type of dots","example":"rounded"},"color":{"type":["string","null"],"description":"Color of dots in CSS format","example":"#000000"},"size":{"type":["number","null"],"description":"Size of dots relative to module size (0-1)","example":0.5},"gradient":{"oneOf":[{"$ref":"Gradient"},{"type":"null"}],"description":"Gradient for dots"}},"description":"Options for QR code dots"},"cornersSquareOptions":{"type":["object","null"],"properties":{"type":{"type":["string","null"],"enum":["dot","square","rounded","classy","outpoint","inpoint",null],"description":"Type of corner squares","example":"square"},"color":{"type":["string","null"],"description":"Color of corner squares in CSS format","example":"#000000"},"gradient":{"oneOf":[{"$ref":"Gradient"},{"type":"null"}],"description":"Gradient for corner squares"}},"description":"Options for QR code corner squares"},"cornersDotOptions":{"type":["object","null"],"properties":{"type":{"type":["string","null"],"enum":["dot","square","heart","rounded","classy","outpoint","inpoint",null],"description":"Type of corner dots","example":"dot"},"color":{"type":["string","null"],"description":"Color of corner dots in CSS format","example":"#000000"},"gradient":{"oneOf":[{"$ref":"Gradient"},{"type":"null"}],"description":"Gradient for corner dots"}},"description":"Options for QR code corner dots"},"backgroundOptions":{"anyOf":[{"type":"object","properties":{"color":{"type":["string","null"],"description":"Background color in CSS format","example":"#ffffff"},"round":{"anyOf":[{"type":"number","minimum":0,"maximum":1},{"type":"string"},{"type":"null"}],"description":"Background corner rounding (0-1 or CSS value)","example":0.1},"gradient":{"oneOf":[{"$ref":"Gradient"},{"type":"null"}],"description":"Gradient for background"}},"required":["color"]},{"type":"boolean","const":false}],"description":"Options for QR code background or false to disable"},"image":{"anyOf":[{"type":"string"},{},{},{"type":"null"}],"description":"Image to embed in the QR code (URL, Buffer, or Blob)","example":"https://example.com/logo.png"},"imageOptions":{"type":["object","null"],"properties":{"mode":{"type":["string","null"],"enum":["center","overlay","background",null],"description":"Mode for embedded image","example":"center"},"imageSize":{"type":["number","null"],"minimum":0,"maximum":1,"description":"Size of image relative to QR code (0-1)","example":0.2},"margin":{"type":["number","null"],"description":"Margin around the image in pixels","example":5},"crossOrigin":{"type":["string","null"],"description":"Cross-origin attribute for image","example":"anonymous"},"fill":{"type":["object","null"],"properties":{"color":{"type":["string","null"],"description":"Fill color in CSS format","example":"#ffffff"},"gradient":{"oneOf":[{"$ref":"Gradient"},{"type":"null"}],"description":"Gradient for fill"}},"description":"Fill options for image area"}},"description":"Options for embedded image"},"borderOptions":{"type":["object","null"],"properties":{"hasBorder":{"type":["boolean","null"],"description":"Whether to show border","example":true},"thickness":{"type":["number","null"],"description":"Border thickness in pixels","example":2},"color":{"type":["string","null"],"description":"Border color in CSS format","example":"#000000"},"radius":{"type":["string","null"],"description":"Border radius in CSS format","example":"10px"},"noBorderThickness":{"type":["number","null"],"description":"Thickness when no border is shown","example":0},"background":{"type":["string","null"],"description":"Border background color in CSS format","example":"#ffffff"},"inner":{"type":["object","null"],"properties":{"radius":{"type":["string","null"],"description":"Inner radius in CSS format","example":"5px"},"scale":{"type":["number","null"],"minimum":0,"maximum":1.5,"description":"Inner scale factor (0-1.5)","example":1},"horizontalOffset":{"type":["number","null"],"description":"Inner horizontal offset in pixels","example":0},"verticalOffset":{"type":["number","null"],"description":"Inner vertical offset in pixels","example":0}},"description":"Inner border configuration"},"borderOuter":{"oneOf":[{"$ref":"BorderInnerOuter"},{"type":"null"}],"description":"Outer border configuration"},"borderInner":{"oneOf":[{"$ref":"BorderInnerOuter"},{"type":"null"}],"description":"Inner border configuration"},"decorations":{"type":["object","null"],"properties":{"top":{"oneOf":[{"$ref":"DecorationOptions"},{"type":"null"}],"description":"Top decoration configuration"},"right":{"oneOf":[{"$ref":"DecorationOptions"},{"type":"null"}],"description":"Right decoration configuration"},"bottom":{"oneOf":[{"$ref":"DecorationOptions"},{"type":"null"}],"description":"Bottom decoration configuration"},"left":{"oneOf":[{"$ref":"DecorationOptions"},{"type":"null"}],"description":"Left decoration configuration"}},"description":"Border decorations configuration"}},"description":"Border configuration options"}},"description":"Complete configuration for QR code generation"}}},
{"type":"string"},
{"type":"null"}
]
// Border ID to apply to the QR code
borderId?: string | null
// Border object with options or border ID string
border?: anyOf: [
{"type":["object","null"],"properties":{"options":{"oneOf":[{"$ref":"BorderOptions"},{"type":"null"}]}}},
{"type":"string"},
{"type":"null"}
]
// Text ID to apply to the QR code
textId?: string | null
// Text object with options or text ID string
text?: anyOf: [
{"type":["object","null"],"properties":{"options":{"oneOf":[{"$ref":"TextOptions"},{"type":"null"}]}}},
{"type":"string"},
{"type":"null"}
]
}
Responses
- 200 Generated QR Code file content
type: image/png
{
"type": "string",
"format": "binary"
}
type: image/svg+xml
{
"type": "string",
"format": "binary"
}
type: application/pdf
{
"type": "string",
"format": "binary"
}
- 400 Invalid input data
// Validation error response message
{
message: string
errors?: []
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization or code not found.
// Organization or code not found.
anyOf: [
{"$ref":"CodeNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: CodeNotFoundMessage OrganizationNotFoundMessage
Validate QR Code Options
POST /codes/validate
Validates QR Code styling options without generating or saving the QR Code
- Security: bearerAuth
RequestBody
{
// QR code data content
data?: string
// QR code generation options
options?: {
// Overall shape of the QR code
shape?: enum[square, circle, ]
// Margin around the QR code in pixels
margin?: number | null
// Whether QR code is responsive
isResponsive?: boolean | null
// Scale factor for QR code (0-1.5)
scale?: number | null
// General offset in pixels
offset?: number | null
// Vertical offset in pixels
verticalOffset?: number | null
// Horizontal offset in pixels
horizontalOffset?: number | null
// QR code specific options
qrOptions?: object | null
// Options for QR code dots
dotsOptions?: object | null
// Options for QR code corner squares
cornersSquareOptions?: object | null
// Options for QR code corner dots
cornersDotOptions?: object | null
// Options for QR code background or false to disable
backgroundOptions?: anyOf: [
{"type":"object","properties":{"color":{"type":["string","null"],"description":"Background color in CSS format","example":"#ffffff"},"round":{"anyOf":[{"type":"number","minimum":0,"maximum":1},{"type":"string"},{"type":"null"}],"description":"Background corner rounding (0-1 or CSS value)","example":0.1},"gradient":{"oneOf":[{"$ref":"Gradient"},{"type":"null"}],"description":"Gradient for background"}},"required":["color"]},
{"type":"boolean","const":false}
]
// Image to embed in the QR code (URL, Buffer, or Blob)
image?: anyOf: [
{"type":"string"},
{},
{},
{"type":"null"}
]
// Options for embedded image
imageOptions?: object | null
// Border configuration options
borderOptions?: object | null
// Data to encode in the QR code (optional in this context)
data?: string
}
// Style ID to apply to the QR code
styleId?: string | null
// Style object with options or style name string
style?: anyOf: [
{"type":["object","null"],"properties":{"options":{"oneOf":[{"$ref":"StyleOptions"},{"type":"null"}]}}},
{"type":"string"},
{"type":"null"}
]
// Template ID to apply to the QR code
templateId?: string | null
// Template object with options or template ID string
template?: anyOf: [
{"type":["object","null"],"properties":{"options":{"type":["object","null"],"properties":{"shape":{"type":["string","null"],"enum":["square","circle",null],"description":"Overall shape of the QR code","example":"square"},"margin":{"type":["number","null"],"description":"Margin around the QR code in pixels","example":10},"isResponsive":{"type":["boolean","null"],"description":"Whether QR code is responsive","example":true},"scale":{"type":["number","null"],"minimum":0,"maximum":1.5,"description":"Scale factor for QR code (0-1.5)","example":1},"offset":{"type":["number","null"],"description":"General offset in pixels","example":0},"verticalOffset":{"type":["number","null"],"description":"Vertical offset in pixels","example":0},"horizontalOffset":{"type":["number","null"],"description":"Horizontal offset in pixels","example":0},"qrOptions":{"type":["object","null"],"properties":{"typeNumber":{"type":["number","null"],"minimum":0,"maximum":40,"description":"QR code type number (0-40)","example":0},"mode":{"type":"string","enum":["numeric","alphanumeric","byte","kanji","unicode"],"description":"QR code encoding mode","example":"byte"},"errorCorrectionLevel":{"type":["string","null"],"enum":["L","M","Q","H",null],"description":"Error correction level","example":"M"}},"description":"QR code specific options"},"dotsOptions":{"type":["object","null"],"properties":{"type":{"type":["string","null"],"enum":["dot","square","rounded","extra-rounded","classy","classy-rounded","vertical-line","horizontal-line","random-dot","small-square","tiny-square","star","plus","diamond",null],"description":"Type of dots","example":"rounded"},"color":{"type":["string","null"],"description":"Color of dots in CSS format","example":"#000000"},"size":{"type":["number","null"],"description":"Size of dots relative to module size (0-1)","example":0.5},"gradient":{"oneOf":[{"$ref":"Gradient"},{"type":"null"}],"description":"Gradient for dots"}},"description":"Options for QR code dots"},"cornersSquareOptions":{"type":["object","null"],"properties":{"type":{"type":["string","null"],"enum":["dot","square","rounded","classy","outpoint","inpoint",null],"description":"Type of corner squares","example":"square"},"color":{"type":["string","null"],"description":"Color of corner squares in CSS format","example":"#000000"},"gradient":{"oneOf":[{"$ref":"Gradient"},{"type":"null"}],"description":"Gradient for corner squares"}},"description":"Options for QR code corner squares"},"cornersDotOptions":{"type":["object","null"],"properties":{"type":{"type":["string","null"],"enum":["dot","square","heart","rounded","classy","outpoint","inpoint",null],"description":"Type of corner dots","example":"dot"},"color":{"type":["string","null"],"description":"Color of corner dots in CSS format","example":"#000000"},"gradient":{"oneOf":[{"$ref":"Gradient"},{"type":"null"}],"description":"Gradient for corner dots"}},"description":"Options for QR code corner dots"},"backgroundOptions":{"anyOf":[{"type":"object","properties":{"color":{"type":["string","null"],"description":"Background color in CSS format","example":"#ffffff"},"round":{"anyOf":[{"type":"number","minimum":0,"maximum":1},{"type":"string"},{"type":"null"}],"description":"Background corner rounding (0-1 or CSS value)","example":0.1},"gradient":{"oneOf":[{"$ref":"Gradient"},{"type":"null"}],"description":"Gradient for background"}},"required":["color"]},{"type":"boolean","const":false}],"description":"Options for QR code background or false to disable"},"image":{"anyOf":[{"type":"string"},{},{},{"type":"null"}],"description":"Image to embed in the QR code (URL, Buffer, or Blob)","example":"https://example.com/logo.png"},"imageOptions":{"type":["object","null"],"properties":{"mode":{"type":["string","null"],"enum":["center","overlay","background",null],"description":"Mode for embedded image","example":"center"},"imageSize":{"type":["number","null"],"minimum":0,"maximum":1,"description":"Size of image relative to QR code (0-1)","example":0.2},"margin":{"type":["number","null"],"description":"Margin around the image in pixels","example":5},"crossOrigin":{"type":["string","null"],"description":"Cross-origin attribute for image","example":"anonymous"},"fill":{"type":["object","null"],"properties":{"color":{"type":["string","null"],"description":"Fill color in CSS format","example":"#ffffff"},"gradient":{"oneOf":[{"$ref":"Gradient"},{"type":"null"}],"description":"Gradient for fill"}},"description":"Fill options for image area"}},"description":"Options for embedded image"},"borderOptions":{"type":["object","null"],"properties":{"hasBorder":{"type":["boolean","null"],"description":"Whether to show border","example":true},"thickness":{"type":["number","null"],"description":"Border thickness in pixels","example":2},"color":{"type":["string","null"],"description":"Border color in CSS format","example":"#000000"},"radius":{"type":["string","null"],"description":"Border radius in CSS format","example":"10px"},"noBorderThickness":{"type":["number","null"],"description":"Thickness when no border is shown","example":0},"background":{"type":["string","null"],"description":"Border background color in CSS format","example":"#ffffff"},"inner":{"type":["object","null"],"properties":{"radius":{"type":["string","null"],"description":"Inner radius in CSS format","example":"5px"},"scale":{"type":["number","null"],"minimum":0,"maximum":1.5,"description":"Inner scale factor (0-1.5)","example":1},"horizontalOffset":{"type":["number","null"],"description":"Inner horizontal offset in pixels","example":0},"verticalOffset":{"type":["number","null"],"description":"Inner vertical offset in pixels","example":0}},"description":"Inner border configuration"},"borderOuter":{"oneOf":[{"$ref":"BorderInnerOuter"},{"type":"null"}],"description":"Outer border configuration"},"borderInner":{"oneOf":[{"$ref":"BorderInnerOuter"},{"type":"null"}],"description":"Inner border configuration"},"decorations":{"type":["object","null"],"properties":{"top":{"oneOf":[{"$ref":"DecorationOptions"},{"type":"null"}],"description":"Top decoration configuration"},"right":{"oneOf":[{"$ref":"DecorationOptions"},{"type":"null"}],"description":"Right decoration configuration"},"bottom":{"oneOf":[{"$ref":"DecorationOptions"},{"type":"null"}],"description":"Bottom decoration configuration"},"left":{"oneOf":[{"$ref":"DecorationOptions"},{"type":"null"}],"description":"Left decoration configuration"}},"description":"Border decorations configuration"}},"description":"Border configuration options"}},"description":"Complete configuration for QR code generation"}}},
{"type":"string"},
{"type":"null"}
]
// Border ID to apply to the QR code
borderId?: string | null
// Border object with options or border ID string
border?: anyOf: [
{"type":["object","null"],"properties":{"options":{"oneOf":[{"$ref":"BorderOptions"},{"type":"null"}]}}},
{"type":"string"},
{"type":"null"}
]
// Text ID to apply to the QR code
textId?: string | null
// Text object with options or text ID string
text?: anyOf: [
{"type":["object","null"],"properties":{"options":{"oneOf":[{"$ref":"TextOptions"},{"type":"null"}]}}},
{"type":"string"},
{"type":"null"}
]
}
Responses
- 200 Validation result
{
// Whether the QR code options are valid
isValid: boolean
}
- 400 Invalid request to validate QR Code options.
// Error response for validation failures
{
message: string
errors?: []
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 QR Codeor Organization not found.
// QR Codeor Organization not found.
anyOf: [
{"$ref":"OrganizationNotFoundMessage"},
{"$ref":"CodeNotFoundMessage"}
]
Schemas: OrganizationNotFoundMessage CodeNotFoundMessage
Validate Existing QR Code
POST /codes/{codeId}/validate
Validates an existing QR Code and updates its validation status in the database
- Security: bearerAuth
Responses
- 200 Validation result with detailed information
{
// Unique identifier for the QR code
id: string
// Whether the QR code is valid
isValid: boolean
// Detailed validation results
validationDetails: {
// Boolean indicating if the QR code uses inverted colors
isInverted: boolean
// The decoded data from the QR code
data?: string | null
// Validation message explaining the result
message: string
// Number of decoding attempts made
attempts?: number | null
// Identifier of the validation method used
validator: string
}
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization or code not found.
// Organization or code not found.
anyOf: [
{"$ref":"CodeNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: CodeNotFoundMessage OrganizationNotFoundMessage
Bulk Refresh QR Code Links
POST /codes/links/refresh
Refreshes QR code links/files for all code versions matching the specified design element filters
- Security: bearerAuth
Responses
- 200 Bulk link refresh completed
{
// Whether the operation was successful
success: boolean
// Summary of the regeneration operation
summary: {
// Number of code versions processed
codeVersionsProcessed: number
// Number of files regenerated
filesRegenerated: number
// Number of errors encountered
errors: number
}
}
- 400 Invalid request to refresh links.
// Error response for validation failures
{
message: string
errors?: []
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization not found.
// Indicates that the organization context was not found or is invalid
{
// The specified organization could not be found or is not accessible
message: string
}
Get QR Code version
GET /codes/{codeId}/version/{version}
Retrieves a specific version of a QR Code by ID and version number
- Security: bearerAuth
Responses
- 200 The requested QR Code version version
// QR code response with audit information and file links
allOf: [
{"$ref":"BaseCodeResponseWithAudit"}
]
Schemas: BaseCodeResponseWithAudit
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Code, version or Organization not found.
// Code, version or Organization not found.
anyOf: [
{"$ref":"CodeNotFoundMessage"},
{"$ref":"VersionNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: CodeNotFoundMessage VersionNotFoundMessage OrganizationNotFoundMessage
List QR Code versions
GET /codes/{codeId}/versions
Retrieves all versions of a QR Code by its unique identifier
- Security: bearerAuth
Responses
- 200 A paginated list of QR Code versions
// Paginated list response
{
// Pagination metadata
pagination: {
// Total number of items matching the filter criteria
total: number
// Current page number
page: number
// Number of items per page
limit: number
// Total number of pages
totalPages: number
}
data: []
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization or code not found, or code has no versions.
// Organization or code not found, or code has no versions.
anyOf: [
{"$ref":"EmptyArrayResponse"},
{"$ref":"CodeNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: EmptyArrayResponse CodeNotFoundMessage OrganizationNotFoundMessage
Delete All QR Code Versions
DELETE /codes/{codeId}/versions
Deletes all versions of a QR Code except the current one
- Security: bearerAuth
Responses
- 200 All versions deleted successfully
{
// Confirmation message
message: string
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization or code not found.
// Organization or code not found.
anyOf: [
{"$ref":"CodeNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: CodeNotFoundMessage OrganizationNotFoundMessage
Restore QR Code Version
POST /codes/{codeId}/version/{version}/restore
Restores a specific version of a QR Code as the current version
- Security: bearerAuth
Responses
- 200 QR Code version restored successfully
// QR code response with audit information and file links
allOf: [
{"$ref":"BaseCodeResponseWithAudit"}
]
Schemas: BaseCodeResponseWithAudit
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization, code, or version not found.
// Organization, code, or version not found.
anyOf: [
{"$ref":"CodeNotFoundMessage"},
{"$ref":"VersionNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: CodeNotFoundMessage VersionNotFoundMessage OrganizationNotFoundMessage
Get QR Code Version File Content
GET /codes/{codeId}/version/{version}/{type}
Retrieves the file content of a specific QR Code version
- Security: bearerAuth
Responses
- 200 File content for the QR Code version
type: image/svg+xml
{
"type": "string",
"format": "binary"
}
type: image/png
{
"type": "string",
"format": "binary"
}
type: application/pdf
{
"type": "string",
"format": "binary"
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Code, version or Organization not found.
// Code, version or Organization not found.
anyOf: [
{"$ref":"CodeNotFoundMessage"},
{"$ref":"VersionNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: CodeNotFoundMessage VersionNotFoundMessage OrganizationNotFoundMessage
Get QR Code Version Link
GET /codes/{codeId}/version/{version}/{type}/link
Retrieves a link to the file representation of a specific QR Code version
- Security: bearerAuth
Responses
- 200 Link to the file for the QR Code version
{
// URL to access the generated file
url: string
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization, code, version, or link not found.
// Organization, code, version, or link not found.
anyOf: [
{"$ref":"CodeNotFoundMessage"},
{"$ref":"VersionNotFoundMessage"},
{"$ref":"LinkNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: CodeNotFoundMessage VersionNotFoundMessage LinkNotFoundMessage OrganizationNotFoundMessage
Delete QR Code version links
DELETE /codes/{codeId}/versions/{version}/links
Deletes all QR Code version links for a specific version of a QR Code
- Security: bearerAuth
Responses
- 200 QR Code version links deleted successfully
// Success response message
{
message: string
}
- 400 Invalid request to delete code version links.
// Error response for validation failures
{
message: string
errors?: []
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization, code, or version not found.
// Organization, code, or version not found.
anyOf: [
{"$ref":"CodeNotFoundMessage"},
{"$ref":"VersionNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: CodeNotFoundMessage VersionNotFoundMessage OrganizationNotFoundMessage
Delete QR Code version link by Type
DELETE /codes/{codeId}/versions/{version}/links/{type}
Deletes a specific QR Code version link for a specific version of a QR Code
- Security: bearerAuth
Responses
- 200 QR Code version link deleted successfully
// Success response message
{
message: string
}
- 400 Invalid request to delete code version link by type.
// Invalid request to delete code version link by type.
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"CodeVersionLinkNotFoundForTypeMessage"}
]
Schemas: ValidationErrorMessage CodeVersionLinkNotFoundForTypeMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization, code, version, or link not found.
// Organization, code, version, or link not found.
anyOf: [
{"$ref":"CodeNotFoundMessage"},
{"$ref":"VersionNotFoundMessage"},
{"$ref":"LinkNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: CodeNotFoundMessage VersionNotFoundMessage LinkNotFoundMessage OrganizationNotFoundMessage
Delete All QR Code Versions Links
DELETE /codes/{codeId}/versions/links
Deletes all file links for all versions of a QR Code
- Security: bearerAuth
Responses
- 200 QR Code version links deleted successfully
// Success response message
{
message: string
}
- 400 Invalid request to delete all code versions links.
// Invalid request to delete all code versions links.
anyOf: [
{"$ref":"CodeNoVersionsFoundForLinkDeletionMessage"},
{"$ref":"CodeNoLinksOfTypeFoundForAnyVersionMessage"}
]
Schemas: CodeNoVersionsFoundForLinkDeletionMessage CodeNoLinksOfTypeFoundForAnyVersionMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization or code not found.
// Organization or code not found.
anyOf: [
{"$ref":"CodeNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: CodeNotFoundMessage OrganizationNotFoundMessage
Delete All QR Code Versions Links by Type
DELETE /codes/{codeId}/versions/links/{type}
Deletes a specific file type link for all versions of a QR Code
- Security: bearerAuth
Responses
- 200 QR Code version links deleted successfully
// Success response message
{
message: string
}
- 400 Invalid request to delete all code versions links by type.
// Invalid request to delete all code versions links by type.
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"CodeNoVersionsFoundForLinkDeletionMessage"},
{"$ref":"CodeNoLinksOfTypeFoundForAnyVersionMessage"}
]
Schemas: ValidationErrorMessage CodeNoVersionsFoundForLinkDeletionMessage CodeNoLinksOfTypeFoundForAnyVersionMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization or code not found.
// Organization or code not found.
anyOf: [
{"$ref":"CodeNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: CodeNotFoundMessage OrganizationNotFoundMessage
Get QR Code File Content (SVG, PNG, PDF)
GET /codes/{codeId}/{type}
Retrieves the SVG, PNG, or PDF representation of a QR Code
- Security: bearerAuth
Responses
- 200 SVG, PNG, or PDF content for the QR Code
type: image/svg+xml
{
"type": "string",
"format": "binary"
}
type: image/png
{
"type": "string",
"format": "binary"
}
type: application/pdf
{
"type": "string",
"format": "binary"
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization or code not found.
// Organization or code not found.
anyOf: [
{"$ref":"CodeNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: CodeNotFoundMessage OrganizationNotFoundMessage
Get QR Code link
GET /codes/{codeId}/{type}/link
Retrieves a link to the SVG, PNG, or PDF representation of a QR Code
- Security: bearerAuth
Responses
- 200 Link to the SVG, PNG, or PDF file for the QR Code
{
// URL to access the generated file
url: string
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization or code not found.
// Organization or code not found.
anyOf: [
{"$ref":"CodeNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: CodeNotFoundMessage OrganizationNotFoundMessage
Delete QR Code links
DELETE /codes/{codeId}/links
Deletes all links for the current version of a QR Code
- Security: bearerAuth
Responses
- 200 QR Code links deleted successfully
// Success response message
{
message: string
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization or code not found.
// Organization or code not found.
anyOf: [
{"$ref":"CodeNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: CodeNotFoundMessage OrganizationNotFoundMessage
Delete QR Code link by Type
DELETE /codes/{codeId}/links/{type}
Deletes a specific file type link for the current version of a QR Code
- Security: bearerAuth
Responses
- 200 QR Code link deleted successfully
// Success response message
{
message: string
}
- 400 Invalid input data
// Validation error response message
{
message: string
errors?: []
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization, code, or link not found.
// Organization, code, or link not found.
anyOf: [
{"$ref":"CodeNotFoundMessage"},
{"$ref":"LinkNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: CodeNotFoundMessage LinkNotFoundMessage OrganizationNotFoundMessage
Create a new template
POST /templates
Creates a new QR code template for an organization or workspace.
RequestBody
// Base template schema
{
// Name of the template
name: string
// Description of the template
description?: string
// QR code options for the template (without data field)
options: {
// Overall shape of the QR code
shape?: enum[square, circle, ]
// Margin around the QR code in pixels
margin?: number | null
// Whether QR code is responsive
isResponsive?: boolean | null
// Scale factor for QR code (0-1.5)
scale?: number | null
// General offset in pixels
offset?: number | null
// Vertical offset in pixels
verticalOffset?: number | null
// Horizontal offset in pixels
horizontalOffset?: number | null
// QR code specific options
qrOptions?: object | null
// Options for QR code dots
dotsOptions?: object | null
// Options for QR code corner squares
cornersSquareOptions?: object | null
// Options for QR code corner dots
cornersDotOptions?: object | null
// Options for QR code background or false to disable
backgroundOptions?: anyOf: [
{"type":"object","properties":{"color":{"type":["string","null"],"description":"Background color in CSS format","example":"#ffffff"},"round":{"anyOf":[{"type":"number","minimum":0,"maximum":1},{"type":"string"},{"type":"null"}],"description":"Background corner rounding (0-1 or CSS value)","example":0.1},"gradient":{"oneOf":[{"$ref":"Gradient"},{"type":"null"}],"description":"Gradient for background"}},"required":["color"]},
{"type":"boolean","const":false}
]
// Image to embed in the QR code (URL, Buffer, or Blob)
image?: anyOf: [
{"type":"string"},
{},
{},
{"type":"null"}
]
// Options for embedded image
imageOptions?: object | null
// Border configuration options
borderOptions?: object | null
}
// Custom metadata for the template as JSON object
metadata?: object | null
// Workspace ID if the template is workspace-specific
workspaceId?: string | null
}
Responses
- 201 Template created successfully
// Response schema for a template
{
// Unique identifier for the template
id: string
// Name of the template
name: string
// Description of the template
description?: string | null
// QR code options for the template (without data field)
options: {
// Overall shape of the QR code
shape?: enum[square, circle, ]
// Margin around the QR code in pixels
margin?: number | null
// Whether QR code is responsive
isResponsive?: boolean | null
// Scale factor for QR code (0-1.5)
scale?: number | null
// General offset in pixels
offset?: number | null
// Vertical offset in pixels
verticalOffset?: number | null
// Horizontal offset in pixels
horizontalOffset?: number | null
// QR code specific options
qrOptions?: object | null
// Options for QR code dots
dotsOptions?: object | null
// Options for QR code corner squares
cornersSquareOptions?: object | null
// Options for QR code corner dots
cornersDotOptions?: object | null
// Options for QR code background or false to disable
backgroundOptions?: anyOf: [
{"type":"object","properties":{"color":{"type":["string","null"],"description":"Background color in CSS format","example":"#ffffff"},"round":{"anyOf":[{"type":"number","minimum":0,"maximum":1},{"type":"string"},{"type":"null"}],"description":"Background corner rounding (0-1 or CSS value)","example":0.1},"gradient":{"oneOf":[{"$ref":"Gradient"},{"type":"null"}],"description":"Gradient for background"}},"required":["color"]},
{"type":"boolean","const":false}
]
// Image to embed in the QR code (URL, Buffer, or Blob)
image?: anyOf: [
{"type":"string"},
{},
{},
{"type":"null"}
]
// Options for embedded image
imageOptions?: object | null
// Border configuration options
borderOptions?: object | null
}
// Custom metadata for the template as JSON object
metadata: object | null
// Workspace ID if the template is workspace-specific
workspaceId?: string | null
// User who created the resource
createdByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// User who last updated the resource
updatedByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// API key used to create the resource
createdByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// API key used to last update the resource
updatedByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// When the resource was created
createdAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
// When the resource was last updated
updatedAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
}
Schemas: AuditInfoMember AuditInfoApiKey
- 400 Bad Request when creating template
// Bad Request when creating template
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"OptionsRequiredMessage"},
{"$ref":"TemplateNameTakenMessage"}
]
Schemas: ValidationErrorMessage OptionsRequiredMessage TemplateNameTakenMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Could not create template due to missing resources.
// Could not create template due to missing resources.
anyOf: [
{"$ref":"OrganizationNotFoundMessage"},
{"$ref":"WorkspaceNotFoundMessage"}
]
Schemas: OrganizationNotFoundMessage WorkspaceNotFoundMessage
List all templates
GET /templates
Retrieves all templates available to the user, grouped by organization and workspace.
Parameters(Query)
// Filter by template name
name?: string
Responses
- 200 List of templates
// Response schema for getting templates
{
organizations: []
workspaces: TemplateResponse[]
}
Schemas: TemplateResponse
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization not found, no templates available, or the list of templates is empty.
// Organization not found, no templates available, or the list of templates is empty.
anyOf: [
{"$ref":"EmptyTemplatesOrgContextResponse"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: EmptyTemplatesOrgContextResponse OrganizationNotFoundMessage
List base templates
GET /templates/base
Retrieves all base templates from the QRCodeJs library with optional name filtering.
Parameters(Query)
name?: string
Responses
- 200 List of base templates
[]
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
Get template by ID
GET /templates/{templateId}
Retrieves a template by its unique identifier.
Responses
- 200 Template details
// Response schema for a template
{
// Unique identifier for the template
id: string
// Name of the template
name: string
// Description of the template
description?: string | null
// QR code options for the template (without data field)
options: {
// Overall shape of the QR code
shape?: enum[square, circle, ]
// Margin around the QR code in pixels
margin?: number | null
// Whether QR code is responsive
isResponsive?: boolean | null
// Scale factor for QR code (0-1.5)
scale?: number | null
// General offset in pixels
offset?: number | null
// Vertical offset in pixels
verticalOffset?: number | null
// Horizontal offset in pixels
horizontalOffset?: number | null
// QR code specific options
qrOptions?: object | null
// Options for QR code dots
dotsOptions?: object | null
// Options for QR code corner squares
cornersSquareOptions?: object | null
// Options for QR code corner dots
cornersDotOptions?: object | null
// Options for QR code background or false to disable
backgroundOptions?: anyOf: [
{"type":"object","properties":{"color":{"type":["string","null"],"description":"Background color in CSS format","example":"#ffffff"},"round":{"anyOf":[{"type":"number","minimum":0,"maximum":1},{"type":"string"},{"type":"null"}],"description":"Background corner rounding (0-1 or CSS value)","example":0.1},"gradient":{"oneOf":[{"$ref":"Gradient"},{"type":"null"}],"description":"Gradient for background"}},"required":["color"]},
{"type":"boolean","const":false}
]
// Image to embed in the QR code (URL, Buffer, or Blob)
image?: anyOf: [
{"type":"string"},
{},
{},
{"type":"null"}
]
// Options for embedded image
imageOptions?: object | null
// Border configuration options
borderOptions?: object | null
}
// Custom metadata for the template as JSON object
metadata: object | null
// Workspace ID if the template is workspace-specific
workspaceId?: string | null
// User who created the resource
createdByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// User who last updated the resource
updatedByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// API key used to create the resource
createdByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// API key used to last update the resource
updatedByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// When the resource was created
createdAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
// When the resource was last updated
updatedAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
}
Schemas: AuditInfoMember AuditInfoApiKey
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization or template not found.
// Organization or template not found.
anyOf: [
{"$ref":"TemplateNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: TemplateNotFoundMessage OrganizationNotFoundMessage
Update template by ID
PUT /templates/{templateId}
Updates a template by its unique identifier.
RequestBody
// Schema for updating a template
{
// Name of the template
name?: string
// Description of the template
description?: string
// QR code options for the template (without data field)
options?: {
// Overall shape of the QR code
shape?: enum[square, circle, ]
// Margin around the QR code in pixels
margin?: number | null
// Whether QR code is responsive
isResponsive?: boolean | null
// Scale factor for QR code (0-1.5)
scale?: number | null
// General offset in pixels
offset?: number | null
// Vertical offset in pixels
verticalOffset?: number | null
// Horizontal offset in pixels
horizontalOffset?: number | null
// QR code specific options
qrOptions?: object | null
// Options for QR code dots
dotsOptions?: object | null
// Options for QR code corner squares
cornersSquareOptions?: object | null
// Options for QR code corner dots
cornersDotOptions?: object | null
// Options for QR code background or false to disable
backgroundOptions?: anyOf: [
{"type":"object","properties":{"color":{"type":["string","null"],"description":"Background color in CSS format","example":"#ffffff"},"round":{"anyOf":[{"type":"number","minimum":0,"maximum":1},{"type":"string"},{"type":"null"}],"description":"Background corner rounding (0-1 or CSS value)","example":0.1},"gradient":{"oneOf":[{"$ref":"Gradient"},{"type":"null"}],"description":"Gradient for background"}},"required":["color"]},
{"type":"boolean","const":false}
]
// Image to embed in the QR code (URL, Buffer, or Blob)
image?: anyOf: [
{"type":"string"},
{},
{},
{"type":"null"}
]
// Options for embedded image
imageOptions?: object | null
// Border configuration options
borderOptions?: object | null
}
// Updated custom metadata for the template as JSON object
metadata?: object | null
}
Responses
- 200 Template updated successfully
// Response schema for a template
{
// Unique identifier for the template
id: string
// Name of the template
name: string
// Description of the template
description?: string | null
// QR code options for the template (without data field)
options: {
// Overall shape of the QR code
shape?: enum[square, circle, ]
// Margin around the QR code in pixels
margin?: number | null
// Whether QR code is responsive
isResponsive?: boolean | null
// Scale factor for QR code (0-1.5)
scale?: number | null
// General offset in pixels
offset?: number | null
// Vertical offset in pixels
verticalOffset?: number | null
// Horizontal offset in pixels
horizontalOffset?: number | null
// QR code specific options
qrOptions?: object | null
// Options for QR code dots
dotsOptions?: object | null
// Options for QR code corner squares
cornersSquareOptions?: object | null
// Options for QR code corner dots
cornersDotOptions?: object | null
// Options for QR code background or false to disable
backgroundOptions?: anyOf: [
{"type":"object","properties":{"color":{"type":["string","null"],"description":"Background color in CSS format","example":"#ffffff"},"round":{"anyOf":[{"type":"number","minimum":0,"maximum":1},{"type":"string"},{"type":"null"}],"description":"Background corner rounding (0-1 or CSS value)","example":0.1},"gradient":{"oneOf":[{"$ref":"Gradient"},{"type":"null"}],"description":"Gradient for background"}},"required":["color"]},
{"type":"boolean","const":false}
]
// Image to embed in the QR code (URL, Buffer, or Blob)
image?: anyOf: [
{"type":"string"},
{},
{},
{"type":"null"}
]
// Options for embedded image
imageOptions?: object | null
// Border configuration options
borderOptions?: object | null
}
// Custom metadata for the template as JSON object
metadata: object | null
// Workspace ID if the template is workspace-specific
workspaceId?: string | null
// User who created the resource
createdByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// User who last updated the resource
updatedByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// API key used to create the resource
createdByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// API key used to last update the resource
updatedByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// When the resource was created
createdAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
// When the resource was last updated
updatedAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
}
Schemas: AuditInfoMember AuditInfoApiKey
- 400 Bad Request when updating template
// Bad Request when updating template
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"UpdateFieldRequiredMessage"},
{"$ref":"TemplateNameTakenMessage"}
]
Schemas: ValidationErrorMessage UpdateFieldRequiredMessage TemplateNameTakenMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization or template not found.
// Organization or template not found.
anyOf: [
{"$ref":"TemplateNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: TemplateNotFoundMessage OrganizationNotFoundMessage
Delete template by ID
DELETE /templates/{templateId}
Deletes a template by its unique identifier. Fails if the template is used by codes.
Responses
- 200 Template deleted successfully
{
message: string
}
- 400 Bad Request when deleting template
// Error response when a resource cannot be modified/deleted because it is in use
{
message: string
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization or template not found.
// Organization or template not found.
anyOf: [
{"$ref":"TemplateNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: TemplateNotFoundMessage OrganizationNotFoundMessage
Partially update template options by ID
PUT /templates/{templateId}/options
Partially updates a template options by its unique identifier using a deep merge. Use null to delete a field.
RequestBody
{
// Partial QR code options for the template (without data field) to update. All fields are optional. Use null as a value to delete a field. At least one option field must be provided.
options: {
// Shape of the QR code
shape?: enum[square, circle, ]
margin?: number | null
isResponsive?: boolean | null
scale?: number | null
offset?: number | null
verticalOffset?: number | null
horizontalOffset?: number | null
qrOptions?: object | null
dotsOptions?: object | null
cornersSquareOptions?: object | null
cornersDotOptions?: object | null
backgroundOptions?: anyOf: [
{"type":"object","properties":{"color":{"type":["string","null"],"description":"Background color in CSS format","example":"#ffffff"},"round":{"anyOf":[{"type":"number","minimum":0,"maximum":1},{"type":"string"},{"type":"null"}],"description":"Background corner rounding (0-1 or CSS value)","example":0.1},"gradient":{"oneOf":[{"$ref":"Gradient"},{"type":"null"}],"description":"Gradient for background"}},"required":["color"]},
{"type":"boolean","const":false}
]
image?: anyOf: [
{"type":"string"},
{},
{},
{"type":"null"}
]
imageOptions?: object | null
borderOptions?: object | null
}
}
Responses
- 200 Template options updated successfully
// Response schema for a template
{
// Unique identifier for the template
id: string
// Name of the template
name: string
// Description of the template
description?: string | null
// QR code options for the template (without data field)
options: {
// Overall shape of the QR code
shape?: enum[square, circle, ]
// Margin around the QR code in pixels
margin?: number | null
// Whether QR code is responsive
isResponsive?: boolean | null
// Scale factor for QR code (0-1.5)
scale?: number | null
// General offset in pixels
offset?: number | null
// Vertical offset in pixels
verticalOffset?: number | null
// Horizontal offset in pixels
horizontalOffset?: number | null
// QR code specific options
qrOptions?: object | null
// Options for QR code dots
dotsOptions?: object | null
// Options for QR code corner squares
cornersSquareOptions?: object | null
// Options for QR code corner dots
cornersDotOptions?: object | null
// Options for QR code background or false to disable
backgroundOptions?: anyOf: [
{"type":"object","properties":{"color":{"type":["string","null"],"description":"Background color in CSS format","example":"#ffffff"},"round":{"anyOf":[{"type":"number","minimum":0,"maximum":1},{"type":"string"},{"type":"null"}],"description":"Background corner rounding (0-1 or CSS value)","example":0.1},"gradient":{"oneOf":[{"$ref":"Gradient"},{"type":"null"}],"description":"Gradient for background"}},"required":["color"]},
{"type":"boolean","const":false}
]
// Image to embed in the QR code (URL, Buffer, or Blob)
image?: anyOf: [
{"type":"string"},
{},
{},
{"type":"null"}
]
// Options for embedded image
imageOptions?: object | null
// Border configuration options
borderOptions?: object | null
}
// Custom metadata for the template as JSON object
metadata: object | null
// Workspace ID if the template is workspace-specific
workspaceId?: string | null
// User who created the resource
createdByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// User who last updated the resource
updatedByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// API key used to create the resource
createdByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// API key used to last update the resource
updatedByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// When the resource was created
createdAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
// When the resource was last updated
updatedAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
}
Schemas: AuditInfoMember AuditInfoApiKey
- 400 Bad Request when updating template options
// Bad Request when updating template options
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"UpdateOptionsFieldRequiredMessage"}
]
Schemas: ValidationErrorMessage UpdateOptionsFieldRequiredMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization or template not found.
// Organization or template not found.
anyOf: [
{"$ref":"TemplateNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: TemplateNotFoundMessage OrganizationNotFoundMessage
List templates for a workspace
GET /templates/workspace/{workspaceId}
Retrieves all templates for a specific workspace.
Parameters(Query)
// Filter by template name
name?: string
Responses
- 200 List of templates for the workspace
[]
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization or workspace not found, or no templates in workspace.
// Organization or workspace not found, or no templates in workspace.
anyOf: [
{"$ref":"EmptyArrayResponse"},
{"$ref":"WorkspaceNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: EmptyArrayResponse WorkspaceNotFoundMessage OrganizationNotFoundMessage
Create a new style
POST /styles
Creates a new style for an organization or workspace.
RequestBody
// Base schema for style definitions
{
// Name of the style
name: string
// Description of the style
description?: string
// Custom metadata for the style as JSON object
metadata?: object | null
// ID of the workspace this style belongs to (null for organization-level styles)
workspaceId?: string | null
}
Responses
- 201 Style created successfully
// Style data returned in API responses
{
// Unique identifier of the style
id: string
// Name of the style
name: string
// Description of the style
description?: string | null
// Style configuration options
options: {
// Primary color for QR code elements in CSS format
primaryColor?: string | null
// Secondary color for QR code elements in CSS format
secondaryColor?: string | null
// Tertiary color for QR code elements in CSS format
thirdColor?: string | null
// Background color of the QR code in CSS format
backgroundColor?: string | null
// Gradient configuration for QR code dots
dotsGradient?: oneOf: [
{"$ref":"Gradient"},
{"type":"null"}
]
// Gradient configuration for corner dots
cornersDotGradient?: oneOf: [
{"$ref":"Gradient"},
{"type":"null"}
]
// Gradient configuration for corners
cornersGradient?: oneOf: [
{"$ref":"Gradient"},
{"type":"null"}
]
// Gradient configuration for QR code background
backgroundGradient?: oneOf: [
{"$ref":"Gradient"},
{"type":"null"}
]
// Shape style for the QR code dots
dotShape?: enum[dot, square, rounded, extra-rounded, classy, classy-rounded, vertical-line, horizontal-line, random-dot, small-square, tiny-square, star, plus, diamond, ]
// Shape style for the QR code corner squares
cornerSquareShape?: enum[dot, square, rounded, classy, outpoint, inpoint, ]
// Shape style for the QR code corner dots
cornerDotShape?: enum[dot, square, heart, rounded, classy, outpoint, inpoint, ]
// Logo to be placed on the QR code (URL, Base64, Buffer, or Blob)
logo?: anyOf: [
{"type":"string"},
{},
{},
{"type":"null"}
]
// Size of the logo relative to QR code (0-1)
logoSize?: number | null
// Placement mode for the logo
logoMode?: enum[center, overlay, background, ]
// Margin around the logo in pixels
logoMargin?: number | null
// Background color for logo in CSS format
logoBackgroundColor?: string | null
// Padding around the logo in pixels
logoPadding?: number | null
// Border radius for logo in pixels or CSS format
logoRadius?: anyOf: [
{"type":"string"},
{"type":"number"},
{"type":"null"}
]
// Color of the QR code border in CSS format
borderColor?: string | null
// Thickness of the border in pixels
borderThickness?: number | null
// Border radius in pixels or CSS format
borderRadius?: anyOf: [
{"type":"string"},
{"type":"number"},
{"type":"null"}
]
// Color of the inner border in CSS format
borderInnerColor?: string | null
// Thickness of the inner border in pixels
borderInnerThickness?: number | null
// Inner border radius in pixels or CSS format
borderInnerRadius?: anyOf: [
{"type":"string"},
{"type":"number"},
{"type":"null"}
]
// Color of the outer border in CSS format
borderOuterColor?: string | null
// Thickness of the outer border in pixels
borderOuterThickness?: number | null
// Text to display on top border
borderTextTop?: string | null
// Text to display on right border
borderTextRight?: string | null
// Text to display on bottom border
borderTextBottom?: string | null
// Text to display on left border
borderTextLeft?: string | null
// Font family for border text
borderFontFace?: string | null
// Font size for border text in pixels
borderFontSize?: number | null
// Font color for border text in CSS format
borderFontColor?: string | null
// Letter spacing for border text in pixels
borderLetterSpacing?: number | null
// Text transformation for border text
borderTextTransform?: enum[uppercase, lowercase, capitalize, ]
// Font weight for border text
borderFontWeight?: string
}
// Custom metadata for the style as JSON object
metadata: object | null
// ID of the workspace this style belongs to (null for organization-level styles)
workspaceId?: string | null
// User who created the resource
createdByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// User who last updated the resource
updatedByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// API key used to create the resource
createdByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// API key used to last update the resource
updatedByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// When the resource was created
createdAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
// When the resource was last updated
updatedAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
}
Schemas: Gradient AuditInfoMember AuditInfoApiKey
- 400 Bad Request when creating style
// Bad Request when creating style
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"OptionsRequiredMessage"},
{"$ref":"StyleNameTakenMessage"}
]
Schemas: ValidationErrorMessage OptionsRequiredMessage StyleNameTakenMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization or Workspace context not found during style creation.
// Organization or Workspace context not found during style creation.
anyOf: [
{"$ref":"OrganizationNotFoundMessage"},
{"$ref":"WorkspaceNotFoundMessage"}
]
Schemas: OrganizationNotFoundMessage WorkspaceNotFoundMessage
List all styles
GET /styles
Retrieves all styles available to the user.
Parameters(Query)
// Filter by style name
name?: string
Responses
- 200 List of styles
// Response containing organization and workspace styles
{
organizations: []
workspaces: StyleResponse[]
}
Schemas: StyleResponse
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 No styles found for the organization context, or organization context invalid.
// No styles found for the organization context, or organization context invalid.
anyOf: [
{"$ref":"EmptyStylesOrgContextResponse"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: EmptyStylesOrgContextResponse OrganizationNotFoundMessage
List base styles
GET /styles/base
Retrieves all base styles from the QRCodeJs library with optional name filtering.
Parameters(Query)
name?: string
Responses
- 200 List of base styles
[]
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
Get style by ID
GET /styles/{styleId}
Retrieves a style by its unique identifier.
Responses
- 200 Style details
// Style data returned in API responses
{
// Unique identifier of the style
id: string
// Name of the style
name: string
// Description of the style
description?: string | null
// Style configuration options
options: {
// Primary color for QR code elements in CSS format
primaryColor?: string | null
// Secondary color for QR code elements in CSS format
secondaryColor?: string | null
// Tertiary color for QR code elements in CSS format
thirdColor?: string | null
// Background color of the QR code in CSS format
backgroundColor?: string | null
// Gradient configuration for QR code dots
dotsGradient?: oneOf: [
{"$ref":"Gradient"},
{"type":"null"}
]
// Gradient configuration for corner dots
cornersDotGradient?: oneOf: [
{"$ref":"Gradient"},
{"type":"null"}
]
// Gradient configuration for corners
cornersGradient?: oneOf: [
{"$ref":"Gradient"},
{"type":"null"}
]
// Gradient configuration for QR code background
backgroundGradient?: oneOf: [
{"$ref":"Gradient"},
{"type":"null"}
]
// Shape style for the QR code dots
dotShape?: enum[dot, square, rounded, extra-rounded, classy, classy-rounded, vertical-line, horizontal-line, random-dot, small-square, tiny-square, star, plus, diamond, ]
// Shape style for the QR code corner squares
cornerSquareShape?: enum[dot, square, rounded, classy, outpoint, inpoint, ]
// Shape style for the QR code corner dots
cornerDotShape?: enum[dot, square, heart, rounded, classy, outpoint, inpoint, ]
// Logo to be placed on the QR code (URL, Base64, Buffer, or Blob)
logo?: anyOf: [
{"type":"string"},
{},
{},
{"type":"null"}
]
// Size of the logo relative to QR code (0-1)
logoSize?: number | null
// Placement mode for the logo
logoMode?: enum[center, overlay, background, ]
// Margin around the logo in pixels
logoMargin?: number | null
// Background color for logo in CSS format
logoBackgroundColor?: string | null
// Padding around the logo in pixels
logoPadding?: number | null
// Border radius for logo in pixels or CSS format
logoRadius?: anyOf: [
{"type":"string"},
{"type":"number"},
{"type":"null"}
]
// Color of the QR code border in CSS format
borderColor?: string | null
// Thickness of the border in pixels
borderThickness?: number | null
// Border radius in pixels or CSS format
borderRadius?: anyOf: [
{"type":"string"},
{"type":"number"},
{"type":"null"}
]
// Color of the inner border in CSS format
borderInnerColor?: string | null
// Thickness of the inner border in pixels
borderInnerThickness?: number | null
// Inner border radius in pixels or CSS format
borderInnerRadius?: anyOf: [
{"type":"string"},
{"type":"number"},
{"type":"null"}
]
// Color of the outer border in CSS format
borderOuterColor?: string | null
// Thickness of the outer border in pixels
borderOuterThickness?: number | null
// Text to display on top border
borderTextTop?: string | null
// Text to display on right border
borderTextRight?: string | null
// Text to display on bottom border
borderTextBottom?: string | null
// Text to display on left border
borderTextLeft?: string | null
// Font family for border text
borderFontFace?: string | null
// Font size for border text in pixels
borderFontSize?: number | null
// Font color for border text in CSS format
borderFontColor?: string | null
// Letter spacing for border text in pixels
borderLetterSpacing?: number | null
// Text transformation for border text
borderTextTransform?: enum[uppercase, lowercase, capitalize, ]
// Font weight for border text
borderFontWeight?: string
}
// Custom metadata for the style as JSON object
metadata: object | null
// ID of the workspace this style belongs to (null for organization-level styles)
workspaceId?: string | null
// User who created the resource
createdByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// User who last updated the resource
updatedByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// API key used to create the resource
createdByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// API key used to last update the resource
updatedByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// When the resource was created
createdAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
// When the resource was last updated
updatedAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
}
Schemas: Gradient AuditInfoMember AuditInfoApiKey
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Style not found, or its parent organization context is invalid.
// Style not found, or its parent organization context is invalid.
anyOf: [
{"$ref":"StyleNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: StyleNotFoundMessage OrganizationNotFoundMessage
Update style by ID
PUT /styles/{styleId}
Updates a style by its unique identifier.
RequestBody
// Schema for updating an existing style
{
// Updated name of the style
name?: string
// Updated description of the style
description?: string
// Updated custom metadata for the style as JSON object
metadata?: object | null
}
Responses
- 200 Style updated successfully
// Style data returned in API responses
{
// Unique identifier of the style
id: string
// Name of the style
name: string
// Description of the style
description?: string | null
// Style configuration options
options: {
// Primary color for QR code elements in CSS format
primaryColor?: string | null
// Secondary color for QR code elements in CSS format
secondaryColor?: string | null
// Tertiary color for QR code elements in CSS format
thirdColor?: string | null
// Background color of the QR code in CSS format
backgroundColor?: string | null
// Gradient configuration for QR code dots
dotsGradient?: oneOf: [
{"$ref":"Gradient"},
{"type":"null"}
]
// Gradient configuration for corner dots
cornersDotGradient?: oneOf: [
{"$ref":"Gradient"},
{"type":"null"}
]
// Gradient configuration for corners
cornersGradient?: oneOf: [
{"$ref":"Gradient"},
{"type":"null"}
]
// Gradient configuration for QR code background
backgroundGradient?: oneOf: [
{"$ref":"Gradient"},
{"type":"null"}
]
// Shape style for the QR code dots
dotShape?: enum[dot, square, rounded, extra-rounded, classy, classy-rounded, vertical-line, horizontal-line, random-dot, small-square, tiny-square, star, plus, diamond, ]
// Shape style for the QR code corner squares
cornerSquareShape?: enum[dot, square, rounded, classy, outpoint, inpoint, ]
// Shape style for the QR code corner dots
cornerDotShape?: enum[dot, square, heart, rounded, classy, outpoint, inpoint, ]
// Logo to be placed on the QR code (URL, Base64, Buffer, or Blob)
logo?: anyOf: [
{"type":"string"},
{},
{},
{"type":"null"}
]
// Size of the logo relative to QR code (0-1)
logoSize?: number | null
// Placement mode for the logo
logoMode?: enum[center, overlay, background, ]
// Margin around the logo in pixels
logoMargin?: number | null
// Background color for logo in CSS format
logoBackgroundColor?: string | null
// Padding around the logo in pixels
logoPadding?: number | null
// Border radius for logo in pixels or CSS format
logoRadius?: anyOf: [
{"type":"string"},
{"type":"number"},
{"type":"null"}
]
// Color of the QR code border in CSS format
borderColor?: string | null
// Thickness of the border in pixels
borderThickness?: number | null
// Border radius in pixels or CSS format
borderRadius?: anyOf: [
{"type":"string"},
{"type":"number"},
{"type":"null"}
]
// Color of the inner border in CSS format
borderInnerColor?: string | null
// Thickness of the inner border in pixels
borderInnerThickness?: number | null
// Inner border radius in pixels or CSS format
borderInnerRadius?: anyOf: [
{"type":"string"},
{"type":"number"},
{"type":"null"}
]
// Color of the outer border in CSS format
borderOuterColor?: string | null
// Thickness of the outer border in pixels
borderOuterThickness?: number | null
// Text to display on top border
borderTextTop?: string | null
// Text to display on right border
borderTextRight?: string | null
// Text to display on bottom border
borderTextBottom?: string | null
// Text to display on left border
borderTextLeft?: string | null
// Font family for border text
borderFontFace?: string | null
// Font size for border text in pixels
borderFontSize?: number | null
// Font color for border text in CSS format
borderFontColor?: string | null
// Letter spacing for border text in pixels
borderLetterSpacing?: number | null
// Text transformation for border text
borderTextTransform?: enum[uppercase, lowercase, capitalize, ]
// Font weight for border text
borderFontWeight?: string
}
// Custom metadata for the style as JSON object
metadata: object | null
// ID of the workspace this style belongs to (null for organization-level styles)
workspaceId?: string | null
// User who created the resource
createdByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// User who last updated the resource
updatedByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// API key used to create the resource
createdByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// API key used to last update the resource
updatedByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// When the resource was created
createdAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
// When the resource was last updated
updatedAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
}
Schemas: Gradient AuditInfoMember AuditInfoApiKey
- 400 Bad Request when updating style
// Bad Request when updating style
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"UpdateFieldRequiredMessage"},
{"$ref":"StyleNameTakenMessage"}
]
Schemas: ValidationErrorMessage UpdateFieldRequiredMessage StyleNameTakenMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Style to update not found, or its parent organization context is invalid.
// Style to update not found, or its parent organization context is invalid.
anyOf: [
{"$ref":"StyleNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: StyleNotFoundMessage OrganizationNotFoundMessage
Delete style by ID
DELETE /styles/{styleId}
Deletes a style by its unique identifier. Fails if the style is used by codes.
Responses
- 200 Style deleted successfully
{
// Success message
message: string
}
- 400 Bad Request when deleting style
// Error response when a resource cannot be modified/deleted because it is in use
{
message: string
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Style to delete not found, or its parent organization context is invalid.
// Style to delete not found, or its parent organization context is invalid.
anyOf: [
{"$ref":"StyleNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: StyleNotFoundMessage OrganizationNotFoundMessage
Partially update style options by ID
PUT /styles/{styleId}/options
Partially updates a style options by its unique identifier using a deep merge. Use null to delete a field.
RequestBody
{
// Partial style options to update. All fields are optional. Use null as a value to delete a field. At least one option field must be provided.
options: {
primaryColor?: string | null
secondaryColor?: string | null
thirdColor?: string | null
backgroundColor?: string | null
// Gradient definition
dotsGradient?: object | null
// Gradient definition
cornersDotGradient?: object | null
// Gradient definition
cornersGradient?: object | null
// Gradient definition
backgroundGradient?: object | null
// Type of dots in QR code
dotShape?: enum[dot, square, rounded, extra-rounded, classy, classy-rounded, vertical-line, horizontal-line, random-dot, small-square, tiny-square, star, plus, diamond, ]
// Type of corner squares in QR code
cornerSquareShape?: enum[dot, square, rounded, classy, outpoint, inpoint, ]
// Type of corner dots in QR code
cornerDotShape?: enum[dot, square, heart, rounded, classy, outpoint, inpoint, ]
logo?: anyOf: [
{"type":"string"},
{},
{},
{"type":"null"}
]
logoSize?: number | null
// Mode for embedding images in QR code
logoMode?: enum[center, overlay, background, ]
logoMargin?: number | null
logoBackgroundColor?: string | null
logoPadding?: number | null
logoRadius?: anyOf: [
{"type":"string"},
{"type":"number"},
{"type":"null"}
]
borderColor?: string | null
borderThickness?: number | null
borderRadius?: anyOf: [
{"type":"string"},
{"type":"number"},
{"type":"null"}
]
borderInnerColor?: string | null
borderInnerThickness?: number | null
borderInnerRadius?: anyOf: [
{"type":"string"},
{"type":"number"},
{"type":"null"}
]
borderOuterColor?: string | null
borderOuterThickness?: number | null
borderTextTop?: string | null
borderTextRight?: string | null
borderTextBottom?: string | null
borderTextLeft?: string | null
borderFontFace?: string | null
borderFontSize?: number | null
borderFontColor?: string | null
borderLetterSpacing?: number | null
borderTextTransform?: enum[uppercase, lowercase, capitalize, ]
borderFontWeight?: string
}
}
Responses
- 200 Style options updated successfully
// Style data returned in API responses
{
// Unique identifier of the style
id: string
// Name of the style
name: string
// Description of the style
description?: string | null
// Style configuration options
options: {
// Primary color for QR code elements in CSS format
primaryColor?: string | null
// Secondary color for QR code elements in CSS format
secondaryColor?: string | null
// Tertiary color for QR code elements in CSS format
thirdColor?: string | null
// Background color of the QR code in CSS format
backgroundColor?: string | null
// Gradient configuration for QR code dots
dotsGradient?: oneOf: [
{"$ref":"Gradient"},
{"type":"null"}
]
// Gradient configuration for corner dots
cornersDotGradient?: oneOf: [
{"$ref":"Gradient"},
{"type":"null"}
]
// Gradient configuration for corners
cornersGradient?: oneOf: [
{"$ref":"Gradient"},
{"type":"null"}
]
// Gradient configuration for QR code background
backgroundGradient?: oneOf: [
{"$ref":"Gradient"},
{"type":"null"}
]
// Shape style for the QR code dots
dotShape?: enum[dot, square, rounded, extra-rounded, classy, classy-rounded, vertical-line, horizontal-line, random-dot, small-square, tiny-square, star, plus, diamond, ]
// Shape style for the QR code corner squares
cornerSquareShape?: enum[dot, square, rounded, classy, outpoint, inpoint, ]
// Shape style for the QR code corner dots
cornerDotShape?: enum[dot, square, heart, rounded, classy, outpoint, inpoint, ]
// Logo to be placed on the QR code (URL, Base64, Buffer, or Blob)
logo?: anyOf: [
{"type":"string"},
{},
{},
{"type":"null"}
]
// Size of the logo relative to QR code (0-1)
logoSize?: number | null
// Placement mode for the logo
logoMode?: enum[center, overlay, background, ]
// Margin around the logo in pixels
logoMargin?: number | null
// Background color for logo in CSS format
logoBackgroundColor?: string | null
// Padding around the logo in pixels
logoPadding?: number | null
// Border radius for logo in pixels or CSS format
logoRadius?: anyOf: [
{"type":"string"},
{"type":"number"},
{"type":"null"}
]
// Color of the QR code border in CSS format
borderColor?: string | null
// Thickness of the border in pixels
borderThickness?: number | null
// Border radius in pixels or CSS format
borderRadius?: anyOf: [
{"type":"string"},
{"type":"number"},
{"type":"null"}
]
// Color of the inner border in CSS format
borderInnerColor?: string | null
// Thickness of the inner border in pixels
borderInnerThickness?: number | null
// Inner border radius in pixels or CSS format
borderInnerRadius?: anyOf: [
{"type":"string"},
{"type":"number"},
{"type":"null"}
]
// Color of the outer border in CSS format
borderOuterColor?: string | null
// Thickness of the outer border in pixels
borderOuterThickness?: number | null
// Text to display on top border
borderTextTop?: string | null
// Text to display on right border
borderTextRight?: string | null
// Text to display on bottom border
borderTextBottom?: string | null
// Text to display on left border
borderTextLeft?: string | null
// Font family for border text
borderFontFace?: string | null
// Font size for border text in pixels
borderFontSize?: number | null
// Font color for border text in CSS format
borderFontColor?: string | null
// Letter spacing for border text in pixels
borderLetterSpacing?: number | null
// Text transformation for border text
borderTextTransform?: enum[uppercase, lowercase, capitalize, ]
// Font weight for border text
borderFontWeight?: string
}
// Custom metadata for the style as JSON object
metadata: object | null
// ID of the workspace this style belongs to (null for organization-level styles)
workspaceId?: string | null
// User who created the resource
createdByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// User who last updated the resource
updatedByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// API key used to create the resource
createdByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// API key used to last update the resource
updatedByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// When the resource was created
createdAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
// When the resource was last updated
updatedAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
}
Schemas: Gradient AuditInfoMember AuditInfoApiKey
- 400 Bad Request when updating style options
// Bad Request when updating style options
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"UpdateOptionsFieldRequiredMessage"}
]
Schemas: ValidationErrorMessage UpdateOptionsFieldRequiredMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization or style not found.
// Organization or style not found.
anyOf: [
{"$ref":"StyleNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: StyleNotFoundMessage OrganizationNotFoundMessage
List styles for a workspace
GET /styles/workspace/{workspaceId}
Retrieves all styles for a specific workspace.
Parameters(Query)
// Filter by style name
name?: string
Responses
- 200 List of styles for the workspace
[]
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 No styles found for the workspace (returns empty array), or workspace itself not found.
// No styles found for the workspace (returns empty array), or workspace itself not found.
anyOf: [
{"$ref":"EmptyArrayResponse"},
{"$ref":"WorkspaceNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: EmptyArrayResponse WorkspaceNotFoundMessage OrganizationNotFoundMessage
Create a new text
POST /texts
Creates a new text for an organization or workspace.
RequestBody
// Base schema for text definitions
{
// Name of the text
name: string
// Description of the text
description?: string
// Custom metadata for the text as JSON object
metadata?: object | null
// ID of the workspace this text belongs to, if any
workspaceId?: string | null
}
Responses
- 201 Text created successfully
// Text data returned in API responses
{
// Unique identifier for the text
id: string
// Name of the text
name: string
// Description of the text
description?: string | null
// Text configuration options
options: {
// Text value for all positions
value?: string | null
// Text value for the top position
topValue?: string | null
// Text value for the bottom position
bottomValue?: string | null
// Text value for the right position
rightValue?: string | null
// Text value for the left position
leftValue?: string | null
}
// Custom metadata for the text as JSON object
metadata: object | null
// ID of the workspace this text belongs to, if any
workspaceId?: string | null
// User who created the resource
createdByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// User who last updated the resource
updatedByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// API key used to create the resource
createdByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// API key used to last update the resource
updatedByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// When the resource was created
createdAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
// When the resource was last updated
updatedAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
}
Schemas: AuditInfoMember AuditInfoApiKey
- 400 Bad Request when creating text
// Bad Request when creating text
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"OptionsRequiredMessage"},
{"$ref":"TextNameTakenMessage"}
]
Schemas: ValidationErrorMessage OptionsRequiredMessage TextNameTakenMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Could not create text entity due to missing resources.
// Could not create text entity due to missing resources.
anyOf: [
{"$ref":"OrganizationNotFoundMessage"},
{"$ref":"WorkspaceNotFoundMessage"}
]
Schemas: OrganizationNotFoundMessage WorkspaceNotFoundMessage
List all texts
GET /texts
Retrieves all texts available to the user.
Parameters(Query)
// Filter by text name
name?: string
Responses
- 200 List of texts
// List of texts grouped by organization and workspace
{
organizations: []
workspaces: TextResponse[]
}
Schemas: TextResponse
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization not found or no text entities available.
// Organization not found or no text entities available.
anyOf: [
{"$ref":"EmptyTextsOrgContextResponse"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: EmptyTextsOrgContextResponse OrganizationNotFoundMessage
List base texts
GET /texts/base
Retrieves all base text templates from the QRCodeJs library with optional name filtering.
Parameters(Query)
name?: string
Responses
- 200 List of base texts
[]
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
Get text by ID
GET /texts/{textId}
Retrieves a text by its unique identifier.
Responses
- 200 Text details
// Text data returned in API responses
{
// Unique identifier for the text
id: string
// Name of the text
name: string
// Description of the text
description?: string | null
// Text configuration options
options: {
// Text value for all positions
value?: string | null
// Text value for the top position
topValue?: string | null
// Text value for the bottom position
bottomValue?: string | null
// Text value for the right position
rightValue?: string | null
// Text value for the left position
leftValue?: string | null
}
// Custom metadata for the text as JSON object
metadata: object | null
// ID of the workspace this text belongs to, if any
workspaceId?: string | null
// User who created the resource
createdByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// User who last updated the resource
updatedByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// API key used to create the resource
createdByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// API key used to last update the resource
updatedByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// When the resource was created
createdAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
// When the resource was last updated
updatedAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
}
Schemas: AuditInfoMember AuditInfoApiKey
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization or text entity not found.
// Organization or text entity not found.
anyOf: [
{"$ref":"TextNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: TextNotFoundMessage OrganizationNotFoundMessage
Update text by ID
PUT /texts/{textId}
Updates a text by its unique identifier.
RequestBody
// Schema for updating an existing text
{
// Name of the text
name?: string
// Description of the text
description?: string
// Updated custom metadata for the text as JSON object
metadata?: object | null
// ID of the workspace this text belongs to, if any
workspaceId?: string | null
}
Responses
- 200 Text updated successfully
// Text data returned in API responses
{
// Unique identifier for the text
id: string
// Name of the text
name: string
// Description of the text
description?: string | null
// Text configuration options
options: {
// Text value for all positions
value?: string | null
// Text value for the top position
topValue?: string | null
// Text value for the bottom position
bottomValue?: string | null
// Text value for the right position
rightValue?: string | null
// Text value for the left position
leftValue?: string | null
}
// Custom metadata for the text as JSON object
metadata: object | null
// ID of the workspace this text belongs to, if any
workspaceId?: string | null
// User who created the resource
createdByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// User who last updated the resource
updatedByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// API key used to create the resource
createdByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// API key used to last update the resource
updatedByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// When the resource was created
createdAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
// When the resource was last updated
updatedAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
}
Schemas: AuditInfoMember AuditInfoApiKey
- 400 Bad Request when updating text
// Bad Request when updating text
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"UpdateFieldRequiredMessage"},
{"$ref":"TextNameTakenMessage"}
]
Schemas: ValidationErrorMessage UpdateFieldRequiredMessage TextNameTakenMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization or text entity not found.
// Organization or text entity not found.
anyOf: [
{"$ref":"TextNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: TextNotFoundMessage OrganizationNotFoundMessage
Delete text by ID
DELETE /texts/{textId}
Deletes a text by its unique identifier. Fails if the text is used by codes.
Responses
- 200 Text deleted successfully
// Response for successful text deletion
{
// Success message
message: string
}
- 400 Bad Request when deleting text
// Error response when a resource cannot be modified/deleted because it is in use
{
message: string
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization or text entity not found.
// Organization or text entity not found.
anyOf: [
{"$ref":"TextNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: TextNotFoundMessage OrganizationNotFoundMessage
Partially update text options by ID
PUT /texts/{textId}/options
Partially updates a text options by its unique identifier using a deep merge. Use null to delete a field.
RequestBody
{
// Partial text options to update. All fields are optional. Use null as a value to delete a field. At least one option field must be provided.
options: {
value?: string | null
topValue?: string | null
bottomValue?: string | null
rightValue?: string | null
leftValue?: string | null
}
}
Responses
- 200 Text options updated successfully
// Text data returned in API responses
{
// Unique identifier for the text
id: string
// Name of the text
name: string
// Description of the text
description?: string | null
// Text configuration options
options: {
// Text value for all positions
value?: string | null
// Text value for the top position
topValue?: string | null
// Text value for the bottom position
bottomValue?: string | null
// Text value for the right position
rightValue?: string | null
// Text value for the left position
leftValue?: string | null
}
// Custom metadata for the text as JSON object
metadata: object | null
// ID of the workspace this text belongs to, if any
workspaceId?: string | null
// User who created the resource
createdByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// User who last updated the resource
updatedByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// API key used to create the resource
createdByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// API key used to last update the resource
updatedByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// When the resource was created
createdAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
// When the resource was last updated
updatedAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
}
Schemas: AuditInfoMember AuditInfoApiKey
- 400 Bad Request when updating text options
// Bad Request when updating text options
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"UpdateFieldRequiredMessage"}
]
Schemas: ValidationErrorMessage UpdateFieldRequiredMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization or text not found.
// Organization or text not found.
anyOf: [
{"$ref":"TextNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: TextNotFoundMessage OrganizationNotFoundMessage
List texts for a workspace
GET /texts/workspace/{workspaceId}
Retrieves all texts for a specific workspace.
Parameters(Query)
// Filter by text name
name?: string
Responses
- 200 List of texts for the workspace
[]
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization or workspace not found, or no text entities in workspace.
// Organization or workspace not found, or no text entities in workspace.
anyOf: [
{"$ref":"WorkspaceNotFoundMessage"},
{"$ref":"EmptyArrayResponse"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: WorkspaceNotFoundMessage EmptyArrayResponse OrganizationNotFoundMessage
Create a new border
POST /borders
Creates a new border for an organization or workspace.
RequestBody
// Border Base Schema
{
// Name of the border
name: string
// Description of the border
description?: string
// Custom metadata for the border as JSON object
metadata?: object | null
// ID of the workspace this border belongs to, if any
workspaceId?: string | null
}
Responses
- 201 Border created successfully
// Border Response Schema
{
// Unique identifier for the border
id: string
// Name of the border
name: string
// Description of the border
description?: string | null
// Custom metadata for the border as JSON object
metadata: object | null
// ID of the workspace this border belongs to, if any
workspaceId?: string | null
// User who created the resource
createdByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// User who last updated the resource
updatedByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// API key used to create the resource
createdByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// API key used to last update the resource
updatedByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// When the resource was created
createdAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
// When the resource was last updated
updatedAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
}
Schemas: AuditInfoMember AuditInfoApiKey
- 400 Bad Request when creating a border
// Bad Request when creating a border
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"BorderNameTakenMessage"}
]
Schemas: ValidationErrorMessage BorderNameTakenMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Could not create border entity due to missing resources.
// Could not create border entity due to missing resources.
anyOf: [
{"$ref":"OrganizationNotFoundMessage"},
{"$ref":"WorkspaceNotFoundMessage"}
]
Schemas: OrganizationNotFoundMessage WorkspaceNotFoundMessage
List all borders
GET /borders
Retrieves all borders available to the user.
Parameters(Query)
// Filter by border name
name?: string
Responses
- 200 List of borders
// List of borders grouped by organization and workspace
{
organizations: []
workspaces: BorderResponse[]
}
Schemas: BorderResponse
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization not found or no border entities available.
// Organization not found or no border entities available.
anyOf: [
{"$ref":"EmptyBordersOrgContextResponseMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: EmptyBordersOrgContextResponseMessage OrganizationNotFoundMessage
List base borders
GET /borders/base
Retrieves all base border templates from the QRCodeJs library with optional name filtering.
Parameters(Query)
name?: string
Responses
- 200 List of base borders
[]
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
Get border by ID
GET /borders/{borderId}
Retrieves a border by its unique identifier.
Responses
- 200 Border details
// Border Response Schema
{
// Unique identifier for the border
id: string
// Name of the border
name: string
// Description of the border
description?: string | null
// Custom metadata for the border as JSON object
metadata: object | null
// ID of the workspace this border belongs to, if any
workspaceId?: string | null
// User who created the resource
createdByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// User who last updated the resource
updatedByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// API key used to create the resource
createdByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// API key used to last update the resource
updatedByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// When the resource was created
createdAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
// When the resource was last updated
updatedAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
}
Schemas: AuditInfoMember AuditInfoApiKey
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization or border entity not found.
// Organization or border entity not found.
anyOf: [
{"$ref":"BorderNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: BorderNotFoundMessage OrganizationNotFoundMessage
Update border by ID
PUT /borders/{borderId}
Updates a border by its unique identifier.
RequestBody
// Update Border Schema
{
// Name of the border
name?: string
// Description of the border
description?: string
// Updated custom metadata for the border as JSON object
metadata?: object | null
}
Responses
- 200 Border updated successfully
// Border Response Schema
{
// Unique identifier for the border
id: string
// Name of the border
name: string
// Description of the border
description?: string | null
// Custom metadata for the border as JSON object
metadata: object | null
// ID of the workspace this border belongs to, if any
workspaceId?: string | null
// User who created the resource
createdByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// User who last updated the resource
updatedByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// API key used to create the resource
createdByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// API key used to last update the resource
updatedByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// When the resource was created
createdAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
// When the resource was last updated
updatedAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
}
Schemas: AuditInfoMember AuditInfoApiKey
- 400 Bad Request when updating a border
// Bad Request when updating a border
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"UpdateFieldRequiredMessage"},
{"$ref":"BorderNameTakenMessage"}
]
Schemas: ValidationErrorMessage UpdateFieldRequiredMessage BorderNameTakenMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization or border entity not found.
// Organization or border entity not found.
anyOf: [
{"$ref":"BorderNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: BorderNotFoundMessage OrganizationNotFoundMessage
Delete border by ID
DELETE /borders/{borderId}
Deletes a border by its unique identifier.
Responses
- 200 Border deleted successfully
// Delete Border Response Schema
{
// Success message
message: string
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization or border entity not found.
// Organization or border entity not found.
anyOf: [
{"$ref":"BorderNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: BorderNotFoundMessage OrganizationNotFoundMessage
Partially update border options by ID
PUT /borders/{borderId}/options
Partially updates border options by its unique identifier using a deep merge. Use null to delete a field.
RequestBody
{
// Partial border options to update. borderOptions is required and must contain at least one field (can be nullable). Other top-level options are optional. Use null as a value to delete a field.
options: {
borderOptions: {
hasBorder?: boolean | null
thickness?: number | null
color?: string | null
radius?: string | null
noBorderThickness?: number | null
background?: string | null
inner?: object | null
// Inner or outer border configuration
borderOuter?: object | null
// Inner or outer border configuration
borderInner?: object | null
decorations?: object | null
}
// Overall shape of the QR code
shape?: enum[square, circle, ]
// Margin around the QR code in pixels
margin?: number | null
// Whether QR code is responsive
isResponsive?: boolean | null
// Scale factor for QR code (0-1.5)
scale?: number | null
// General offset in pixels
offset?: number | null
// Vertical offset in pixels
verticalOffset?: number | null
// Horizontal offset in pixels
horizontalOffset?: number | null
// QR code specific options
qrOptions?: object | null
// Options for QR code dots
dotsOptions?: object | null
// Options for QR code corner squares
cornersSquareOptions?: object | null
// Options for QR code corner dots
cornersDotOptions?: object | null
// Options for QR code background or false to disable
backgroundOptions?: anyOf: [
{"type":"object","properties":{"color":{"type":["string","null"],"description":"Background color in CSS format","example":"#ffffff"},"round":{"anyOf":[{"type":"number","minimum":0,"maximum":1},{"type":"string"},{"type":"null"}],"description":"Background corner rounding (0-1 or CSS value)","example":0.1},"gradient":{"oneOf":[{"$ref":"Gradient"},{"type":"null"}],"description":"Gradient for background"}},"required":["color"]},
{"type":"boolean","const":false}
]
// Image to embed in the QR code (URL, Buffer, or Blob)
image?: anyOf: [
{"type":"string"},
{},
{},
{"type":"null"}
]
// Options for embedded image
imageOptions?: object | null
}
}
Responses
- 200 Border options updated successfully
// Border Response Schema
{
// Unique identifier for the border
id: string
// Name of the border
name: string
// Description of the border
description?: string | null
// Custom metadata for the border as JSON object
metadata: object | null
// ID of the workspace this border belongs to, if any
workspaceId?: string | null
// User who created the resource
createdByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// User who last updated the resource
updatedByUser?: oneOf: [
{"$ref":"AuditInfoMember"},
{"type":"null"}
]
// API key used to create the resource
createdByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// API key used to last update the resource
updatedByApiKey?: oneOf: [
{"$ref":"AuditInfoApiKey"},
{"type":"null"}
]
// When the resource was created
createdAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
// When the resource was last updated
updatedAt?: anyOf: [
{"type":"string"},
{"type":"string"},
{"type":"null"}
]
}
Schemas: AuditInfoMember AuditInfoApiKey
- 400 Bad Request when updating border options
// Bad Request when updating border options
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"$ref":"UpdateOptionsFieldRequiredMessage"}
]
Schemas: ValidationErrorMessage UpdateOptionsFieldRequiredMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization or border not found.
// Organization or border not found.
anyOf: [
{"$ref":"BorderNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: BorderNotFoundMessage OrganizationNotFoundMessage
List borders for a workspace
GET /borders/workspace/{workspaceId}
Retrieves all borders for a specific workspace.
Parameters(Query)
// Filter by border name
name?: string
Responses
- 200 List of borders for the workspace
[]
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Organization or workspace not found, or no border entities in workspace.
// Organization or workspace not found, or no border entities in workspace.
anyOf: [
{"$ref":"WorkspaceNotFoundMessage"},
{"$ref":"EmptyArrayResponse"},
{"$ref":"OrganizationNotFoundMessage"}
]
Schemas: WorkspaceNotFoundMessage EmptyArrayResponse OrganizationNotFoundMessage
List All Country Codes
GET /country-codes
Retrieves a list of all available country codes with their names and full names
Responses
- 200 A list of all country codes
{
data: {
// ISO 3166-1 alpha-2 country code
code: string
// Short country name
name: string
// Full official country name
fullName: string
}[]
}
Create Router Rule Template
POST /router-rule-templates
Creates a new router rule template. The template can be organization-level (no workspaceId) or workspace-specific. Template names must be unique within the organization scope.
- Security: bearerAuth
RequestBody
{}
Responses
- 201 Router rule template created successfully
- 400 Invalid request data or template name already exists
// Invalid request data or template name already exists
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"type":"object","properties":{"error":{"type":"string","const":"TEMPLATE_COMPOSITE_RULE_NESTING_DEPTH_EXCEEDED"},"message":{"type":"string"},"maxDepth":{"type":"number"},"actualDepth":{"type":"number"}},"required":["error","message","maxDepth","actualDepth"],"description":"Template composite rule nesting depth exceeded maximum allowed depth","example":{"error":"TEMPLATE_COMPOSITE_RULE_NESTING_DEPTH_EXCEEDED","message":"Template condition nesting depth exceeds maximum allowed depth of 5","maxDepth":5,"actualDepth":7}},
{"type":"object","properties":{"error":{"type":"string","const":"TEMPLATE_COMPOSITE_RULE_CONDITION_COUNT_EXCEEDED"},"message":{"type":"string"},"maxConditions":{"type":"number"},"actualConditions":{"type":"number"}},"required":["error","message","maxConditions","actualConditions"],"description":"Template composite rule condition count exceeded maximum allowed","example":{"error":"TEMPLATE_COMPOSITE_RULE_CONDITION_COUNT_EXCEEDED","message":"Too many conditions in template (150). Maximum allowed is 100 for performance reasons.","maxConditions":100,"actualConditions":150}},
{"type":"object","properties":{"error":{"type":"string","const":"TEMPLATE_COMPOSITE_RULE_CONDITIONS_REQUIRED"},"message":{"type":"string"},"ruleType":{"type":"string"}},"required":["error","message","ruleType"],"description":"Template composite rules require enhanced conditions to be specified","example":{"error":"TEMPLATE_COMPOSITE_RULE_CONDITIONS_REQUIRED","message":"composite templates require enhanced conditions to be specified","ruleType":"composite"}}
]
Schemas: ValidationErrorMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 429 You have reached the limit for router rule templates. Please upgrade your plan to continue
// Limit reached response message
{
message: string
}
List Router Rule Templates
GET /router-rule-templates
Retrieves available router rule templates based on user access. Returns global templates (if includeGlobal=true), organization-level templates, and workspace-specific templates the user has access to.
- Security: bearerAuth
Parameters(Query)
page?: integer //default: 1
limit?: integer //default: 20
includeGlobal?: boolean //default: true
type?: enum[location, continent, geo, time, date, timezone, language, browser, os, deviceVendor, deviceModel, scanLimit]
Responses
- 200 A paginated list of router rule templates with metadata
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
Get Router Rule Template
GET /router-rule-templates/{routerRuleTemplateId}
Retrieves a specific router rule template by ID. Returns global templates and organization templates the user has access to.
- Security: bearerAuth
Responses
- 200 Router rule template details
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Router rule template not found, or organization/workspace context not found.
// Router rule template not found, or organization/workspace context not found.
anyOf: [
{"$ref":"RouterRuleTemplateNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"},
{"$ref":"WorkspaceNotFoundMessage"}
]
Schemas: RouterRuleTemplateNotFoundMessage OrganizationNotFoundMessage WorkspaceNotFoundMessage
Update Router Rule Template
PUT /router-rule-templates/{routerRuleTemplateId}
Updates a router rule template. Only organization templates can be updated (not global templates). Users can only update templates within their organization.
- Security: bearerAuth
RequestBody
{}
Responses
- 200 Router rule template updated successfully
- 400 Invalid request data for template update
// Invalid request data for template update
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"type":"object","properties":{"error":{"type":"string","const":"TEMPLATE_COMPOSITE_RULE_NESTING_DEPTH_EXCEEDED"},"message":{"type":"string"},"maxDepth":{"type":"number"},"actualDepth":{"type":"number"}},"required":["error","message","maxDepth","actualDepth"],"description":"Template composite rule nesting depth exceeded maximum allowed depth","example":{"error":"TEMPLATE_COMPOSITE_RULE_NESTING_DEPTH_EXCEEDED","message":"Template condition nesting depth exceeds maximum allowed depth of 5","maxDepth":5,"actualDepth":7}},
{"type":"object","properties":{"error":{"type":"string","const":"TEMPLATE_COMPOSITE_RULE_CONDITION_COUNT_EXCEEDED"},"message":{"type":"string"},"maxConditions":{"type":"number"},"actualConditions":{"type":"number"}},"required":["error","message","maxConditions","actualConditions"],"description":"Template composite rule condition count exceeded maximum allowed","example":{"error":"TEMPLATE_COMPOSITE_RULE_CONDITION_COUNT_EXCEEDED","message":"Too many conditions in template (150). Maximum allowed is 100 for performance reasons.","maxConditions":100,"actualConditions":150}},
{"type":"object","properties":{"error":{"type":"string","const":"TEMPLATE_COMPOSITE_RULE_CONDITIONS_REQUIRED"},"message":{"type":"string"},"ruleType":{"type":"string"}},"required":["error","message","ruleType"],"description":"Template composite rules require enhanced conditions to be specified","example":{"error":"TEMPLATE_COMPOSITE_RULE_CONDITIONS_REQUIRED","message":"composite templates require enhanced conditions to be specified","ruleType":"composite"}}
]
Schemas: ValidationErrorMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Router rule template not found, or organization/workspace context not found.
// Router rule template not found, or organization/workspace context not found.
anyOf: [
{"$ref":"RouterRuleTemplateNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"},
{"$ref":"WorkspaceNotFoundMessage"}
]
Schemas: RouterRuleTemplateNotFoundMessage OrganizationNotFoundMessage WorkspaceNotFoundMessage
Delete Router Rule Template
DELETE /router-rule-templates/{routerRuleTemplateId}
Deletes a router rule template. Templates that are currently being used by router rules cannot be deleted. Only organization templates can be deleted (not global templates).
- Security: bearerAuth
Responses
- 200 Router rule template deleted successfully
{
message?: string
}
- 400 Template is in use and cannot be deleted
{
error?: string
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Router rule template not found, or organization/workspace context not found.
// Router rule template not found, or organization/workspace context not found.
anyOf: [
{"$ref":"RouterRuleTemplateNotFoundMessage"},
{"$ref":"OrganizationNotFoundMessage"},
{"$ref":"WorkspaceNotFoundMessage"}
]
Schemas: RouterRuleTemplateNotFoundMessage OrganizationNotFoundMessage WorkspaceNotFoundMessage
List Organization Router Rules
GET /router-rules
Retrieves all router rules across the organization. Users with organization-level access see all rules, while workspace-limited users see only rules from their permitted workspaces.
- Security: bearerAuth
Parameters(Query)
page?: integer //default: 1
limit?: integer //default: 10
includeDisabled?: boolean
type?: enum[location, continent, geo, time, date, timezone, language, browser, os, deviceVendor, deviceModel, scanLimit]
priority?: integer
dataType?: enum[url, text, email, wifi, vcard, event, json, file]
workspaceId?: string
codeId?: string
Responses
- 200 A paginated list of organization router rules with code and workspace context
// Paginated list response
{
// Pagination metadata
pagination: {
// Total number of items matching the filter criteria
total: number
// Current page number
page: number
// Number of items per page
limit: number
// Total number of pages
totalPages: number
}
data: []
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
List Workspace Router Rule Assignments
GET /workspaces/{workspaceId}/router-rules
Retrieves all router rule assignments within a specific workspace with pagination and filtering options. Returns rules sorted by priority (highest first) with enriched template data and QR code context.
- Security: bearerAuth
Parameters(Query)
page?: integer //default: 1
limit?: integer //default: 10
includeDisabled?: boolean
type?: enum[location, continent, geo, time, date, timezone, language, browser, os, deviceVendor, deviceModel, scanLimit]
priority?: integer
dataType?: enum[url, text, email, phone, sms, wifi, vcard, event]
codeId?: string
Responses
- 200 A paginated list of workspace Router Rule assignments with QR code context
// Paginated list response
{
// Pagination metadata
pagination: {
// Total number of items matching the filter criteria
total: number
// Current page number
page: number
// Number of items per page
limit: number
// Total number of pages
totalPages: number
}
data: []
}
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 404 Workspace not found or no access
{
error?: string
}
Create Workspace Router Rule Template
POST /workspaces/{workspaceId}/router-rule-templates
Creates a new router rule template scoped to the specified workspace. Template names must be unique within the organization scope. The workspaceId from the URL path will be used to scope the template.
- Security: bearerAuth
RequestBody
{}
Responses
- 201 Workspace router rule template created successfully
- 400 Invalid request data, template name already exists, or insufficient workspace permissions
// Invalid request data, template name already exists, or insufficient workspace permissions
anyOf: [
{"$ref":"ValidationErrorMessage"},
{"type":"object","properties":{"error":{"type":"string","const":"TEMPLATE_COMPOSITE_RULE_NESTING_DEPTH_EXCEEDED"},"message":{"type":"string"},"maxDepth":{"type":"number"},"actualDepth":{"type":"number"}},"required":["error","message","maxDepth","actualDepth"],"description":"Template composite rule nesting depth exceeded maximum allowed depth","example":{"error":"TEMPLATE_COMPOSITE_RULE_NESTING_DEPTH_EXCEEDED","message":"Template condition nesting depth exceeds maximum allowed depth of 5","maxDepth":5,"actualDepth":7}},
{"type":"object","properties":{"error":{"type":"string","const":"TEMPLATE_COMPOSITE_RULE_CONDITION_COUNT_EXCEEDED"},"message":{"type":"string"},"maxConditions":{"type":"number"},"actualConditions":{"type":"number"}},"required":["error","message","maxConditions","actualConditions"],"description":"Template composite rule condition count exceeded maximum allowed","example":{"error":"TEMPLATE_COMPOSITE_RULE_CONDITION_COUNT_EXCEEDED","message":"Too many conditions in template (150). Maximum allowed is 100 for performance reasons.","maxConditions":100,"actualConditions":150}},
{"type":"object","properties":{"error":{"type":"string","const":"TEMPLATE_COMPOSITE_RULE_CONDITIONS_REQUIRED"},"message":{"type":"string"},"ruleType":{"type":"string"}},"required":["error","message","ruleType"],"description":"Template composite rules require enhanced conditions to be specified","example":{"error":"TEMPLATE_COMPOSITE_RULE_CONDITIONS_REQUIRED","message":"composite templates require enhanced conditions to be specified","ruleType":"composite"}}
]
Schemas: ValidationErrorMessage
- 401 Unauthorized
// Unauthorized response message
{
message: string
}
- 403 Forbidden
// Forbidden response message
{
message: string
}
- 429 You have reached the limit for router rule templates. Please upgrade your plan to continue
// Limit reached response message
{
message: string
}