Organizations & Projects
An Organization groups your workspace's Projects. Each Project holds the configuration and conversation records for a particular integration, customer, or environment.
Resource ownership
Assistants, Channels, Exchanges, Hooks, and Knowledge Bases belong to a Project. Each of these resources has a projectId and an organizationId identifying its owners.
Some resources have a broader scope. AI models come from a shared catalog, and resources such as Processes and Advanced Settings can belong to an Organization without a Project. Do not assume every API endpoint requires a projectId.
Choose your project boundaries
Use separate Projects when resources need separate access or configuration. Common boundaries include:
- Customers, when your integration manages Assistants for several clients.
- Environments, such as development and production.
- Products or teams that manage independent configurations.
For example, use separate Staging and Production Projects to test changes without editing the production Assistant. Resources in each Project have their own IDs. Creating a second Project does not copy the first Project's configuration.
Use Blueprints when you need to provision the same set of related resources repeatedly.
Find your Project ID
List the Projects in your Organization with an organization-scoped API key. Project management endpoints do not accept project-scoped keys. See Authentication for the access rules.
The request paths below are relative to your deployment host and include the /data_next service prefix. Use the deployment shown in the API reference.
Code
The response is an array of Projects. This excerpt shows the fields needed to identify one:
Code
Use the Project's id as projectId. Its organizationId identifies the parent Organization.
Create a Project
Use an organization-scoped key to create a Project in that Organization:
Code
externalId is optional. Use it to link the Project to an identifier in your own system. The response contains the created Project; save its id.
Create resources in a Project
For project-owned resources, the API takes projectId from a project-scoped key. With an organization-scoped key, include the destination projectId in the creation payload. The API checks that the Project belongs to the key's Organization.
Choose the destination before creating a resource. You cannot move an existing resource to another Project by updating its projectId.
Next steps
- Authentication covers creating and using keys for your chosen scope.
- Quickstart creates an Assistant and Channel in one Project.
- Assistants & Models explains the configuration an Assistant holds.