> ## Documentation Index > Fetch the complete documentation index at: https://paper.brimble.io/llms.txt > Use this file to discover all available pages before exploring further. # List secrets for an environment > Secrets are encrypted at rest. This endpoint returns each `value` **encrypted**, not as plain text. To read the plain values, send the `name` and `value` of the secrets you need to [`POST /v1/decrypt`](/api-reference/secrets/decrypt-secrets): ```json { "environments": [{ "name": "DATABASE_URL", "value": "" }] } ``` **API key scope:** `env.read` **Team role permission:** `env.read` ## OpenAPI ````yaml /api-reference/core.openapi.yaml get /v1/envs/{projectId}/{environment} openapi: 3.0.3 info: title: Brimble API version: 1.0.0 description: > The Brimble API lets you deploy and manage projects, databases, domains, sandboxes, object storage and more. ## Base URL All endpoints are relative to `https://api.brimble.io/core`, for example `GET https://api.brimble.io/core/v1/projects`. ## Authentication Create an API key in the dashboard under **Settings → API keys** and send it in the `x-brimble-key` header: ``` x-brimble-key: ``` Each API key carries permission scopes such as `project.read` or `project.deploy`. Every endpoint lists the scope it needs; a key without that scope gets `403`. Dashboard session tokens (`Authorization: Bearer `) are also accepted, but integrations should use API keys. ## Teams Endpoints act on your personal workspace unless you pass a team. Most endpoints accept `teamId` (as a query parameter, or in the body for writes). API keys created for a team act in that team. Inside a team, your team role must also allow the action; each endpoint lists the team permission it checks. ## Responses Successful responses are JSON with this shape: ```json { "message": "Projects fetched", "data": { } } ``` Errors return a `message`: ```json { "message": "Project not found", "data": {} } ``` Requests that fail validation return `400` with every invalid field: ```json { "errors": [{ "type": "field", "msg": "Project name should be provided", "path": "name", "location": "body" }] } ``` ## Rate limits Requests made with an API key are rate limited. Responses include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Bucket`. Command execution and file transfer endpoints use separate buckets. ## Idempotency Endpoints that accept an `Idempotency-Key` header return the original result when retried with the same key and body, instead of repeating the operation. ## Streaming Command execution endpoints can stream output as Server-Sent Events (`text/event-stream`). Each event is `data: ` where the JSON has a `type` of `stdout`, `stderr`, `done` or `error`. ## Webhooks To receive events instead of polling, configure a webhook with `PATCH /v1/webhooks`. See the [Webhooks guide](/webhooks/overview) and the [Webhook events reference](/webhooks/events) for every payload. contact: name: Brimble url: https://brimble.io servers: - url: https://api.brimble.io/core description: Production security: - ApiKeyAuth: [] - BearerAuth: [] tags: - name: Projects description: Create, deploy, configure and manage projects. - name: Deployments and Logs description: Deployment history, build logs and request logs. - name: Environments description: Project environments (production, staging, previews) and their variables. - name: Secrets description: >- Secrets (environment variables) set on a single project. Not to be confused with Environments, which group projects into production, staging and preview. Secret values are encrypted at rest and returned encrypted; use `POST /v1/decrypt` to read them. - name: Webhooks description: >- Receive events from Brimble at your own endpoint (or a Discord or Slack channel). Configure the destination and events with `PATCH /v1/webhooks`; use `*` to receive every event. See the [Webhooks guide](/webhooks/overview) for setup, and the [Webhook events reference](/webhooks/events) for the payload each event delivers. | Event | Sent when | | --- | --- | | `project.created` | A project is created | | `project.updated` | A project is updated | | `project.deleted` | A project is deleted | | `project.domain.updated` | A project domain changes | | `deployment.created` | A deployment is queued | | `deployment.started` | A deployment starts | | `deployment.success` | A deployment succeeds | | `deployment.failed` | A deployment fails | | `environment.variables.added` | Environment variables are added | | `environment.variables.updated` | Environment variables are updated | | `environment.variables.deleted` | Environment variables are deleted | | `domain.created` | A domain is added | | `domain.purchased` | A domain is purchased | | `domain.renewed` | A domain is renewed | | `domain.expired` | A domain expires | | `dns.record.created` | A DNS record is created | | `dns.record.updated` | A DNS record is updated | | `dns.record.deleted` | A DNS record is deleted | | `database.created` | A database is created | | `database.backup.completed` | A database backup completes | | `autoscaling.group.created` | An autoscaling rule is created | | `autoscaling.group.updated` | An autoscaling rule is updated | | `autoscaling.group.deleted` | An autoscaling rule is deleted | | `payment.successful` | A payment succeeds | | `payment.failed` | A payment fails | Test deliveries sent with `POST /v1/webhooks/test` include the header `X-Brimble-Test: true`. - name: Git Providers description: Connected git accounts, repositories and linking repositories to projects. - name: Domains description: Custom domains, DNS records and domain registration. - name: Databases description: 'Managed databases: provisioning, backups, users and linking to projects.' - name: Log Drains description: Stream logs to external destinations. - name: Sandboxes description: Isolated sandboxes for running code, with files and snapshots. - name: Object Storage description: S3-compatible buckets, objects and credentials. - name: Scaling and Networking description: Autoscaling rules, networking and CDN cache, and rate limits. - name: Teams description: Teams, members, invitations and roles. - name: Catalog description: Regions, frameworks and plans. No authentication required. paths: /v1/envs/{projectId}/{environment}: get: tags: - Secrets summary: List secrets for an environment description: >- Secrets are encrypted at rest. This endpoint returns each `value` **encrypted**, not as plain text. To read the plain values, send the `name` and `value` of the secrets you need to [`POST /v1/decrypt`](/api-reference/secrets/decrypt-secrets): ```json { "environments": [{ "name": "DATABASE_URL", "value": "" }] } ``` **API key scope:** `env.read` **Team role permission:** `env.read` operationId: listSecretsForEnvironment parameters: - name: projectId in: path required: true description: ID of the project. schema: type: string pattern: ^[a-fA-F0-9]{24}$ - name: environment in: path required: true schema: type: string enum: - PRODUCTION - PREVIEW description: >- `PREVIEW` for secrets used by preview deployments; any other value means production. Use the path without this segment for production. - name: includeEnvironment in: query required: false description: >- Also return variables shared by the project's environment, marked with `source: environment`. schema: type: boolean - name: limit in: query required: false description: Accepted for compatibility. Every secret is returned. schema: type: string - name: page in: query required: false description: Accepted for compatibility. Every secret is returned. schema: type: string - name: filterBy in: query required: false description: Accepted for compatibility. Secrets are always sorted by name. schema: type: string responses: '200': description: Env fetched successfully content: application/json: schema: type: object required: - message - data properties: message: type: string description: Human-readable result of the request. example: Env fetched successfully data: type: object description: The result of the request. properties: envs: type: array description: Secrets, sorted by name. items: oneOf: - $ref: '#/components/schemas/EnvVariableResponse' - type: object properties: id: type: string description: ID of the secret. name: type: string description: Secret name. value: type: string description: >- Encrypted value. Use `POST /v1/decrypt` to read it. environment: type: string description: '`PRODUCTION` or `PREVIEW`.' createdAt: type: string format: date-time nullable: true description: When the secret was created. updatedAt: type: string format: date-time nullable: true description: When the secret was last changed. user: type: string description: Who last changed the secret. avatar: type: string description: Avatar URL of who last changed the secret. source: type: string description: >- Always `environment`: the variable is shared by the project's environment, not set on the project. enum: - environment sharedSource: type: string description: >- `own` when set on the project's environment; `inherited` when it comes from a parent environment. enum: - inherited - own sourceEnvironment: type: string nullable: true description: >- Name of the environment that defines the variable. inheritable: type: boolean nullable: true description: >- `true` when environments that inherit from this one receive the variable. sourceProject: type: string nullable: true description: >- ID of the project the variable is scoped to. `null` for variables shared with every project. required: - id - name - value - environment - createdAt - updatedAt - user - avatar - source - sharedSource - sourceEnvironment - inheritable - sourceProject filterBy: type: string nullable: true description: Echo of the `filterBy` query parameter. deployId: type: string nullable: true description: >- When `environment` is a preview name, ID of that preview's latest deployment. required: - envs - filterBy - deployId '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' components: schemas: EnvVariableResponse: type: object properties: id: type: string nullable: true description: ID of the secret. name: type: string description: Secret name. value: type: string description: Encrypted value. Use `POST /v1/decrypt` to read it. environment: type: string description: '`PRODUCTION` or `PREVIEW`.' createdAt: type: string format: date-time nullable: true description: When the secret was created (ISO 8601). updatedAt: type: string format: date-time nullable: true description: When the secret was last changed (ISO 8601). user: type: string description: Name of who last changed the secret. avatar: type: string description: Avatar URL of who last changed the secret. source: type: string enum: - preview - environment - production nullable: true description: >- Where the value comes from: `production` or `preview` (set on the project), or `environment` (shared by the project's environment). productionValue: type: string nullable: true description: >- Preview listings only: encrypted production value of the same secret, for comparison. sharedSource: type: string enum: - inherited - own nullable: true description: >- Environment variables only: `own` when set on this environment; `inherited` when it comes from a parent environment. sourceEnvironment: type: string nullable: true description: Environment variables only. Name of the environment that defines it. inheritable: type: boolean nullable: true description: >- Environment variables only: `true` when environments that inherit from this one receive it. sourceProject: type: string nullable: true description: Environment variables only. ID of the project it is scoped to. required: - id - name - value - environment - createdAt - updatedAt - user - avatar ValidationErrorResponse: type: object required: - errors properties: errors: type: array description: One entry per invalid field. items: type: object properties: type: type: string description: Always `field`. example: field value: description: Value that was sent. msg: type: string description: What is wrong with the value. example: Invalid value path: type: string description: >- Name of the invalid field. Nested fields use dots, for example `repo.branch`. example: name location: type: string description: Part of the request the field was in. enum: - body - query - params - headers - cookies ErrorResponse: type: object required: - message properties: message: type: string description: Human-readable error message. example: Project not found data: type: object description: Always empty on errors. example: {} responses: ValidationError: description: Request validation failed content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' Unauthorized: description: Missing, invalid or expired credentials content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Forbidden: description: >- The API key lacks the required scope, your team role lacks the permission, or the feature is not available on your account content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' ServerError: description: Unexpected server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-brimble-key description: >- API key created in the dashboard under Settings → API keys. Each key carries permission scopes; every endpoint lists the scope it needs. BearerAuth: type: http scheme: bearer bearerFormat: JWT description: Dashboard session token. Use an API key for integrations. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.