# Organizations

This resource lets you work with organizations in YouTrack.
Available since YouTrack 2026.1.

|  Resource  |     ```GENERIC /api/admin/organizations ```    |
| --- | --- |
|  Returned entity  |  [Organization](api-entity-Organization.html). For the description of the entity attributes, see [Supported Fields](#Organization-supported-fields) section.  |
|  Supported methods  |      * `GET`: [Read a List of Organizations](#get_all-Organization-method).    * `POST`: [Add a New Organization](#create-Organization-method).    |

## Organization attributes

Represents an organization in YouTrack.

Available since YouTrack 2026.1.

### Attributes

This table describes attributes of the `Organization` entity.

* To receive an attribute in the response from the server, specify it explicitly in the `fields` request parameter.

* To update an attribute, provide it in the body of a POST request.

|  Field  |  Type  |  Description  |
| --- | --- | --- |
|  id  |  String  |  The database ID of the organization. `Read-only`.  |
|  key  |  String  |  The unique key of the organization.  |
|  name  |  String  |  The name of the organization.  |
|  description  |  String  |  The description of the organization. `Can be null`.  |
|  iconUrl  |  String  |  The URL of the organization's icon. `Read-only`. `Can be null`.  |
|  projects  |  [Array of Projects](api-entity-Project.html)  |  The list of projects that belong to the organization.  |

## Read a List of Organizations

Get the list of all organizations in YouTrack.

### Request syntax

```GENERIC
GET /api/admin/organizations?{fields}&{$top}&{$skip}
```

|  null  |  The database ID of Organization  |
| --- | --- |

### Request parameters

|  Parameter  |  Type  |  Description  |
| --- | --- | --- |
|  fields  |  String  |  A list of Organization attributes that should be returned in the response. If no field is specified, only the `entityID` is returned.  |
|  $skip  |  Int  |  Optional. Lets you set a number of returned entities to skip before returning the first one.  |
|  $top  |  Int  |     Optional. Lets you specify the maximum number of entries that are returned in the response. If you don't set the $top value, the server limits the maximum number of returned entries.       The server returns a maximum of 42 entries for most resources that return collections. For more information, see [Pagination](api-concept-pagination.html).     |

### Sample

#### Sample request

```CURL
https://example.youtrack.cloud/api/admin/organizations?fields=id,key,name,projects(id,name,shortName)
```

#### Sample response body

```JSON
[
  {
    "id": "120-1",
    "key": "92da6595-c398-481d-9071-c821ff49772b",
    "name": "JetBrains",
    "projects": [
      {
        "id": "0-0",
        "name": "Sample Project",
        "shortName": "SP",
        "$type": "Project"
      }
    ],
    "$type": "Organization"
  },
  {
    "id": "120-2",
    "key": "V2x9UNmH_L-5PHQ71qd0S",
    "name": "Acme Corp",
    "projects": [],
    "$type": "Organization"
  }
]
```

## Add a New Organization

Create a new organization in YouTrack.

Required fields: `name`.

### Request syntax

```GENERIC
POST /api/admin/organizations?{fields}
```

|  null  |  The database ID of Organization  |
| --- | --- |

### Request parameters

|  Parameter  |  Type  |  Description  |
| --- | --- | --- |
|  fields  |  String  |  A list of Organization attributes that should be returned in the response. If no field is specified, only the `entityID` is returned.  |

### Sample

#### Sample request

```CURL
https://example.youtrack.cloud/api/admin/organizations?fields=id,key,name,projects(id,name,shortName)
```

#### Sample request body

```JSON
{
  "name": "Acme Corp",
  "key": "acme"
}
```

#### Sample response body

```JSON
{
  "id": "120-2",
  "key": "acme",
  "name": "Acme Corp",
  "projects": [],
  "$type": "Organization"
}
```