{ "openapi": "3.0.3", "info": { "title": "Pattlist Public API", "version": "1.0.0", "description": "Read-only HTTP API for Pattlist integrators. Authenticate with a Plus API key (`plt_live_…`). Each endpoint requires a specific scope on the key." }, "tags": [ { "name": "Lists", "description": "Shopping lists the caller can access." }, { "name": "Items", "description": "Items on a list." }, { "name": "Members", "description": "People who share a list." }, { "name": "Invites", "description": "Pending invitations to join a list." }, { "name": "Attachments", "description": "Photos attached to list items." } ], "servers": [ { "url": "https://api.pattlist.com", "description": "Production API" } ], "x-rateLimit": { "policy": "Fair-use limits may apply; not enforced at initial launch.", "suggested": "60 requests per minute per API key" }, "components": { "securitySchemes": { "bearerApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "API key", "description": "Pattlist Plus API key issued from the mobile app. Send as `Authorization: Bearer plt_live__`." } }, "schemas": { "PublicList": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "icon": { "type": "string" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp with timezone offset", "example": "2026-01-15T10:30:00.000Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp with timezone offset", "example": "2026-01-15T10:30:00.000Z" } }, "required": [ "id", "name", "icon", "createdAt", "updatedAt" ] }, "ApiError": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] }, "PublicListItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "listId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "markerKey": { "type": "string", "nullable": true, "description": "Optional item marker wire key: `lucide:{IconName}` or `brand:{retailerId}` (retailer id from company markers catalog).", "example": "lucide:Tag" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp with timezone offset", "example": "2026-01-15T10:30:00.000Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp with timezone offset", "example": "2026-01-15T10:30:00.000Z" }, "boughtAt": { "type": "string", "nullable": true, "description": "ISO 8601 timestamp with timezone offset", "example": "2026-01-15T10:30:00.000Z" } }, "required": [ "id", "listId", "name", "markerKey", "createdAt", "updatedAt", "boughtAt" ] }, "PublicListMember": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "listId": { "type": "string", "format": "uuid" }, "userId": { "type": "string" }, "role": { "type": "string" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp with timezone offset", "example": "2026-01-15T10:30:00.000Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp with timezone offset", "example": "2026-01-15T10:30:00.000Z" } }, "required": [ "id", "listId", "userId", "role", "createdAt", "updatedAt" ] }, "PublicListInvite": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "listId": { "type": "string", "format": "uuid" }, "inviteeUserId": { "type": "string" }, "inviterUserId": { "type": "string" }, "role": { "type": "string" }, "status": { "type": "string" }, "expiresAt": { "type": "string", "description": "ISO 8601 timestamp with timezone offset", "example": "2026-01-15T10:30:00.000Z" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp with timezone offset", "example": "2026-01-15T10:30:00.000Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp with timezone offset", "example": "2026-01-15T10:30:00.000Z" } }, "required": [ "id", "listId", "inviteeUserId", "inviterUserId", "role", "status", "expiresAt", "createdAt", "updatedAt" ] }, "PublicListItemAttachment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "listItemId": { "type": "string", "format": "uuid" }, "listId": { "type": "string", "format": "uuid" }, "contentType": { "type": "string" }, "byteSize": { "type": "integer" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp with timezone offset", "example": "2026-01-15T10:30:00.000Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp with timezone offset", "example": "2026-01-15T10:30:00.000Z" } }, "required": [ "id", "listItemId", "listId", "contentType", "byteSize", "createdAt", "updatedAt" ] } }, "parameters": {} }, "paths": { "/v1/lists": { "get": { "operationId": "listLists", "tags": [ "Lists" ], "summary": "List accessible lists", "description": "Returns all lists the authenticated user can access.", "security": [ { "bearerApiKey": [] } ], "x-required-scope": "lists:read", "x-rateLimit": { "policy": "Fair-use limits may apply; not enforced at initial launch.", "suggested": "60 requests per minute per API key" }, "responses": { "200": { "description": "Lists visible to the caller", "content": { "application/json": { "schema": { "type": "object", "properties": { "lists": { "type": "array", "items": { "$ref": "#/components/schemas/PublicList" } } }, "required": [ "lists" ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden (insufficient scope, Plus required, or list permission)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "List or resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Invalid path or query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/lists/{listId}": { "get": { "operationId": "getList", "tags": [ "Lists" ], "summary": "Get a list", "description": "Returns a single list when the caller is an active member.", "security": [ { "bearerApiKey": [] } ], "x-required-scope": "lists:read", "x-rateLimit": { "policy": "Fair-use limits may apply; not enforced at initial launch.", "suggested": "60 requests per minute per API key" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "listId", "in": "path" } ], "responses": { "200": { "description": "List details", "content": { "application/json": { "schema": { "type": "object", "properties": { "list": { "$ref": "#/components/schemas/PublicList" } }, "required": [ "list" ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden (insufficient scope, Plus required, or list permission)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "List or resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Invalid path or query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/lists/{listId}/items": { "get": { "operationId": "listListItems", "tags": [ "Items" ], "summary": "List items on a list", "description": "Returns items for a list. Use `visibility` to include bought items or restrict to unbought only.", "security": [ { "bearerApiKey": [] } ], "x-required-scope": "items:read", "x-rateLimit": { "policy": "Fair-use limits may apply; not enforced at initial launch.", "suggested": "60 requests per minute per API key" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "listId", "in": "path" }, { "schema": { "type": "string", "enum": [ "active", "bought", "unbought" ], "default": "active", "description": "Filter items by bought state. `active` (default): all non-deleted items; `bought`: purchased only; `unbought`: not yet purchased." }, "required": false, "name": "visibility", "in": "query" } ], "responses": { "200": { "description": "List items", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PublicListItem" } } }, "required": [ "items" ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden (insufficient scope, Plus required, or list permission)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "List or resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Invalid path or query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/lists/{listId}/members": { "get": { "operationId": "listListMembers", "tags": [ "Members" ], "summary": "List members", "description": "Returns active memberships for a list.", "security": [ { "bearerApiKey": [] } ], "x-required-scope": "memberships:read", "x-rateLimit": { "policy": "Fair-use limits may apply; not enforced at initial launch.", "suggested": "60 requests per minute per API key" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "listId", "in": "path" } ], "responses": { "200": { "description": "List members", "content": { "application/json": { "schema": { "type": "object", "properties": { "members": { "type": "array", "items": { "$ref": "#/components/schemas/PublicListMember" } } }, "required": [ "members" ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden (insufficient scope, Plus required, or list permission)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "List or resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Invalid path or query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/lists/{listId}/invites": { "get": { "operationId": "listListInvites", "tags": [ "Invites" ], "summary": "List pending invites", "description": "Returns pending invites for a list. Requires owner or admin role; members receive 403.", "security": [ { "bearerApiKey": [] } ], "x-required-scope": "invites:read", "x-rateLimit": { "policy": "Fair-use limits may apply; not enforced at initial launch.", "suggested": "60 requests per minute per API key" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "listId", "in": "path" } ], "responses": { "200": { "description": "Pending invites", "content": { "application/json": { "schema": { "type": "object", "properties": { "invites": { "type": "array", "items": { "$ref": "#/components/schemas/PublicListInvite" } } }, "required": [ "invites" ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden (insufficient scope, Plus required, or list permission)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "List or resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Invalid path or query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/lists/{listId}/items/{itemId}/attachments": { "get": { "operationId": "listItemAttachments", "tags": [ "Attachments" ], "summary": "List item photo attachments", "description": "Returns ready photo attachments for a list item. Requires `attachments:read` (not included in `items:read`).", "security": [ { "bearerApiKey": [] } ], "x-required-scope": "attachments:read", "x-rateLimit": { "policy": "Fair-use limits may apply; not enforced at initial launch.", "suggested": "60 requests per minute per API key" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "listId", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "itemId", "in": "path" } ], "responses": { "200": { "description": "Item attachments", "content": { "application/json": { "schema": { "type": "object", "properties": { "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/PublicListItemAttachment" } } }, "required": [ "attachments" ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden (insufficient scope, Plus required, or list permission)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "List or resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Invalid path or query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/lists/{listId}/items/{itemId}/attachments/{attachmentId}/download-url": { "get": { "operationId": "getAttachmentDownloadUrl", "tags": [ "Attachments" ], "summary": "Attachment download URL", "description": "Returns a short-lived URL to download attachment bytes.", "security": [ { "bearerApiKey": [] } ], "x-required-scope": "attachments:read", "x-rateLimit": { "policy": "Fair-use limits may apply; not enforced at initial launch.", "suggested": "60 requests per minute per API key" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "listId", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "itemId", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "attachmentId", "in": "path" } ], "responses": { "200": { "description": "Presigned download URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "downloadUrl": { "type": "string", "format": "uri" }, "expiresAt": { "type": "string", "description": "ISO 8601 timestamp with timezone offset", "example": "2026-01-15T10:30:00.000Z" } }, "required": [ "downloadUrl", "expiresAt" ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden (insufficient scope, Plus required, or list permission)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "List or resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Invalid path or query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } } } }