> ## Documentation Index > Fetch the complete documentation index at: https://docs.lithoblocks.com/llms.txt > Use this file to discover all available pages before exploring further. # Expire every message with a reference > Expire every live message your sends tagged with `reference` (a bulk send shares one across its destinations), so an automation can retire "the messages for ticket 123" without keeping our ids. Each is due at once: its buttons stop working immediately and it is replaced within about a minute. A member's request leaves alone the messages others sent, and says how many. At most 100 messages per call. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/messages/expire openapi: 3.0.0 info: version: 0.0.1 title: LithoBlocks API description: >- Manage templates, compile and send Slack messages, schedule delivery, build batch digests, and configure interactive workflows. Use /v1 paths and snake_case request fields. Authenticate with an organization-scoped API key in the Authorization: Bearer header. Each operation documents its required scope; a key without it receives 403 and required_scopes. A user's organization role limits which scopes a key can receive. Compiling and sending require messages:create; read access alone does not allow either operation. Create and manage keys in Integrations → API Keys. Store credentials in a secret manager, grant only the scopes needed, and use separate keys for each environment. Resources and credentials do not transfer between environments. Use code and request_id to diagnose API errors. The error field can be a string or a schema-validation object; consult the endpoint response schema for details. Resource list endpoints document their pagination and compatibility fields individually. See the documentation guides for API key lifecycle, the complete scope/role matrix, environment availability, input-schema discovery, and idempotent sending. The endpoint definitions below are the source for request and response contracts. contact: name: LithoBlocks url: https://lithoblocks.com email: support@lithoblocks.com servers: - url: https://api.lithoblocks.com description: Production (paths in this spec are rooted at /v1/...) - url: http://localhost:9999 description: Local dev (paths in this spec are rooted at /v1/...) security: [] paths: /v1/messages/expire: post: tags: - Messages summary: Expire every message with a reference description: >- Expire every live message your sends tagged with `reference` (a bulk send shares one across its destinations), so an automation can retire "the messages for ticket 123" without keeping our ids. Each is due at once: its buttons stop working immediately and it is replaced within about a minute. A member's request leaves alone the messages others sent, and says how many. At most 100 messages per call. parameters: - schema: type: string minLength: 1 maxLength: 255 description: >- Any unique string (a UUID is fine). Repeating a request with the same key and body within 24 hours replays the original response with `Idempotency-Replayed: true` instead of running again; the same key with a different body is a 409. Incomplete and 5xx outcomes are retained for reconciliation beyond 24 hours. Applies only on the documented endpoints. Never automatically change keys to bypass an uncertain outcome. example: 3f7d2c1a-9b4e-4f0a-8c6d-2e1b5a7c9d10 required: false in: header name: Idempotency-Key requestBody: description: The reference, and how they expire required: true content: application/json: schema: type: object properties: mode: type: string enum: - replace - delete description: Defaults to the pending expiry's mode, else `replace`. retain_content: type: boolean description: >- Defaults to the pending expiry's choice, else `false`: LithoBlocks' copies are cleared. reference: type: string minLength: 1 maxLength: 255 description: Every live message your sends tagged with this reference. required: - reference additionalProperties: false responses: '202': description: The messages now due to expire content: application/json: schema: $ref: '#/components/schemas/SentMessageExpireByReferenceResult' '400': description: '`invalid_request`: an edit with nothing to change' content: application/json: schema: $ref: '#/components/schemas/ApiError' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ApiError' '402': description: >- `insufficient_credits` or `overage_limit_exceeded`: a re-render uses one credit content: application/json: schema: $ref: '#/components/schemas/ApiError' '403': description: >- Insufficient scope, or `not_message_sender`: members change only the messages they sent content: application/json: schema: $ref: '#/components/schemas/ApiError' '404': description: Message not found in your organization content: application/json: schema: $ref: '#/components/schemas/ApiError' '409': description: >- `message_not_live`, `expiration_in_progress`, `no_expiration`, `mutation_in_progress` or `reconciliation_required`; also an Idempotency-Key conflict, or `slack_not_connected` content: application/json: schema: $ref: '#/components/schemas/ApiError' '422': description: >- Validation failed, or `expiration_in_past`: an expiry must be at least 60 seconds away content: application/json: schema: anyOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/ApiError' '429': description: Rate limited content: application/json: schema: $ref: '#/components/schemas/ApiError' '500': description: Internal error content: application/json: schema: $ref: '#/components/schemas/ApiError' '502': description: >- `slack_refused`: Slack refused the change and nothing changed; `details` carries Slack's error content: application/json: schema: $ref: '#/components/schemas/ApiError' '503': description: >- `rate_limited`: Slack is rate limiting changes; retry after the Retry-After header content: application/json: schema: $ref: '#/components/schemas/ApiError' '504': description: >- `slack_outcome_unknown`: the change may or may not have happened; the message now needs reconciliation content: application/json: schema: $ref: '#/components/schemas/ApiError' security: - bearerAuth: - messages:update components: schemas: SentMessageExpireByReferenceResult: type: object properties: scheduled: type: integer description: >- Messages due to expire now. Each is replaced within about a minute; their buttons stop working at once. not_permitted: type: integer description: >- Messages carrying the reference that a member did not send, and so left alone. message_ids: type: array items: type: string format: uuid required: - scheduled - not_permitted - message_ids ApiError: type: object properties: error: type: string description: Human-readable summary. Not stable; match on `code`. code: $ref: '#/components/schemas/ErrorCode' request_id: type: string description: >- Echoed from the request's X-Request-Id header, or generated. Quote it in support requests. message: type: string details: type: string error_details: type: string success: type: boolean enum: - false valid: type: boolean enum: - false required_scopes: type: array items: type: string user_scopes: type: array items: type: string required: - error - code - request_id ValidationError: type: object properties: success: type: boolean enum: - false error: type: object properties: issues: type: array items: type: object properties: code: type: string path: type: array items: anyOf: - type: string - type: number message: type: string required: - code - path - message name: type: string required: - issues - name message: type: string description: >- The issues as one line, `path: message; path: message`, for callers that show a string (form builders such as Make) code: type: string enum: - validation_failed request_id: type: string required: - success - error - message - code - request_id ErrorCode: type: string enum: - unauthenticated - invalid_token - insufficient_scope - access_denied - validation_failed - invalid_request - invalid_data - invalid_destination - invalid_search_query - not_found - template_not_found - version_not_found - organization_not_found - entity_not_found - field_not_found - user_not_found - profile_not_found - credits_not_found - insufficient_credits - overage_limit_exceeded - credit_deduction_failed - compilation_failed - no_blocks_to_send - slack_not_connected - slack_user_not_found - slack_dm_failed - slack_token_decrypt_failed - slack_api_error - already_exists - invitation_pending - idempotency_conflict - idempotency_in_progress - rate_limited - tier_limit - invalid_state - template_archived - template_in_use - template_not_activated - current_version_changed - message_not_found - not_message_sender - revision_conflict - message_not_live - mutation_in_progress - reconciliation_required - nothing_to_reconcile - text_not_editable - slack_refused - slack_outcome_unknown - expiration_in_past - expiration_in_progress - no_expiration - expiration_exceeds_maximum - maintenance - misconfigured - internal_error description: >- Machine-readable reason for the failure. Match on this, not on `error`. New codes may be added; existing ones are stable. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: >- LithoBlocks API key obtained from your organization dashboard. The LithoBlocks MCP server also presents a Supabase-issued user session token here on the user's behalf; such a token acts as that user with the scopes their organization role allows. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.