Data Operations#

Perform data operations including batch inserts/deletes, linear merge sync, backup/restore, and individual key lookups.

Batch Operations#

Efficiently insert or delete multiple documents in a single request. The batch endpoint accepts both inserts (map of key-value pairs) and deletes (array of keys).

Distributed Transactions#

Antfly provides atomic cross-shard write transactions using a coordinator-based 2-phase commit (2PC) protocol. When a batch operation spans multiple shards, Antfly automatically executes it as a distributed transaction.

How it works:

Metadata server allocates HLC timestamp and selects coordinator shard
Coordinator writes transaction record, participants write intents
After all intents succeed, coordinator commits transaction
Participants are notified asynchronously to resolve intents
Recovery loop ensures notifications complete even after coordinator failure

Features:

Automatic: No special API required - just use the batch endpoint
Atomic: All writes across all shards commit or abort together
Recoverable: Coordinator failures are handled via recovery loops
Efficient: ~20ms latency for cross-shard transactions

Performance:

Single-shard batches: < 5ms latency
Cross-shard transactions: ~20ms latency
Intent resolution: < 30 seconds worst-case (via recovery loop)

Guarantees:

All writes succeed or all fail (atomicity)
Coordinator failure is recoverable (new leader resumes notifications)
Idempotent resolution (duplicate notifications are safe)

Use Cases:

Updating related records across shards (e.g., user profile + preferences)
Multi-table inserts that must succeed together
Bulk imports requiring all-or-nothing semantics

Linear Merge (Data Sync)#

Synchronize and keep Antfly in sync with external data sources like Shopify, Postgres, S3, or any sorted record source. Also known as: data synchronization, database sync, incremental sync, e-commerce sync.

Both source and Antfly must be sorted by the same key. Performs three-way merge: inserts new records, updates changed records, deletes records absent from source.

How it works:

Query external source with pagination (sorted by key)
Send sorted page to linear merge endpoint
Antfly merges: upserts present records, deletes Antfly records absent from page
Repeat for next page - no sync state required between pages

Use Cases:

Postgres/MySQL: SELECT * FROM products ORDER BY id LIMIT 1000 OFFSET 0
- Sync production DB to Antfly for hybrid search
- Run periodically (hourly/daily) to stay in sync
Shopify API: GET /admin/api/2024-01/products.json?order=id&limit=250
- Sync e-commerce catalog with cursor pagination
- Antfly becomes searchable product index
S3 Data Lake: Sorted JSON files (data/0001.json, data/0002.json, ...)
- Batch import from data warehouse exports
- Process files in order, send contents page by page
Databricks: SELECT * FROM delta_table ORDER BY key LIMIT 10000
- Sync data warehouse tables to Antfly
- Enable low-latency search over warehouse data

Benefits:

Stateless: No cursors or checkpoints - restart from any page
Idempotent: Safe to re-run if interrupted
Efficient: Stream comparison, no random access needed

WARNING: Not safe for concurrent merges with overlapping ranges. Single-client sync API only.

Backup and Restore#

Create backups to various storage backends:

file:///path/to/backup - Local filesystem
s3://bucket/path - Amazon S3

Restore operations rebuild tables from backup snapshots.

Key Lookups#

Direct key-value lookups for retrieving individual documents by their unique key.

Common questions about this section

How do distributed transactions work in Antfly?
How do I sync data from Postgres or Shopify?
What's the difference between batch operations and linear merge?
How do I backup and restore a table?

Cross-table batch operations#

POST/batch

Perform batch inserts, deletes, and transforms across multiple tables in a single atomic transaction.

All operations across all tables are committed atomically using distributed 2-phase commit (2PC). Either all operations succeed, or none do.

Use cases:

Transfer records between tables (insert in one, delete from another)
Maintain referential integrity across tables
Atomic multi-table updates

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "tables": {
        "users": {
            "inserts": {
                "user:123": {
                    "name": "John Doe",
                    "email": "john@example.com"
                }
            }
        },
        "orders": {
            "inserts": {
                "order:456": {
                    "user_id": "user:123",
                    "total": 99.99
                }
            }
        }
    },
    "sync_level": "propose"
}

Code Examples#

curl -X POST "/db/v1/batch" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "tables": {
        "users": {
            "inserts": {
                "user:123": {
                    "name": "John Doe",
                    "email": "john@example.com"
                }
            }
        },
        "orders": {
            "inserts": {
                "order:456": {
                    "user_id": "user:123",
                    "total": 99.99
                }
            }
        }
    },
    "sync_level": "propose"
}'

const response = await fetch('/db/v1/batch', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "tables": {
            "users": {
                "inserts": {
                    "user:123": {
                        "name": "John Doe",
                        "email": "john@example.com"
                    }
                }
            },
            "orders": {
                "inserts": {
                    "order:456": {
                        "user_id": "user:123",
                        "total": 99.99
                    }
                }
            }
        },
        "sync_level": "propose"
    })
});

const data = await response.json();

fetch('/db/v1/batch', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "tables": {
            "users": {
                "inserts": {
                    "user:123": {
                        "name": "John Doe",
                        "email": "john@example.com"
                    }
                }
            },
            "orders": {
                "inserts": {
                    "order:456": {
                        "user_id": "user:123",
                        "total": 99.99
                    }
                }
            }
        },
        "sync_level": "propose"
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/batch',
    headers=headers,
    json={
        "tables": {
            "users": {
                "inserts": {
                    "user:123": {
                        "name": "John Doe",
                        "email": "john@example.com"
                    }
                }
            },
            "orders": {
                "inserts": {
                    "order:456": {
                        "user_id": "user:123",
                        "total": 99.99
                    }
                }
            }
        },
        "sync_level": "propose"
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "tables": {
        "users": {
            "inserts": {
                "user:123": {
                    "name": "John Doe",
                    "email": "john@example.com"
                }
            }
        },
        "orders": {
            "inserts": {
                "order:456": {
                    "user_id": "user:123",
                    "total": 99.99
                }
            }
        }
    },
    "sync_level": "propose"
}`)
    req, _ := http.NewRequest("POST", "/db/v1/batch", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "status": "committed",
  "tables": {}
}

{
  "status": "committed",
  "tables": {}
}

{
  "status": "committed",
  "conflict": {
    "table": "string",
    "key": "string",
    "message": "string",
    "kind": "version_conflict",
    "retryable": true,
    "retry_after_ms": 1,
    "retry_scope": "topology",
    "expected_version": 0,
    "current_version": 0,
    "participant": {
      "group_id": 0,
      "phase": "begin"
    }
  },
  "tables": {}
}

Commit an OCC transaction#

POST/transactions/commit

Commit a stateless OCC (Optimistic Concurrency Control) transaction.

Workflow:

Read documents using regular lookup endpoints, capturing the X-Antfly-Version response header for each read
Compute writes locally based on the read values
Submit this commit request with the read set (keys + versions) and the write set (batch operations per table)

The server validates that all read versions still match current state. If any version has changed, the transaction is aborted with a 409 Conflict response containing details about which key conflicted.

If all versions match, writes are executed atomically via 2PC.

Stateless clients manage their own read set. For server-managed read-modify-write workflows, use the transaction session endpoints.

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "read_set": [
        {
            "table": "string",
            "key": "string",
            "version": "string"
        }
    ],
    "tables": {},
    "sync_level": "propose"
}

Code Examples#

curl -X POST "/db/v1/transactions/commit" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "read_set": [
        {
            "table": "string",
            "key": "string",
            "version": "string"
        }
    ],
    "tables": {},
    "sync_level": "propose"
}'

const response = await fetch('/db/v1/transactions/commit', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "read_set": [
            {
                "table": "string",
                "key": "string",
                "version": "string"
            }
        ],
        "tables": {},
        "sync_level": "propose"
    })
});

const data = await response.json();

fetch('/db/v1/transactions/commit', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "read_set": [
            {
                "table": "string",
                "key": "string",
                "version": "string"
            }
        ],
        "tables": {},
        "sync_level": "propose"
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/transactions/commit',
    headers=headers,
    json={
        "read_set": [
            {
                "table": "string",
                "key": "string",
                "version": "string"
            }
        ],
        "tables": {},
        "sync_level": "propose"
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "read_set": [
        {
            "table": "string",
            "key": "string",
            "version": "string"
        }
    ],
    "tables": {},
    "sync_level": "propose"
}`)
    req, _ := http.NewRequest("POST", "/db/v1/transactions/commit", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "status": "committed",
  "conflict": {
    "table": "string",
    "key": "string",
    "message": "string",
    "kind": "version_conflict",
    "retryable": true,
    "retry_after_ms": 1,
    "retry_scope": "topology",
    "expected_version": 0,
    "current_version": 0,
    "participant": {
      "group_id": 0,
      "phase": "begin"
    }
  },
  "tables": {}
}

