---
title: Repositories API
description: Create, read, rename, list and delete integration repositories on /distribution/v1/repositories.
slug: distribution/repositories-api
docKind: reference
hub: luigisbox-ai
---

Repositories are managed on `/distribution/v1/repositories`, with a token for the
`https://api.<region>.luigisbox.ai/distribution` audience.

```text
POST   /distribution/v1/repositories
GET    /distribution/v1/repositories?organization_id=…
GET    /distribution/v1/repositories/{repository_id}
PATCH  /distribution/v1/repositories/{repository_id}
DELETE /distribution/v1/repositories/{repository_id}
```

A repository is addressed by its ID alone — the owning organization travels in the create
body and as a list filter.

:::hub[Config → Front-end Integration]{path="/frontend-integration"}
Lists your organization's repositories with their state, creates one, renames one, and
copies the clone URL and the loader script URL. Deleting a repository, and setting
`channel_id` and `channel_name` at creation, are API-only.
:::

## The repository record

```json
{
  "repository_id": "lbdr_8w3k2p",
  "organization_id": "lbo_r2vn8c",
  "name": "example.com storefront",
  "state": "active",
  "git_url": "https://git.eu1.luigisbox.ai/lbo_r2vn8c/lbdr_8w3k2p.git",
  "loader_script_url": "https://cdn.eu1.luigisbox.ai/b/lbdr_8w3k2p/loader.js",
  "created_at": "2026-09-03T10:12:44Z",
  "updated_at": "2026-09-03T10:12:44Z"
}
```

| Field | Notes |
|---|---|
| `repository_id` | Assigned, immutable |
| `organization_id` | Owner, immutable |
| `name` | Display label, or `null`. Metadata only — never written into the repository's code. |
| `state` | `active`, `provisioning` or `deleting` — see below |
| `git_url` | Clone and push URL |
| `loader_script_url` | Public URL of the published script. `404` until the first release. |

Read both URLs from this record rather than composing them. They are stable for the life of
the repository, so embedding `loader_script_url` in your storefront once is enough.

### State

| `state` | Meaning |
|---|---|
| `active` | Ready. The only state it can be cloned or pushed in. |
| `provisioning` | Creation has not finished |
| `deleting` | A delete did not finish |

A repository that stays in `provisioning` or `deleting` did not finish that operation. For a
stuck delete, repeat the delete — that is what completes it.

## Creating

| Field | Required | Notes |
|---|---|---|
| `organization_id` | Yes | Owner. Immutable. |
| `name` | No | Display label, 1–200 characters, single-line |
| `channel_id` | No | The channel the seeded integration reads |
| `channel_name` | No | The channel's name, usually the site's domain |

```bash
curl -X POST 'https://api.eu1.luigisbox.ai/distribution/v1/repositories' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "organization_id": "lbo_r2vn8c",
    "name": "example.com storefront",
    "channel_id": "lbn_4hj9tv",
    "channel_name": "example.com"
  }'
```

Responds `201` with the record, and the repository is seeded with the scaffold, a `main`
branch and a `testing` branch.

`channel_id` and `channel_name` shape what the seeded repository knows about itself: the
channel it reads, and the site name recorded in its agent instructions. Both can be set
afterwards by editing the repository, but passing them now saves an agent from having to ask
which site it is working on.

## Renaming

```bash
curl -X PATCH 'https://api.eu1.luigisbox.ai/distribution/v1/repositories/lbdr_8w3k2p' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"name": "example.com — storefront"}'
```

`name` is the only editable field. Omitting it leaves the current name; sending `null` clears
it. The name is metadata: renaming changes nothing inside the repository and nothing about
its URLs.

## Listing

```bash
curl -G 'https://api.eu1.luigisbox.ai/distribution/v1/repositories' \
  --data-urlencode 'organization_id=lbo_r2vn8c' \
  -H 'Authorization: Bearer <token>'
```

`organization_id` is required. One page of that organization's repositories, oldest first,
in the standard [paginated envelope](/api-basics/requests-and-responses/#pagination).
Repositories mid-create or mid-delete are listed too, and say so in `state`.

## Deleting

```bash
curl -X DELETE 'https://api.eu1.luigisbox.ai/distribution/v1/repositories/lbdr_8w3k2p' \
  -H 'Authorization: Bearer <token>'
```

:::danger[Permanent]
This deletes the repository and its entire git history. It is not recoverable, and there is
no archived state to restore from — unlike a
[campaign](/merchandising/business-rules/authoring-api/#archiving), which archives rather than erases.
Clone a copy first if there is any chance you want the history.
:::

Responds `204`. A delete that fails leaves the repository listed as `deleting`; repeating it
is safe and is what finishes it.

## Access

Luigi's Box grants your credentials the capability to read, push to and manage repositories,
per repository or across an organization. A valid token whose principal holds no grant on a
repository gets `403`; one that may not see the repository at all gets `404`, so an ID
cannot be probed for existence.

Push permission is granted per branch category: pushing to feature branches and pushing to
`main` are separate permissions. A push refused with a `remote:` permission message needs a
wider grant — ask Luigi's Box.

## See also

- [Your first integration](/distribution/quickstart/) — these calls in sequence
- [Previews and releases](/distribution/previews-and-releases/) — what a push does
- [Server-to-server tokens](/authentication/server-to-server/) — getting the token
- [API Reference](/api/)