# 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](/docs/blueprints-overview) 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](/docs/authentication#key-scopes) 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](/api).

```http title="List Projects"
GET /data_next/core/projects
Authorization: Bearer {your-org-scoped-key}
```

The response is an array of Projects. This excerpt shows the fields needed to identify one:

```json title="Response excerpt"
[
  {
    "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
    "name": "Production",
    "organizationId": "0464c89f-14cc-42e3-a82d-aa1bc5ff432a"
  }
]
```

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:

```http title="Create a Project"
POST /data_next/core/projects
Authorization: Bearer {your-org-scoped-key}
Content-Type: application/json

{
  "name": "Staging",
  "externalId": "customer-123-staging"
}
```

`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](/docs/authentication) covers creating and using keys for your chosen scope.
- [Quickstart](/docs/quickstart) creates an Assistant and Channel in one Project.
- [Assistants & Models](/docs/assistants-and-models) explains the configuration an Assistant holds.
