Saved lists

Saved lists help you group spots you want to revisit. A spot can be in one list or many.

The saved list model

Saved lists contain user-defined groups (including a default list). The API exposes list metadata and counts so you can sync to spreadsheets or CRMs.

Properties

Name
id
Type
integer
Description
Unique identifier for the saved list.
Name
name
Type
string
Description
Display name of the list.
Name
is_default
Type
boolean
Description
Whether this is the default list.
Name
created_at
Type
timestamp
Description
Timestamp of when the list was created.
Name
items_count
Type
integer
Description
Number of saved items in the list.

GET/v1/saved-lists/

List saved lists

Retrieve saved lists for the authenticated user. Lists are typically few, but the API still supports cursor pagination.

Optional attributes

Name
limit
Type
integer
Description
Limit the number of lists returned (default 50, max 200).
Name
before_id
Type
integer
Description
Return lists with id less than this value.

Required scope

Tokens must include read:saved_lists (OAuth tokens and API keys).

Request

GET

/v1/saved-lists/

curl -G https://api.twentybaan.com/v1/saved-lists/ \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d limit=10

GET

/v1/saved-lists/

const token = process.env.TWENTYBAAN_API_KEY;

const url = new URL("https://api.twentybaan.com/v1/saved-lists/");
url.searchParams.set("limit", "10");

const res = await fetch(url.toString(), {
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
  },
});

if (!res.ok) throw new Error(`HTTP ${res.status}`);
console.log(await res.json());

GET

/v1/saved-lists/

type TwentybaanSavedList = {
  id: number;
  name: string;
  is_default: boolean;
  created_at: string;
  items_count: number;
};

type TwentybaanSavedListsResponse =
  | { ok: true; items: TwentybaanSavedList[]; next_before_id: number | null }
  | { ok: false; error: string };

const token = process.env.TWENTYBAAN_API_KEY!;

const url = new URL("https://api.twentybaan.com/v1/saved-lists/");
url.searchParams.set("limit", "10");

const res = await fetch(url.toString(), {
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
  },
});

const data = (await res.json()) as TwentybaanSavedListsResponse;
if (!res.ok || !data.ok) throw new Error("Request failed");

console.log(data.items);

GET

/v1/saved-lists/

import os
import requests

token = os.environ["TWENTYBAAN_API_KEY"]

res = requests.get(
  "https://api.twentybaan.com/v1/saved-lists/",
  headers={
    "Accept": "application/json",
    "Authorization": f"Bearer {token}",
  },
  params={"limit": 10},
  timeout=30,
)
res.raise_for_status()
print(res.json())

GET

/v1/saved-lists/

<?php

$token = getenv('TWENTYBAAN_API_KEY') ?: '';

$url = "https://api.twentybaan.com/v1/saved-lists/" . '?' . http_build_query(['limit' => 10]);

$ch = curl_init($url);
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Accept: application/json",
    "Authorization: Bearer " . $token,
  ],
]);

$body = curl_exec($ch);
$status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo "HTTP {$status}\n";
echo $body;

GET

/v1/saved-lists/

using System;
using System.Net.Http;
using System.Net.Http.Headers;

var token = Environment.GetEnvironmentVariable("TWENTYBAAN_API_KEY") ?? "";
var url = "https://api.twentybaan.com/v1/saved-lists/?limit=10";

using var client = new HttpClient();
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

var res = await client.GetAsync(url);
var body = await res.Content.ReadAsStringAsync();

Console.WriteLine((int)res.StatusCode);
Console.WriteLine(body);

GET

/v1/saved-lists/

require "net/http"
require "json"

token = ENV.fetch("TWENTYBAAN_API_KEY")
uri = URI("https://api.twentybaan.com/v1/saved-lists/")
uri.query = URI.encode_www_form({ limit: 10 })

req = Net::HTTP::Get.new(uri)
req["Accept"] = "application/json"
req["Authorization"] = "Bearer #{token}"

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(req)
end

puts res.code
puts res.body

GET

/v1/saved-lists/

package main

import (
  "fmt"
  "io"
  "net/http"
  "net/url"
  "os"
  "time"
)

func main() {
  token := os.Getenv("TWENTYBAAN_API_KEY")

  u, err := url.Parse("https://api.twentybaan.com/v1/saved-lists/")
  if err != nil {
    panic(err)
  }

  q := u.Query()
  q.Set("limit", "10")
  u.RawQuery = q.Encode()

  req, err := http.NewRequest("GET", u.String(), nil)
  if err != nil {
    panic(err)
  }

  req.Header.Set("Accept", "application/json")
  req.Header.Set("Authorization", "Bearer "+token)

  client := &http.Client{Timeout: 30 * time.Second}
  res, err := client.Do(req)
  if err != nil {
    panic(err)
  }
  defer res.Body.Close()

  body, _ := io.ReadAll(res.Body)
  fmt.Println(res.Status)
  fmt.Println(string(body))
}

