API Reference¶

Liveness Probe¶

GET /check/healthz

Responds with status 200 OK if the Terralist instance is healthy.

Example Request¶

curl -L http://localhost:5758/check/healthz

Example Response¶

Status 200

Readiness Probe¶

GET /check/readyz

Responds with status 200 OK if the Terralist instance is ready.

Example Request¶

curl -L http://localhost:5758/check/readyz

Example Response¶

Status 200

Service Discovery¶

GET /.well-known/terraform.json

Terraform/OpenTofu service discovery endpoint. Instructs the CLI tool where to find resources.

Example Request¶

curl -L http://localhost:5758/.well-known/terraform.json

Example Response¶

Status 200

{
  "login.v1": {
    "authz": "/v1/auth/authorization",
    "client": "terraform-cli",
    "grant_types": [
      "authz_code"
    ],
    "ports": [10000, 10010],
    "token": "/v1/auth/token"
  },
  "modules.v1": "/v1/modules/",
  "providers.v1": "/v1/providers/"
}

List all versions for a provider¶

GET /v1/providers/:namespace/:name/versions

Get all versions for a provider.

Example Request¶

curl -L \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http://localhost:5758/v1/providers/NAMESPACE/NAME/versions

Example Response¶

Status 200Status 401Status 404

{
  "versions": [
    {
      "version": "5.46.0",
      "protocols": [
        "5.0"
      ],
      "platforms": [
        {
          "os": "linux",
          "arch": "amd64"
        },
        {
          "os": "darwin",
          "arch": "amd64"
        },
        {
          "os": "darwin",
          "arch": "arm64"
        },
        {
          "os": "windows",
          "arch": "amd64"
        }
      ]
    }
  ]
}

{
  "errors": [
    "Authorization: missing",
    "X-API-Key: missing"
  ]
}

{
  "errors": "requested provider was not found: no provider found with given arguments (provider hashicorp/aws)"
}

Download provider version¶

GET /v1/providers/:namespace/:name/:version/download/:system/:arch

Download a specific provider version.

Example Request¶

curl -L \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http://localhost:5758/v1/providers/NAMESPACE/NAME/VERSION/download/SYSTEM/ARCH

Example Response¶

Status 200Status 401Status 404

{
  "protocols": [
    "5.0"
  ],
  "os": "linux",
  "arch": "amd64",
  "filename": "terraform-provider-aws_5.46.0_linux_amd64.zip",
  "download_url": "https://SOME-BUCKET-NAME.s3.SOME-REGION.amazonaws.com/providers/hashicorp/aws/5.46.0/terraform-provider-aws_5.46.0_linux_amd64.zip?X-Amz-Algorithm=[REDACTED]&X-Amz-Credential=[REDACTED]&X-Amz-Date=[REDACTED]&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=[REDACTED]",
  "shasums_url": "https://SOME-BUCKET-NAME.s3.SOME-REGION.amazonaws.com/providers/hashicorp/aws/5.46.0/terraform-provider-aws_5.46.0_SHA256SUMS?X-Amz-Algorithm=[REDACTED]&X-Amz-Credential=[REDACTED]&X-Amz-Date=[REDACTED]&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=[REDACTED]",
  "shasums_signature_url": "https://SOME-BUCKET-NAME.s3.SOME-REGION.amazonaws.com/providers/hashicorp/aws/5.46.0/terraform-provider-aws_5.46.0_SHA256SUMS.sigX-Amz-Algorithm=[REDACTED]&X-Amz-Credential=[REDACTED]&X-Amz-Date=[REDACTED]&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=[REDACTED]",
  "shasum": "37cdf4292649a10f12858622826925e18ad4eca354c31f61d02c66895eb91274",
  "signing_keys": {
    "gpg_public_keys": [
      {
        "key_id": "34365D9472D7468F",
        "ascii_armor": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n\n[REDACTED FOR SIMPLICITY]\n-----END PGP PUBLIC KEY BLOCK-----",
        "trust_signature": "",
        "string": "hashicorp",
        "source_url": "https://www.hashicorp.com/security.html"
      }
    ]
  }
}

