---
title: "Create a new organization (Basic)"
method: POST
path: "/organizations"
tags: ["Organizations"]
---

# Create a new organization (Basic)

`POST /organizations`

Create a new organization and assign the current user as admin.

## Request body

- OrganizationCreate — Pydantic model for creating an organization (request body).
  - `name` string, required

## Response `201`

Successful Response

- Organization — Pydantic model for an organization.
  - `id` string, required
  - `name` string, required
  - `slug` string, required
  - `usage_limit` union — Monthly usage limit
    - object
    - string
  - `nav_config` object, nullable — Per-organization nav config: { '<key>': { 'show': bool, 'disabled': bool, 'badgeLabel': str | None, 'badgeTooltip': str | None } }
  - `plotting_preferences` string, nullable — Free-text markdown describing how this organization wants the battery agent to format plots; injected into the agent's system prompt each turn. None means not set (nothing is injected).
  - `logo_path` string, nullable — Storage object path of the light-mode organization logo, or None when unset. Not a URL: the bucket is private, so clients fetch the image from GET /organizations/{id}/logo, which returns a signed URL. Set via POST /organizations/{id}/logo, not via PATCH.
  - `logo_path_dark` string, nullable — Storage object path of the dark-mode organization logo, or None when unset. Optional: dark mode falls back to `logo_path` when this is None, and light mode falls back to this when `logo_path` is None. Set via POST /organizations/{id}/logo?variant=dark.
  - `user_organization_roles` UserOrganizationRole[], nullable — List of user organization roles
    - `user_id` string, nullable
    - `users` UsersResponse
      - `id` string, required
      - `email` string, nullable
    - `organization_id` string, required
    - `organization_role_id` string, nullable
    - `organization_roles` OrganizationRole
      - `name` string, required
      - `id` string, nullable
      - `created_at` string, date-time, nullable
      - `updated_at` string, date-time, nullable
      - `organization_role_permissions` object[], nullable — The permissions for the organization role.
    - `deactivated_at` string, date-time, nullable
  - `created_at` string, date-time, nullable — Timestamp of creation
  - `updated_at` string, date-time, nullable — Timestamp of last update

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/ionworks/apis/fastapi.md) · [All operations](https://skmtc.dev/ionworks/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ionworks/fastapi/revisions/7337a3cbdaf2/schema)