{
  "status": "committed",
  "conflict": {
    "table": "string",
    "key": "string",
    "message": "string",
    "kind": "version_conflict",
    "retryable": true,
    "retry_after_ms": 1,
    "retry_scope": "topology",
    "expected_version": 0,
    "current_version": 0,
    "participant": {
      "group_id": 0,
      "phase": "begin"
    }
  },
  "tables": {}
}

{
  "status": "committed",
  "conflict": {
    "table": "string",
    "key": "string",
    "message": "string",
    "kind": "version_conflict",
    "retryable": true,
    "retry_after_ms": 1,
    "retry_scope": "topology",
    "expected_version": 0,
    "current_version": 0,
    "participant": {
      "group_id": 0,
      "phase": "begin"
    }
  },
  "tables": {}
}

List transaction sessions#

GET/transactions

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Code Examples#

curl -X GET "/db/v1/transactions" \
    -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('/db/v1/transactions', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const data = await response.json();

fetch('/db/v1/transactions', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.get('/db/v1/transactions', headers=headers)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "/db/v1/transactions", nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "session_count": 0,
  "lease_held_count": 0,
  "lease_expired_count": 0,
  "sessions": [
    {
      "transaction_id": "string",
      "owner_node_id": 0,
      "begin_timestamp": 0,
      "last_touched_timestamp": 0,
      "lease_expires_at": 0,
      "lease_state": "string",
      "sync_level": "string",
      "staged_table_count": 0,
      "staged_read_count": 0,
      "staged_write_count": 0,
      "staged_delete_count": 0,
      "read_snapshot_count": 0,
      "savepoint_count": 0,
      "savepoint_limit": 0,
      "remaining_savepoints": 0,
      "durable": true
    }
  ]
}

Clean up expired transaction sessions#

POST/transactions/cleanup

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Parameters#

Name	Type	Location	Required	Description
`cutoff_ns`	string	query	No

Code Examples#

curl -X POST "/db/v1/transactions/cleanup?cutoff_ns=value" \
    -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('/db/v1/transactions/cleanup?cutoff_ns=value', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const data = await response.json();

fetch('/db/v1/transactions/cleanup?cutoff_ns=value', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post('/db/v1/transactions/cleanup?cutoff_ns=value', headers=headers)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "/db/v1/transactions/cleanup?cutoff_ns=value", nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "removed": 0,
  "cutoff_ns": 0
}

Begin a transaction session#

POST/transactions/begin

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "sync_level": "propose"
}

Code Examples#

curl -X POST "/db/v1/transactions/begin" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "sync_level": "propose"
}'

const response = await fetch('/db/v1/transactions/begin', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "sync_level": "propose"
    })
});

const data = await response.json();

fetch('/db/v1/transactions/begin', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "sync_level": "propose"
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/transactions/begin',
    headers=headers,
    json={
        "sync_level": "propose"
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "sync_level": "propose"
}`)
    req, _ := http.NewRequest("POST", "/db/v1/transactions/begin", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "transaction_id": "string",
  "begin_timestamp": 0,
  "sync_level": "string"
}

Get transaction session details#

GET/transactions/{transaction_id}

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Parameters#

Name	Type	Location	Required	Description
`transaction_id`	string	path	Yes

Code Examples#

curl -X GET "/db/v1/transactions/{transaction_id}" \
    -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('/db/v1/transactions/{transaction_id}', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const data = await response.json();

fetch('/db/v1/transactions/{transaction_id}', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.get('/db/v1/transactions/{transaction_id}', headers=headers)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "/db/v1/transactions/{transaction_id}", nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "transaction_id": "string",
  "owner_node_id": 0,
  "begin_timestamp": 0,
  "last_touched_timestamp": 0,
  "lease_expires_at": 0,
  "lease_state": "string",
  "sync_level": "string",
  "staged_table_count": 0,
  "staged_read_count": 0,
  "staged_write_count": 0,
  "staged_delete_count": 0,
  "read_snapshot_count": 0,
  "savepoint_count": 0,
  "savepoint_limit": 0,
  "remaining_savepoints": 0,
  "durable": true
}

Stage a transaction commit request#

POST/transactions/{transaction_id}/stage

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Parameters#

Name	Type	Location	Required	Description
`transaction_id`	string	path	Yes

Request Body#

Example:

{
    "read_set": [
        {
            "table": "string",
            "key": "string",
            "version": "string"
        }
    ],
    "tables": {},
    "sync_level": "propose"
}

Code Examples#

curl -X POST "/db/v1/transactions/{transaction_id}/stage" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "read_set": [
        {
            "table": "string",
            "key": "string",
            "version": "string"
        }
    ],
    "tables": {},
    "sync_level": "propose"
}'

const response = await fetch('/db/v1/transactions/{transaction_id}/stage', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "read_set": [
            {
                "table": "string",
                "key": "string",
                "version": "string"
            }
        ],
        "tables": {},
        "sync_level": "propose"
    })
});

const data = await response.json();

fetch('/db/v1/transactions/{transaction_id}/stage', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "read_set": [
            {
                "table": "string",
                "key": "string",
                "version": "string"
            }
        ],
        "tables": {},
        "sync_level": "propose"
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/transactions/{transaction_id}/stage',
    headers=headers,
    json={
        "read_set": [
            {
                "table": "string",
                "key": "string",
                "version": "string"
            }
        ],
        "tables": {},
        "sync_level": "propose"
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "read_set": [
        {
            "table": "string",
            "key": "string",
            "version": "string"
        }
    ],
    "tables": {},
    "sync_level": "propose"
}`)
    req, _ := http.NewRequest("POST", "/db/v1/transactions/{transaction_id}/stage", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "status": "string",
  "transaction_id": "string"
}

Stage a transaction read version#

POST/transactions/{transaction_id}/read

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Parameters#

Name	Type	Location	Required	Description
`transaction_id`	string	path	Yes

Request Body#

Example:

{
    "table": "string",
    "key": "string",
    "version": "string"
}

Code Examples#

curl -X POST "/db/v1/transactions/{transaction_id}/read" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "table": "string",
    "key": "string",
    "version": "string"
}'

const response = await fetch('/db/v1/transactions/{transaction_id}/read', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "table": "string",
        "key": "string",
        "version": "string"
    })
});

const data = await response.json();

fetch('/db/v1/transactions/{transaction_id}/read', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "table": "string",
        "key": "string",
        "version": "string"
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/transactions/{transaction_id}/read',
    headers=headers,
    json={
        "table": "string",
        "key": "string",
        "version": "string"
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "table": "string",
    "key": "string",
    "version": "string"
}`)
    req, _ := http.NewRequest("POST", "/db/v1/transactions/{transaction_id}/read", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "status": "string",
  "transaction_id": "string",
  "snapshot": {
    "table": "string",
    "key": "string",
    "version": "string",
    "document": null
  }
}

{
  "status": "committed",
  "conflict": {
    "table": "string",
    "key": "string",
    "message": "string",
    "kind": "version_conflict",
    "retryable": true,
    "retry_after_ms": 1,
    "retry_scope": "topology",
    "expected_version": 0,
    "current_version": 0,
    "participant": {
      "group_id": 0,
      "phase": "begin"
    }
  },
  "tables": {}
}

Stage a transaction write#

POST/transactions/{transaction_id}/write

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Parameters#

Name	Type	Location	Required	Description
`transaction_id`	string	path	Yes

Request Body#

Example:

{
    "table": "string",
    "key": "string",
    "document": {}
}

Code Examples#

curl -X POST "/db/v1/transactions/{transaction_id}/write" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "table": "string",
    "key": "string",
    "document": {}
}'

const response = await fetch('/db/v1/transactions/{transaction_id}/write', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "table": "string",
        "key": "string",
        "document": {}
    })
});

const data = await response.json();

fetch('/db/v1/transactions/{transaction_id}/write', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "table": "string",
        "key": "string",
        "document": {}
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/transactions/{transaction_id}/write',
    headers=headers,
    json={
        "table": "string",
        "key": "string",
        "document": {}
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "table": "string",
    "key": "string",
    "document": {}
}`)
    req, _ := http.NewRequest("POST", "/db/v1/transactions/{transaction_id}/write", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "status": "string",
  "transaction_id": "string"
}

Stage a transaction delete#

POST/transactions/{transaction_id}/delete

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Parameters#

Name	Type	Location	Required	Description
`transaction_id`	string	path	Yes

