Deploy Actions

Action endpoints trigger async operations on environments (deploy, restart, start, stop). All action endpoints return 202 Accepted immediately with a task_id. The actual work happens in the background.

Base URL: https://api.oec.sh/api/public/v1

Async Pattern

All action endpoints follow the same pattern:

1. POST the action → receive a task_id and poll_url immediately (202)
2. GET the poll_url to check progress
3. Poll until status reaches a terminal state: completed or failed

Task Status Values

Idempotency

All action endpoints support the Idempotency-Key header. Supply a unique string to safely retry on network errors without triggering duplicate operations. Idempotency results are cached for 24 hours.

Concurrency Protection

Only one action may be queued or running for an environment at a time. If another task is already active, the endpoint returns 409 Conflict with error code task_in_progress.

Trigger a Deployment

POST /environments/{env_id}/deploy

Triggers a full redeployment (pull latest Git code, update containers, run database migrations).

Path Parameters

Headers

Response — 202 Accepted

{
  "task_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "status": "queued",
  "environment_id": "YOUR_ENV_ID",
  "poll_url": "/api/public/v1/deployments/a1b2c3d4-5678-90ab-cdef-1234567890ab"
}

Response Fields

Example

curl -X POST "https://api.oec.sh/api/public/v1/environments/YOUR_ENV_ID/deploy" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: deploy-$(date +%s)"

Restart Environment

POST /environments/{env_id}/restart

Restarts the environment's containers without redeploying code. The environment must be in running status.

Path Parameters

Headers

Response — 202 Accepted

Returns the same action response shape as deploy.

Error Cases

Example

curl -X POST "https://api.oec.sh/api/public/v1/environments/YOUR_ENV_ID/restart" \
  -H "Authorization: Bearer YOUR_API_KEY"

Start Environment

POST /environments/{env_id}/start

Starts a stopped environment. The environment must be in stopped status.

Path Parameters

Headers

Response — 202 Accepted

Returns the same action response shape as deploy.

Error Cases

Example

curl -X POST "https://api.oec.sh/api/public/v1/environments/YOUR_ENV_ID/start" \
  -H "Authorization: Bearer YOUR_API_KEY"

Stop Environment

POST /environments/{env_id}/stop

Stops a running environment's containers. Data is preserved. The environment must be in running status.

Path Parameters

Headers

Response — 202 Accepted

Returns the same action response shape as deploy.

Error Cases

Example

curl -X POST "https://api.oec.sh/api/public/v1/environments/YOUR_ENV_ID/stop" \
  -H "Authorization: Bearer YOUR_API_KEY"

List Deployments

GET /environments/{env_id}/deployments

Returns the deployment history for an environment, newest first. Only includes deploy and redeploy task types.

Path Parameters

Query Parameters

Response — 200 OK

{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "type": "deploy",
      "status": "completed",
      "environment_id": "YOUR_ENV_ID",
      "progress_percent": 100,
      "current_step": null,
      "steps_completed": 12,
      "total_steps": 12,
      "started_at": "2026-03-01T12:00:00Z",
      "completed_at": "2026-03-01T12:05:00Z",
      "duration_seconds": 300,
      "error_message": null,
      "triggered_by": null
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null,
    "total": 5
  }
}

Deployment Object Fields

Get Deployment Status

GET /deployments/{task_id}

Returns the current status of a single deployment task. Use this to poll after triggering an action.

Path Parameters

Response — 200 OK

Returns the Deployment object.

Complete Polling Example

Deploy an environment and wait for it to finish:

import requests
import time
 
BASE_URL = "https://api.oec.sh/api/public/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}
ENV_ID = "YOUR_ENV_ID"
 
# Step 1: Trigger deploy
response = requests.post(
    f"{BASE_URL}/environments/{ENV_ID}/deploy",
    headers=HEADERS,
)
response.raise_for_status()
data = response.json()
task_id = data["task_id"]
print(f"Deploy queued. Task ID: {task_id}")
 
# Step 2: Poll until complete
while True:
    status_response = requests.get(
        f"{BASE_URL}/deployments/{task_id}",
        headers=HEADERS,
    )
    task = status_response.json()
    print(f"Status: {task['status']} ({task['progress_percent']}%)")
 
    if task["status"] in ("completed", "failed", "cancelled"):
        break
 
    time.sleep(5)
 
# Step 3: Check result
if task["status"] == "completed":
    print("Deploy succeeded!")
else:
    print(f"Deploy failed: {task['error_message']}")