Lists API

Lists are ordered collections. They are useful for queues, stacks, feeds, and ordered work items.

Endpoints

Method	Endpoint	Description
POST	`/{plateId}/lists/left/push`	Push to the left
POST	`/{plateId}/lists/right/push`	Push to the right
POST	`/{plateId}/lists/left/pop`	Pop from the left
POST	`/{plateId}/lists/right/pop`	Pop from the right
GET	`/{plateId}/lists/range/{key}`	Read a range
GET	`/{plateId}/lists/item/{key}/{index}`	Read one item
GET	`/{plateId}/lists/length/{key}`	Count items
POST	`/{plateId}/lists/position`	Find an item's position
POST	`/{plateId}/lists/set`	Replace an item by index
POST	`/{plateId}/lists/insert`	Insert before or after a pivot
POST	`/{plateId}/lists/remove`	Remove matching items
POST	`/{plateId}/lists/trim`	Trim list bounds
POST	`/{plateId}/lists/move`	Move between lists
POST	`/{plateId}/lists/command`	Execute allowed list commands
POST	`/{plateId}/lists/{key}/command`	Execute key-specific list commands

Examples

Push to the right

const plateId = "[id]";
const apiKey = "your-api-key";
const baseUrl = "[base-url]";

const response = await fetch(`${baseUrl}/$[id]/lists/right/push`, {
  method: "POST",
  headers: {
    "Authorization": apiKey,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    key: "jobs",
    values: ["a", "b", "c"]
  })
});

const data = await response.json();
console.log(data);

Pop from the left

const plateId = "[id]";
const apiKey = "your-api-key";
const baseUrl = "[base-url]";

const response = await fetch(`${baseUrl}/$[id]/lists/left/pop`, {
  method: "POST",
  headers: {
    "Authorization": apiKey,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    key: "jobs",
    count: 2
  })
});

const data = await response.json();
console.log(data);

Read a range

const plateId = "[id]";
const apiKey = "your-api-key";
const baseUrl = "[base-url]";

const response = await fetch(`${baseUrl}/$[id]/lists/range/jobs?start=0&stop=9`, {
  headers: {
    "Authorization": apiKey,
    "Content-Type": "application/json"
  }
});

const data = await response.json();
console.log(data);

Insert relative to a pivot

const plateId = "[id]";
const apiKey = "your-api-key";
const baseUrl = "[base-url]";

const response = await fetch(`${baseUrl}/$[id]/lists/insert`, {
  method: "POST",
  headers: {
    "Authorization": apiKey,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    key: "jobs",
    where: "before",
    pivot: "b",
    value: "urgent"
  })
});

const data = await response.json();
console.log(data);

Move an item between lists

const plateId = "[id]";
const apiKey = "your-api-key";
const baseUrl = "[base-url]";

const response = await fetch(`${baseUrl}/$[id]/lists/move`, {
  method: "POST",
  headers: {
    "Authorization": apiKey,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    source: "pending",
    destination: "processing",
    from: "right",
    to: "left"
  })
});

const data = await response.json();
console.log(data);

Get Item by Index

const plateId = "[id]";
const apiKey = "your-api-key";
const baseUrl = "[base-url]";

const response = await fetch(`${baseUrl}/$[id]/lists/item/jobs/0`, {
  headers: {
    "Authorization": apiKey,
    "Content-Type": "application/json"
  }
});

const data = await response.json();
console.log(data);

Get Length

const plateId = "[id]";
const apiKey = "your-api-key";
const baseUrl = "[base-url]";

const response = await fetch(`${baseUrl}/$[id]/lists/length/jobs`, {
  headers: {
    "Authorization": apiKey,
    "Content-Type": "application/json"
  }
});

const data = await response.json();
console.log(data);

Find Position (LPOS)

const plateId = "[id]";
const apiKey = "your-api-key";
const baseUrl = "[base-url]";

const response = await fetch(`${baseUrl}/$[id]/lists/position`, {
  method: "POST",
  headers: {
    "Authorization": apiKey,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    key: "jobs",
    value: "urgent",
    rank: 1,
    count: 5
  })
});

const data = await response.json();
console.log(data);

Query parameters (via JSON body):

rank (optional): Start searching from this position
count (optional): Number of positions to return
maxlen (optional): Limit search depth

Set Item by Index

const plateId = "[id]";
const apiKey = "your-api-key";
const baseUrl = "[base-url]";

const response = await fetch(`${baseUrl}/$[id]/lists/set`, {
  method: "POST",
  headers: {
    "Authorization": apiKey,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    key: "jobs",
    index: 0,
    value: "replaced"
  })
});

const data = await response.json();
console.log(data);

Remove Items

const plateId = "[id]";
const apiKey = "your-api-key";
const baseUrl = "[base-url]";

const response = await fetch(`${baseUrl}/$[id]/lists/remove`, {
  method: "POST",
  headers: {
    "Authorization": apiKey,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    key: "jobs",
    value: "done",
    count: 1
  })
});

const data = await response.json();
console.log(data);

Set count to 0 to remove all matching items.

Trim List

const plateId = "[id]";
const apiKey = "your-api-key";
const baseUrl = "[base-url]";

const response = await fetch(`${baseUrl}/$[id]/lists/trim`, {
  method: "POST",
  headers: {
    "Authorization": apiKey,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    key: "jobs",
    start: 0,
    stop: 99
  })
});

const data = await response.json();
console.log(data);

Keeps only elements from index 0 to 99, removing everything after.

Command Compatibility

const plateId = "[id]";
const apiKey = "your-api-key";
const baseUrl = "[base-url]";

const response = await fetch(`${baseUrl}/$[id]/lists/command`, {
  method: "POST",
  headers: {
    "Authorization": apiKey,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    command: "LPUSH",
    args: ["mylist", "a", "b", "c"]
  })
});

const data = await response.json();
console.log(data);

Command Endpoints

`POST /[id]/lists/command`

Execute allowed list commands across the plate.

Allowed Commands:

Command	Description
LPUSH	Push to left
RPUSH	Push to right
LPOP	Pop from left
RPOP	Pop from right
LLEN	Get length
LRANGE	Get range
LINDEX	Get by index
LPOS	Find position
LSET	Set by index
LINSERT	Insert relative to pivot
LREM	Remove items
LTRIM	Trim list
LMOVE	Move between lists

Query Parameters for LRANGE:

start (optional): Start index (default: 0)
stop (optional): End index (default: -1)

Query Parameters for LPOS:

rank (optional): Start position from this rank
count (optional): Number of matches to return
maxlen (optional): Limit search length

`POST /[id]/lists/[key]/command`

Execute allowed commands on a specific list key.

Allowed Commands: Same as above.

Request:

const plateId = "[id]";
const apiKey = "your-api-key";
const baseUrl = "[base-url]";

const response = await fetch(`${baseUrl}/$[id]/lists/mylist/command`, {
  method: "POST",
  headers: {
    "Authorization": apiKey,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    command: "LLEN"
  })
});

const data = await response.json();
console.log(data);

Lists API

On this page