Response

{
  "ok": true,
  "items": [
    {
      "id": 12,
      "name": "Saved listings",
      "is_default": true,
      "created_at": "2026-01-01T12:34:56Z",
      "items_count": 4
    }
  ],
  "next_before_id": null
}

GET/v1/saved-lists?id=:id

Retrieve a saved list

Fetch a single saved list by id.

Required attributes

Name
id
Type
integer
Description
The saved list id to retrieve.

Optional attributes

Name
include_items
Type
boolean
Description
When set to 1, embed saved list items in the response (also requires read:saved_list_items).

Required scope

Tokens must include read:saved_lists.

Request

GET

/v1/saved-lists?id=123

curl -G https://api.twentybaan.com/v1/saved-lists/ \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d id=123

GET

/v1/saved-lists?id=123

const token = process.env.TWENTYBAAN_API_KEY;

const url = new URL("https://api.twentybaan.com/v1/saved-lists/");
url.searchParams.set("id", "123");

const res = await fetch(url.toString(), {
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
  },
});

if (!res.ok) throw new Error(`HTTP ${res.status}`);
console.log(await res.json());

GET

/v1/saved-lists?id=123

type TwentybaanSavedList = {
  id: number;
  name: string;
  is_default: boolean;
  created_at: string;
  items_count: number;
};

type TwentybaanSavedListResponse =
  | { ok: true; saved_list: TwentybaanSavedList }
  | { ok: false; error: string };

const token = process.env.TWENTYBAAN_API_KEY!;

const url = new URL("https://api.twentybaan.com/v1/saved-lists/");
url.searchParams.set("id", "123");

const res = await fetch(url.toString(), {
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
  },
});

const data = (await res.json()) as TwentybaanSavedListResponse;
if (!res.ok || !data.ok) throw new Error("Request failed");

console.log(data.saved_list);

GET

/v1/saved-lists?id=123

import os
import requests

token = os.environ["TWENTYBAAN_API_KEY"]

res = requests.get(
  "https://api.twentybaan.com/v1/saved-lists/",
  headers={
    "Accept": "application/json",
    "Authorization": f"Bearer {token}",
  },
  params={"id": 123},
  timeout=30,
)
res.raise_for_status()
print(res.json())

GET

/v1/saved-lists?id=123

<?php

$token = getenv('TWENTYBAAN_API_KEY') ?: '';

$url = "https://api.twentybaan.com/v1/saved-lists/" . '?' . http_build_query(['id' => 123]);

$ch = curl_init($url);
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Accept: application/json",
    "Authorization: Bearer " . $token,
  ],
]);

$body = curl_exec($ch);
$status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo "HTTP {$status}\n";
echo $body;

GET

/v1/saved-lists?id=123

using System;
using System.Net.Http;
using System.Net.Http.Headers;

var token = Environment.GetEnvironmentVariable("TWENTYBAAN_API_KEY") ?? "";
var url = "https://api.twentybaan.com/v1/saved-lists/?id=123";

using var client = new HttpClient();
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

var res = await client.GetAsync(url);
var body = await res.Content.ReadAsStringAsync();

Console.WriteLine((int)res.StatusCode);
Console.WriteLine(body);

GET

/v1/saved-lists?id=123

require "net/http"
require "json"

token = ENV.fetch("TWENTYBAAN_API_KEY")
uri = URI("https://api.twentybaan.com/v1/saved-lists/")
uri.query = URI.encode_www_form({ id: 123 })

req = Net::HTTP::Get.new(uri)
req["Accept"] = "application/json"
req["Authorization"] = "Bearer #{token}"

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(req)
end

puts res.code
puts res.body

GET

/v1/saved-lists?id=123

package main

import (
  "fmt"
  "io"
  "net/http"
  "net/url"
  "os"
  "time"
)

func main() {
  token := os.Getenv("TWENTYBAAN_API_KEY")

  u, err := url.Parse("https://api.twentybaan.com/v1/saved-lists/")
  if err != nil {
    panic(err)
  }

  q := u.Query()
  q.Set("id", "123")
  u.RawQuery = q.Encode()

  req, err := http.NewRequest("GET", u.String(), nil)
  if err != nil {
    panic(err)
  }

  req.Header.Set("Accept", "application/json")
  req.Header.Set("Authorization", "Bearer "+token)

  client := &http.Client{Timeout: 30 * time.Second}
  res, err := client.Do(req)
  if err != nil {
    panic(err)
  }
  defer res.Body.Close()

  body, _ := io.ReadAll(res.Body)
  fmt.Println(res.Status)
  fmt.Println(string(body))
}

Response

{
  "ok": true,
  "saved_list": {
    "id": 12,
    "name": "Saved listings",
    "is_default": true,
    "created_at": "2026-01-01T12:34:56Z",
    "items_count": 4
  }
}