External API

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

Authentication

All external API requests are authenticated with your organisation’s API key. Pass it in the request body as key.

You can find and manage API keys under Settings > API Keys.

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

Field	Type	Required	Description
`key`	`string`	Yes	Organisation API key
`name`	`string`	Yes	Project name
`code`	`string`	Yes	Unique project code within the organisation
`environments`	`string[]`	No	Names of existing environments to connect
`connectedApps`	`ConnectedApplication[]`	No	Applications to connect
`agents`	`Agent[]`	No	Existing agents to link (matched by name)

ConnectedApplication

Field	Type	Required	Description
`appCode`	`string`	Yes	Application code
`autoDeployRules`	`Record<EnvironmentName, AutoDeployRule>`	No	Auto-deploy rules keyed by environment name
`configs`	`Record<ConfigName, Record<EnvironmentName, string>>`	No	Config overrides keyed by config file name, then environment name

AutoDeployRule

Field	Type	Required	Description
`rule`	`string`	No	Regex pattern to match version names. Leave empty to match all versions.
`enabled`	`boolean`	No	Whether the rule is active. Defaults to `true`.

Agent

Field	Type	Required	Description
`name`	`string`	Yes	Agent name (must already exist in the organisation)

Response

Returns the created project object on success (201).

Error Responses

Status	Description
`401`	Invalid or missing API key
`404`	Environment, application, config, or agent not found

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

Parameter	Type	Required	Description
`key`	`string`	Yes	Organisation API key
`appCode`	`string`	Yes	Application code
`version`	`string`	Yes	Version name (e.g. `v1.2.3`, `main`, `abc1234`)

Response

Returns the created version object on success (201).

Error Responses

Status	Description
`401`	Invalid or missing API key
`404`	Application not found or version could not be created

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 Example

A typical pipeline step that creates a version after a successful build:


# GitLab CI example
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"


# GitHub Actions example
- 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 }}"

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

External API

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

Authentication

All external API requests are authenticated with your organisation’s API key. Pass it in the request body as key.

You can find and manage API keys under Settings > API Keys.

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

Field	Type	Required	Description
`key`	`string`	Yes	Organisation API key
`name`	`string`	Yes	Project name
`code`	`string`	Yes	Unique project code within the organisation
`environments`	`string[]`	No	Names of existing environments to connect
`connectedApps`	`ConnectedApplication[]`	No	Applications to connect
`agents`	`Agent[]`	No	Existing agents to link (matched by name)

ConnectedApplication

Field	Type	Required	Description
`appCode`	`string`	Yes	Application code
`autoDeployRules`	`Record<EnvironmentName, AutoDeployRule>`	No	Auto-deploy rules keyed by environment name
`configs`	`Record<ConfigName, Record<EnvironmentName, string>>`	No	Config overrides keyed by config file name, then environment name

AutoDeployRule

Field	Type	Required	Description
`rule`	`string`	No	Regex pattern to match version names. Leave empty to match all versions.
`enabled`	`boolean`	No	Whether the rule is active. Defaults to `true`.

Agent

Field	Type	Required	Description
`name`	`string`	Yes	Agent name (must already exist in the organisation)

Response

Returns the created project object on success (201).

Error Responses

Status	Description
`401`	Invalid or missing API key
`404`	Environment, application, config, or agent not found

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

Parameter	Type	Required	Description
`key`	`string`	Yes	Organisation API key
`appCode`	`string`	Yes	Application code
`version`	`string`	Yes	Version name (e.g. `v1.2.3`, `main`, `abc1234`)

Response

Returns the created version object on success (201).

Error Responses

Status	Description
`401`	Invalid or missing API key
`404`	Application not found or version could not be created

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 Example

A typical pipeline step that creates a version after a successful build:


# GitLab CI example
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"


# GitHub Actions example
- 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 }}"

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