> ## Documentation Index > Fetch the complete documentation index at: https://docs.sailresearch.com/llms.txt > Use this file to discover all available pages before exploring further. # Set a secret > Creates a secret for your organization, or replaces its value when the name already exists. Sail never returns the stored value. After this call succeeds, the next matching request from any Sailbox using this organization secret gets the new value. ## OpenAPI ````yaml /sailbox-openapi.json put /secrets/{name} openapi: 3.1.0 info: title: Sail Sailbox API version: '2026-08-24' description: >- Create and operate Sailboxes over HTTP. Sailboxes are fast-booting virtual machines that you can pause, resume, and checkpoint. Three things happen outside this API: running commands and moving files, turning on SSH, and building an image. The first two take an SDK or the CLI, and building an image takes an SDK. Once SSH is on you can use `ssh` and `scp` for the first of those. See the [HTTP API guide](/sailboxes-http-api). servers: - url: https://sailbox-api.sailresearch.com/v1 security: - BearerAuth: [] tags: - name: Apps description: Groups that own Sailboxes. One app per workload. - name: Lifecycle description: >- A Sailbox's whole life: create it, watch it, stop and start it, terminate it. - name: Checkpoints description: Save a Sailbox to start from later, and copy a running one. - name: Networking description: >- Publish ports, serve them on hostnames you own, and identify a Sailbox to other Sailboxes. - name: Secrets description: >- Organization values that HTTP policies can add to matching requests. Sail never returns a stored value. - name: HTTP policies description: Rules for HTTPS requests a Sailbox sends. - name: Volumes description: >- Shared storage that outlives any one Sailbox. Alpha: these endpoints can still change. - name: SSH access description: Certificates for connecting to a Sailbox with `ssh`. - name: Usage description: Resource usage and spend. - name: Identity description: Who your API key belongs to. paths: /secrets/{name}: put: tags: - Secrets summary: Set a secret description: >- Creates a secret for your organization, or replaces its value when the name already exists. Sail never returns the stored value. After this call succeeds, the next matching request from any Sailbox using this organization secret gets the new value. operationId: setSecret parameters: - $ref: '#/components/parameters/SecretName' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SetSecretRequest' example: value: token-from-your-service responses: '200': description: The secret metadata. content: application/json: schema: $ref: '#/components/schemas/Secret' '400': description: >- The request was rejected. See the error message for the offending field. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: message: value is required type: invalid_request_error param: null code: null '401': description: The API key is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: message: Invalid API key type: authentication_error param: null code: invalid_api_key '402': description: >- The organization is out of credits. The error carries a `billing_url` pointing at the page where you add them. Retry once you have. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: message: >- Your API key has been disabled due to insufficient credits. Visit https://app.sailresearch.com/billing to add credits. type: billing_error param: null code: credits_exhausted billing_url: https://app.sailresearch.com/billing '403': description: The API key is not allowed to perform this operation. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: message: sailboxes require an organization-scoped API key type: permission_error param: null code: null '413': description: >- The encoded request body is larger than 512 KiB (JSON escaping can expand a value). A value over its own 64 KiB limit inside a smaller body is rejected with `400`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: message: request body too large type: invalid_request_error param: null code: null '429': description: >- Too many requests are in flight, or your organization already has 1,000 secrets. Replacing an existing secret still works at that limit. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: message: organization is limited to 1000 secrets type: quota_exceeded_error param: null code: null headers: Retry-After: $ref: '#/components/headers/RetryAfter' '500': description: Server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: message: set secret failed type: server_error param: null code: null '503': description: >- Sail is momentarily unavailable. Retry after the delay in the `Retry-After` header when one is present, and with backoff otherwise. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: message: Authentication service unavailable type: server_error param: null code: null headers: Retry-After: $ref: '#/components/headers/RetryAfter' components: parameters: SecretName: name: name in: path required: true schema: type: string pattern: >- ^[\t-\r\u0020\u0085\u00A0\u1680\u2000-\u200A\u2028\u2029\u202F\u205F\u3000]*[A-Za-z0-9][A-Za-z0-9_-]{0,127}[\t-\r\u0020\u0085\u00A0\u1680\u2000-\u200A\u2028\u2029\u202F\u205F\u3000]*$ description: >- Secret name. It starts with a letter or number and contains only letters, numbers, underscores, and dashes, up to 128 characters. Surrounding whitespace is ignored. schemas: SetSecretRequest: type: object additionalProperties: false required: - value properties: value: type: string minLength: 1 maxLength: 65536 pattern: ^[^\u0000-\u001f\u007f]+$ description: >- Value to store. It must be one line of text and at most 64 KiB as UTF-8. Sail never returns it after this request. Secret: type: object additionalProperties: false properties: org_id: type: string description: Organization that owns the secret. name: type: string pattern: ^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$ description: >- Name used in HTTP policy references. The secret value is never returned. created_at: type: string format: date-time description: When the secret was first created. updated_at: type: string format: date-time description: When the secret value was last replaced. required: - org_id - name - created_at - updated_at ErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorObject' ErrorObject: type: object required: - message - type - param - code properties: message: type: string description: Human-readable description of what went wrong. type: type: string description: >- Error category: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `not_found_error`, `conflict_error`, `rate_limit_error`, `quota_exceeded_error`, or `server_error`. param: oneOf: - type: string - type: 'null' description: >- The request field the error refers to, when the error is about one field. code: oneOf: - type: string - type: integer - type: 'null' description: Stable short code for the error, when one applies. billing_url: type: string format: uri description: Page where you add credits. Sent with a 402. additionalProperties: true headers: RetryAfter: description: >- How many seconds to wait before retrying. On a 429 it also means the request never started, so the retry can reuse the same `Idempotency-Key`. schema: type: integer minimum: 0 securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: API Key ````