Request Body#

Example:

{
    "table": "string",
    "key": "string"
}

Code Examples#

curl -X POST "/db/v1/transactions/{transaction_id}/delete" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "table": "string",
    "key": "string"
}'

const response = await fetch('/db/v1/transactions/{transaction_id}/delete', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "table": "string",
        "key": "string"
    })
});

const data = await response.json();

fetch('/db/v1/transactions/{transaction_id}/delete', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "table": "string",
        "key": "string"
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/transactions/{transaction_id}/delete',
    headers=headers,
    json={
        "table": "string",
        "key": "string"
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "table": "string",
    "key": "string"
}`)
    req, _ := http.NewRequest("POST", "/db/v1/transactions/{transaction_id}/delete", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "status": "string",
  "transaction_id": "string"
}

Create a transaction savepoint#

POST/transactions/{transaction_id}/savepoints

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Parameters#

Name	Type	Location	Required	Description
`transaction_id`	string	path	Yes

Code Examples#

curl -X POST "/db/v1/transactions/{transaction_id}/savepoints" \
    -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('/db/v1/transactions/{transaction_id}/savepoints', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const data = await response.json();

fetch('/db/v1/transactions/{transaction_id}/savepoints', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post('/db/v1/transactions/{transaction_id}/savepoints', headers=headers)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "/db/v1/transactions/{transaction_id}/savepoints", nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "status": "string",
  "transaction_id": "string",
  "savepoint_id": 0
}

Roll back a transaction session to a savepoint#

POST/transactions/{transaction_id}/savepoints/{savepoint_id}/rollback

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Parameters#

Name	Type	Location	Required	Description
`transaction_id`	string	path	Yes
`savepoint_id`	string	path	Yes

Code Examples#

curl -X POST "/db/v1/transactions/{transaction_id}/savepoints/{savepoint_id}/rollback" \
    -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('/db/v1/transactions/{transaction_id}/savepoints/{savepoint_id}/rollback', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const data = await response.json();

fetch('/db/v1/transactions/{transaction_id}/savepoints/{savepoint_id}/rollback', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post('/db/v1/transactions/{transaction_id}/savepoints/{savepoint_id}/rollback', headers=headers)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "/db/v1/transactions/{transaction_id}/savepoints/{savepoint_id}/rollback", nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "status": "string",
  "transaction_id": "string",
  "savepoint_id": 0
}

Commit a transaction session#

POST/transactions/{transaction_id}/commit

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Parameters#

Name	Type	Location	Required	Description
`transaction_id`	string	path	Yes

Request Body#

Example:

{
    "read_set": [
        {
            "table": "string",
            "key": "string",
            "version": "string"
        }
    ],
    "tables": {},
    "sync_level": "propose"
}

Code Examples#

curl -X POST "/db/v1/transactions/{transaction_id}/commit" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "read_set": [
        {
            "table": "string",
            "key": "string",
            "version": "string"
        }
    ],
    "tables": {},
    "sync_level": "propose"
}'

const response = await fetch('/db/v1/transactions/{transaction_id}/commit', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "read_set": [
            {
                "table": "string",
                "key": "string",
                "version": "string"
            }
        ],
        "tables": {},
        "sync_level": "propose"
    })
});

const data = await response.json();

fetch('/db/v1/transactions/{transaction_id}/commit', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "read_set": [
            {
                "table": "string",
                "key": "string",
                "version": "string"
            }
        ],
        "tables": {},
        "sync_level": "propose"
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/transactions/{transaction_id}/commit',
    headers=headers,
    json={
        "read_set": [
            {
                "table": "string",
                "key": "string",
                "version": "string"
            }
        ],
        "tables": {},
        "sync_level": "propose"
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "read_set": [
        {
            "table": "string",
            "key": "string",
            "version": "string"
        }
    ],
    "tables": {},
    "sync_level": "propose"
}`)
    req, _ := http.NewRequest("POST", "/db/v1/transactions/{transaction_id}/commit", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "status": "committed",
  "conflict": {
    "table": "string",
    "key": "string",
    "message": "string",
    "kind": "version_conflict",
    "retryable": true,
    "retry_after_ms": 1,
    "retry_scope": "topology",
    "expected_version": 0,
    "current_version": 0,
    "participant": {
      "group_id": 0,
      "phase": "begin"
    }
  },
  "tables": {}
}

{
  "status": "committed",
  "conflict": {
    "table": "string",
    "key": "string",
    "message": "string",
    "kind": "version_conflict",
    "retryable": true,
    "retry_after_ms": 1,
    "retry_scope": "topology",
    "expected_version": 0,
    "current_version": 0,
    "participant": {
      "group_id": 0,
      "phase": "begin"
    }
  },
  "tables": {}
}

{
  "status": "committed",
  "conflict": {
    "table": "string",
    "key": "string",
    "message": "string",
    "kind": "version_conflict",
    "retryable": true,
    "retry_after_ms": 1,
    "retry_scope": "topology",
    "expected_version": 0,
    "current_version": 0,
    "participant": {
      "group_id": 0,
      "phase": "begin"
    }
  },
  "tables": {}
}

Abort a transaction session#

POST/transactions/{transaction_id}/abort

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Parameters#

Name	Type	Location	Required	Description
`transaction_id`	string	path	Yes

Code Examples#

curl -X POST "/db/v1/transactions/{transaction_id}/abort" \
    -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('/db/v1/transactions/{transaction_id}/abort', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const data = await response.json();

fetch('/db/v1/transactions/{transaction_id}/abort', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post('/db/v1/transactions/{transaction_id}/abort', headers=headers)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "/db/v1/transactions/{transaction_id}/abort", nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "status": "string",
  "transaction_id": "string"
}

Perform batch inserts and deletes on a table#

POST/tables/{tableName}/batch

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "inserts": {
        "user:123": {
            "name": "John Doe",
            "email": "john@example.com",
            "age": 30,
            "tags": [
                "customer",
                "premium"
            ]
        },
        "user:456": {
            "name": "Jane Smith",
            "email": "jane@example.com",
            "age": 25,
            "tags": [
                "customer"
            ]
        }
    },
    "deletes": [
        "user:789",
        "user:old_account"
    ]
}

Code Examples#

curl -X POST "/db/v1/tables/{tableName}/batch" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "inserts": {
        "user:123": {
            "name": "John Doe",
            "email": "john@example.com",
            "age": 30,
            "tags": [
                "customer",
                "premium"
            ]
        },
        "user:456": {
            "name": "Jane Smith",
            "email": "jane@example.com",
            "age": 25,
            "tags": [
                "customer"
            ]
        }
    },
    "deletes": [
        "user:789",
        "user:old_account"
    ]
}'

