Securely manage account-level Secrets (API keys, tokens, credentials) that Runloop injects into Devboxes at runtime. Raw secret values are never exposed to agent code or to the Devbox shell environment after creation — they are referenced by name.
openapi: 3.0.3
info:
title: Runloop Secrets API
version: '0.1'
description: Securely manage account-level Secrets (API keys, tokens, credentials) that are injected at Devbox runtime without
exposing raw values to agent code.
contact:
name: Runloop AI Support
url: https://runloop.ai
email: support@runloop.ai
servers:
- url: https://api.runloop.ai
description: Runloop API
variables: {}
tags:
- name: secrets
paths:
/v1/secrets:
post:
tags:
- secrets
summary: Create a Secret.
description: Create a new Secret with a globally unique name and value. The Secret will be encrypted at rest and made
available as an environment variable in Devboxes.
operationId: createSecret
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SecretCreateParameters'
required: false
responses:
'200':
description: Secret created successfully. Returns the Secret with its value included.
content:
application/json:
schema:
$ref: '#/components/schemas/SecretView'
'400':
description: Bad request. Secret name already exists, is invalid, or contains illegal characters.
'401':
description: Unauthorized. Invalid or missing authentication.
'403':
description: Forbidden. Account does not have devbox capability.
'500':
description: Internal server error.
deprecated: false
get:
tags:
- secrets
summary: List Secrets.
description: List all Secrets for the authenticated account. Secret values are not included for security reasons.
operationId: listSecrets
parameters:
- name: limit
in: query
description: The limit of items to return. Default is 20. Max is 5000.
required: false
deprecated: false
allowEmptyValue: true
schema:
type: integer
format: int32
responses:
'200':
description: Successfully retrieved list of Secrets. Values are omitted for security.
content:
application/json:
schema:
$ref: '#/components/schemas/SecretListView'
'401':
description: Unauthorized. Invalid or missing authentication.
'403':
description: Forbidden. Account does not have devbox capability.
'500':
description: Internal server error.
deprecated: false
/v1/secrets/{name}:
get:
tags:
- secrets
summary: Get a Secret.
description: Retrieve a Secret by name. The secret value is not included for security.
operationId: getSecret
parameters:
- name: name
in: path
description: The name of the Secret to retrieve.
required: true
deprecated: false
allowEmptyValue: false
schema:
type: string
responses:
'200':
description: Successfully retrieved the Secret. Value is omitted for security.
content:
application/json:
schema:
$ref: '#/components/schemas/SecretView'
'404':
description: Secret not found.
deprecated: false
post:
tags:
- secrets
summary: Update a Secret.
description: Update the value of an existing Secret by name. The new value will be encrypted at rest.
operationId: updateSecret
parameters:
- name: name
in: path
description: The name of the Secret to update.
required: true
deprecated: false
allowEmptyValue: false
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SecretUpdateParameters'
required: false
responses:
'200':
description: Secret updated successfully. Returns the Secret with its new value included.
content:
application/json:
schema:
$ref: '#/components/schemas/SecretView'
'400':
description: Bad request. Invalid parameters.
'401':
description: Unauthorized. Invalid or missing authentication.
'403':
description: Forbidden. Account does not have devbox capability.
'404':
description: Secret not found.
'500':
description: Internal server error.
deprecated: false
/v1/secrets/{name}/delete:
post:
tags:
- secrets
summary: Delete a Secret.
description: Delete an existing Secret by name. This action is irreversible and will remove the Secret from all Devboxes.
operationId: deleteSecret
parameters:
- name: name
in: path
description: The name of the Secret to delete.
required: true
deprecated: false
allowEmptyValue: false
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EmptyRecord'
required: false
responses:
'200':
description: Secret deleted successfully. Returns the deleted Secret (without value for security).
content:
application/json:
schema:
$ref: '#/components/schemas/SecretView'
'401':
description: Unauthorized. Invalid or missing authentication.
'403':
description: Forbidden. Account does not have devbox capability.
'404':
description: Secret not found.
'500':
description: Internal server error.
deprecated: false
components:
schemas:
EmptyRecord:
type: object
additionalProperties: false
properties: {}
SecretCreateParameters:
type: object
additionalProperties: false
description: Parameters required to create a new Secret.
properties:
name:
type: string
description: 'The globally unique name for the Secret. Must be a valid environment variable name (alphanumeric and
underscores only). Example: ''DATABASE_PASSWORD'''
value:
type: string
description: 'The value to store for this Secret. This will be encrypted at rest and made available as an environment
variable in Devboxes. Example: ''my-secure-password'''
required:
- name
- value
SecretListView:
type: object
additionalProperties: false
description: A paginated list of Secrets.
properties:
secrets:
type: array
items:
$ref: '#/components/schemas/SecretView'
description: List of Secret objects. Values are omitted for security.
has_more:
type: boolean
description: True if there are more results available beyond this page.
total_count:
type: integer
format: int32
nullable: true
description: Total number of Secrets across all pages.
required:
- secrets
- has_more
SecretUpdateParameters:
type: object
additionalProperties: false
description: Parameters required to update an existing Secret.
properties:
value:
type: string
description: 'The new value for the Secret. This will replace the existing value and be encrypted at rest. Example:
''my-updated-secure-password'''
required:
- value
SecretView:
type: object
additionalProperties: false
description: A Secret represents a key-value pair that can be securely stored and used in Devboxes as environment variables.
properties:
id:
type: string
description: The unique identifier of the Secret.
name:
type: string
description: The globally unique name of the Secret. Used as the environment variable name in Devboxes.
create_time_ms:
type: integer
format: int64
description: Creation time of the Secret (Unix timestamp in milliseconds).
update_time_ms:
type: integer
format: int64
description: Last update time of the Secret (Unix timestamp in milliseconds).
required:
- id
- name
- create_time_ms
- update_time_ms
securitySchemes:
bearerAuth:
scheme: bearer
type: http
security:
- bearerAuth: []