API REFERENCE

Delete trailing chat messages

On this page

DELETE/api/chats/{id}/messages/trailing

Delete a message in a Workflow chat and every message after it, ordered by created_at then id. Concurrent edit/resend is unsupported: stop other writers first, because an active workflow run returns 409. 200 means the delete ran, possibly affecting zero rows; after a transport failure, refresh the chat history instead of resending.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL

curl --request DELETE \
  --url 'https://api.recoupable.dev/api/chats/YOUR_ID/messages/trailing?from_message_id=YOUR_FROM_MESSAGE_ID' \
  --header 'x-api-key: YOUR_API_KEY'

Replace the YOUR_ placeholders with your values. Required query parameters are included; optional parameters are listed below.

Try it

Fill in the fields, send the request from your browser, and read the live response. The curl below updates as you type.

API keyx-api-key header

Kept in this browser tab only and cleared when it closes.

idpath · stringrequired

from_message_idquery · stringrequired

account_idquery · string

cURL for this request

curl --request DELETE \
  --url 'https://api.recoupable.dev/api/chats/{id}/messages/trailing'

Parameters

Path parameters

idstringrequired

UUID of the owned Workflow chat.

Query parameters

from_message_idstringrequired

UUID of the persisted message in this Workflow chat to use as the inclusive created_at, id boundary. Any persisted message role is eligible.

account_idstring

Optional effective account override, accepted only when current authentication authorizes access to that account. It does not grant access by itself.

Responses

200Delete statement succeeded, including a possible zero-row result. No deleted count, durable-absence or concurrent edit/resend guarantee.

application/json

statusstring · enumrequired

Status of the request

Values: "success"

Example: "success"

chat_idstringrequired

The chat UUID where deletion was applied.

format: uuid

from_message_idstringrequired

The message UUID used as the trailing deletion boundary.

format: uuid

statementSuccess

{
  "status": "success",
  "chat_id": "11111111-1111-4111-8111-111111111111",
  "from_message_id": "22222222-2222-4222-8222-222222222222"
}

400Invalid chat UUID or missing/invalid from_message_id query UUID.

application/json

statusstring · enumrequired

Status of the request

Values: "error"

errorstringrequired

Error message describing what went wrong.

missing_fieldsarray<string>

List of missing or invalid parameter fields (when validation fails).

Item properties

string

401Missing, conflicting or invalid credentials. Authentication errors retain the error or message envelope returned by the selected authentication path.

application/json

anyOf · object 1

statusstring · enumrequired

Always error.

Values: "error"

errorstringrequired

Human-readable error message or documented error code.

Additional properties

any

anyOf · object 2

statusstring · enumrequired

Always error.

Values: "error"

messagestringrequired

Human-readable authentication error message.

Additional properties

any

403Access denied to the requested account_id override or the effective account does not own the Workflow chat session.

application/json

statusstring · enumrequired

Status of the request

Values: "error"

errorstringrequired

Error message describing what went wrong.

missing_fieldsarray<string>

List of missing or invalid parameter fields (when validation fails).

Item properties

string

404Workflow chat/session is absent, or the anchor is absent from this chat (including a foreign-chat anchor).

application/json

statusstring · enumrequired

Status of the request

Values: "error"

errorstringrequired

Error message describing what went wrong.

missing_fieldsarray<string>

List of missing or invalid parameter fields (when validation fails).

Item properties

string

409An occupied workflow slot was observed. Pending reservations and other nonnull values are rejected without provider calls, cancellation or slot mutation. This check is not a concurrency lock.

application/json

statusstring · enumrequired

Status of the request

Values: "error"

errorstringrequired

Error message describing what went wrong.

missing_fieldsarray<string>

List of missing or invalid parameter fields (when validation fails).

Item properties

string

occupiedSlot

{
  "status": "error",
  "error": "Chat has an active workflow reservation; retry after it clears"
}

500Authentication/storage failure, chat/session/anchor read failure, invalid stored boundary, or delete failure. A transport failure may leave the commit outcome unknown; refresh history before further action.

application/json

statusstring · enumrequired

Status of the request

Values: "error"

errorstringrequired

Error message describing what went wrong.

missing_fieldsarray<string>

List of missing or invalid parameter fields (when validation fails).

Item properties

string

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download research.json

View operation source

json

{
  "operationId": "deleteChatsByIdMessagesTrailing",
  "description": "Delete a message in a Workflow chat and every message after it, ordered by `created_at` then `id`. Concurrent edit/resend is unsupported: stop other writers first, because an active workflow run returns `409`. `200` means the delete ran, possibly affecting zero rows; after a transport failure, refresh the chat history instead of resending.",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "description": "UUID of the owned Workflow chat.",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "name": "from_message_id",
      "in": "query",
      "description": "UUID of the persisted message in this Workflow chat to use as the inclusive created_at, id boundary. Any persisted message role is eligible.",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "name": "account_id",
      "in": "query",
      "required": false,
      "description": "Optional effective account override, accepted only when current authentication authorizes access to that account. It does not grant access by itself.",
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Delete statement succeeded, including a possible zero-row result. No deleted count, durable-absence or concurrent edit/resend guarantee.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/DeleteTrailingChatMessagesResponse"
          },
          "examples": {
            "statementSuccess": {
              "value": {
                "status": "success",
                "chat_id": "11111111-1111-4111-8111-111111111111",
                "from_message_id": "22222222-2222-4222-8222-222222222222"
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "Invalid chat UUID or missing/invalid from_message_id query UUID.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/DeleteTrailingChatMessagesErrorResponse"
          }
        }
      }
    },
    "401": {
      "description": "Missing, conflicting or invalid credentials. Authentication errors retain the error or message envelope returned by the selected authentication path.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/DeleteTrailingChatAuthenticationErrorResponse"
          }
        }
      }
    },
    "403": {
      "description": "Access denied to the requested account_id override or the effective account does not own the Workflow chat session.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/DeleteTrailingChatMessagesErrorResponse"
          }
        }
      }
    },
    "404": {
      "description": "Workflow chat/session is absent, or the anchor is absent from this chat (including a foreign-chat anchor).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/DeleteTrailingChatMessagesErrorResponse"
          }
        }
      }
    },
    "409": {
      "description": "An occupied workflow slot was observed. Pending reservations and other nonnull values are rejected without provider calls, cancellation or slot mutation. This check is not a concurrency lock.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/DeleteTrailingChatMessagesErrorResponse"
          },
          "examples": {
            "occupiedSlot": {
              "value": {
                "status": "error",
                "error": "Chat has an active workflow reservation; retry after it clears"
              }
            }
          }
        }
      }
    },
    "500": {
      "description": "Authentication/storage failure, chat/session/anchor read failure, invalid stored boundary, or delete failure. A transport failure may leave the commit outcome unknown; refresh history before further action.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/DeleteTrailingChatMessagesErrorResponse"
          }
        }
      }
    }
  },
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ]
}

Get started with Recoup.

Try Our Platform

Build Your Platform

Delete trailing chat messages

Authentication

Request

Try it

Parameters

Path parameters

Query parameters

Responses

Full specification