const response = await fetch('/db/v1/tables/{tableName}/batch', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "inserts": {
            "user:123": {
                "name": "John Doe",
                "email": "john@example.com",
                "age": 30,
                "tags": [
                    "customer",
                    "premium"
                ]
            },
            "user:456": {
                "name": "Jane Smith",
                "email": "jane@example.com",
                "age": 25,
                "tags": [
                    "customer"
                ]
            }
        },
        "deletes": [
            "user:789",
            "user:old_account"
        ]
    })
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/batch', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "inserts": {
            "user:123": {
                "name": "John Doe",
                "email": "john@example.com",
                "age": 30,
                "tags": [
                    "customer",
                    "premium"
                ]
            },
            "user:456": {
                "name": "Jane Smith",
                "email": "jane@example.com",
                "age": 25,
                "tags": [
                    "customer"
                ]
            }
        },
        "deletes": [
            "user:789",
            "user:old_account"
        ]
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/tables/{tableName}/batch',
    headers=headers,
    json={
        "inserts": {
            "user:123": {
                "name": "John Doe",
                "email": "john@example.com",
                "age": 30,
                "tags": [
                    "customer",
                    "premium"
                ]
            },
            "user:456": {
                "name": "Jane Smith",
                "email": "jane@example.com",
                "age": 25,
                "tags": [
                    "customer"
                ]
            }
        },
        "deletes": [
            "user:789",
            "user:old_account"
        ]
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "inserts": {
        "user:123": {
            "name": "John Doe",
            "email": "john@example.com",
            "age": 30,
            "tags": [
                "customer",
                "premium"
            ]
        },
        "user:456": {
            "name": "Jane Smith",
            "email": "jane@example.com",
            "age": 25,
            "tags": [
                "customer"
            ]
        }
    },
    "deletes": [
        "user:789",
        "user:old_account"
    ]
}`)
    req, _ := http.NewRequest("POST", "/db/v1/tables/{tableName}/batch", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "status": "committed",
  "inserted": 0,
  "deleted": 0,
  "transformed": 0
}

{
  "status": "committed",
  "inserted": 0,
  "deleted": 0,
  "transformed": 0
}

Synchronize data from external sources (Shopify, Postgres, S3) using a linear merge#

POST/tables/{tableName}/merge

Both source and destination must be sorted by the same key. Performs three-way merge:

Inserts new records from source
Updates changed records
Deletes Antfly records absent from source page

Stateless & Idempotent: No sync state between pages. Safe to restart from any page if interrupted.

Use Cases: Sync production databases, e-commerce APIs (Shopify, WooCommerce), data lake exports, or warehouse tables to Antfly for low-latency hybrid search.

WARNING: Not safe for concurrent merges with overlapping ranges. Single-client sync API only.

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "records": {
        "product:001": {
            "name": "Laptop",
            "price": 999.99
        },
        "product:002": {
            "name": "Mouse",
            "price": 29.99
        },
        "product:003": {
            "name": "Keyboard",
            "price": 79.99
        }
    },
    "last_merged_id": "product:003",
    "dry_run": false,
    "sync_level": "propose"
}

Code Examples#

curl -X POST "/db/v1/tables/{tableName}/merge" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "records": {
        "product:001": {
            "name": "Laptop",
            "price": 999.99
        },
        "product:002": {
            "name": "Mouse",
            "price": 29.99
        },
        "product:003": {
            "name": "Keyboard",
            "price": 79.99
        }
    },
    "last_merged_id": "product:003",
    "dry_run": false,
    "sync_level": "propose"
}'

const response = await fetch('/db/v1/tables/{tableName}/merge', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "records": {
            "product:001": {
                "name": "Laptop",
                "price": 999.99
            },
            "product:002": {
                "name": "Mouse",
                "price": 29.99
            },
            "product:003": {
                "name": "Keyboard",
                "price": 79.99
            }
        },
        "last_merged_id": "product:003",
        "dry_run": false,
        "sync_level": "propose"
    })
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/merge', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "records": {
            "product:001": {
                "name": "Laptop",
                "price": 999.99
            },
            "product:002": {
                "name": "Mouse",
                "price": 29.99
            },
            "product:003": {
                "name": "Keyboard",
                "price": 79.99
            }
        },
        "last_merged_id": "product:003",
        "dry_run": false,
        "sync_level": "propose"
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/tables/{tableName}/merge',
    headers=headers,
    json={
        "records": {
            "product:001": {
                "name": "Laptop",
                "price": 999.99
            },
            "product:002": {
                "name": "Mouse",
                "price": 29.99
            },
            "product:003": {
                "name": "Keyboard",
                "price": 79.99
            }
        },
        "last_merged_id": "product:003",
        "dry_run": false,
        "sync_level": "propose"
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "records": {
        "product:001": {
            "name": "Laptop",
            "price": 999.99
        },
        "product:002": {
            "name": "Mouse",
            "price": 29.99
        },
        "product:003": {
            "name": "Keyboard",
            "price": 79.99
        }
    },
    "last_merged_id": "product:003",
    "dry_run": false,
    "sync_level": "propose"
}`)
    req, _ := http.NewRequest("POST", "/db/v1/tables/{tableName}/merge", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "status": "success",
  "upserted": 0,
  "skipped": 0,
  "deleted": 0,
  "deleted_ids": [
    "string"
  ],
  "failed": [
    {
      "id": "string",
      "operation": "upsert",
      "error": "string"
    }
  ],
  "next_cursor": "string",
  "key_range": {
    "from": "string",
    "to": "string"
  },
  "keys_scanned": 0,
  "message": "string",
  "took": 0
}

Backup a table#

POST/tables/{tableName}/backup

Backup IDs are immutable. Reusing an already published ID returns 409 without changing the existing backup.

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "backup_id": "backup-2025-01-15-v2",
    "location": "s3://mybucket/antfly-backups/users-table/2025-01-15",
    "connection": "string",
    "format": "portable"
}

Code Examples#

curl -X POST "/db/v1/tables/{tableName}/backup" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "backup_id": "backup-2025-01-15-v2",
    "location": "s3://mybucket/antfly-backups/users-table/2025-01-15",
    "connection": "string",
    "format": "portable"
}'

const response = await fetch('/db/v1/tables/{tableName}/backup', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "backup_id": "backup-2025-01-15-v2",
        "location": "s3://mybucket/antfly-backups/users-table/2025-01-15",
        "connection": "string",
        "format": "portable"
    })
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/backup', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "backup_id": "backup-2025-01-15-v2",
        "location": "s3://mybucket/antfly-backups/users-table/2025-01-15",
        "connection": "string",
        "format": "portable"
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/tables/{tableName}/backup',
    headers=headers,
    json={
        "backup_id": "backup-2025-01-15-v2",
        "location": "s3://mybucket/antfly-backups/users-table/2025-01-15",
        "connection": "string",
        "format": "portable"
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "backup_id": "backup-2025-01-15-v2",
    "location": "s3://mybucket/antfly-backups/users-table/2025-01-15",
    "connection": "string",
    "format": "portable"
}`)
    req, _ := http.NewRequest("POST", "/db/v1/tables/{tableName}/backup", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "backup": "successful"
}

Restore a table from backup#

POST/tables/{tableName}/restore

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Parameters#

Name	Type	Location	Required	Description
`Idempotency-Key`	string	header	No	Stable key used to safely retry creation of this restore job. Keys are scoped to the authenticated principal and table. Requests without this header create a new job.

Request Body#

Example:

{
    "backup_id": "backup-2025-01-15-v2",
    "location": "s3://mybucket/antfly-backups/users-table/2025-01-15",
    "connection": "string"
}

Code Examples#

curl -X POST "/db/v1/tables/{tableName}/restore" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "backup_id": "backup-2025-01-15-v2",
    "location": "s3://mybucket/antfly-backups/users-table/2025-01-15",
    "connection": "string"
}'

const response = await fetch('/db/v1/tables/{tableName}/restore', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "backup_id": "backup-2025-01-15-v2",
        "location": "s3://mybucket/antfly-backups/users-table/2025-01-15",
        "connection": "string"
    })
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/restore', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "backup_id": "backup-2025-01-15-v2",
        "location": "s3://mybucket/antfly-backups/users-table/2025-01-15",
        "connection": "string"
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/tables/{tableName}/restore',
    headers=headers,
    json={
        "backup_id": "backup-2025-01-15-v2",
        "location": "s3://mybucket/antfly-backups/users-table/2025-01-15",
        "connection": "string"
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "backup_id": "backup-2025-01-15-v2",
    "location": "s3://mybucket/antfly-backups/users-table/2025-01-15",
    "connection": "string"
}`)
    req, _ := http.NewRequest("POST", "/db/v1/tables/{tableName}/restore", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "job_id": "string",
  "attempt_id": 0,
  "scope": "table",
  "table_name": "string",
  "backup_id": "string",
  "phase": "queued",
  "cancel_requested": true,
  "durability_pending_table_count": 0,
  "published_table_count": 0,
  "completed_table_count": 0,
  "total_table_count": 0,
  "result": {
    "restore": "triggered",
    "durability": "pending",
    "status": "completed",
    "triggered_table_count": 0,
    "committed_table_count": 0,
    "durability_pending_table_count": 0,
    "skipped_table_count": 0,
    "failed_table_count": 0,
    "failure_details": [
      {
        "table_name": "string",
        "error": "string",
        "table_name_truncated": true
      }
    ],
    "failure_details_truncated": true
  },
  "error": "string",
  "created_at_ms": 0,
  "updated_at_ms": 0,
  "expires_at_ms": 0
}

{
  "code": "string",
  "error": "An error message",
  "message": "string",
  "retryable": true,
  "retry_after_ms": 1
}

Scan documents in a table within a key range#

POST/tables/{tableName}/documents

Scans keys in a table within an optional key range and returns them as newline-delimited JSON (NDJSON). Each line contains a JSON object with the _id document identifier and optionally projected document fields. This is useful for iterating through all keys in a table or a subset of keys within a range.

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "from": "user:100",
    "to": "user:200",
    "inclusive_from": true,
    "exclusive_to": true,
    "fields": [
        "title",
        "author",
        "metadata.tags"
    ],
    "filter_query": {
        "term": "string",
        "field": "string",
        "boost": 0
    },
    "limit": 100
}

Code Examples#

curl -X POST "/db/v1/tables/{tableName}/documents" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "from": "user:100",
    "to": "user:200",
    "inclusive_from": true,
    "exclusive_to": true,
    "fields": [
        "title",
        "author",
        "metadata.tags"
    ],
    "filter_query": {
        "term": "string",
        "field": "string",
        "boost": 0
    },
    "limit": 100
}'