{
  "errors": [
    "Authorization: missing",
    "X-API-Key: missing"
  ]
}

{
  "errors": [
    "not found"
  ]
}

Upload a provider version¶

POST /v1/api/providers/:name/:version/upload

Upload a new provider version.

If the URLs from which the provider files should be downloaded are of types http or https, a dictionary of headers can be additionally passed, depending on your needs. If those headers are passed-in for other URL types, they will be ignored.

Example Request¶

curl -L -X POST \
  -H "Authorization: Bearer x-api-key:<YOUR-TOKEN>" \
  -d '{
    "protocols": ["5.0"],
    "headers": {
      "Accept": "application/octet-stream",
      "Authorization": "Bearer {TOKEN}",
      "X-GitHub-Api-Version": "2022-11-28"
    },
    "shasums": {
      "url": "https://api.github.com/repos/{OWNER}/{REPO}/releases/assets/{SHA256SUMS-ASSET-ID}",
      "signature_url": "https://api.github.com/repos/{OWNER}/{REPO}/releases/assets/{SHA256SUMS-SIG-ASSET-ID}",
    },
    "platforms": [
      {
        "os": "linux",
        "arch": "amd64",
        "download_url": "https://api.github.com/repos/{OWNER}/{REPO}/releases/assets/{PROVIDER-LINUX-AMD64-ASSET-ID}",
        "shasum": "{SHASUM}"
      }
    ]
  }' \
  http://localhost:5758/v1/api/providers/NAME/VERSION/upload

There is no need for you to specify the namespace, as Terralist will resolve it based on your API key.

Status 200Status 401Status 4xx/5xx

{
  "errors": []
}

{
  "errors": [
    "Authorization: missing",
    "X-API-Key: missing"
  ]
}

{
  "errors": [
    "...",
  ]
}

Remove a provider¶

DELETE /v1/api/providers/:name/remove

Remove a provider together with all its uploaded versions.

Example Request¶

curl -L -X DELETE \
  -H "Authorization: Bearer x-api-key:<YOUR-TOKEN>" \
  http://localhost:5758/v1/api/providers/NAME/remove

There is no need for you to specify the namespace, as Terralist will resolve it based on your API key.

Example Response¶

Status 200Status 401Status 4xx/5xx

{
  "errors": []
}

{
  "errors": [
    "Authorization: missing",
    "X-API-Key: missing"
  ]
}

{
  "errors": [
    "...",
  ]
}

Remove a provider version¶

DELETE /v1/api/providers/:name/:version/remove

Remove a specific provider version.

Example Request¶

curl -L -X DELETE \
  -H "Authorization: Bearer x-api-key:<YOUR-TOKEN>" \
  http://localhost:5758/v1/api/providers/NAME/VERSION/remove

There is no need for you to specify the namespace, as Terralist will resolve it based on your API key.

Example Response¶

Status 200Status 401Status 4xx/5xx

{
  "errors": []
}

{
  "errors": [
    "Authorization: missing",
    "X-API-Key: missing"
  ]
}

{
  "errors": [
    "...",
  ]
}

List all versions for a module¶

GET /v1/modules/:namespace/:name/:provider/versions

Get all versions for a module.

Example Request¶

curl -L \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http://localhost:5758/v1/modules/NAMESPACE/NAME/PROVIDER/versions

Example Response¶

Status 200Status 401Status 404

{
  "modules": [
    {
      "versions": [
        {
          "version": "5.5.3"
        },
        {
          "version": "5.6.0"
        },
        {
          "version": "5.7.0"
        },
        {
          "version": "5.7.1"
        }
      ]
    }
  ]
}

{
  "errors": [
    "Authorization: missing",
    "X-API-Key: missing"
  ]
}

{
  "errors": "no module found with given arguments (source terraform-aws-modules/vpc/aws)"
}

Download module version¶

GET /v1/modules/:namespace/:name/:provider/:version/download

Download a specific provider version.

Example Request¶

curl -L \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http://localhost:5758/v1/modules/NAMESPACE/NAME/PROVIDER/VERSION/download

Example Response¶

Status 204Status 401Status 404

{}

