Using the Deploynix API to Automate Your Deployment Workflow

Clicking a "Deploy" button works fine when you are shipping once a day. But as your team grows and your release cadence accelerates, manual deployments become a bottleneck. You want deployments to happen automatically when your CI pipeline passes, triggered by a merge to main, not by someone remembering to log into a dashboard.

Deploynix provides a comprehensive REST API that lets you automate every aspect of your deployment workflow. Built on Laravel Sanctum token authentication with granular abilities, the API gives you fine-grained control over what automated systems can and cannot do with your infrastructure. API access is available on Professional and Enterprise plans.

In this guide, we will cover creating and managing API tokens, understanding token abilities, triggering deployments programmatically, integrating with GitHub Actions, and setting up Slack notifications for deployment status.

Creating an API Token

API tokens in Deploynix are personal access tokens tied to your user account. They inherit your permissions within the organization, so a token can only access servers and sites that you have access to.

To create a token, navigate to your account settings and find the API Tokens section. Click "Create Token" and you will be prompted for two things: a name and a set of scopes.

Token name: Give it a descriptive name that tells you where the token is used. Something like "GitHub Actions - Production" or "CI Pipeline - Staging" makes it easy to audit and rotate tokens later.

Abilities: This is where Deploynix's API security model shines. Instead of creating all-powerful tokens, you select only the permissions the token needs. Abilities follow a resource:action pattern with granular CRUD controls:

• server:read — View server details and status
• server:create, server:update, server:delete — Manage servers
• site:read — View site details and configuration
• site:create, site:update, site:delete — Manage sites
• site:deploy — Trigger, schedule, cancel, and rollback deployments
• database:read — View database details
• database:create, database:update, database:delete — Manage databases
• certificate:read — View SSL certificate status
• certificate:create, certificate:delete — Provision and manage SSL certificates
• queue-worker:read, queue-worker:create, queue-worker:update, queue-worker:delete — Manage queue workers
• daemon:read, daemon:create, daemon:update, daemon:delete — Manage daemons
• crontab:read, crontab:create, crontab:update, crontab:delete — Manage cron jobs

For a CI/CD pipeline that only needs to trigger deployments, you would select site:deploy and site:read. There is no reason to give your CI system the ability to delete servers or modify database configurations.

After creating the token, Deploynix displays it once. Copy it immediately and store it securely. You will not be able to see the full token again.

Authentication

Every API request must include your token in the Authorization header using the Bearer scheme:

curl -X GET https://deploynix.io/api/v1/servers \
  -H "Authorization: Bearer your-api-token-here" \
  -H "Accept: application/json"

If the token is invalid, expired, or lacks the required ability for the requested endpoint, you will receive a 401 Unauthorized or 403 Forbidden response.

Core API Endpoints

Let us walk through the endpoints you will use most frequently in an automated deployment workflow.

Listing Your Servers

GET /api/v1/servers

This returns a paginated list of servers in your organization. Each server object includes its name, IP address, status, provider, region, and other metadata. Use this to programmatically discover server IDs for subsequent API calls.

Getting Server Details

GET /api/v1/servers/{serverId}

Returns detailed information about a specific server, including its sites, databases, and current resource usage.

Listing Sites on a Server

GET /api/v1/servers/{serverId}/sites

Returns all sites configured on the specified server. You will need the site ID to trigger deployments.

Triggering a Deployment

This is the endpoint your CI/CD pipeline will call most often:

POST /api/v1/servers/{serverId}/sites/{siteId}/deploy

This triggers a new deployment for the specified site. The deployment follows the same pipeline as a manual deployment from the dashboard: pulling the latest code, installing dependencies, running migrations, building assets, and swapping the symlink.

The response confirms the deployment has been queued:

{
  "message": "Deployment started."
}

Checking Site Status

To monitor the deployment progress, poll the site details endpoint:

GET /api/v1/servers/{serverId}/sites/{siteId}