const response = await fetch('/db/v1/tables/{tableName}/documents', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "from": "user:100",
        "to": "user:200",
        "inclusive_from": true,
        "exclusive_to": true,
        "fields": [
            "title",
            "author",
            "metadata.tags"
        ],
        "filter_query": {
            "term": "string",
            "field": "string",
            "boost": 0
        },
        "limit": 100
    })
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/documents', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "from": "user:100",
        "to": "user:200",
        "inclusive_from": true,
        "exclusive_to": true,
        "fields": [
            "title",
            "author",
            "metadata.tags"
        ],
        "filter_query": {
            "term": "string",
            "field": "string",
            "boost": 0
        },
        "limit": 100
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/tables/{tableName}/documents',
    headers=headers,
    json={
        "from": "user:100",
        "to": "user:200",
        "inclusive_from": true,
        "exclusive_to": true,
        "fields": [
            "title",
            "author",
            "metadata.tags"
        ],
        "filter_query": {
            "term": "string",
            "field": "string",
            "boost": 0
        },
        "limit": 100
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "from": "user:100",
    "to": "user:200",
    "inclusive_from": true,
    "exclusive_to": true,
    "fields": [
        "title",
        "author",
        "metadata.tags"
    ],
    "filter_query": {
        "term": "string",
        "field": "string",
        "boost": 0
    },
    "limit": 100
}`)
    req, _ := http.NewRequest("POST", "/db/v1/tables/{tableName}/documents", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

No response body

Retrieve a document by key#

GET/tables/{tableName}/documents/{key}

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Parameters#

Name	Type	Location	Required	Description
`fields`	string	query	No	Comma-separated list of fields to include in the response.
If not specified, returns the full document. Supports:

Simple fields: "title,author"
Nested paths: "user.address.city"
Wildcards: "_chunks.*"
Exclusions: "-_chunks.*._embedding"
Special fields: "_embeddings,_summaries,_chunks" | | consistency | string | query | No | Read consistency for the lookup. The default read_index routes to the primary for linearizable reads. stale allows a hot standby to serve the lookup at its safe-read LSN. |

Code Examples#

curl -X GET "/db/v1/tables/{tableName}/documents/{key}?fields=title,author,metadata.tags&consistency=value" \
    -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('/db/v1/tables/{tableName}/documents/{key}?fields=title,author,metadata.tags&consistency=value', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/documents/{key}?fields=title,author,metadata.tags&consistency=value', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.get('/db/v1/tables/{tableName}/documents/{key}?fields=title,author,metadata.tags&consistency=value', headers=headers)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "/db/v1/tables/{tableName}/documents/{key}?fields=title,author,metadata.tags&consistency=value", nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{}

List derived document artifact manifests#

GET/tables/{tableName}/documents/{key}/artifacts

Returns the derived document artifact manifests currently available for a source document. This lets clients discover artifact names before inspecting a single manifest or triggering reprocessing.

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Parameters#

Name	Type	Location	Required	Description
`detail`	string	query	No	Response detail level. `summary` returns typed manifest fields only.
`raw` also includes opaque manifest/state JSON and requires table
admin permission when authentication is enabled.

Code Examples#

curl -X GET "/db/v1/tables/{tableName}/documents/{key}/artifacts?detail=value" \
    -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('/db/v1/tables/{tableName}/documents/{key}/artifacts?detail=value', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/documents/{key}/artifacts?detail=value', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.get('/db/v1/tables/{tableName}/documents/{key}/artifacts?detail=value', headers=headers)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "/db/v1/tables/{tableName}/documents/{key}/artifacts?detail=value", nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "document_id": "string",
  "artifacts": [
    {
      "document_id": "string",
      "artifact_name": "document_units_v1",
      "artifact_id": "string",
      "manifest_version": 0,
      "generation": 0,
      "source_url": "string",
      "source_fingerprint": "string",
      "content_type": "string",
      "route_type": "pdf",
      "unsupported_reason": "string",
      "unit_count": 0,
      "chunk_count": 0,
      "ocr_attempted_count": 0,
      "ocr_selected_count": 0,
      "ocr_retained_embedded_count": 0,
      "ocr_failed_count": 0,
      "ocr_failed_page_numbers": [
        0
      ],
      "ocr_failed_pages_truncated": true,
      "child_ranges": [
        {
          "range_id": "string",
          "range_kind": "string",
          "artifact_name": "string",
          "split_boundary": "string",
          "placement": "string",
          "owner_group_id": 0,
          "placement_generation": 0,
          "route_status": "string",
          "split_eligible": true,
          "start_key": "string",
          "end_key_exclusive": "string",
          "last_key": "string",
          "child_count": 0,
          "text_bytes": 0
        }
      ],
      "child_range_count": 0,
      "merge_status": "string",
      "merge_from_generation": 0,
      "merge_to_generation": 0,
      "merge_operation_granularity": "string",
      "merge_operation_count": 0,
      "last_error_code": "string",
      "last_error_message": "string",
      "manifest_json": "string",
      "state_json": "string"
    }
  ]
}

List table repair issues#

POST/tables/{tableName}/repair/issues

Lists durable repair debt for a table. This operator-facing endpoint returns exact document keys, artifact keys, index names, and repair errors, and therefore requires table admin permission when authentication is enabled. Request filters are supplied in the JSON body. This release supports target=artifact for durable artifact queue entries and target=index for index repair candidates.

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "target": "artifact",
    "kind": "embedding",
    "index": "string",
    "cursor": "string",
    "limit": 1
}

Code Examples#

curl -X POST "/db/v1/tables/{tableName}/repair/issues" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "target": "artifact",
    "kind": "embedding",
    "index": "string",
    "cursor": "string",
    "limit": 1
}'

const response = await fetch('/db/v1/tables/{tableName}/repair/issues', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "target": "artifact",
        "kind": "embedding",
        "index": "string",
        "cursor": "string",
        "limit": 1
    })
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/repair/issues', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "target": "artifact",
        "kind": "embedding",
        "index": "string",
        "cursor": "string",
        "limit": 1
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/tables/{tableName}/repair/issues',
    headers=headers,
    json={
        "target": "artifact",
        "kind": "embedding",
        "index": "string",
        "cursor": "string",
        "limit": 1
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "target": "artifact",
    "kind": "embedding",
    "index": "string",
    "cursor": "string",
    "limit": 1
}`)
    req, _ := http.NewRequest("POST", "/db/v1/tables/{tableName}/repair/issues", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "table": "string",
  "target": "artifact",
  "limit": 0,
  "scanned": 0,
  "groups_scanned": 0,
  "has_more": true,
  "next_cursor": "string",
  "issues": [
    {
      "artifact_kind": "embedding",
      "index_name": "string",
      "doc_key": "string",
      "parent_doc_key": "string",
      "unit_id": "string",
      "index_source_artifact_name": "string",
      "source_artifact_name": "string",
      "artifact_name": "string",
      "artifact_key": "string",
      "chunk_id": 0,
      "repairable": true,
      "unsupported_reason": "string",
      "sequence": 0,
      "reason": "missing_artifact",
      "generation_attempts": 0,
      "generation_error": "string",
      "attempts": 0,
      "first_seen_ns": 0,
      "last_seen_ns": 0,
      "last_error": "string"
    }
  ]
}

Run a bounded table repair pass#

POST/tables/{tableName}/repair/run

Synchronously attempts to repair queued table issues. target=artifact reprocesses supported artifact kinds and replays derived state; it is bounded by limit and returns an opaque continuation cursor when another artifact repair page is available. target=index repairs one named index by building a shadow replacement, catching it up to the current derived replay sequence, and atomically swapping it into service; healthy indexes are skipped unless force=true is supplied, and any positive limit permits that single named index repair. The response reports unresolved debt separately, and the endpoint requires table admin permission when authentication is enabled.

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "target": "artifact",
    "kind": "embedding",
    "index": "string",
    "cursor": "string",
    "force": true,
    "control": "pause_automatic",
    "repair_id": "string",
    "limit": 1
}

Code Examples#

curl -X POST "/db/v1/tables/{tableName}/repair/run" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "target": "artifact",
    "kind": "embedding",
    "index": "string",
    "cursor": "string",
    "force": true,
    "control": "pause_automatic",
    "repair_id": "string",
    "limit": 1
}'

