Import & Export

Import and export operations run as async jobs because they can process thousands of bookmarks. You start a job, poll its status, and download the result when complete.

These are heavy endpoints with a rate limit of 1 request per minute.

Export

Start an Export

POST /export/:format

Scope: export

Formats: json, csv, html

Response:

{
  "data": {
    "jobId": "job_abc123"
  }
}

Check Job Status

GET /jobs/:id

Scope: any valid token (ownership verified)

{
  "data": {
    "id": "job_abc123",
    "type": "export",
    "status": "running",
    "progress": 65,
    "createdAt": "2026-01-15T10:30:00Z"
  }
}

Job statuses:

Status	Description
`pending`	Job created, waiting to start
`running`	Processing in progress
`completed`	Done, artifact ready for download
`failed`	Job failed (check `errorMessage`)

Download the Export

POST /jobs/:id/download

Scope: export

Returns the export file as a streaming response. The Content-Type header matches the requested format.

Notes:

Artifacts expire 2 hours after job completion
A cleanup cron removes expired artifacts, stuck jobs, and orphaned chunks

Full Export Workflow

# 1. Start the export
curl -X POST https://api.bookmark.land/v1/export/json \
  -H "Authorization: Bearer bkl_your_token"

# Response: {"data": {"jobId": "job_abc123"}}

# 2. Poll status until completed
curl https://api.bookmark.land/v1/jobs/job_abc123 \
  -H "Authorization: Bearer bkl_your_token"

# 3. Download when status is "completed"
curl -X POST https://api.bookmark.land/v1/jobs/job_abc123/download \
  -H "Authorization: Bearer bkl_your_token" \
  -o bookmarks.json

Import

Reserve an Import Job

POST /import/reserve

Scope: import

Creates an import job and returns a job ID for tracking.

{
  "data": {
    "jobId": "job_def456"
  }
}

Start the Import

POST /import/start

Scope: import

Body:

{
  "jobId": "job_def456",
  "storageId": "storage_xyz"
}

The import processes bookmarks in batches of 50. Use GET /jobs/:id to track progress.

Full Import Workflow

# 1. Reserve import slot
curl -X POST https://api.bookmark.land/v1/import/reserve \
  -H "Authorization: Bearer bkl_your_token"

# 2. Upload file to get storageId (via Convex storage)

# 3. Start the import
curl -X POST https://api.bookmark.land/v1/import/start \
  -H "Authorization: Bearer bkl_your_token" \
  -H "Content-Type: application/json" \
  -d '{"jobId": "job_def456", "storageId": "storage_xyz"}'

# 4. Poll status
curl https://api.bookmark.land/v1/jobs/job_def456 \
  -H "Authorization: Bearer bkl_your_token"

Import & Export

On this page