The site's status field reflects the current state. Status values include pending, installing, deploying, active, failed, configuring, and deleting. A site transitions to deploying when a deployment is in progress and back to active when it completes successfully.

Rolling Back a Deployment

If something goes wrong, you can roll back to the previous release (available for sites with zero-downtime deployments enabled):

POST /api/v1/servers/{serverId}/sites/{siteId}/rollback

Getting Server Logs

To view server-level logs including deployment output:

GET /api/v1/servers/{serverId}/logs

This is invaluable for debugging failed deployments in your CI pipeline without needing to log into the Deploynix dashboard.

GitHub Actions Integration

Now let us put this together in a real-world CI/CD pipeline. Here is a GitHub Actions workflow that runs your test suite and, if tests pass, triggers a deployment to Deploynix.

Create a file at .github/workflows/deploy.yml in your repository:

name: Test & Deploy

on:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      mysql:
        image: mysql:8
        env:
          MYSQL_ROOT_PASSWORD: password
          MYSQL_DATABASE: testing
        ports:
          - 3306:3306
        options: >-
          --health-cmd="mysqladmin ping"
          --health-interval=10s
          --health-timeout=5s
          --health-retries=3

    steps:
      - uses: actions/checkout@v4

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: "8.4"
          extensions: mbstring, xml, curl, zip, bcmath, redis, mysql
          coverage: none

      - name: Install Dependencies
        run: composer install --no-interaction --prefer-dist

      - name: Run Tests
        run: php artisan test --compact
        env:
          DB_CONNECTION: mysql
          DB_HOST: 127.0.0.1
          DB_PORT: 3306
          DB_DATABASE: testing
          DB_USERNAME: root
          DB_PASSWORD: password

  deploy:
    needs: test
    runs-on: ubuntu-latest
    if: success()
    steps:
      - name: Trigger Deploynix Deployment
        run: |
          RESPONSE=$(curl -s -w "\n%{http_code}" -X POST \
            "https://deploynix.io/api/v1/servers/${{ secrets.DEPLOYNIX_SERVER_ID }}/sites/${{ secrets.DEPLOYNIX_SITE_ID }}/deploy" \
            -H "Authorization: Bearer ${{ secrets.DEPLOYNIX_API_TOKEN }}" \
            -H "Accept: application/json" \
            -H "Content-Type: application/json")

          HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
          BODY=$(echo "$RESPONSE" | sed '$d')

          if [ "$HTTP_CODE" -ne 200 ] && [ "$HTTP_CODE" -ne 201 ]; then
            echo "Deployment trigger failed with status $HTTP_CODE"
            echo "$BODY"
            exit 1
          fi

          echo "Deployment triggered successfully"

      - name: Wait for Deployment
        run: |
          SERVER_ID=${{ secrets.DEPLOYNIX_SERVER_ID }}
          SITE_ID=${{ secrets.DEPLOYNIX_SITE_ID }}

          for i in $(seq 1 60); do
            STATUS=$(curl -s \
              "https://deploynix.io/api/v1/servers/$SERVER_ID/sites/$SITE_ID" \
              -H "Authorization: Bearer ${{ secrets.DEPLOYNIX_API_TOKEN }}" \
              -H "Accept: application/json" \
              | jq -r '.data.status')

            echo "Site status: $STATUS (attempt $i/60)"

            if [ "$STATUS" = "active" ]; then
              echo "Deployment completed successfully!"
              exit 0
            elif [ "$STATUS" = "failed" ]; then
              echo "Deployment failed!"
              exit 1
            fi

            sleep 10
          done

          echo "Deployment timed out"
          exit 1

Setting Up GitHub Secrets

Before this workflow will work, add these secrets to your GitHub repository settings:

• DEPLOYNIX_API_TOKEN — Your API token with site:deploy and site:read abilities
• DEPLOYNIX_SERVER_ID — The numeric ID of your server (visible in the Deploynix dashboard URL or API response)
• DEPLOYNIX_SITE_ID — The numeric ID of your site