const response = await fetch('/db/v1/tables/{tableName}/repair/run', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "target": "artifact",
        "kind": "embedding",
        "index": "string",
        "cursor": "string",
        "force": true,
        "control": "pause_automatic",
        "repair_id": "string",
        "limit": 1
    })
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/repair/run', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "target": "artifact",
        "kind": "embedding",
        "index": "string",
        "cursor": "string",
        "force": true,
        "control": "pause_automatic",
        "repair_id": "string",
        "limit": 1
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/tables/{tableName}/repair/run',
    headers=headers,
    json={
        "target": "artifact",
        "kind": "embedding",
        "index": "string",
        "cursor": "string",
        "force": true,
        "control": "pause_automatic",
        "repair_id": "string",
        "limit": 1
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "target": "artifact",
    "kind": "embedding",
    "index": "string",
    "cursor": "string",
    "force": true,
    "control": "pause_automatic",
    "repair_id": "string",
    "limit": 1
}`)
    req, _ := http.NewRequest("POST", "/db/v1/tables/{tableName}/repair/run", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "table": "string",
  "target": "artifact",
  "limit": 0,
  "result": {
    "scanned": 0,
    "groups_scanned": 0,
    "reprocessed": 0,
    "repaired": 0,
    "missing_source_docs": 0,
    "failed": 0,
    "unsupported": 0,
    "unresolved": 0,
    "in_progress": 0,
    "indexes_rebuilt": 0,
    "indexes_degraded_before": 0,
    "indexes_degraded_after": 0,
    "controls_applied": 0,
    "limit": 0,
    "next_cursor": "string",
    "has_more": true,
    "debt_remaining": true
  }
}

Start a durable table repair job#

POST/tables/{tableName}/repair/jobs

Creates a durable table repair job for large or long-running repair work. The job stores progress and accumulated counters across bounded advance calls. Use this endpoint instead of synchronous runTableRepair when repairing large indexes or when clients need retryable progress.

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "target": "artifact",
    "kind": "embedding",
    "index": "string",
    "cursor": "string",
    "force": true,
    "limit": 1,
    "advance": true
}

Code Examples#

curl -X POST "/db/v1/tables/{tableName}/repair/jobs" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "target": "artifact",
    "kind": "embedding",
    "index": "string",
    "cursor": "string",
    "force": true,
    "limit": 1,
    "advance": true
}'

const response = await fetch('/db/v1/tables/{tableName}/repair/jobs', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "target": "artifact",
        "kind": "embedding",
        "index": "string",
        "cursor": "string",
        "force": true,
        "limit": 1,
        "advance": true
    })
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/repair/jobs', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "target": "artifact",
        "kind": "embedding",
        "index": "string",
        "cursor": "string",
        "force": true,
        "limit": 1,
        "advance": true
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/tables/{tableName}/repair/jobs',
    headers=headers,
    json={
        "target": "artifact",
        "kind": "embedding",
        "index": "string",
        "cursor": "string",
        "force": true,
        "limit": 1,
        "advance": true
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "target": "artifact",
    "kind": "embedding",
    "index": "string",
    "cursor": "string",
    "force": true,
    "limit": 1,
    "advance": true
}`)
    req, _ := http.NewRequest("POST", "/db/v1/tables/{tableName}/repair/jobs", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "job_id": 0,
  "attempt_id": 0,
  "table_name": "string",
  "phase": "queued",
  "repair_status": "in_progress",
  "target": "artifact",
  "kind": "embedding",
  "index": "string",
  "cursor": "string",
  "limit": 0,
  "force": true,
  "result": {
    "scanned": 0,
    "groups_scanned": 0,
    "reprocessed": 0,
    "repaired": 0,
    "missing_source_docs": 0,
    "failed": 0,
    "unsupported": 0,
    "unresolved": 0,
    "in_progress": 0,
    "indexes_rebuilt": 0,
    "indexes_degraded_before": 0,
    "indexes_degraded_after": 0,
    "controls_applied": 0,
    "limit": 0,
    "next_cursor": "string",
    "has_more": true,
    "debt_remaining": true
  },
  "last_error": "string",
  "cancel_requested": true,
  "created_at_millis": 0,
  "last_updated_at_millis": 0,
  "expires_at_millis": 0
}

{
  "job_id": 0,
  "attempt_id": 0,
  "table_name": "string",
  "phase": "queued",
  "repair_status": "in_progress",
  "target": "artifact",
  "kind": "embedding",
  "index": "string",
  "cursor": "string",
  "limit": 0,
  "force": true,
  "result": {
    "scanned": 0,
    "groups_scanned": 0,
    "reprocessed": 0,
    "repaired": 0,
    "missing_source_docs": 0,
    "failed": 0,
    "unsupported": 0,
    "unresolved": 0,
    "in_progress": 0,
    "indexes_rebuilt": 0,
    "indexes_degraded_before": 0,
    "indexes_degraded_after": 0,
    "controls_applied": 0,
    "limit": 0,
    "next_cursor": "string",
    "has_more": true,
    "debt_remaining": true
  },
  "last_error": "string",
  "cancel_requested": true,
  "created_at_millis": 0,
  "last_updated_at_millis": 0,
  "expires_at_millis": 0
}

Get a table repair job#

GET/tables/{tableName}/repair/jobs/{jobId}

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Code Examples#

curl -X GET "/db/v1/tables/{tableName}/repair/jobs/{jobId}" \
    -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('/db/v1/tables/{tableName}/repair/jobs/{jobId}', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/repair/jobs/{jobId}', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.get('/db/v1/tables/{tableName}/repair/jobs/{jobId}', headers=headers)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "/db/v1/tables/{tableName}/repair/jobs/{jobId}", nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "job_id": 0,
  "attempt_id": 0,
  "table_name": "string",
  "phase": "queued",
  "repair_status": "in_progress",
  "target": "artifact",
  "kind": "embedding",
  "index": "string",
  "cursor": "string",
  "limit": 0,
  "force": true,
  "result": {
    "scanned": 0,
    "groups_scanned": 0,
    "reprocessed": 0,
    "repaired": 0,
    "missing_source_docs": 0,
    "failed": 0,
    "unsupported": 0,
    "unresolved": 0,
    "in_progress": 0,
    "indexes_rebuilt": 0,
    "indexes_degraded_before": 0,
    "indexes_degraded_after": 0,
    "controls_applied": 0,
    "limit": 0,
    "next_cursor": "string",
    "has_more": true,
    "debt_remaining": true
  },
  "last_error": "string",
  "cancel_requested": true,
  "created_at_millis": 0,
  "last_updated_at_millis": 0,
  "expires_at_millis": 0
}

Advance a table repair job#

POST/tables/{tableName}/repair/jobs/{jobId}/advance

Runs at most one bounded repair pass for the job. Concurrent advances use the job lease and return the current running state.

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Code Examples#

curl -X POST "/db/v1/tables/{tableName}/repair/jobs/{jobId}/advance" \
    -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('/db/v1/tables/{tableName}/repair/jobs/{jobId}/advance', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/repair/jobs/{jobId}/advance', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post('/db/v1/tables/{tableName}/repair/jobs/{jobId}/advance', headers=headers)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "/db/v1/tables/{tableName}/repair/jobs/{jobId}/advance", nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "job_id": 0,
  "attempt_id": 0,
  "table_name": "string",
  "phase": "queued",
  "repair_status": "in_progress",
  "target": "artifact",
  "kind": "embedding",
  "index": "string",
  "cursor": "string",
  "limit": 0,
  "force": true,
  "result": {
    "scanned": 0,
    "groups_scanned": 0,
    "reprocessed": 0,
    "repaired": 0,
    "missing_source_docs": 0,
    "failed": 0,
    "unsupported": 0,
    "unresolved": 0,
    "in_progress": 0,
    "indexes_rebuilt": 0,
    "indexes_degraded_before": 0,
    "indexes_degraded_after": 0,
    "controls_applied": 0,
    "limit": 0,
    "next_cursor": "string",
    "has_more": true,
    "debt_remaining": true
  },
  "last_error": "string",
  "cancel_requested": true,
  "created_at_millis": 0,
  "last_updated_at_millis": 0,
  "expires_at_millis": 0
}

{
  "job_id": 0,
  "attempt_id": 0,
  "table_name": "string",
  "phase": "queued",
  "repair_status": "in_progress",
  "target": "artifact",
  "kind": "embedding",
  "index": "string",
  "cursor": "string",
  "limit": 0,
  "force": true,
  "result": {
    "scanned": 0,
    "groups_scanned": 0,
    "reprocessed": 0,
    "repaired": 0,
    "missing_source_docs": 0,
    "failed": 0,
    "unsupported": 0,
    "unresolved": 0,
    "in_progress": 0,
    "indexes_rebuilt": 0,
    "indexes_degraded_before": 0,
    "indexes_degraded_after": 0,
    "controls_applied": 0,
    "limit": 0,
    "next_cursor": "string",
    "has_more": true,
    "debt_remaining": true
  },
  "last_error": "string",
  "cancel_requested": true,
  "created_at_millis": 0,
  "last_updated_at_millis": 0,
  "expires_at_millis": 0
}

