Update Deploy Image

Updates the Docker image of the project to initiate a new deploy.

Required permissions

The minimum scope is project.image.update on project:<project-id>. An owner user session has full access; assistant, member, and organization API Keys need this specific grant.

PATCH /v1/project/:id/image

Apart from the preview environment routes with the opt-in enabled, this is the only route that still accepts the legacy project key. Rate limit: 10 requests per minute (counted per source IP).

Path Parameters

Parameter	Type	Description
`id`	string	Project ID

Headers

Header	Required	Description
`x-api-key` or `Authorization`	Yes	Organization API Key or user token
`x-organization-id`	With a user token	Active project organization. Not needed with an organization API key
`Content-Type: application/json`	Yes	Required because the request has a JSON body

Body

Field	Type	Required	Description
`image`	string	Yes	Docker image name with registry and tag (e.g., `docker.io/library/nginx:1.27.3`, `myregistry.com/myapp:v1.0`). Important: Always use a specific, immutable tag (like `v1.0.0`) instead of `latest` to avoid pulling different images unexpectedly. Length from 8 to 256 characters; references starting with `http://` or `https://` are rejected.

Example

{
  "image": "docker.io/library/nginx:1.27.3"
}

Response

{
  "status": "success",
  "message": "updated with success"
}

Errors

Status	When it happens
`400`	`image` missing or in an invalid format
`404`	Project not found

Examples

curl

curl -X PATCH "https://api.zenifra.com/v1/project/507f1f77bcf86cd799439011/image" \
  -H "x-api-key: your-api-key" \
  -H "x-organization-id: your-organization-id" \
  -H "Content-Type: application/json" \
  -d '{"image": "docker.io/library/nginx:1.27.3"}'

Python

import requests

API_KEY = "your-api-key"
ORGANIZATION_ID = "your-organization-id"
PROJECT_ID = "507f1f77bcf86cd799439011"

response = requests.patch(
    f"https://api.zenifra.com/v1/project/{PROJECT_ID}/image",
    headers={"x-api-key": API_KEY, "x-organization-id": ORGANIZATION_ID},
    json={"image": "docker.io/library/nginx:1.27.3"}
)
print(response.json())

Node.js

const axios = require('axios');

const API_KEY = 'your-api-key';
const ORGANIZATION_ID = 'your-organization-id';
const PROJECT_ID = '507f1f77bcf86cd799439011';

axios.patch(
  `https://api.zenifra.com/v1/project/${PROJECT_ID}/image`,
  { image: 'docker.io/library/nginx:1.27.3' },
  { headers: { 'x-api-key': API_KEY, 'x-organization-id': ORGANIZATION_ID } }
).then(res => console.log(res.data));

On this page