GitLab CI/CD Integration

If you use GitLab instead of GitHub, the concept is identical. Here is a .gitlab-ci.yml equivalent:

stages:
  - test
  - deploy

test:
  stage: test
  image: php:8.4-cli
  script:
    - composer install --no-interaction
    - php artisan test --compact

deploy:
  stage: deploy
  image: curlimages/curl:latest
  only:
    - main
  script:
    - |
      RESPONSE=$(curl -s -X POST \
        "https://deploynix.io/api/v1/servers/${DEPLOYNIX_SERVER_ID}/sites/${DEPLOYNIX_SITE_ID}/deploy" \
        -H "Authorization: Bearer ${DEPLOYNIX_API_TOKEN}" \
        -H "Accept: application/json")
      echo $RESPONSE

Adding Slack Notifications

Knowing when a deployment succeeds or fails is crucial. You can extend your CI pipeline to send Slack notifications after each deployment.

Add a notification step to your GitHub Actions workflow:

- name: Notify Slack
        if: always()
        run: |
          if [ "${{ job.status }}" = "success" ]; then
            COLOR="#36a64f"
            STATUS="successful"
            EMOJI=":white_check_mark:"
          else
            COLOR="#dc3545"
            STATUS="failed"
            EMOJI=":x:"
          fi

          curl -X POST ${{ secrets.SLACK_WEBHOOK_URL }} \
            -H "Content-Type: application/json" \
            -d "{
              \"attachments\": [{
                \"color\": \"$COLOR\",
                \"text\": \"$EMOJI Deployment to production $STATUS\nCommit: ${{ github.sha }}\nAuthor: ${{ github.actor }}\"
              }]
            }"

This gives your team instant visibility into deployment status without anyone needing to watch the CI pipeline or the Deploynix dashboard.

Scheduled Deployments via API

Deploynix supports scheduled deployments, allowing you to trigger a deployment that will execute at a future time. This is useful for coordinating releases during maintenance windows or off-peak hours.

POST /api/v1/servers/{serverId}/sites/{siteId}/schedule-deploy
Content-Type: application/json

{
  "scheduled_at": "2026-03-20T03:00:00Z"
}

The deployment will be queued and executed at the specified time. You can cancel a scheduled deployment before it runs:

POST /api/v1/servers/{serverId}/sites/{siteId}/cancel-scheduled-deploy

Best Practices for API Automation

Use minimal abilities. Every token should have the minimum permissions required for its purpose. A deployment pipeline token does not need server creation or deletion permissions.

Rotate tokens regularly. Set a reminder to rotate your API tokens every 90 days. When you rotate, update the token in all CI systems before revoking the old one.

Use separate tokens per environment. Your staging deployment pipeline should use a different token than your production pipeline. This limits blast radius if a token is compromised.

Handle failures gracefully. Your CI pipeline should handle API errors, deployment failures, and timeouts. Always check HTTP status codes and deployment status before proceeding.

Log deployment metadata. Include the commit hash, branch name, and author in your deployment notes. This makes it easy to trace which code is running in which environment.

Test your pipeline on staging first. Before configuring automated production deployments, run the same pipeline against a staging environment. Make sure the entire flow works end-to-end before pointing it at production.

Token Management

If you suspect a token has been compromised, you can revoke it immediately from the API Tokens section of your account settings. All subsequent requests using that token will be rejected.

Conclusion

The Deploynix API transforms your deployment workflow from a manual, error-prone process into a fully automated pipeline. With Sanctum-based token authentication, granular abilities, and comprehensive endpoints, you have everything you need to build a CI/CD workflow that fits your team's needs.

Whether you are a solo developer automating deployments on push-to-main, or a team coordinating releases across multiple environments with Slack notifications, the API gives you the building blocks to make deployments boring, and boring is exactly what you want from your deployment process.

Create your first API token at deploynix.io and start automating today.