Cancel a table repair job#

POST/tables/{tableName}/repair/jobs/{jobId}/cancel

Requests cancellation at a bounded repair boundary. For a named-index job, the server also traverses the table in bounded passes, durably pauses matching automatic repair, and asks an active owner to yield. The job remains nonterminal until that traversal completes, so a cancelled response means detached reconstruction will not restart without an explicit resume action. If the API process restarts during the traversal, server maintenance resumes it automatically; clients do not need to advance or repeat the cancellation request.

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Code Examples#

curl -X POST "/db/v1/tables/{tableName}/repair/jobs/{jobId}/cancel" \
    -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('/db/v1/tables/{tableName}/repair/jobs/{jobId}/cancel', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/repair/jobs/{jobId}/cancel', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post('/db/v1/tables/{tableName}/repair/jobs/{jobId}/cancel', headers=headers)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "/db/v1/tables/{tableName}/repair/jobs/{jobId}/cancel", nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "job_id": 0,
  "attempt_id": 0,
  "table_name": "string",
  "phase": "queued",
  "repair_status": "in_progress",
  "target": "artifact",
  "kind": "embedding",
  "index": "string",
  "cursor": "string",
  "limit": 0,
  "force": true,
  "result": {
    "scanned": 0,
    "groups_scanned": 0,
    "reprocessed": 0,
    "repaired": 0,
    "missing_source_docs": 0,
    "failed": 0,
    "unsupported": 0,
    "unresolved": 0,
    "in_progress": 0,
    "indexes_rebuilt": 0,
    "indexes_degraded_before": 0,
    "indexes_degraded_after": 0,
    "controls_applied": 0,
    "limit": 0,
    "next_cursor": "string",
    "has_more": true,
    "debt_remaining": true
  },
  "last_error": "string",
  "cancel_requested": true,
  "created_at_millis": 0,
  "last_updated_at_millis": 0,
  "expires_at_millis": 0
}

{
  "job_id": 0,
  "attempt_id": 0,
  "table_name": "string",
  "phase": "queued",
  "repair_status": "in_progress",
  "target": "artifact",
  "kind": "embedding",
  "index": "string",
  "cursor": "string",
  "limit": 0,
  "force": true,
  "result": {
    "scanned": 0,
    "groups_scanned": 0,
    "reprocessed": 0,
    "repaired": 0,
    "missing_source_docs": 0,
    "failed": 0,
    "unsupported": 0,
    "unresolved": 0,
    "in_progress": 0,
    "indexes_rebuilt": 0,
    "indexes_degraded_before": 0,
    "indexes_degraded_after": 0,
    "controls_applied": 0,
    "limit": 0,
    "next_cursor": "string",
    "has_more": true,
    "debt_remaining": true
  },
  "last_error": "string",
  "cancel_requested": true,
  "created_at_millis": 0,
  "last_updated_at_millis": 0,
  "expires_at_millis": 0
}

Reprocess a derived asset across a table range#

POST/tables/{tableName}/artifacts/{artifactName}/reprocess

Runs a bounded operational repair pass for any asset producer type across source rows in key order. Use next_key from the response as the next request's from_key for simple single-cursor continuation. Distributed repair controllers should persist shard_cursors from the response and pass them back on the next request to resume each shard independently when scanning large sharded tables.

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "from_key": "string",
    "to_key": "string",
    "limit": 0,
    "shard_cursors": [
        {
            "group_id": 0,
            "next_key": "string",
            "scanned": 0,
            "reprocessed": 0,
            "skipped": 0,
            "failed": 0,
            "limit": 0
        }
    ]
}

Code Examples#

curl -X POST "/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "from_key": "string",
    "to_key": "string",
    "limit": 0,
    "shard_cursors": [
        {
            "group_id": 0,
            "next_key": "string",
            "scanned": 0,
            "reprocessed": 0,
            "skipped": 0,
            "failed": 0,
            "limit": 0
        }
    ]
}'

