# Image access API

Source: https://docs.oiy.ai/docs/api/images

Create, rotate, inspect, and remove exact-repository pull access.



## Operations [#operations]

| Method | Path                   | Purpose                                                |
| ------ | ---------------------- | ------------------------------------------------------ |
| GET    | `/api/registries`      | Read account-owned access metadata and linked services |
| POST   | `/api/registries`      | Save access for a private repository                   |
| PUT    | `/api/registries/{id}` | Replace credentials at the current revision            |
| DELETE | `/api/registries/{id}` | Remove access after linked services are paused         |

All operations use normal Oiy account authentication. Creating and rotating require verified email; these routes are not restricted to interactive Firebase sign-in. Mutations require `Idempotency-Key`.

## Create body [#create-body]

The strict specification contains:

| Field        | Requirement                                                                        |
| ------------ | ---------------------------------------------------------------------------------- |
| `name`       | Trimmed display name, 1–64 characters                                              |
| `repository` | Exact fully qualified repository, 3–512 characters, without scheme, tag, or digest |
| `username`   | Write-only, 1–512 characters; no colon, line break, or null character              |
| `password`   | Write-only pull credential, 1–8,192 characters                                     |

Use a repository-scoped pull-only credential. Supply secret values from a secure local environment when building the HTTPS request. They are not service environment variables.

A successful creation returns a **bare metadata object** with HTTP `201`: `id`, `name`, `repository`, `revision`, `createdAt`, and `updatedAt`. Timestamps are Unix milliseconds. No username or password is returned.

## Read metadata [#read-metadata]

`GET /api/registries` returns `{ "registries": [...] }`. Each entry extends the metadata with `services`, listing linked service ID, name, status, and allocation state. The list never exposes secret material.

## Rotate [#rotate]

`PUT /api/registries/{id}` accepts a wrapper containing the current `revision` and a complete `spec`. Include the unchanged repository, the desired display name, and replacement username/password values.

The response is a bare metadata object with HTTP `200`. Rotation affects future admitted launches; it neither stops existing work nor rewrites already-admitted credential snapshots.

## Remove [#remove]

`DELETE /api/registries/{id}` includes a JSON body with `revision`. Every linked service must be `sleeping` and unallocated. The response is `{ "id": "REGISTRY_ID", "deleted": true }`.

Deletion removes saved access, not image contents or workspace files. Bound services must restore access or change images before launching again; they do not silently fall back to anonymous pulls.

## Common rejections [#common-rejections]

| Code                       | Meaning                                                               |
| -------------------------- | --------------------------------------------------------------------- |
| `EMAIL_NOT_VERIFIED`       | Verify the account before saving or rotating.                         |
| `REGISTRY_SCOPE`           | The repository cannot be changed in-place.                            |
| `REGISTRY_EXISTS`          | This exact repository already has an entry.                           |
| `REGISTRY_LIMIT`           | The account already has 20 entries.                                   |
| `REVISION_CHANGED`         | Read the latest metadata before another mutation.                     |
| `REGISTRY_IN_USE`          | Wait for confirmed pause of all linked services.                      |
| `REGISTRY_ACCESS_REQUIRED` | Restore access or choose another image before a bound service starts. |

See [Private container images](/docs/private-images) for the complete user workflow.