{
  "openapi": "3.1.0",
  "info": {
    "title": "Twentybaan API",
    "version": "v1",
    "description": "The Twentybaan API lets you connect your account to internal tools, CRMs, and automation platforms like Zapier and Make.com."
  },
  "servers": [
    {
      "url": "https://api.twentybaan.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "token"
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": ["ok", "error"],
        "properties": {
          "ok": { "const": false },
          "error": { "type": "string" }
        },
        "examples": [{ "ok": false, "error": "Unauthorized" }]
      },
      "CursorPage": {
        "type": "object",
        "additionalProperties": false,
        "required": ["ok"],
        "properties": {
          "ok": { "const": true },
          "next_before_id": { "type": ["integer", "null"] }
        }
      },
      "Me": {
        "type": "object",
        "additionalProperties": true,
        "required": ["id", "email", "name", "is_admin", "is_lister", "plan"],
        "properties": {
          "id": { "type": "integer" },
          "email": { "type": "string" },
          "name": { "type": "string" },
          "is_admin": { "type": "boolean" },
          "is_lister": { "type": "boolean" },
          "plan": { "type": ["string", "null"] }
        }
      },
      "MeResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": ["ok", "me"],
        "properties": {
          "ok": { "const": true },
          "me": { "$ref": "#/components/schemas/Me" }
        }
      },
      "Listing": {
        "type": "object",
        "additionalProperties": true,
        "required": ["id", "status", "slug", "title", "city", "area", "offer_type", "created_at", "updated_at"],
        "properties": {
          "id": { "type": "integer" },
          "status": { "type": "string" },
          "slug": { "type": ["string", "null"] },
          "title": { "type": ["string", "null"] },
          "city": { "type": ["string", "null"] },
          "area": { "type": ["string", "null"] },
          "offer_type": { "type": ["string", "null"] },
          "image_url": { "type": ["string", "null"] },
          "published_at": { "type": ["string", "null"] },
          "created_at": { "type": "string" },
          "updated_at": { "type": "string" }
        }
      },
      "ListingsListResponse": {
        "allOf": [
          { "$ref": "#/components/schemas/CursorPage" },
          {
            "type": "object",
            "additionalProperties": false,
            "required": ["items"],
            "properties": {
              "items": {
                "type": "array",
                "items": { "$ref": "#/components/schemas/Listing" }
              }
            }
          }
        ]
      },
      "ListingGetResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": ["ok", "listing"],
        "properties": {
          "ok": { "const": true },
          "listing": { "$ref": "#/components/schemas/Listing" }
        }
      },
      "SavedList": {
        "type": "object",
        "additionalProperties": false,
        "required": ["id", "name", "is_default", "created_at", "items_count"],
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" },
          "is_default": { "type": "boolean" },
          "created_at": { "type": "string" },
          "items_count": { "type": "integer" }
        }
      },
      "SavedListsListResponse": {
        "allOf": [
          { "$ref": "#/components/schemas/CursorPage" },
          {
            "type": "object",
            "additionalProperties": false,
            "required": ["items"],
            "properties": {
              "items": {
                "type": "array",
                "items": { "$ref": "#/components/schemas/SavedList" }
              }
            }
          }
        ]
      },
      "SavedListGetResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": ["ok", "saved_list"],
        "properties": {
          "ok": { "const": true },
          "saved_list": { "$ref": "#/components/schemas/SavedList" }
        }
      },
      "SavedListItem": {
        "type": "object",
        "additionalProperties": false,
        "required": ["id", "list_id", "spot_url", "created_at"],
        "properties": {
          "id": { "type": "integer" },
          "list_id": { "type": "integer" },
          "spot_url": { "type": "string" },
          "title": { "type": ["string", "null"] },
          "location": { "type": ["string", "null"] },
          "price_text": { "type": ["string", "null"] },
          "beds_text": { "type": ["string", "null"] },
          "area_sqm": { "type": ["integer", "null"] },
          "image_url": { "type": ["string", "null"] },
          "created_at": { "type": "string" }
        }
      },
      "SavedListItemsListResponse": {
        "allOf": [
          { "$ref": "#/components/schemas/CursorPage" },
          {
            "type": "object",
            "additionalProperties": false,
            "required": ["items"],
            "properties": {
              "items": {
                "type": "array",
                "items": { "$ref": "#/components/schemas/SavedListItem" }
              }
            }
          }
        ]
      },
      "SavedListItemGetResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": ["ok", "item"],
        "properties": {
          "ok": { "const": true },
          "item": { "$ref": "#/components/schemas/SavedListItem" }
        }
      },
      "ContactMessage": {
        "type": "object",
        "additionalProperties": true,
        "required": ["id", "created_at"],
        "properties": {
          "id": { "type": "integer" },
          "topic": { "type": ["string", "null"] },
          "spot_name": { "type": ["string", "null"] },
          "spot_slug": { "type": ["string", "null"] },
          "from_url": { "type": ["string", "null"] },
          "name": { "type": ["string", "null"] },
          "email": { "type": ["string", "null"] },
          "phone": { "type": ["string", "null"] },
          "created_at": { "type": "string" }
        }
      },
      "ContactMessagesListResponse": {
        "allOf": [
          { "$ref": "#/components/schemas/CursorPage" },
          {
            "type": "object",
            "additionalProperties": false,
            "required": ["items"],
            "properties": {
              "items": {
                "type": "array",
                "items": { "$ref": "#/components/schemas/ContactMessage" }
              }
            }
          }
        ]
      },
      "ContactMessageGetResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": ["ok", "contact_message"],
        "properties": {
          "ok": { "const": true },
          "contact_message": { "$ref": "#/components/schemas/ContactMessage" }
        }
      },
      "Contract": {
        "type": "object",
        "additionalProperties": true,
        "required": ["id", "kind", "status", "created_at", "updated_at"],
        "properties": {
          "id": { "type": "integer" },
          "listing_id": { "type": ["integer", "null"] },
          "unit_id": { "type": ["integer", "null"] },
          "kind": { "type": "string" },
          "status": { "type": "string" },
          "created_at": { "type": "string" },
          "updated_at": { "type": "string" }
        }
      },
      "ContractsListResponse": {
        "allOf": [
          { "$ref": "#/components/schemas/CursorPage" },
          {
            "type": "object",
            "additionalProperties": false,
            "required": ["items"],
            "properties": {
              "items": {
                "type": "array",
                "items": { "$ref": "#/components/schemas/Contract" }
              }
            }
          }
        ]
      },
      "ContractGetResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": ["ok", "contract"],
        "properties": {
          "ok": { "const": true },
          "contract": { "$ref": "#/components/schemas/Contract" }
        }
      },
      "ApiKey": {
        "type": "object",
        "additionalProperties": false,
        "required": ["id", "name", "scopes", "created_at"],
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" },
          "scopes": { "type": "array", "items": { "type": "string" } },
          "created_at": { "type": "string" },
          "last_used_at": { "type": ["string", "null"] },
          "revoked_at": { "type": ["string", "null"] }
        }
      },
      "ApiKeysListResponse": {
        "allOf": [
          { "$ref": "#/components/schemas/CursorPage" },
          {
            "type": "object",
            "additionalProperties": false,
            "required": ["items"],
            "properties": {
              "items": {
                "type": "array",
                "items": { "$ref": "#/components/schemas/ApiKey" }
              }
            }
          }
        ]
      },
      "ApiKeyGetResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": ["ok", "api_key"],
        "properties": {
          "ok": { "const": true },
          "api_key": { "$ref": "#/components/schemas/ApiKey" }
        }
      },
      "WebhookEndpoint": {
        "type": "object",
        "additionalProperties": true,
        "required": ["id", "url", "events", "status", "created_at", "updated_at"],
        "properties": {
          "id": { "type": "integer" },
          "url": { "type": "string" },
          "events": { "type": "array", "items": { "type": "string" } },
          "status": { "type": "string" },
          "created_at": { "type": "string" },
          "updated_at": { "type": "string" }
        }
      },
      "WebhookEndpointsListResponse": {
        "allOf": [
          { "$ref": "#/components/schemas/CursorPage" },
          {
            "type": "object",
            "additionalProperties": false,
            "required": ["items"],
            "properties": {
              "items": {
                "type": "array",
                "items": { "$ref": "#/components/schemas/WebhookEndpoint" }
              }
            }
          }
        ]
      },
      "WebhookEndpointGetResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": ["ok", "endpoint"],
        "properties": {
          "ok": { "const": true },
          "endpoint": { "$ref": "#/components/schemas/WebhookEndpoint" }
        }
      },
      "WebhookDelivery": {
        "type": "object",
        "additionalProperties": true,
        "required": ["id", "endpoint_id", "delivery_id", "event", "attempts", "status"],
        "properties": {
          "id": { "type": "integer" },
          "endpoint_id": { "type": "integer" },
          "delivery_id": { "type": "string" },
          "event": { "type": "string" },
          "attempts": { "type": "integer" },
          "next_attempt_at": { "type": ["integer", "null"] },
          "status": { "type": "string" },
          "last_http_status": { "type": ["integer", "null"] },
          "last_error": { "type": ["string", "null"] },
          "created_at": { "type": ["integer", "null"] },
          "created_at_iso": { "type": ["string", "null"] },
          "sent_at": { "type": ["integer", "null"] },
          "sent_at_iso": { "type": ["string", "null"] }
        }
      },
      "WebhookDeliveriesListResponse": {
        "allOf": [
          { "$ref": "#/components/schemas/CursorPage" },
          {
            "type": "object",
            "additionalProperties": false,
            "required": ["items"],
            "properties": {
              "items": {
                "type": "array",
                "items": { "$ref": "#/components/schemas/WebhookDelivery" }
              }
            }
          }
        ]
      },
      "WebhookDeliveryGetResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": ["ok", "delivery"],
        "properties": {
          "ok": { "const": true },
          "delivery": { "$ref": "#/components/schemas/WebhookDelivery" }
        }
      },
      "WebhookEventsResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": ["ok", "events"],
        "properties": {
          "ok": { "const": true },
          "events": { "type": "array", "items": { "type": "string" } }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Me",
      "description": "Fetch the current authenticated user.",
      "x-docs": { "key": "me", "group": "Resources", "path": "/me/", "tag": "GET", "order": 10 }
    },
    {
      "name": "Listings",
      "description": "List listings or fetch a listing by id.",
      "x-docs": { "key": "listings", "group": "Resources", "path": "/listings/", "tag": "GET", "order": 20 }
    },
    {
      "name": "Contact messages",
      "description": "List contact messages or fetch by id.",
      "x-docs": { "key": "contact_messages", "group": "Resources", "path": "/contact-messages/", "tag": "GET", "order": 30 }
    },
    {
      "name": "Contracts",
      "description": "List contracts or fetch by id.",
      "x-docs": { "key": "contracts", "group": "Resources", "path": "/contracts/", "tag": "GET", "order": 40 }
    },
    {
      "name": "Saved lists",
      "description": "List saved lists or fetch a list by id.",
      "x-docs": { "key": "saved_lists", "group": "Resources", "path": "/saved-lists/", "tag": "GET", "order": 50 }
    },
    {
      "name": "Saved list items",
      "description": "List items in a saved list or fetch by id.",
      "x-docs": { "key": "saved_list_items", "group": "Resources", "path": "/saved-list-items/", "tag": "GET", "order": 60 }
    },
    {
      "name": "API keys",
      "description": "List API keys (metadata only).",
      "x-docs": { "key": "api_keys", "group": "Resources", "path": "/api-keys/", "tag": "GET", "order": 70 }
    },
    {
      "name": "Webhook endpoints",
      "description": "List webhook endpoints and event filters.",
      "x-docs": { "key": "webhook_endpoints", "group": "Resources", "path": "/webhook-endpoints/", "tag": "GET", "order": 80 }
    },
    {
      "name": "Webhook deliveries",
      "description": "Inspect webhook delivery attempts.",
      "x-docs": { "key": "webhook_deliveries", "group": "Resources", "path": "/webhook-deliveries/", "tag": "GET", "order": 90 }
    },
    {
      "name": "Webhook events",
      "description": "List supported webhook event names.",
      "x-docs": { "key": "webhook_events", "group": "Resources", "path": "/webhook-events/", "tag": "GET", "order": 100 }
    }
  ],
  "paths": {
    "/v1/me/": {
      "get": {
        "tags": ["Me"],
        "summary": "Fetch the current authenticated user.",
        "operationId": "getMe",
        "x-scopes": ["read:me"],
        "responses": {
          "200": {
            "description": "OK",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeResponse" } } }
          },
          "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
        }
      }
    },
    "/v1/listings/": {
      "get": {
        "tags": ["Listings"],
        "summary": "List listings or retrieve a listing by id.",
        "operationId": "getListings",
        "x-scopes": ["read:listings"],
        "parameters": [
          { "name": "id", "in": "query", "schema": { "type": "integer" }, "description": "Retrieve a single listing by id." },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "Limit the number of items returned." },
          { "name": "before_id", "in": "query", "schema": { "type": "integer" }, "description": "Cursor pagination. Return items with id less than this value." }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    { "$ref": "#/components/schemas/ListingsListResponse" },
                    { "$ref": "#/components/schemas/ListingGetResponse" }
                  ]
                }
              }
            }
          },
          "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
        }
      }
    },
    "/v1/contact-messages/": {
      "get": {
        "tags": ["Contact messages"],
        "summary": "List contact messages or retrieve a message by id.",
        "operationId": "getContactMessages",
        "x-scopes": ["read:contact_messages"],
        "parameters": [
          { "name": "id", "in": "query", "schema": { "type": "integer" }, "description": "Retrieve a single contact message by id." },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "Limit the number of items returned." },
          { "name": "before_id", "in": "query", "schema": { "type": "integer" }, "description": "Cursor pagination. Return items with id less than this value." }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    { "$ref": "#/components/schemas/ContactMessagesListResponse" },
                    { "$ref": "#/components/schemas/ContactMessageGetResponse" }
                  ]
                }
              }
            }
          },
          "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
        }
      }
    },
    "/v1/contracts/": {
      "get": {
        "tags": ["Contracts"],
        "summary": "List contracts or retrieve a contract by id.",
        "operationId": "getContracts",
        "x-scopes": ["read:contracts"],
        "parameters": [
          { "name": "id", "in": "query", "schema": { "type": "integer" }, "description": "Retrieve a single contract by id." },
          { "name": "include_data", "in": "query", "schema": { "type": "integer", "enum": [0, 1] }, "description": "When set to 1, include the contract data blob (if available)." },
          { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Filter by contract status." },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "Limit the number of items returned." },
          { "name": "before_id", "in": "query", "schema": { "type": "integer" }, "description": "Cursor pagination. Return items with id less than this value." }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    { "$ref": "#/components/schemas/ContractsListResponse" },
                    { "$ref": "#/components/schemas/ContractGetResponse" }
                  ]
                }
              }
            }
          },
          "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
        }
      }
    },
    "/v1/api-keys/": {
      "get": {
        "tags": ["API keys"],
        "summary": "List API keys (metadata) or retrieve an API key by id.",
        "operationId": "getApiKeys",
        "x-scopes": ["read:api_keys"],
        "parameters": [
          { "name": "id", "in": "query", "schema": { "type": "integer" }, "description": "Retrieve a single API key by id." },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "Limit the number of items returned." },
          { "name": "before_id", "in": "query", "schema": { "type": "integer" }, "description": "Cursor pagination. Return items with id less than this value." }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    { "$ref": "#/components/schemas/ApiKeysListResponse" },
                    { "$ref": "#/components/schemas/ApiKeyGetResponse" }
                  ]
                }
              }
            }
          },
          "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
        }
      }
    },
    "/v1/webhook-endpoints/": {
      "get": {
        "tags": ["Webhook endpoints"],
        "summary": "List webhook endpoints or retrieve an endpoint by id.",
        "operationId": "getWebhookEndpoints",
        "x-scopes": ["webhooks:manage"],
        "parameters": [
          { "name": "id", "in": "query", "schema": { "type": "integer" }, "description": "Retrieve a single webhook endpoint by id." },
          { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Filter by endpoint status." },
          { "name": "source", "in": "query", "schema": { "type": "string" }, "description": "Filter by source." },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "Limit the number of items returned." },
          { "name": "before_id", "in": "query", "schema": { "type": "integer" }, "description": "Cursor pagination. Return items with id less than this value." }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    { "$ref": "#/components/schemas/WebhookEndpointsListResponse" },
                    { "$ref": "#/components/schemas/WebhookEndpointGetResponse" }
                  ]
                }
              }
            }
          },
          "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
        }
      }
    },
    "/v1/webhook-deliveries/": {
      "get": {
        "tags": ["Webhook deliveries"],
        "summary": "List webhook deliveries or retrieve a delivery by id.",
        "operationId": "getWebhookDeliveries",
        "x-scopes": ["webhooks:manage"],
        "parameters": [
          { "name": "id", "in": "query", "schema": { "type": "integer" }, "description": "Retrieve a single delivery by id." },
          { "name": "endpoint_id", "in": "query", "schema": { "type": "integer" }, "description": "Filter by webhook endpoint id." },
          { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Filter by delivery status." },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "Limit the number of items returned." },
          { "name": "before_id", "in": "query", "schema": { "type": "integer" }, "description": "Cursor pagination. Return items with id less than this value." }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    { "$ref": "#/components/schemas/WebhookDeliveriesListResponse" },
                    { "$ref": "#/components/schemas/WebhookDeliveryGetResponse" }
                  ]
                }
              }
            }
          },
          "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
        }
      }
    },
    "/v1/webhook-events/": {
      "get": {
        "tags": ["Webhook events"],
        "summary": "List supported webhook event names.",
        "operationId": "getWebhookEvents",
        "x-scopes": ["webhooks:manage"],
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventsResponse" } } } },
          "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
        }
      }
    },
    "/v1/saved-lists/": {
      "get": {
        "tags": ["Saved lists"],
        "summary": "List saved lists or retrieve a saved list by id.",
        "operationId": "getSavedLists",
        "x-scopes": ["read:saved_lists"],
        "parameters": [
          { "name": "id", "in": "query", "schema": { "type": "integer" }, "description": "Retrieve a single saved list by id." },
          { "name": "include_items", "in": "query", "schema": { "type": "integer", "enum": [0, 1] }, "description": "When set to 1, include items in the response (requires read:saved_list_items)." },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "Limit the number of lists (or items when include_items=1)." },
          { "name": "before_id", "in": "query", "schema": { "type": "integer" }, "description": "Cursor pagination. Return lists/items with id less than this value." }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    { "$ref": "#/components/schemas/SavedListsListResponse" },
                    { "$ref": "#/components/schemas/SavedListGetResponse" }
                  ]
                }
              }
            }
          },
          "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
        }
      }
    },
    "/v1/saved-list-items/": {
      "get": {
        "tags": ["Saved list items"],
        "summary": "List saved list items or retrieve a saved list item by id.",
        "operationId": "getSavedListItems",
        "x-scopes": ["read:saved_list_items"],
        "parameters": [
          { "name": "list_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Saved list id." },
          { "name": "id", "in": "query", "schema": { "type": "integer" }, "description": "Retrieve a single item by id." },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "Limit the number of items returned." },
          { "name": "before_id", "in": "query", "schema": { "type": "integer" }, "description": "Cursor pagination. Return items with id less than this value." }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    { "$ref": "#/components/schemas/SavedListItemsListResponse" },
                    { "$ref": "#/components/schemas/SavedListItemGetResponse" }
                  ]
                }
              }
            }
          },
          "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
        }
      }
    }
  }
}
