Dockerfile Studio API

Start Dockerfile generations, refine them, download the files and open pull requests from your own tools or CI with a Dockerfile Studio API key.


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

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.

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

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

Send a message, or an action: small, alpine, dev, tests or digest (the quick actions).

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

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`