The X-Terraform-Get header should be set to the correct download link for this module.

{
  "errors": [
    "Authorization: missing",
    "X-API-Key: missing"
  ]
}

{
  "errors": [
    "not found"
  ]
}

Upload a module version¶

POST /v1/api/modules/:name/:provider/:version/upload

Upload a new module version.

If the URL from which the module files should be downloaded is of types http or https, a dictionary of headers can be additionally passed, depending on your needs. If those headers are passed-in for other URL types, they will be ignored.

Example Request¶

GitHub APIGitHub HTTP

curl -L -X POST \
  -H "Authorization: Bearer x-api-key:<YOUR-TOKEN>" \
  -d '{
    "download_url": "https://api.github.com/repos/{OWNER}/{REPO}/releases/assets/{ASSET-ID}",
    "headers": {
        "Accept": "application/octet-stream",
        "Authorization": "Bearer {TOKEN}",
        "X-GitHub-Api-Version": "2022-11-28"
    }
  }' \
  http://localhost:5758/v1/api/modules/NAME/PROVIDER/VERSION/upload

curl -L -X POST \
  -H "Authorization: Bearer x-api-key:<YOUR-TOKEN>" \
  -d '{
    "download_url": "https://github.com/{OWNER}/{REPO}/archive/refs/tags/{RELEASE-TAG-NAME}.zip",
    "headers": {
        "Accept": "application/octet-stream",
        "Authorization": "Basic {YOUR-GITHUB-BASE64ENC-USERNAME-TOKEN}"
    }
  }' \
  http://localhost:5758/v1/api/modules/NAME/PROVIDER/VERSION/upload

To obtain the basic auth token you can base64-encode the following string: {your-github-username}:{your-github-pat-with-read-access-to-the-repository}.

There is no need for you to specify the namespace, as Terralist will resolve it based on your API key.

Example Response¶

Status 200Status 401Status 4xx/5xx

{
  "errors": []
}

{
  "errors": [
    "Authorization: missing",
    "X-API-Key: missing"
  ]
}

{
  "errors": [
    "...",
  ]
}

Upload a module version (with local files)¶

POST /v1/api/modules/:name/:provider/:version/upload-files

Upload a new module version (with local files).

Example Request¶

curl -L -X POST \
  -H "Authorization: Bearer x-api-key:<YOUR-TOKEN>" \
  -F "module=@/path/to/your-module.zip"
  http://localhost:5758/v1/api/modules/NAME/PROVIDER/VERSION/upload-files

There is no need for you to specify the namespace, as Terralist will resolve it based on your API key.

Example Response¶

Status 200Status 401Status 4xx/5xx

{
  "errors": []
}

{
  "errors": [
    "Authorization: missing",
    "X-API-Key: missing"
  ]
}

{
  "errors": [
    "...",
  ]
}

Remove a module¶

DELETE /v1/api/modules/:name/:provider/remove

Remove a module together with all its uploaded versions.

Example Request¶

curl -L -X DELETE \
  -H "Authorization: Bearer x-api-key:<YOUR-TOKEN>" \
  http://localhost:5758/v1/api/modules/NAME/PROVIDER/remove

There is no need for you to specify the namespace, as Terralist will resolve it based on your API key.

Status 200Status 401Status 4xx/5xx

{
  "errors": []
}

{
  "errors": [
    "Authorization: missing",
    "X-API-Key: missing"
  ]
}

{
  "errors": [
    "...",
  ]
}

Remove a module version¶

DELETE /v1/api/modules/:name/:provider/:version/remove

Remove a specific module version.

Example Request¶

curl -L -X DELETE \
  -H "Authorization: Bearer x-api-key:<YOUR-TOKEN>" \
  http://localhost:5758/v1/api/modules/NAME/PROVIDER/VERSION/remove

There is no need for you to specify the namespace, as Terralist will resolve it based on your API key.

Example Response¶

Status 200Status 401Status 4xx/5xx

{
  "errors": []
}

{
  "errors": [
    "Authorization: missing",
    "X-API-Key: missing"
  ]
}

{
  "errors": [
    "...",
  ]
}