Skip to main content
A workspace is the foundation of your AI Builder projects. It provides a complete environment for building, configuring, and deploying your AI applications.

​
What is a Workspace?

  • Overview
  • Workspace Structure
A workspace is a project that:
  • Enables various Automations inside your organization, connecting your APIs and systems
  • Is easily configurable through workspace config, Apps, and automation graphs
  • Produces events recording activities and optionally triggering automations
  • Presents computed data through Web Pages accessible to admins or external users
  • Has configurable roles providing distinct user groups with fine-grained permissions
Workspaces serve as isolated environments where you can create, test, and deploy complete AI-powered solutions.

​
Workspace Configuration

The workspace config provides centralized settings and parameters for your entire workspace.
Workspace configuration is defined in the workspace source code:
name: MyConfiguredWorkspace
slug: test
config:
  value:
    API_URL: https://api.mycompany.com
    LOGIN_URL: "{{config.API_URL}}/login"
    headers:
      apiKey: someAPIKey
The config.value field is exposed as a config variable inside your automations, making these settings accessible throughout your workspace.
You can reference other config values within your configuration using the {{config.PROPERTY}} syntax, as shown in the LOGIN_URL example above.
For sensitive configuration values, use secrets:
config:
  value:
    API_URL: https://api.mycompany.com
    headers:
      apiKey: "{{secret.apiKey}}"
Secrets provide a secure way to store and use sensitive information like API keys, passwords, and tokens without exposing them in your code.
Secrets with names starting with prismeai_* are reserved for super admins to configure system settings by workspace.
You can also inject configuration values from environment variables:
WORKSPACE_CONFIG_test_API_URL=https://api.mycompany.com
This environment variable would set config.API_URL for a workspace with the slug “test”. Workspace config takes precedence over environment variables.
For more controlled configuration, especially for Apps, you can define a schema for your config:
config:
  schema:
    type: object
    properties:
      API_URL:
        type: string
        title: API URL
        description: Base URL for the API
      maxRetries:
        type: number
        title: Maximum Retries
        default: 3
  value:
    API_URL: https://api.mycompany.com
    maxRetries: 5
This schema defines the structure, types, and defaults for your configuration, providing better validation and documentation.

​
Workspace Events

Each workspace maintains a continuous real-time stream of events that describe activities and interactions:
Workspace Events
  • Event Types
  • Event Structure
  • Working with Events
Workspaces work with two main types of events:
  • Native Events: Automatically generated by the platform (updates, webhooks, errors, automation executions, etc.)
  • Custom Events: Emitted by your automations or installed apps
Events are stored for up to 3 years and can be viewed/searched from the Activity view of the workspace.
Events from workspaces inactive for longer than 15 days and with fewer than 100 events are regularly deleted. Events from deleted workspaces are kept for up to 6 months after deletion.
The Activity view provides a real-time window into your workspace events:
  • Filter Events: Narrow down by event type, source, or time range
  • Inspect Details: View complete event data including payload and source
  • Track Correlations: Follow chains of related events
  • Debug Issues: Identify problems by examining event flows
This view is invaluable for monitoring, debugging, and understanding your workspace’s behavior.

​
Workspace Secrets

Secrets provide a secure way to store sensitive information like API keys, passwords, and access tokens.
Workspaces can have secrets provided through:
  • The web interface
  • API calls
  • CI pipeline integration with an external secrets manager
By default, only workspace owners can access these secrets.
You can manage secrets programmatically using the /workspaces/:workspaceId/security/secrets API.
Secrets can be used in:
  1. Workspace Configuration:
config:
  value:
    headers:
      apiKey: '{{secret.apiKey}}'
  1. Repository Configuration:
repositories:
  github:
    name: My Repository
    type: git
    mode: read-write
    config:
      url: https://github.com/YourUser/your-repository.git
      branch: main
      auth:
        user: 'your git user'
        password: '{{secret.gitPassword}}'
Secrets beginning with prismeai_* are reserved for super admins to configure system settings.

​
Version Control

Workspace versioning allows you to save the current state of your workspace to a remote git repository, providing backup, history, and collaboration capabilities.
Configure version control in your workspace source code:
repositories:
  github:
    name: My GitHub Repository
    type: git
    mode: read-write
    config:
      url: https://github.com/YourUser/your-repository.git
      branch: main
      auth:
        user: 'your git user'
        password: '{{secret.gitPassword}}'
Different authentication methods are supported:
  • Username/Password: For basic authentication
  • Personal Access Tokens: For services like GitHub which forbid user password usage from CLI, instead they let you generate a Personal Access Token you will use exactly like a password
  • SSH Keys: For secure key-based authentication, see below example.
You can configure multiple repositories with different access modes:
  • read-write (default): Both push and pull operations
  • read-only: Only pull operations
  • write-only: Only push operations
If you want to use SSH authentication, use the following :
repositories:
  github:
    name: Github Perso
    type: git
    mode: read-write
    config:
      url: git@github.com:YourUser/your-repository.git
      branch: main
      auth:
        sshkey: |-
          YOUR SSH
          KEY
          HERE
Note that the repository url must be prefixed with git@ when using SSH, and https:// when using user / password authentication.
You can also use secrets inside repositories config section :
config:
auth:
  password: '{{secret.gitPassword}}
Once a repository is configured:
  • Push: Save the current workspace state to the repository
  • Pull: Update the workspace from the repository
