---
title: API reference: Organizations
description: List, create, and read organizations and their repositories with the GitLite REST API.
url: https://pr-1-12825562dfc9.thally.app/api/organizations
lastVerified: 2026-09-15T00:00:00.000Z
verifiedVersion: GitLite 1.27.3
---

# API reference: Organizations

List, create, and read organizations and their repositories with the GitLite REST API.

All endpoints on this page are relative to `http://localhost:3000/api/v1` and
require an access token in the `Authorization` header, set up as `GITLITE_AUTH` in
[Authentication](/authentication). The examples use an organization named
`acme`.

| Method | Path | Operation | Scope |
| --- | --- | --- | --- |
| `GET` | `/orgs` | List all organizations | `read:organization` |
| `POST` | `/orgs` | Create an organization | `write:organization` |
| `GET` | `/orgs/{org}` | Get an organization | `read:organization` |
| `GET` | `/orgs/{org}/repos` | List an organization's repositories | `read:organization` |

## List organizations

`GET /orgs` accepts `page` and `limit` (default and maximum page size are on
[Pagination](/pagination)) and returns
`200` with an array of `Organization` objects visible to you, plus
`X-Total-Count`. See [Pagination](/pagination).

#### curl

    ```bash
    curl -s "http://localhost:3000/api/v1/orgs?limit=10" \
      -H "Authorization: $GITLITE_AUTH"
    ```

#### JavaScript

    ```js
    const res = await fetch('http://localhost:3000/api/v1/orgs?limit=10', {
      headers: { Authorization: process.env.GITLITE_AUTH },
    })
    console.log(res.headers.get('x-total-count'), (await res.json()).map((o) => o.name))
    ```

## Create an organization

`POST /orgs`

| Body field | Type | Required | Description |
| --- | --- | --- | --- |
| `username` | string | yes | Organization name, used in URLs. |
| `full_name` | string | no | Display name. |
| `description` | string | no | Short description. |
| `visibility` | string | no | `public` (default), `limited`, or `private`. |

| Status | Meaning |
| --- | --- |
| `201` | Organization created. You are its owner. |
| `403` | Your account is not allowed to create organizations. |
| `422` | Validation failed, or the name is already taken. |

#### curl

    ```bash
    curl -s -X POST http://localhost:3000/api/v1/orgs \
      -H "Authorization: $GITLITE_AUTH" \
      -H "Content-Type: application/json" \
      -d '{"username": "acme-docs", "full_name": "Acme Documentation", "visibility": "private"}'
    ```

#### JavaScript

    ```js
    const res = await fetch('http://localhost:3000/api/v1/orgs', {
      method: 'POST',
      headers: {
        Authorization: process.env.GITLITE_AUTH,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ username: 'acme-docs-js', visibility: 'private' }),
    })
    console.log(res.status, (await res.json()).name)
    ```

## Get an organization

`GET /orgs/{org}` returns `200` with an `Organization`, or `404`.

#### curl

    ```bash
    curl -s http://localhost:3000/api/v1/orgs/acme \
      -H "Authorization: $GITLITE_AUTH"
    ```

#### JavaScript

    ```js
    const res = await fetch('http://localhost:3000/api/v1/orgs/acme', {
      headers: { Authorization: process.env.GITLITE_AUTH },
    })
    const org = await res.json()
    console.log(res.status, org.name, org.visibility)
    ```

## List an organization's repositories

`GET /orgs/{org}/repos` accepts `page` and `limit` and returns `200` with an array
of `Repository` objects and `X-Total-Count`.

#### curl

    ```bash
    curl -s "http://localhost:3000/api/v1/orgs/acme/repos?page=1&limit=20" \
      -H "Authorization: $GITLITE_AUTH"
    ```

#### JavaScript

    ```js
    const res = await fetch('http://localhost:3000/api/v1/orgs/acme/repos?page=1&limit=20', {
      headers: { Authorization: process.env.GITLITE_AUTH },
    })
    console.log(res.headers.get('x-total-count'), (await res.json()).length)
    ```