External API

The External API allows you to integrate Hydra Deploy into your CI/CD pipelines and automation tools using an organisation API key, with no user login required.

Overview

The External API currently provides two endpoints:

• Create Project: create a fully configured project in a single call (environments, applications, auto-deploy rules, config overrides, and agents)
• Create Version: create a new application version, automatically triggering any matching auto-deploy rules

Both endpoints authenticate via an organisation API key passed in the request.

Authentication

All external API requests are authenticated with your organisation’s API key. Pass it in the request body (for project creation) or as a query parameter (for version creation).

You can find and manage API keys under Settings > API Keys. See Organization & Management for details on creating API keys.

Important: API keys grant full access to your organisation’s resources. Keep them secret and rotate them if compromised.

Create Project

Creates a new project and optionally connects environments, applications, auto-deploy rules, config overrides, and agents in a single call.

POST /api/externals/project/create

Request Body

{
  "key": "your-api-key",
  "name": "My Project",
  "code": "my-project",
  "environments": ["Development", "Staging", "Production"],
  "connectedApps": [
    {
      "appCode": "backend",
      "autoDeployRules": {
        "Development": {
          "rule": "main",
          "enabled": true
        },
        "Staging": {
          "rule": "v[0-9]+\\.[0-9]+\\.[0-9]+",
          "enabled": true
        }
      },
      "configs": {
        "app.env": {
          "Development": "NODE_ENV=development\nPORT=3000",
          "Staging": "NODE_ENV=staging\nPORT=3000"
        }
      }
    }
  ],
  "agents": [
    { "name": "production-server" }
  ]
}

Schema

ConnectedApplication

AutoDeployRule

Agent

Response

Returns the created project object on success (201).

Error Responses

Example

curl -X POST https://your-domain.com/api/externals/project/create \
  -H "Content-Type: application/json" \
  -d '{
    "key": "your-api-key",
    "name": "Payment Service",
    "code": "payment-service",
    "environments": ["Development", "Production"],
    "connectedApps": [
      {
        "appCode": "payment-api",
        "autoDeployRules": {
          "Development": { "rule": "", "enabled": true },
          "Production": { "rule": "v[0-9]+\\.[0-9]+\\.[0-9]+", "enabled": true }
        },
        "configs": {
          "app.env": {
            "Development": "STRIPE_SECRET=sk_test_xxx",
            "Production": "STRIPE_SECRET=sk_live_xxx"
          }
        }
      }
    ],
    "agents": [{ "name": "prod-server-1" }]
  }'

Create Version

Creates a new version for an application. If any auto-deploy rules match the version name, deployments are automatically triggered.

POST /api/externals/version/create?key=...&appCode=...&version=...

Query Parameters

What Happens

1. The version is created and linked to the application
2. A snapshot of all the application’s current config files is taken and attached to the version
3. All auto-deploy rules for the application are evaluated against the version name
4. Matching rules trigger automatic deployments to their configured project/environment

Response

Returns the created version object on success (201).

Error Responses

Example

curl -X POST "https://your-domain.com/api/externals/version/create?key=your-api-key&appCode=payment-api&version=v1.2.3"

CI/CD Integration Examples

GitLab CI

deploy:
  stage: deploy
  script:
    - |
      curl -X POST "https://your-domain.com/api/externals/version/create?key=$HYDRA_API_KEY&appCode=$APP_CODE&version=$CI_COMMIT_TAG"
  only:
    - tags

GitHub Actions

- name: Create Hydra Deploy version
  run: |
    curl -X POST "https://your-domain.com/api/externals/version/create?key=${{ secrets.HYDRA_API_KEY }}&appCode=my-app&version=${{ github.ref_name }}"

Jenkins

stage('Deploy to Hydra') {
    steps {
        sh """
            curl -X POST "https://your-domain.com/api/externals/version/create?key=${HYDRA_API_KEY}&appCode=${APP_CODE}&version=${env.BUILD_TAG}"
        """
    }
}

Azure DevOps

- task: Bash@3
  displayName: 'Create Hydra Deploy version'
  inputs:
    targetType: 'inline'
    script: |
      curl -X POST "https://your-domain.com/api/externals/version/create?key=$(HYDRA_API_KEY)&appCode=$(APP_CODE)&version=$(Build.BuildNumber)"

Full Pipeline Example

A complete CI/CD workflow with Hydra Deploy:

1. Build: compile and package your application
2. Test: run unit and integration tests
3. Publish: push the artifact to your registry (Docker Hub, npm, etc.)
4. Create Version: call the External API to create the version in Hydra Deploy
5. Auto Deploy: matching auto-deploy rules trigger deployments automatically

# GitLab CI full pipeline
stages:
  - build
  - test
  - publish
  - deploy
 
build:
  stage: build
  script:
    - docker build -t my-app:$CI_COMMIT_TAG .
 
test:
  stage: test
  script:
    - npm test
 
publish:
  stage: publish
  script:
    - docker push my-registry/my-app:$CI_COMMIT_TAG
 
deploy:
  stage: deploy
  script:
    - |
      curl -sf -X POST "https://your-domain.com/api/externals/version/create?key=$HYDRA_API_KEY&appCode=my-app&version=$CI_COMMIT_TAG"
  only:
    - tags

Once the version is created, any matching auto-deploy rules will automatically trigger deployments to the configured environments.

Response Format

All API responses follow this format:

{
  "data": { ... },
  "succeeded": true,
  "error": null,
  "code": null
}

On error:

{
  "data": null,
  "succeeded": false,
  "error": "Description of what went wrong",
  "code": 1234
}