# Dockerfile Studio API
Source: https://docs.infraista.com/en/developer-tools/dockerfile-studio/api



|                |                                                                               |
| -------------- | ----------------------------------------------------------------------------- |
| Base URL       | `https://api.infraista.com/api/v1/dockerfile-studio`                          |
| Authentication | `Authorization: Bearer <API key>`                                             |
| Rate limits    | 300 requests a minute per key; starting generations is limited to 30 a minute |

## Get a key [#get-a-key]

Create a **Dockerfile Studio** key under **Settings › API keys**, for one organization, with the scopes
you need:

* `dockerfile:read`: list and read generations, read settings, download the files;
* `dockerfile:write`: start, refine and edit generations, restore versions and open pull requests
  (includes read).

Each call also needs the key owner's Dockerfile Studio permission for that action; without it the API
answers 403. A full-access key works too, with `?organization=<id>`. See [API keys](/en/account/api-keys).

## Endpoints [#endpoints]

| Method | Path                             | Scope | What it does                                                                    |
| ------ | -------------------------------- | ----- | ------------------------------------------------------------------------------- |
| GET    | `/generations?limit=50`          | read  | Newest first (up to 100), with this month's usage                               |
| POST   | `/generations`                   | write | Start a generation. Answers 202                                                 |
| GET    | `/generations/<id>`              | read  | Status, steps, detection, current files, checks, versions and pull request      |
| POST   | `/generations/<id>/refine`       | write | A `message` in plain language, or an `action`. Answers 202                      |
| PUT    | `/generations/<id>/files`        | write | Your own edit: `file` (`dockerfile`, `dockerignore` or `compose`) and `content` |
| POST   | `/generations/<id>/restore`      | write | Make a `version` current                                                        |
| GET    | `/generations/<id>/download.zip` | read  | The current files                                                               |
| POST   | `/generations/<id>/pull-request` | write | Open the pull request. Answers 201                                              |
| GET    | `/settings`                      | read  | Your organization's defaults and rules                                          |

## Start a generation [#start-a-generation]

```bash
curl -X POST https://api.infraista.com/api/v1/dockerfile-studio/generations \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"connectionId": 12, "repo": "northwind/web-app", "ref": "main", "path": ".",
       "options": {"target": "prod", "base": "slim", "arch": "amd64", "compose": false}}'
```

* `connectionId` is a Git connection in the organization (GitHub, GitLab or Bitbucket).
* All `options` are optional; missing ones come from your organization's defaults.

| Option                                         | Values                                                 |
| ---------------------------------------------- | ------------------------------------------------------ |
| `target`                                       | `prod`, `dev`                                          |
| `base`                                         | `slim`, `alpine`, `distroless`                         |
| `arch`                                         | `amd64`, `arm64`, `multi`                              |
| `healthcheck`, `pinDigest`, `tests`, `compose` | `true` or `false`                                      |
| `healthPath`                                   | For example `/healthz`                                 |
| `extra`                                        | Instructions in plain language, up to 1,000 characters |

Then poll `GET /generations/<id>` until `status` is `ready` or `failed`. In between it's `queued`,
`analysing`, `detected`, `generating` or `refining`. The files are in `version.files` and the checks in
`version.checks`.

## Refine [#refine]

Send a `message`, or an `action`: `small`, `alpine`, `dev`, `tests` or `digest` (the
[quick actions](/en/developer-tools/dockerfile-studio/refine-and-open-a-pull-request#refine-with-ai)).

## Open a pull request [#open-a-pull-request]

All fields are optional; missing ones come from your settings: `branch`, `title`, `body`, `files` (any
of `dockerfile`, `dockerignore`, `compose`), `reviewers`, `labels`, `draft`, `footer`. The pull request
always opens against the repository's default branch, from a new branch. The answer includes any
`warnings`.

## Errors [#errors]

| Status | When                                                                                                                                                                                 |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 403    | The key is missing a scope (`missing_scope`), or its owner lacks the permission (`forbidden`)                                                                                        |
| 404    | The generation isn't in this organization, or Dockerfile Studio is off                                                                                                               |
| 422    | Invalid input, or the request was refused (for example the monthly allowance is used up while new generations are stopped, or the branch already exists). The reason is in `message` |

## Related [#related]

* [Generate a Dockerfile](/en/developer-tools/dockerfile-studio/generate-a-dockerfile)
* [API keys](/en/account/api-keys)