const response = await fetch('/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "from_key": "string",
        "to_key": "string",
        "limit": 0,
        "shard_cursors": [
            {
                "group_id": 0,
                "next_key": "string",
                "scanned": 0,
                "reprocessed": 0,
                "skipped": 0,
                "failed": 0,
                "limit": 0
            }
        ]
    })
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "from_key": "string",
        "to_key": "string",
        "limit": 0,
        "shard_cursors": [
            {
                "group_id": 0,
                "next_key": "string",
                "scanned": 0,
                "reprocessed": 0,
                "skipped": 0,
                "failed": 0,
                "limit": 0
            }
        ]
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess',
    headers=headers,
    json={
        "from_key": "string",
        "to_key": "string",
        "limit": 0,
        "shard_cursors": [
            {
                "group_id": 0,
                "next_key": "string",
                "scanned": 0,
                "reprocessed": 0,
                "skipped": 0,
                "failed": 0,
                "limit": 0
            }
        ]
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "from_key": "string",
    "to_key": "string",
    "limit": 0,
    "shard_cursors": [
        {
            "group_id": 0,
            "next_key": "string",
            "scanned": 0,
            "reprocessed": 0,
            "skipped": 0,
            "failed": 0,
            "limit": 0
        }
    ]
}`)
    req, _ := http.NewRequest("POST", "/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "reprocess": "triggered",
  "reprocess_status": "in_progress",
  "artifact_name": "string",
  "scanned": 0,
  "reprocessed": 0,
  "skipped": 0,
  "failed": 0,
  "limit": 0,
  "next_key": "string",
  "pending_shards": 0,
  "failures": [
    {
      "key": "string",
      "error_code": "string"
    }
  ],
  "shard_cursors": [
    {
      "group_id": 0,
      "next_key": "string",
      "scanned": 0,
      "reprocessed": 0,
      "skipped": 0,
      "failed": 0,
      "limit": 0
    }
  ]
}

Create a derived document artifact reprocess job#

POST/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs

Creates a durable user-facing repair job for a derived document artifact. The job advances through the same bounded per-shard repair primitive used by /reprocess, and stores returned continuation cursors so hosted controllers can resume large sharded table repairs without collapsing progress into a single global key cursor.

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "from_key": "string",
    "to_key": "string",
    "limit": 0,
    "advance": true
}

Code Examples#

curl -X POST "/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "from_key": "string",
    "to_key": "string",
    "limit": 0,
    "advance": true
}'

const response = await fetch('/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "from_key": "string",
        "to_key": "string",
        "limit": 0,
        "advance": true
    })
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "from_key": "string",
        "to_key": "string",
        "limit": 0,
        "advance": true
    })
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(
    '/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs',
    headers=headers,
    json={
        "from_key": "string",
        "to_key": "string",
        "limit": 0,
        "advance": true
    }
)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := []byte(`{
    "from_key": "string",
    "to_key": "string",
    "limit": 0,
    "advance": true
}`)
    req, _ := http.NewRequest("POST", "/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "job_id": 0,
  "attempt_id": 0,
  "table_name": "string",
  "artifact_name": "string",
  "phase": "queued",
  "reprocess_status": "in_progress",
  "from_key": "string",
  "to_key": "string",
  "limit": 0,
  "next_key": "string",
  "scanned": 0,
  "reprocessed": 0,
  "skipped": 0,
  "failed": 0,
  "pending_shards": 0,
  "failures": [
    {
      "key": "string",
      "error_code": "string"
    }
  ],
  "shard_cursors": [
    {
      "group_id": 0,
      "next_key": "string",
      "scanned": 0,
      "reprocessed": 0,
      "skipped": 0,
      "failed": 0,
      "limit": 0
    }
  ],
  "last_error": "string",
  "cancel_requested": true,
  "created_at_millis": 0,
  "last_updated_at_millis": 0,
  "expires_at_millis": 0
}

Get derived document artifact reprocess job status#

GET/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs/{jobId}

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Code Examples#

curl -X GET "/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs/{jobId}" \
    -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs/{jobId}', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs/{jobId}', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.get('/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs/{jobId}', headers=headers)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs/{jobId}", nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "job_id": 0,
  "attempt_id": 0,
  "table_name": "string",
  "artifact_name": "string",
  "phase": "queued",
  "reprocess_status": "in_progress",
  "from_key": "string",
  "to_key": "string",
  "limit": 0,
  "next_key": "string",
  "scanned": 0,
  "reprocessed": 0,
  "skipped": 0,
  "failed": 0,
  "pending_shards": 0,
  "failures": [
    {
      "key": "string",
      "error_code": "string"
    }
  ],
  "shard_cursors": [
    {
      "group_id": 0,
      "next_key": "string",
      "scanned": 0,
      "reprocessed": 0,
      "skipped": 0,
      "failed": 0,
      "limit": 0
    }
  ],
  "last_error": "string",
  "cancel_requested": true,
  "created_at_millis": 0,
  "last_updated_at_millis": 0,
  "expires_at_millis": 0
}

Advance a derived document artifact reprocess job#

POST/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs/{jobId}/advance

Runs one bounded repair pass and persists the resulting job state.

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Code Examples#

curl -X POST "/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs/{jobId}/advance" \
    -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs/{jobId}/advance', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs/{jobId}/advance', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post('/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs/{jobId}/advance', headers=headers)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs/{jobId}/advance", nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "job_id": 0,
  "attempt_id": 0,
  "table_name": "string",
  "artifact_name": "string",
  "phase": "queued",
  "reprocess_status": "in_progress",
  "from_key": "string",
  "to_key": "string",
  "limit": 0,
  "next_key": "string",
  "scanned": 0,
  "reprocessed": 0,
  "skipped": 0,
  "failed": 0,
  "pending_shards": 0,
  "failures": [
    {
      "key": "string",
      "error_code": "string"
    }
  ],
  "shard_cursors": [
    {
      "group_id": 0,
      "next_key": "string",
      "scanned": 0,
      "reprocessed": 0,
      "skipped": 0,
      "failed": 0,
      "limit": 0
    }
  ],
  "last_error": "string",
  "cancel_requested": true,
  "created_at_millis": 0,
  "last_updated_at_millis": 0,
  "expires_at_millis": 0
}

{
  "job_id": 0,
  "attempt_id": 0,
  "table_name": "string",
  "artifact_name": "string",
  "phase": "queued",
  "reprocess_status": "in_progress",
  "from_key": "string",
  "to_key": "string",
  "limit": 0,
  "next_key": "string",
  "scanned": 0,
  "reprocessed": 0,
  "skipped": 0,
  "failed": 0,
  "pending_shards": 0,
  "failures": [
    {
      "key": "string",
      "error_code": "string"
    }
  ],
  "shard_cursors": [
    {
      "group_id": 0,
      "next_key": "string",
      "scanned": 0,
      "reprocessed": 0,
      "skipped": 0,
      "failed": 0,
      "limit": 0
    }
  ],
  "last_error": "string",
  "cancel_requested": true,
  "created_at_millis": 0,
  "last_updated_at_millis": 0,
  "expires_at_millis": 0
}

Cancel a derived document artifact reprocess job#

POST/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs/{jobId}/cancel

Cancels a queued document artifact reprocess job. If a reprocess pass is already running, the response returns the current running state; cancellation is applied only at pass boundaries so the API never reports a committed in-flight pass as cancelled.

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Code Examples#

curl -X POST "/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs/{jobId}/cancel" \
    -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs/{jobId}/cancel', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs/{jobId}/cancel', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post('/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs/{jobId}/cancel', headers=headers)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "/db/v1/tables/{tableName}/artifacts/{artifactName}/reprocess-jobs/{jobId}/cancel", nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "job_id": 0,
  "attempt_id": 0,
  "table_name": "string",
  "artifact_name": "string",
  "phase": "queued",
  "reprocess_status": "in_progress",
  "from_key": "string",
  "to_key": "string",
  "limit": 0,
  "next_key": "string",
  "scanned": 0,
  "reprocessed": 0,
  "skipped": 0,
  "failed": 0,
  "pending_shards": 0,
  "failures": [
    {
      "key": "string",
      "error_code": "string"
    }
  ],
  "shard_cursors": [
    {
      "group_id": 0,
      "next_key": "string",
      "scanned": 0,
      "reprocessed": 0,
      "skipped": 0,
      "failed": 0,
      "limit": 0
    }
  ],
  "last_error": "string",
  "cancel_requested": true,
  "created_at_millis": 0,
  "last_updated_at_millis": 0,
  "expires_at_millis": 0
}

{
  "job_id": 0,
  "attempt_id": 0,
  "table_name": "string",
  "artifact_name": "string",
  "phase": "queued",
  "reprocess_status": "in_progress",
  "from_key": "string",
  "to_key": "string",
  "limit": 0,
  "next_key": "string",
  "scanned": 0,
  "reprocessed": 0,
  "skipped": 0,
  "failed": 0,
  "pending_shards": 0,
  "failures": [
    {
      "key": "string",
      "error_code": "string"
    }
  ],
  "shard_cursors": [
    {
      "group_id": 0,
      "next_key": "string",
      "scanned": 0,
      "reprocessed": 0,
      "skipped": 0,
      "failed": 0,
      "limit": 0
    }
  ],
  "last_error": "string",
  "cancel_requested": true,
  "created_at_millis": 0,
  "last_updated_at_millis": 0,
  "expires_at_millis": 0
}

Inspect a derived document artifact manifest#

GET/tables/{tableName}/documents/{key}/artifacts/{artifactName}

Returns manifest and processing state for a derived document artifact, such as the document-unit hierarchy extracted from a PDF, HTML page, or text field. The route is shard-aware; hosted deployments route the request to the data group that owns the source document key.

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Parameters#

Name	Type	Location	Required	Description
`detail`	string	query	No	Response detail level. `summary` returns typed manifest fields only.
`raw` also includes opaque manifest/state JSON and requires table
admin permission when authentication is enabled.

Code Examples#

curl -X GET "/db/v1/tables/{tableName}/documents/{key}/artifacts/{artifactName}?detail=value" \
    -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('/db/v1/tables/{tableName}/documents/{key}/artifacts/{artifactName}?detail=value', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/documents/{key}/artifacts/{artifactName}?detail=value', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.get('/db/v1/tables/{tableName}/documents/{key}/artifacts/{artifactName}?detail=value', headers=headers)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "/db/v1/tables/{tableName}/documents/{key}/artifacts/{artifactName}?detail=value", nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "document_id": "string",
  "artifact_name": "document_units_v1",
  "artifact_id": "string",
  "manifest_version": 0,
  "generation": 0,
  "source_url": "string",
  "source_fingerprint": "string",
  "content_type": "string",
  "route_type": "pdf",
  "unsupported_reason": "string",
  "unit_count": 0,
  "chunk_count": 0,
  "ocr_attempted_count": 0,
  "ocr_selected_count": 0,
  "ocr_retained_embedded_count": 0,
  "ocr_failed_count": 0,
  "ocr_failed_page_numbers": [
    0
  ],
  "ocr_failed_pages_truncated": true,
  "child_ranges": [
    {
      "range_id": "string",
      "range_kind": "string",
      "artifact_name": "string",
      "split_boundary": "string",
      "placement": "string",
      "owner_group_id": 0,
      "placement_generation": 0,
      "route_status": "string",
      "split_eligible": true,
      "start_key": "string",
      "end_key_exclusive": "string",
      "last_key": "string",
      "child_count": 0,
      "text_bytes": 0
    }
  ],
  "child_range_count": 0,
  "merge_status": "string",
  "merge_from_generation": 0,
  "merge_to_generation": 0,
  "merge_operation_granularity": "string",
  "merge_operation_count": 0,
  "last_error_code": "string",
  "last_error_message": "string",
  "manifest_json": "string",
  "state_json": "string"
}

Reprocess a derived asset#

POST/tables/{tableName}/documents/{key}/artifacts/{artifactName}/reprocess

Invalidates the current artifact state and requests the producer to rebuild the derived asset for the source document. Copy, generator, reader, transcriber, extractor, and document-extraction producers are all supported.

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Code Examples#

curl -X POST "/db/v1/tables/{tableName}/documents/{key}/artifacts/{artifactName}/reprocess" \
    -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('/db/v1/tables/{tableName}/documents/{key}/artifacts/{artifactName}/reprocess', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});

const data = await response.json();

fetch('/db/v1/tables/{tableName}/documents/{key}/artifacts/{artifactName}/reprocess', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
})
    .then(response => response.json())
    .then(data => console.log(data));

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post('/db/v1/tables/{tableName}/documents/{key}/artifacts/{artifactName}/reprocess', headers=headers)

data = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "/db/v1/tables/{tableName}/documents/{key}/artifacts/{artifactName}/reprocess", nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Responses#

{
  "reprocess": "triggered"
}