# Create an instance

> Create a new instance within an organization.

`POST /api/organizations/{organizationId}/instances`

Create an instance.

Creates a new instance within an organization. Provide a display `name` and a unique `handle`. The instance becomes the scope your product data lives in.

> **Handle is permanent**
>
> The `handle` must be unique and is fixed for the life of the instance - it cannot be changed later. Choose a stable, URL-safe value. Only the display `name` can be updated afterwards.

## Path parameters

| Name             | Type     | Required | Description                              |
| ---------------- | -------- | -------- | ---------------------------------------- |
| `organizationId` | `string` | Yes      | OrganizationInstancesResource identifier |

## Request body

| Property | Type     | Required | Description                                                                                                                                                                                                                                                                                                                                   |
| -------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`   | `string` | Yes      | Human-readable display name of the instance.                                                                                                                                                                                                                                                                                                  |
| `handle` | `string` | Yes      | Stable, URL-safe identifier of the instance. Used as the tenant subdomain when addressing the per-instance product services (e.g. `https://acme-eu.product-management.flowkiwi.net`). Lowercase letters and hyphens only, no leading or trailing hyphen, max 30 characters, unique across all instances. It cannot be changed after creation. |

## Response

**201** - Instance successfully created

| Property                     | Type             | Required | Description                                                                                                                                                                                                                                                                           |
| ---------------------------- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `@context`                   | `object`         | -        |                                                                                                                                                                                                                                                                                       |
| `@id`                        | `string`         | Yes      |                                                                                                                                                                                                                                                                                       |
| `@type`                      | `string`         | Yes      |                                                                                                                                                                                                                                                                                       |
| `id`                         | `string \| null` | -        | Unique identifier of the instance.                                                                                                                                                                                                                                                    |
| `name`                       | `string \| null` | -        | Human-readable display name of the instance.                                                                                                                                                                                                                                          |
| `handle`                     | `string \| null` | -        | Stable, URL-safe identifier of the instance. Used as the tenant subdomain when addressing the per-instance product services (e.g. `https://acme-eu.product-management.flowkiwi.net`). Lowercase letters and hyphens only, no leading or trailing hyphen, unique across all instances. |
| `created_at`                 | `string \| null` | -        | Date and time the instance was created (ISO 8601, UTC).                                                                                                                                                                                                                               |
| `updated_at`                 | `string \| null` | -        | Date and time the instance was last updated (ISO 8601, UTC).                                                                                                                                                                                                                          |
| `organization_id`            | `string \| null` | -        | Identifier of the organization that currently owns the instance.                                                                                                                                                                                                                      |
| `created_by_organization_id` | `string \| null` | -        | Identifier of the organization that originally created the instance. Immutable, it does not change when the instance is transferred to another organization.                                                                                                                          |

## Errors

**400** - Invalid input

| Property   | Type             | Required | Description                                                                                                                          |
| ---------- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `@context` | `object`         | -        |                                                                                                                                      |
| `@id`      | `string`         | Yes      |                                                                                                                                      |
| `@type`    | `string`         | Yes      |                                                                                                                                      |
| `title`    | `string \| null` | -        | A short, human-readable summary of the problem.                                                                                      |
| `detail`   | `string \| null` | -        | A human-readable explanation specific to this occurrence of the problem.                                                             |
| `status`   | `number \| null` | -        |                                                                                                                                      |
| `instance` | `string \| null` | -        | A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. |
| `type`     | `string`         | -        | A URI reference that identifies the problem type                                                                                     |

**403** - Only organization owners can create instances

_No response body._

**404** - Organization not found

_No response body._

**422** - Validation error

| Property     | Type             | Required | Description |
| ------------ | ---------------- | -------- | ----------- |
| `@context`   | `object`         | -        |             |
| `@id`        | `string`         | Yes      |             |
| `@type`      | `string`         | Yes      |             |
| `status`     | `integer`        | -        |             |
| `violations` | `object[]`       | -        |             |
| `detail`     | `string`         | -        |             |
| `type`       | `string`         | -        |             |
| `title`      | `string \| null` | -        |             |
| `instance`   | `string \| null` | -        |             |

## Examples

### Example request

```bash
curl -X POST 'https://identity.flowkiwi.net/api/organizations/<organization_id>/instances' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/ld+json' \
  -H 'Content-Type: application/ld+json' \
  -d '{
  "name": "Acme EU",
  "handle": "acme-eu"
}'
```

### Example response

```json
{
  "@context": "string",
  "@id": "string",
  "@type": "OrganizationInstancesResource",
  "id": "0196f3a0-3333-7000-8000-000000000001",
  "name": "Acme EU",
  "handle": "acme-eu",
  "created_at": "2026-01-16T10:00:00+00:00",
  "updated_at": "2026-01-21T08:45:00+00:00",
  "organization_id": "0196f3a0-1111-7000-8000-000000000001",
  "created_by_organization_id": "0196f3a0-1111-7000-8000-000000000001"
}
```