> For the complete documentation index, see [llms.txt](https://docs.terrakube.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.terrakube.io/2.34.0/reference/configuration/api.md). # API Environment variables of the Terrakube **API**. See [Configuration Reference](/2.34.0/reference/configuration.md) for how to set them. An empty default means the variable has no default: either it is optional or it must be provided. ### LIQUIBASE SETUP | Variable | Default | Description | | ------------------ | -------- | --------------------------------------- | | `DatasourceSchema` | `public` | Sets `spring.liquibase.default-schema`. | ### DATABASE TYPE | Variable | Default | Description | | --------------------------------- | -------------------- | ---------------------------------------------------------------- | | `ApiDataSourceType` | | Sets `io.terrakube.api.plugin.datasource.type`. | | `DatasourceHostname` | | Sets `io.terrakube.api.plugin.datasource.hostname`. | | `DatasourceDatabase` | | Sets `io.terrakube.api.plugin.datasource.databaseName`. | | `DatasourceUser` | | Sets `io.terrakube.api.plugin.datasource.databaseUser`. | | `DatasourcePassword` | | Sets `io.terrakube.api.plugin.datasource.databasePassword`. | | `DatasourceSslMode` | `disable` | Sets `io.terrakube.api.plugin.datasource.sslMode`. | | `DatasourceTrustCertificate` | `false` | Sets `io.terrakube.api.plugin.datasource.trustCertificate`. | | `DatasourcePort` | `5432` | Sets `io.terrakube.api.plugin.datasource.databasePort`. | | `DatasourceAwsIamAuth` | `false` | Sets `io.terrakube.api.plugin.datasource.awsIamAuth`. | | `DatasourceAwsRegion` | `aws-region-not-set` | Sets `io.terrakube.api.plugin.datasource.awsRegion`. | | `DatasourcePoolSize` | `10` | Sets `io.terrakube.api.plugin.datasource.poolSize`. | | `DatasourcePoolMinIdle` | `5` | Sets `io.terrakube.api.plugin.datasource.poolMinIdle`. | | `DatasourcePoolConnectionTimeout` | `30000` | Sets `io.terrakube.api.plugin.datasource.poolConnectionTimeout`. | | `DatasourcePoolIdleTimeout` | `600000` | Sets `io.terrakube.api.plugin.datasource.poolIdleTimeout`. | | `DatasourcePoolMaxLifetime` | `1800000` | Sets `io.terrakube.api.plugin.datasource.poolMaxLifetime`. | ### OWNER INSTANCE | Variable | Default | Description | | ----------------------- | ----------------- | -------------------------- | | `TERRAKUBE_ADMIN_GROUP` | `TERRAKUBE_ADMIN` | Sets `io.terrakube.owner`. | ### Validation Types | Variable | Default | Description | | ------------------------------ | ------- | -------------------------------------------- | | `GroupValidationType` | | Sets `io.terrakube.api.groups.type`. | | `UserValidationType` | | Sets `io.terrakube.api.users.type`. | | `AuthenticationValidationType` | | Sets `io.terrakube.api.authentication.type`. | ### HOSTNAME | Variable | Default | Description | | ------------------- | ------- | ----------------------------- | | `TerrakubeHostname` | | Sets `io.terrakube.hostname`. | ### Cors | Variable | Default | Description | | ---------------- | ------- | --------------------------- | | `TerrakubeUiURL` | | Sets `io.terrakube.ui.url`. | ### QUARTZ SETUP | Variable | Default | Description | | ------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- | | `ReconciliationHeartbeatGracePeriodSeconds` | `300` | The Quartz thread pool size comes from io.terrakube.scheduler.thread-count (read by QuartzAutoConfiguration). | | `InactiveJobsMaxAgeHours` | `6` | Runs stuck in pending, queue or running are failed after this many hours. Time spent waiting for approval does not count. | | `InactiveJobsWaitingApprovalTimeoutHours` | `0` | Runs waiting for approval are cancelled after this many hours of waiting. 0 = approvals never time out. | ### NOTIFICATION SETUP | Variable | Default | Description | | ------------------------------- | ------- | ---------------------------------------------------- | | `AgentSsrfBlockPrivateNetworks` | `true` | Sets `io.terrakube.agent.ssrf.blockPrivateNetworks`. | ### WEBHOOK DELIVERY | Variable | Default | Description | | ------------------------------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `WebhookDispatchExecutorCorePoolSize` | `10` | Dispatch pool is bounded so a burst of shared-webhook deliveries (e.g. a force-push touching a repo with many workspaces) can't spawn unbounded threads competing for the app's DB connection pool or the VCS provider's API rate limit. | | `WebhookDispatchExecutorMaxPoolSize` | `20` | Sets `io.terrakube.webhook.dispatch.executor.maxPoolSize`. | | `WebhookDispatchExecutorQueueCapacity` | `200` | Sets `io.terrakube.webhook.dispatch.executor.queueCapacity`. | | `WebhookPollerBatchSize` | `200` | Sets `io.terrakube.webhook.poller.batchSize`. | | `WebhookPollerStuckProcessingThresholdMinutes` | `5` | Sets `io.terrakube.webhook.poller.stuckProcessingThresholdMinutes`. | | `WebhookDeliveryRetentionDays` | `30` | Sets `io.terrakube.webhook.delivery.retentionDays`. | | `WebhookWorkspaceFanoutConcurrency` | `4` | Bounds how many workspaces on one shared webhook are processed concurrently - see WorkspaceFanoutExecutorConfig. | | `WebhookWorkspaceFanoutQueueCapacity` | `200` | Sets `io.terrakube.webhook.workspace-fanout.queue-capacity`. | | `WebhookDispatchConnectTimeoutSeconds` | `5` | Pooled HTTP client for GitHub/GitLab/Azure DevOps API calls (WebhookHttpClientConfig) - replaces a fresh RestTemplate + TCP/TLS handshake per call. | | `WebhookDispatchResponseTimeoutSeconds` | `30` | Sets `io.terrakube.webhook.dispatch.http.responseTimeoutSeconds`. | | `WebhookDispatchConnectionRequestTimeoutSeconds` | `2` | Sets `io.terrakube.webhook.dispatch.http.connectionRequestTimeoutSeconds`. | ### EXECUTOR URL | Variable | Default | Description | | ---------------------- | ------- | --------------------------------- | | `AzBuilderExecutorUrl` | | Sets `io.terrakube.executor.url`. | ### EPHEMERAL EXECUTOR CONFIG | Variable | Default | Description | | ------------------------------------------------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `ExecutorEphemeralNamespace` | `terrakube` | Sets `io.terrakube.executor.ephemeral.namespace`. | | `ExecutorEphemeralImage` | `azbuilder/executor:2.34.0` | Sets `io.terrakube.executor.ephemeral.image`. | | `ExecutorEphemeralSecret` | `terrakube-executor-secrets` | Comma-separated list for multiple secrets: e.g. "secret-one,secret-two" | | `ExecutorEphemeralEmptyDirSecret` | `true` | Sets `io.terrakube.executor.ephemeral.emptyDirSecret`. | | `ExecutorEphemeralInitSecretImage` | `busybox:1.37.0` | Sets `io.terrakube.executor.ephemeral.initSecretImage`. | | `ExecutorEphemeralActiveDeadlineSeconds` | | Maximum seconds a job's pod may run before Kubernetes terminates it as failed; unset means no deadline (unbounded). | | `ExecutorEphemeralBackoffLimit` | | Number of retries before a job is marked failed; unset means Kubernetes' own default (6). Set to 0 for at-most-once execution. | | `ExecutorEphemeralTerminationGracePeriodSeconds` | `60` | Seconds the pod gets to shut down cleanly after SIGTERM before Kubernetes SIGKILLs it; unset means 60. | | `ExecutorEphemeralTtlSecondsAfterFinished` | `30` | Seconds after completion before the job is automatically deleted; unset means 30. | | `ExecutorReplicas` | `1` | Sets `io.terrakube.executor.replicas`. | ### Storage Service | Variable | Default | Description | | ------------- | ------- | --------------------------------- | | `StorageType` | | Sets `io.terrakube.storage.type`. | ### Azure Storage | Variable | Default | Description | | ------------------ | ------- | ---------------------------------------------- | | `AzureAccountName` | | Sets `io.terrakube.storage.azure.accountName`. | | `AzureAccountKey` | | Sets `io.terrakube.storage.azure.accountKey`. | ### AWS Storage | Variable | Default | Description | | ------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `AwsStorageAccessKey` | | Sets `io.terrakube.storage.aws.accessKey`. | | `AwsStorageSecretKey` | | Sets `io.terrakube.storage.aws.secretKey`. | | `AwsStorageBucketName` | | Sets `io.terrakube.storage.aws.bucketName`. | | `AwsStorageRegion` | | Sets `io.terrakube.storage.aws.region`. | | `AwsEndpoint` | | Sets `io.terrakube.storage.aws.endpoint`. | | `AwsEnableRoleAuth` | `false` | Sets `io.terrakube.storage.aws.enableRoleAuthentication`. | | `AwsEndpointRegion` | `auto` | S3-compatible backends (Qumulo, MinIO, ...) that need a real signing region or no chunked/checksum support | | `AwsPathStyleAccess` | `true` | Sets `io.terrakube.storage.aws.pathStyleAccessEnabled`. | | `AwsChunkedEncodingEnabled` | `true` | Sets `io.terrakube.storage.aws.chunkedEncodingEnabled`. | | `AwsChecksumValidationEnabled` | `true` | Sets `io.terrakube.storage.aws.checksumValidationEnabled`. | | `StorageApiCallTimeoutSeconds` | `10` | Storage read resilience - a hung object read fails within apiCallTimeout instead of the SDK's multi-minute default retry ladder. Step-log objects are KB-sized; sub-second latency is normal. | | `StorageApiCallAttemptTimeoutSeconds` | `3` | Sets `io.terrakube.storage.aws.apiCallAttemptTimeoutSeconds`. | | `StorageMaxRetryAttempts` | `2` | Sets `io.terrakube.storage.aws.maxRetryAttempts`. | | `ContextCacheTtl` | `30s` | /context/v1 read path: short per-pod cache + single-flight coalescing of concurrent misses, plus an overall read budget applied on top of the shared S3 client timeouts above. | | `ContextCacheMaxEntries` | `500` | Sets `io.terrakube.context.cache-max-entries`. | | `ContextReadTimeout` | `8s` | Sets `io.terrakube.context.read-timeout`. | | `ContextRetryAfterSeconds` | `5` | Sets `io.terrakube.context.retry-after-seconds`. | | `ContextReadWorkers` | `4` | Sets `io.terrakube.context.read-workers`. | | `ContextReadQueueCapacity` | `64` | Sets `io.terrakube.context.read-queue-capacity`. | ### GCP Storage | Variable | Default | Description | | ----------------------------- | ------- | -------------------------------------------- | | `GcpStorageCredentialsBase64` | | Sets `io.terrakube.storage.gcp.credentials`. | | `GcpStorageBucketName` | | Sets `io.terrakube.storage.gcp.bucketName`. | | `GcpStorageProjectId` | | Sets `io.terrakube.storage.gcp.projectId`. | ### Terrakube Extension Repository | Variable | Default | Description | | -------------------------- | ------- | ------------------------------------- | | `TerrakubeToolsRepository` | | Sets `io.terrakube.tools.repository`. | | `TerrakubeToolsBranch` | | Sets `io.terrakube.tools.branch`. | ### DEX AUTHENTICATION | Variable | Default | Description | | ---------------------------- | ------- | --------------------------------------------------------------------- | | `PatSecret` | | Sets `io.terrakube.token.pat`. | | `InternalSecret` | | Sets `io.terrakube.token.internal`. | | `DexIssuerUri` | | Sets `io.terrakube.token.issuer-uri`. | | `DexClientId` | | Sets `io.terrakube.token.client-id`. | | `TerraformLoginEnabled` | `false` | spring.security.oauth2.resourceserver.jwt.jwk-set-uri=${DexJwtSetUri} | | `TerraformLoginDefaultDays` | `30` | Sets `io.terrakube.token.login.default-days`. | | `TerraformLoginMaxDays` | `365` | Sets `io.terrakube.token.login.max-days`. | | `TerraformLoginApiUrl` | | Sets `io.terrakube.token.login.api-url`. | | `TerraformLoginDexTokenUrl` | | Sets `io.terrakube.token.login.dex-token-url`. | | `TerraformLoginDexJwkSetUrl` | | Sets `io.terrakube.token.login.dex-jwk-set-url`. | ### GRAPHQL SUBSCRIPTIONS | Variable | Default | Description | | --------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `io.terrakube.ui.url` | | Spring Boot's GraphQL endpoints (HTTP + WebSocket) have their own CORS config, entirely separate from the CorsConfigurationSource bean Spring Security uses for every other endpoint - without this, cross-origin requests to /subscriptions... | ### Terraform Releases | Variable | Default | Description | | ------------------------------------- | ------- | ---------------------------------------------------------- | | `CustomTerraformReleasesUrl` | | Sets `io.terrakube.terraform.json.releasesUrl`. | | `CustomReleaseCacheExpirationMinutes` | `30` | Sets `io.terrakube.terraform.json.cacheExpirationMinutes`. | ### Tofu Releases | Variable | Default | Description | | -------------------------- | --------------------------------------------------------- | ------------------------------------------ | | `CustomTofuReleasesUrl` | `https://api.github.com/repos/opentofu/opentofu/releases` | Sets `io.terrakube.tofu.json.releasesUrl`. | | `CustomReleaseGithubToken` | | Sets `io.terrakube.tofu.json.githubToken`. | ### REDIS | Variable | Default | Description | | ----------------------------------- | ------- | ------------------------------------------------------------------------- | | `TerrakubeRedisHostname` | | Sets `io.terrakube.api.redis.hostname`. | | `TerrakubeRedisPort` | | Sets `io.terrakube.api.redis.port`. | | `TerrakubeRedisUsername` | | Sets `io.terrakube.api.redis.username`. | | `TerrakubeRedisPassword` | | Sets `io.terrakube.api.redis.password`. | | `TerrakubeRedisSSL` | `false` | Sets `io.terrakube.api.redis.ssl`. | | `TerrakubeRedisTruststorePath` | | Sets `io.terrakube.api.redis.truststorePath`. | | `TerrakubeRedisTruststorePassword` | | Sets `io.terrakube.api.redis.truststorePassword`. | | `TerrakubeRedisClusterNodes` | | Sets `io.terrakube.api.redis.cluster.nodes`. | | `TerrakubeRedisClusterMaxRedirects` | `0` | Sets `io.terrakube.api.redis.cluster.max-redirects`. | | `TerrakubeRedisSentinelMaster` | | Sets `io.terrakube.api.redis.sentinel.master`. | | `TerrakubeRedisSentinelNodes` | | Sets `io.terrakube.api.redis.sentinel.nodes`. | | `TerrakubeRedisSentinelUsername` | | Sets `io.terrakube.api.redis.sentinel.username`. | | `TerrakubeRedisSentinelPassword` | | Sets `io.terrakube.api.redis.sentinel.password`. | | `TerrakubeRedisPoolMaxTotal` | `64` | Jedis pool per api pod; size against Redis maxclients (pods x max-total). | | `TerrakubeRedisPoolMaxWait` | `5s` | Sets `io.terrakube.api.redis.pool.max-wait`. | ### REDIS MODULE CACHE | Variable | Default | Description | | --------------------- | --------------- | ---------------------------------------------- | | `ModuleCacheMaxTotal` | `128` | Sets `io.terrakube.api.module.cache.maxTotal`. | | `ModuleCacheMaxIdle` | `128` | Sets `io.terrakube.api.module.cache.maxIdle`. | | `ModuleCacheMinIdle` | `64` | Sets `io.terrakube.api.module.cache.minIdle`. | | `ModuleCacheTimeout` | `600000` | Sets `io.terrakube.api.module.cache.timeout`. | | `ModuleCacheSchedule` | `0 */3 * ? * *` | Sets `io.terrakube.api.module.cache.schedule`. | ### LOGS | Variable | Default | Description | | ------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `LogsCacheMaxWeightBytes` | `268435456` | Completed-step logs are immutable - cache them so many concurrent viewers plus polling collapse to a single storage read. Objects larger than cacheable-max-object-bytes stream through uncached. | | `LogsCacheTtl` | `10m` | Sets `io.terrakube.logs.cache-ttl`. | | `LogsCacheableMaxObjectBytes` | `1048576` | Sets `io.terrakube.logs.cacheable-max-object-bytes`. | | `LogsLiveTailRecords` | `5000` | Running-step plain GET returns at most this many trailing lines from the Redis stream, so it never scans the whole (potentially huge) stream from the start. | | `LogsSseMaxConnections` | `1500` | Step-log SSE: one Redis reader per job fans out to all its viewers. Per-pod connection cap returns 503 + Retry-After beyond the limit; a stream is closed after sse-max-stream-duration and the client reconnects with Last-Event-ID. | | `LogsSseJobIdleTimeout` | `2s` | Sets `io.terrakube.logs.sse-job-idle-timeout`. | | `LogsSseMaxStreamDuration` | `30m` | Sets `io.terrakube.logs.sse-max-stream-duration`. | | `LogsJobStatusCacheTtl` | `2s` | Sets `io.terrakube.logs.job-status-cache-ttl`. | | `LogsRedisMaxLen` | `200000` | Cap on a job's live-log Redis stream when logs are ingested via the API (/logs endpoint). | | `LogsAppendMaxBytes` | `4194304` | Sets `io.terrakube.logs.append-max-bytes`. | | `LogsAppendLineMaxBytes` | `65536` | Sets `io.terrakube.logs.append-line-max-bytes`. | | `LogsStreamCleanupCron` | `0 */10 * * * ?` | Housekeeping sweep that reclaims the {jobId} and {jobId}-context Redis streams once a job has been terminal for grace-period-minutes; only jobs terminal within the trailing lookback window are scanned. | | `LogsStreamCleanupGracePeriodMinutes` | `30` | Sets `io.terrakube.logs.stream-cleanup.grace-period-minutes`. | | `LogsStreamCleanupLookbackHours` | `24` | Sets `io.terrakube.logs.stream-cleanup.lookback-hours`. | ### MODULE VERSION REFRESH | Variable | Default | Description | | ----------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ModuleRefreshInterval` | `300` | How often the Quartz job re-reads the Git tags of one module. Lower it to shorten the delay between a module release and the version showing up in the registry. | ### ZERO-PENDING JOB RECONCILIATION | Variable | Default | Description | | ---------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `SchedulerReconciliationSweepEnabled` | `true` | Repairs jobs that are stuck non-terminal with no remaining executable step (they would otherwise block the shared executor FIFO queue forever). See the design doc dated 2026-09-02. | | `SchedulerReconciliationAutoRemediate` | `true` | Sets `io.terrakube.api.scheduler.reconciliation.auto-remediate`. | | `SchedulerReconciliationAdmissionGuardEnabled` | `true` | Sets `io.terrakube.api.scheduler.reconciliation.admission-guard-enabled`. | | `SchedulerReconciliationAnomalyGraceSeconds` | `300` | Sets `io.terrakube.api.scheduler.reconciliation.anomaly-grace-seconds`. | ### DISPATCH RETRY | Variable | Default | Description | | ------------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `SchedulerDispatchRetryEnabled` | `true` | Bounded retry/backoff for pre-submission dispatch failures (currently: VCS access-token acquisition) so a provider outage/misconfiguration fails the job instead of retrying forever and blocking the shared FIFO queue across workspaces. | | `SchedulerDispatchRetryMaxAttempts` | `8` | Sets `io.terrakube.api.scheduler.dispatch-retry.max-attempts`. | | `SchedulerDispatchRetryMaxElapsedMinutes` | `60` | Sets `io.terrakube.api.scheduler.dispatch-retry.max-elapsed-minutes`. | | `SchedulerDispatchRetryInitialBackoffSeconds` | `15` | Sets `io.terrakube.api.scheduler.dispatch-retry.initial-backoff-seconds`. | | `SchedulerDispatchRetryMaxBackoffSeconds` | `900` | Sets `io.terrakube.api.scheduler.dispatch-retry.max-backoff-seconds`. | | `SchedulerDispatchRetryAdmissionDeferralEnabled` | `true` | Sets `io.terrakube.api.scheduler.dispatch-retry.admission-deferral-enabled`. | ### Dynamic Credentials | Variable | Default | Description | | --------------------------------- | -------------------------------------- | --------------------------------------------------------- | | `DynamicCredentialHostname` | | Sets `io.terrakube.dynamic.credentials.hostname`. | | `DynamicCredentialId` | `03446895-220d-47e1-9564-4eeaa3691b42` | Sets `io.terrakube.dynamic.credentials.kid`. | | `DynamicCredentialTtl` | `30` | Sets `io.terrakube.dynamic.credentials.ttl`. | | `DynamicCredentialPublicKeyPath` | | Sets `io.terrakube.dynamic.credentials.public-key-path`. | | `DynamicCredentialPrivateKeyPath` | | Sets `io.terrakube.dynamic.credentials.private-key-path`. | ### IMPORTER ALLOWED URL | Variable | Default | Description | | -------------------- | -------------------------- | ---------------------------------------- | | `ImporterAllowedUrl` | `https://app.terraform.io` | Sets `io.terrakube.importer.allowedUrl`. | ### GITLAB VCS | Variable | Default | Description | | ------------------- | ------- | ---------------------------------------- | | `VcsGitlabTimeOut` | `30` | Sets `io.terrakube.vcs.gitlab.timeout`. | | `VcsGitlabPageSize` | `25` | Sets `io.terrakube.vcs.gitlab.pageSize`. | ### AZURE DEVOPS VCS | Variable | Default | Description | | -------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `AzureDevOpsPollingEnabled` | `false` | AzureDevOpsPollingEnabled Enable polling (true/false). Disabled by default. AzureDevOpsPollingInterval Milliseconds between polls of each workspace (default 15000 = 15s). Lower it to detect commits sooner; raise it to reduce API traffic. | | `AzureDevOpsPollingInterval` | `15000` | Sets `io.terrakube.vcs.azuredevops.polling.interval`. | | `AzureDevOpsPollingInitialDelay` | `10000` | Sets `io.terrakube.vcs.azuredevops.polling.initial-delay`. | ### OPA POLICY GOVERNANCE | Variable | Default | Description | | --------------------------------- | ------------- | ------------------------------------------------------ | | `PolicyDriftCron` | `0 0 2 * * ?` | Sets `io.terrakube.policy.drift.cron`. | | `PolicyDriftBatchSize` | `50` | Sets `io.terrakube.policy.drift.batchSize`. | | `PolicyDriftMaxJobsPerRun` | `100` | Sets `io.terrakube.policy.drift.maxJobsPerRun`. | | `PolicyDriftMaxActiveJobs` | `5` | Sets `io.terrakube.policy.drift.maxActiveJobs`. | | `PolicyDriftFollowUpDelayMinutes` | `2` | Sets `io.terrakube.policy.drift.followUpDelayMinutes`. | | `PolicyDriftCooldownHours` | `12` | Sets `io.terrakube.policy.drift.cooldownHours`. | | `PolicyEvaluationRetentionCron` | `0 0 4 * * ?` | Sets `io.terrakube.policy.evaluation.retentionCron`. | | `PolicyEvaluationRetentionDays` | `90` | Sets `io.terrakube.policy.evaluation.retentionDays`. | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.terrakube.io/2.34.0/reference/configuration/api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.