Claim a Row

Atomically find one row matching an exact-value filter and update it. Use this endpoint when multiple workers may compete for the same work: only one caller can claim a given row. A successful response with `claim: null` means no matching row was available. At least one filtered field must be changed by `data`.

POST/api/v1/tables/{tableId}/rows/claim

Authorization

apiKey
X-API-Key<token>

Your SteelEngine API key (personal or workspace). Generate one from the SteelEngine dashboard under Settings > API Keys.

In: header

Path Parameters

tableId*string

The unique identifier of the table.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST \  "https://steelengine.com/api/v1/tables/{tableId}/rows/claim" \  -H "X-API-Key: YOUR_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "workspaceId": "YOUR_WORKSPACE_ID",    "filter": { "status": "pending" },    "data": { "status": "claimed", "workerId": "worker_123" }  }'

{
  "success": true,
  "data": {
    "claim": {
      "id": "row_abc123",
      "original": {
        "id": "row_abc123",
        "data": {
          "status": "pending"
        },
        "position": 0,
        "createdAt": "2026-01-15T10:30:00Z",
        "updatedAt": "2026-01-15T10:30:00Z"
      },
      "row": {
        "id": "row_abc123",
        "data": {
          "status": "claimed",
          "workerId": "worker_123"
        },
        "position": 0,
        "createdAt": "2026-01-15T10:30:00Z",
        "updatedAt": "2026-01-15T10:31:00Z"
      }
    }
  }
}

{
  "error": "string",
  "details": [
    {}
  ]
}
{
  "error": "string"
}
{
  "error": "string"
}
{
  "error": "string"
}
{
  "error": "Request body exceeds 64 KiB"
}
{
  "error": "string"
}