> ## Documentation Index > Fetch the complete documentation index at: https://empirical.run/docs/llms.txt > Use this file to discover all available pages before exploring further. # Refresh a KV entry's TTL > Resets the entry's TTL without resending its value, e.g. to extend a lock lease. Send `If-Match: ` to refresh only an unchanged entry. ## OpenAPI ````yaml /api-reference/openapi.generated.json patch /api/kv/{key} openapi: 3.1.0 info: title: Empirical API version: 1.0.0 description: Programmatic access to Empirical test runs, snoozes, and more. contact: name: Empirical url: https://empirical.run servers: - url: https://api.empirical.run security: - Bearer: [] tags: - name: Test Runs description: Trigger, list, and inspect end-to-end test runs. - name: Test Cases description: >- Browse the Playwright test cases synced from a project's repository and manage their tags. - name: Environments description: >- Named deployment targets (slug + Playwright project filters) a project's tests run against. - name: Snoozes description: Temporarily suppress known test failures for specific Playwright tests. - name: KV description: >- Project-scoped key-value store shared by test runs, shards and agent sessions. Every entry expires; conditional writes make it safe for locks. - name: Analytics description: Aggregated test-run, test-count and test-case analytics for a project. - name: Badges description: Public README status badge images (SVG) for project environments. - name: Failure Groups description: >- Durable, cross-run identities for failure modes, carrying the latest triage diagnosis. - name: Files description: >- Upload files of any type and get a link to use in tasks, sessions and messages. Agents should use the `upload_file` tool, which returns a project-wide `file@` handle (`` is the file `id` below). - name: Reporter Configuration description: Reporters a project can use in environment and run reporter configs. paths: /api/kv/{key}: patch: tags: - KV summary: Refresh a KV entry's TTL description: >- Resets the entry's TTL without resending its value, e.g. to extend a lock lease. Send `If-Match: ` to refresh only an unchanged entry. operationId: refreshKvEntry parameters: - schema: type: string pattern: ^[A-Za-z0-9._:-]{1,512}$ description: >- Key, 1-512 characters from `A-Z a-z 0-9 . _ : -`. Use `:` to namespace keys, e.g. `pw-lock:1234:user-settings`. required: true description: >- Key, 1-512 characters from `A-Z a-z 0-9 . _ : -`. Use `:` to namespace keys, e.g. `pw-lock:1234:user-settings`. name: key in: path - schema: type: string pattern: ^(?:W\/)?"?\d+"?$ description: >- Apply only if the entry's current `version` equals this value (its `ETag`). required: false description: >- Apply only if the entry's current `version` equals this value (its `ETag`). name: if-match in: header requestBody: content: application/json: schema: $ref: '#/components/schemas/PatchKvEntryRequest' responses: '200': description: The refreshed entry. headers: ETag: schema: type: string description: The entry's `version`, for use in `If-Match`. required: true description: The entry's `version`, for use in `If-Match`. content: application/json: schema: $ref: '#/components/schemas/KvEntryResponse' '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: No entry under this key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '412': description: The `If-Match` or `If-None-Match` condition did not hold. content: application/json: schema: $ref: '#/components/schemas/KvPreconditionFailedResponse' '503': description: KV store not configured. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: PatchKvEntryRequest: type: object properties: ttl: type: integer minimum: 1 maximum: 2592000 description: Time-to-live in seconds (max 30 days). required: - ttl additionalProperties: false KvEntryResponse: type: object properties: data: type: object properties: entry: $ref: '#/components/schemas/KvEntry' required: - entry description: Response payload. required: - data ErrorResponse: type: object properties: data: nullable: true description: Always null for error responses. error: type: object properties: message: type: string description: Human-readable error message. required: - message description: Error details. required: - data - error KvPreconditionFailedResponse: type: object properties: data: nullable: true description: Always null for error responses. error: type: object properties: message: type: string description: Human-readable error message. current: type: object nullable: true properties: key: type: string pattern: ^[A-Za-z0-9._:-]{1,512}$ description: >- Key, 1-512 characters from `A-Z a-z 0-9 . _ : -`. Use `:` to namespace keys, e.g. `pw-lock:1234:user-settings`. value: anyOf: - type: string - type: number - type: boolean - type: array items: nullable: true - type: object additionalProperties: nullable: true description: >- The stored JSON value. Omitted from list responses unless `include_values=true`. nullable: true version: type: integer minimum: 1 description: >- Increments on every write. Send it as `If-Match` to make a write conditional. expires_at: type: string format: date-time description: ISO 8601 timestamp when the entry expires. created_at: type: string format: date-time description: ISO 8601 timestamp when the entry was first written. updated_at: type: string format: date-time description: ISO 8601 timestamp of the latest write or TTL refresh. written_by: $ref: '#/components/schemas/KvWriter' required: - key - version - expires_at - created_at - updated_at - written_by description: The entry as it is now, or `null` if the key does not exist. required: - message - current description: Error details with the current entry. required: - data - error KvEntry: type: object properties: key: type: string pattern: ^[A-Za-z0-9._:-]{1,512}$ description: >- Key, 1-512 characters from `A-Z a-z 0-9 . _ : -`. Use `:` to namespace keys, e.g. `pw-lock:1234:user-settings`. value: anyOf: - type: string - type: number - type: boolean - type: array items: nullable: true - type: object additionalProperties: nullable: true description: >- The stored JSON value. Omitted from list responses unless `include_values=true`. nullable: true version: type: integer minimum: 1 description: >- Increments on every write. Send it as `If-Match` to make a write conditional. expires_at: type: string format: date-time description: ISO 8601 timestamp when the entry expires. created_at: type: string format: date-time description: ISO 8601 timestamp when the entry was first written. updated_at: type: string format: date-time description: ISO 8601 timestamp of the latest write or TTL refresh. written_by: $ref: '#/components/schemas/KvWriter' required: - key - version - expires_at - created_at - updated_at - written_by KvWriter: oneOf: - type: object properties: kind: type: string enum: - user id: type: string minLength: 1 description: User ID. required: - kind - id - type: object properties: kind: type: string enum: - chat_session id: type: string minLength: 1 description: Chat session ID. required: - kind - id - type: object properties: kind: type: string enum: - test_run id: type: string minLength: 1 description: Test run ID. required: - kind - id - type: object properties: kind: type: string enum: - api_key id: type: string minLength: 1 description: Project API key ID. required: - kind - id - type: object properties: kind: type: string enum: - system id: type: string nullable: true minLength: 1 description: Service name, when known. required: - kind - id description: Who last wrote or refreshed the entry. securitySchemes: Bearer: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.