A native repository named “Prismeai” is always available for saving versions to the platform’s storage. However, these versions are lost if the workspace is deleted, unlike with external Git repositories.
Versioning saves the workspace’s static configuration, including security roles, automations, pages, blocks, and apps, but not dynamic data like events, collections, or uploaded files.
When pulling from a repository, you can exclude specific parts of your workspace from being overwritten:
repositories:
  github:
    name: My GitHub Repository
    type: git
    mode: read-write
    config:
      url: https://github.com/YourUser/your-repository.git
      branch: main
    pull:
      exclude:
        - path: 'index'  # Don't override workspace config
        - path: 'security'  # Don't override security files
        - path: 'pages/custom'  # Don't override 'custom' page
This is useful for preserving local customizations while still getting updates from the shared repository.It is also possible to specify pull.exclude option for archive imports using the following system repository (type: archive) :
repositories:
  archives:
    name: Archives
    type: archive
    config: {}
    pull:
      exclude:
        - path: security
        - path: index
After each archive import or repository pull, a workspaces.imported event is emitted with details:
{
 "files": [
  "index",
  "security",
  "pages/test.yml",
   ...
 ],
 "deleted": [
  "automations/removedAutomation.yml"
 ],
 "version": {
  "name": "latest",
  "repository": {
   "id": "yourRepositoryId"
  }
 },
 "errors": [
  {
   "msg": "Could not rename workspace slug from {oldSlug} to {newSlug} as it is already used by workspaceId zlkpbRF",
   "err": "SlugAlreadyInUse",
   "conflictingWorkspaceId": "..."
  }
 ]
}
This event provides a complete record of what changed during the import.
When trying to authenticate using user/password method against a repository with a self-signed HTTPS certificate, you can receive the following error :
  SSL certificate problem: self-signed certificate in certificate chain
This is an infrastructure issue which needs to be solved within prismeai-workspaces deployment, by mounting a copy of the /etc/ssl/certs/ca-certificates.crt file at the same address and adding the git server certificate to it.

​
Custom Domains

You can attach a custom domain to your workspace to display pages under your own domain name.
1

Add DNS Record

Add a CNAME entry to your domain pointing to pages.prisme.aiFor root domains, use an ALIAS record instead of a CNAME.
2

Configure Workspace

Add the domain to your workspace configuration:
customDomains:
  - www.example.com
3

Activate Custom Domain

For Enterprise version, contact support to complete the setup.Contact Support

​
JSON Schema Form

Workspace configuration often uses JSON Schema Form, a standard for creating declarative complex forms. This is particularly important for app configuration.
A schema form starts with a single field, typically of type “object”:
type: 'object'
properties:
  firstname:
    type: string
  lastname:
    type: string
This creates a form with two fields, producing an object with “firstname” and “lastname” properties.
Fields can have various types:
  • string: Text input
  • localized:string: Translatable text
  • number: Numeric input
  • localized:number: Translatable numbers
  • boolean: Switch button
  • localized:boolean: Translatable booleans
  • object: Nested object with properties
  • array: List of items
Additional attributes include:
  • title: Field label
  • description: Help text
  • default: Default value
  • enum: List of allowed values
  • enumNames: Display labels for enum values
  • required: Whether the field is required
  • pattern: Validation regex
  • hidden: Whether to hide the field
Schema forms support advanced features:Custom Widgets
properties:
  description:
    type: string
    ui:widget: textarea
  birthdate:
    type: string
    ui:widget: date
  color:
    type: string
    ui:widget: color
Conditional Fields (oneOf)
properties:
  paymentType:
    oneOf:
      - title: Credit Card
        value: creditCard
        properties:
          cardNumber:
            type: string
            title: Card Number
      - title: Bank Transfer
        value: bankTransfer
        properties:
          accountNumber:
            type: string
            title: Account Number
Arrays and Objects
properties:
  contacts:
    type: array
    title: Contacts
    items:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
Schema forms include validation rules. Each rule can just have a true value to display default message with default behavior but can also be an object with value and message. A field can have many validators. The list of validators is :
  • required: the value is required
  • min: the value as number must be greater than validator value
  • max: the value as number must be lower than validator value
  • email: the value must be a valid email address
  • tel: the value must be a valid phone number
  • date: the value must be a valid Date
  • minLength: the value as string must have a greater length than validator value
  • maxLength: the value as string must have a lower length than validator value
  • pattern: the value must match the regular expression set in validator value.
The following exemple show some implementations of validators:
properties:
  foo:
    type: string
    validators:
      required: true
  bar:
	type: string
    validators:
      required:
        message:
          en: Value is mandatory. Please fill it.
          fr: La valeur est obligatoire. Merci de la renseigner.
		value: true
  email:
    type: string
    validators:
	  email: true
  password:
    type: string
    title: Password
    ui:widget: password
	validators:
	  required: true
      minLength:
        value: 8
        message: Password must be at least 8 characters
Here’s a more complete schema form example:
type: object
title: My Cool Form
description: This is an example of form
properties:
  firstName:
    type: string
    title: Firstname
  lastName:
    type: string
    title: Lastname
  birthdate:
    type: string
    ui:widget: date
    title: Birthdate
  genre:
    type: string
    title: Genre
    enum:
      - 1
      - 2
      - 3
    enumNames:
      - Man
      - Woman
      - Other
  address:
    type: string
    ui:widget: textarea
  hobbies:
    type: object
    title: Your hobbies
    properties:
      favoriteMusic:
        type: array
        title: Favorite music
        items:
          type: string
          title: Type an artist name
This form collects personal information with various field types and widgets.

​
Next Steps

Automations

Create backend processes and workflows

Pages

Build interactive user interfaces

RBAC

Configure security and access control
⌘I