{ "openapi": "3.1.0", "info": { "title": "ArchFindr integration API", "version": "1.0.0", "description": "Read ArchFindr catalogue and request data from your own systems with a scoped API key. Every endpoint lives under `/api/v1/key`." }, "servers": [ { "url": "https://api.archfindr.com" } ], "tags": [ { "name": "Analytics" }, { "name": "Brands" }, { "name": "Invitations" }, { "name": "Members" }, { "name": "Products" }, { "name": "Requests" }, { "name": "Uploads" }, { "name": "Webhooks" }, { "name": "Whoami" } ], "paths": { "/api/v1/key/analytics": { "get": { "operationId": "key.analytics.show", "tags": [ "Analytics" ], "summary": "Views, requests and top products of the vendor over `range` (`7d`, `30d`, `90d`)", "description": "Views, requests and top products of the vendor over `range` (`7d`, `30d`, `90d`).\n\nRequires the `analytics:read` scope.", "x-required-scope": "analytics:read", "security": [ { "apiKey": [ "analytics:read" ] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "7d" ] } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "granularity", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "day" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object", "properties": { "product": { "type": "object", "properties": { "brand": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "logoUrl": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "slug", "logoUrl" ] }, "compareAtPrice": { "type": [ "number", "null" ] }, "currency": { "type": "string" }, "hasBim": { "type": "boolean" }, "id": { "type": "string" }, "inStock": { "type": "boolean" }, "isNew": { "type": "boolean" }, "name": { "type": "string" }, "price": { "type": [ "number", "null" ] }, "priceOnRequest": { "type": "boolean" }, "slug": { "type": "string" }, "type": { "type": "string" }, "coverUrl": { "type": "string" }, "hoverUrl": { "type": "string" } }, "required": [ "brand", "compareAtPrice", "currency", "hasBim", "id", "inStock", "isNew", "name", "price", "priceOnRequest", "slug", "type", "coverUrl", "hoverUrl" ] }, "requests": { "type": "number" }, "favorites": { "type": "number" }, "downloads": { "type": "number" }, "views": { "type": "number" }, "visitors": { "type": "number" }, "pageViews": { "type": "number" }, "conversion": { "type": "number" } }, "required": [ "product", "requests", "favorites", "downloads", "views", "visitors", "pageViews", "conversion" ] } }, "brands": { "type": "array", "items": { "type": "object", "properties": { "brand": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "logoUrl": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "slug", "logoUrl" ] }, "requests": { "type": "number" }, "favorites": { "type": "number" }, "downloads": { "type": "number" }, "views": { "type": "number" }, "visitors": { "type": "number" }, "pageViews": { "type": "number" }, "conversion": { "type": "number" } }, "required": [ "brand", "requests", "favorites", "downloads", "views", "visitors", "pageViews", "conversion" ] } }, "providers": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "active", "suspended" ] }, "logoUrl": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "slug", "status", "logoUrl" ] }, "requests": { "type": "number" }, "favorites": { "type": "number" }, "downloads": { "type": "number" }, "views": { "type": "number" }, "visitors": { "type": "number" }, "pageViews": { "type": "number" }, "conversion": { "type": "number" } }, "required": [ "provider", "requests", "favorites", "downloads", "views", "visitors", "pageViews", "conversion" ] } }, "designers": { "type": "array", "items": { "type": "object", "properties": { "designer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ] }, "requests": { "type": "number" }, "favorites": { "type": "number" }, "downloads": { "type": "number" }, "views": { "type": "number" }, "visitors": { "type": "number" }, "pageViews": { "type": "number" }, "conversion": { "type": "number" } }, "required": [ "designer", "requests", "favorites", "downloads", "views", "visitors", "pageViews", "conversion" ] } }, "requests": { "type": "object", "properties": { "total": { "type": "number" }, "replied": { "type": "number" }, "resolved": { "type": "number" }, "responseRate": { "type": "number" }, "medianResponseHours": { "type": [ "number", "null" ] }, "byType": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "price", "info", "catalogue", "samples" ] }, "count": { "type": "number" } }, "required": [ "type", "count" ] } }, "byStatus": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "quoted", "closed", "new", "open" ] }, "count": { "type": "number" } }, "required": [ "status", "count" ] } }, "byCountry": { "type": "array", "items": { "type": "object", "properties": { "country": { "type": "string" }, "count": { "type": "number" } }, "required": [ "country", "count" ] } } }, "required": [ "total", "replied", "resolved", "responseRate", "medianResponseHours", "byType", "byStatus", "byCountry" ] }, "catalogue": { "type": "object", "properties": { "products": { "type": "number" }, "published": { "type": "number" }, "pending": { "type": "number" } }, "required": [ "products", "published", "pending" ] }, "period": { "type": "object", "properties": { "range": { "type": "string", "enum": [ "7d", "30d", "90d", "custom" ] }, "from": { "type": "string" }, "to": { "type": "string" }, "granularity": { "type": "string", "enum": [ "day", "week" ] }, "days": { "type": "number" } }, "required": [ "range", "from", "to", "granularity", "days" ] }, "totals": { "type": "object", "properties": { "requests": { "type": "number" }, "favorites": { "type": "number" }, "downloads": { "type": "number" }, "views": { "type": "number" }, "visitors": { "type": "number" }, "pageViews": { "type": "number" }, "conversion": { "type": "number" }, "outbound": { "type": "number" } }, "required": [ "requests", "favorites", "downloads", "views", "visitors", "pageViews", "conversion", "outbound" ] }, "previous": { "type": "object", "properties": { "requests": { "type": "number" }, "favorites": { "type": "number" }, "downloads": { "type": "number" }, "views": { "type": "number" }, "visitors": { "type": "number" }, "pageViews": { "type": "number" }, "conversion": { "type": "number" }, "outbound": { "type": "number" } }, "required": [ "requests", "favorites", "downloads", "views", "visitors", "pageViews", "conversion", "outbound" ] }, "series": { "type": "array", "items": { "type": "object", "properties": { "requests": { "type": "number" }, "favorites": { "type": "number" }, "downloads": { "type": "number" }, "views": { "type": "number" }, "visitors": { "type": "number" }, "pageViews": { "type": "number" }, "date": { "type": "string" } }, "required": [ "requests", "favorites", "downloads", "views", "visitors", "pageViews", "date" ] } }, "previousSeries": { "type": "array", "items": { "type": "object", "properties": { "requests": { "type": "number" }, "favorites": { "type": "number" }, "downloads": { "type": "number" }, "views": { "type": "number" }, "visitors": { "type": "number" }, "pageViews": { "type": "number" }, "date": { "type": "string" } }, "required": [ "requests", "favorites", "downloads", "views", "visitors", "pageViews", "date" ] } }, "sources": { "type": "array", "items": { "type": "object", "properties": { "count": { "type": "number" }, "source": { "type": "string", "enum": [ "social", "search", "internal", "direct", "referral" ] } }, "required": [ "count", "source" ] } }, "countries": { "type": "array", "items": { "type": "object", "properties": { "country": { "type": "string" }, "count": { "type": "number" } }, "required": [ "country", "count" ] } }, "locales": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string" }, "count": { "type": "number" } }, "required": [ "locale", "count" ] } }, "audience": { "type": "array", "items": { "type": "object", "properties": { "count": { "type": "number" }, "profession": { "type": [ "string", "null" ] } }, "required": [ "count", "profession" ] } } }, "required": [ "products", "brands", "providers", "designers", "requests", "catalogue", "period", "totals", "previous", "series", "previousSeries", "sources", "countries", "locales", "audience" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/key/brands": { "get": { "operationId": "key.brands.index", "tags": [ "Brands" ], "summary": "The vendor's brands, searchable with `q`", "description": "The vendor's brands, searchable with `q`.\n\nRequires the `brands:read` scope.", "x-required-scope": "brands:read", "security": [ { "apiKey": [ "brands:read" ] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "perPage", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "active", "suspended" ] }, "logoUrl": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "slug", "status", "logoUrl" ] }, "createdAt": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "isFeatured": { "type": "boolean" }, "name": { "type": "string" }, "slug": { "type": "string" }, "city": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "coverUrl": { "type": [ "string", "null" ] }, "logoUrl": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "productsCount": { "type": "number" } }, "required": [ "provider", "createdAt", "description", "id", "isFeatured", "name", "slug", "city", "country", "coverUrl", "logoUrl", "website", "productsCount" ] } }, "metadata": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of items across all pages." }, "perPage": { "type": "integer", "description": "Items per page." }, "currentPage": { "type": "integer", "description": "The page returned (1-based)." }, "lastPage": { "type": "integer", "description": "The last available page." }, "firstPage": { "type": "integer", "description": "Always 1." }, "firstPageUrl": { "type": "string", "description": "Relative URL of the first page." }, "lastPageUrl": { "type": "string", "description": "Relative URL of the last page." }, "nextPageUrl": { "type": [ "string", "null" ], "description": "Relative URL of the next page, null on the last page." }, "previousPageUrl": { "type": [ "string", "null" ], "description": "Relative URL of the previous page, null on the first." } }, "required": [ "total", "perPage", "currentPage", "lastPage", "firstPage", "firstPageUrl", "lastPageUrl", "nextPageUrl", "previousPageUrl" ] } }, "required": [ "data", "metadata" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/key/brands/{id}": { "get": { "operationId": "key.brands.show", "tags": [ "Brands" ], "summary": "One brand with its translations and links", "description": "One brand with its translations and links.\n\nRequires the `brands:read` scope.", "x-required-scope": "brands:read", "security": [ { "apiKey": [ "brands:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "provider": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "active", "suspended" ] }, "logoUrl": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "slug", "status", "logoUrl" ] }, "createdAt": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "isFeatured": { "type": "boolean" }, "name": { "type": "string" }, "slug": { "type": "string" }, "translations": { "type": "object" }, "city": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "coverUrl": { "type": [ "string", "null" ] }, "logoUrl": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "productsCount": { "type": "number" } }, "required": [ "provider", "createdAt", "description", "id", "isFeatured", "name", "slug", "translations", "city", "country", "coverUrl", "logoUrl", "website", "productsCount" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "operationId": "key.brands.update", "tags": [ "Brands" ], "summary": "Edits one of the vendor's brands", "description": "Edits one of the vendor's brands.\n\nRequires the `brands:write` scope.", "x-required-scope": "brands:write", "security": [ { "apiKey": [ "brands:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "maxLength": 150 }, "logoUrl": { "type": [ "string", "null" ], "maxLength": 1024 }, "coverUrl": { "type": [ "string", "null" ], "maxLength": 1024 }, "country": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "translations": {} }, "required": [] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "provider": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "active", "suspended" ] }, "logoUrl": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "slug", "status", "logoUrl" ] }, "createdAt": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "isFeatured": { "type": "boolean" }, "name": { "type": "string" }, "slug": { "type": "string" }, "translations": { "type": "object" }, "city": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "coverUrl": { "type": [ "string", "null" ] }, "logoUrl": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "productsCount": { "type": "number" } }, "required": [ "provider", "createdAt", "description", "id", "isFeatured", "name", "slug", "translations", "city", "country", "coverUrl", "logoUrl", "website", "productsCount" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/key/invitations": { "get": { "operationId": "key.invitations.index", "tags": [ "Invitations" ], "summary": "The pending team invitations", "description": "The pending team invitations.\n\nRequires the `team:read` scope.", "x-required-scope": "team:read", "security": [ { "apiKey": [ "team:read" ] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "createdAt": { "type": "string" }, "id": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ] }, "invitedBy": { "type": [ "string", "null" ] }, "expiresAt": { "type": "string" } }, "required": [ "createdAt", "id", "email", "role", "invitedBy", "expiresAt" ] } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/key/members": { "get": { "operationId": "key.members.index", "tags": [ "Members" ], "summary": "The workspace members with their roles", "description": "The workspace members with their roles.\n\nRequires the `team:read` scope.", "x-required-scope": "team:read", "security": [ { "apiKey": [ "team:read" ] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "createdAt": { "type": "string" }, "id": { "type": "string" }, "role": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ] }, "user": { "type": "object", "properties": { "createdAt": { "type": "string" }, "id": { "type": "string" }, "country": { "type": [ "string", "null" ] }, "avatarUrl": { "type": [ "string", "null" ] }, "email": { "type": "string" }, "phone": { "type": [ "string", "null" ] }, "profession": { "type": [ "string", "null" ] }, "role": { "type": "string", "enum": [ "customer", "professional", "admin" ] }, "company": { "type": [ "string", "null" ] }, "fullName": { "type": [ "string", "null" ] }, "adminRole": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ] }, "emailVerified": { "type": "boolean" }, "phoneVerified": { "type": "boolean" }, "initials": { "type": "string" } }, "required": [ "createdAt", "id", "country", "avatarUrl", "email", "phone", "profession", "role", "company", "fullName", "adminRole", "emailVerified", "phoneVerified", "initials" ] } }, "required": [ "createdAt", "id", "role", "user" ] } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/key/products": { "get": { "operationId": "key.products.index", "tags": [ "Products" ], "summary": "Products of the vendor's brands, filterable like the dashboard list; a platform key lists every product", "description": "Products of the vendor's brands, filterable like the dashboard list; a platform key lists every product.\n\nRequires the `products:read` scope.", "x-required-scope": "products:read", "security": [ { "apiKey": [ "products:read" ] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "perPage", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft" ] } }, { "name": "brand", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "tags", "in": "query", "required": false, "schema": {} }, { "name": "priceOnRequest", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "inStock", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "brand": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "logoUrl": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "slug", "logoUrl" ] }, "compareAtPrice": { "type": [ "number", "null" ] }, "currency": { "type": "string" }, "hasBim": { "type": "boolean" }, "id": { "type": "string" }, "inStock": { "type": "boolean" }, "isNew": { "type": "boolean" }, "name": { "type": "string" }, "price": { "type": [ "number", "null" ] }, "priceOnRequest": { "type": "boolean" }, "slug": { "type": "string" }, "type": { "type": "string" }, "coverUrl": { "type": "string" }, "hoverUrl": { "type": "string" } }, "required": [ "brand", "compareAtPrice", "currency", "hasBim", "id", "inStock", "isNew", "name", "price", "priceOnRequest", "slug", "type", "coverUrl", "hoverUrl" ] } }, "metadata": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of items across all pages." }, "perPage": { "type": "integer", "description": "Items per page." }, "currentPage": { "type": "integer", "description": "The page returned (1-based)." }, "lastPage": { "type": "integer", "description": "The last available page." }, "firstPage": { "type": "integer", "description": "Always 1." }, "firstPageUrl": { "type": "string", "description": "Relative URL of the first page." }, "lastPageUrl": { "type": "string", "description": "Relative URL of the last page." }, "nextPageUrl": { "type": [ "string", "null" ], "description": "Relative URL of the next page, null on the last page." }, "previousPageUrl": { "type": [ "string", "null" ], "description": "Relative URL of the previous page, null on the first." } }, "required": [ "total", "perPage", "currentPage", "lastPage", "firstPage", "firstPageUrl", "lastPageUrl", "nextPageUrl", "previousPageUrl" ] } }, "required": [ "data", "metadata" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "key.products.store", "tags": [ "Products" ], "summary": "Creates a draft product under one of the vendor's brands", "description": "Creates a draft product under one of the vendor's brands.\n\nRequires the `products:write` scope.", "x-required-scope": "products:write", "security": [ { "apiKey": [ "products:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "brandId": { "type": "string", "format": "uuid" }, "categoryId": { "type": "string", "format": "uuid" }, "description": { "type": [ "string", "null" ] }, "materials": { "type": [ "string", "null" ] }, "collection": { "type": [ "string", "null" ] }, "year": { "type": [ "integer", "null" ], "minimum": 1800, "maximum": 2200 }, "price": { "type": [ "number", "null" ], "minimum": 0, "maximum": 9999999999 }, "compareAtPrice": { "type": [ "number", "null" ], "minimum": 0, "maximum": 9999999999 }, "priceOnRequest": { "type": "boolean" }, "sku": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 64 }, "trackStock": { "type": "boolean" }, "stockQuantity": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000000 }, "sellWhenOutOfStock": { "type": "boolean" }, "leadTimeDays": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 3650 }, "isPhysical": { "type": "boolean" }, "length": { "type": [ "number", "null" ], "maximum": 1000000 }, "width": { "type": [ "number", "null" ], "maximum": 1000000 }, "height": { "type": [ "number", "null" ], "maximum": 1000000 }, "dimensionUnit": { "type": "string", "enum": [ "cm" ] }, "weight": { "type": [ "number", "null" ], "maximum": 1000000 }, "weightUnit": { "type": "string", "enum": [ "kg" ] }, "countryOfOrigin": { "type": [ "string", "null" ] }, "hsCode": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 40 }, "maxLength": 30 }, "currency": { "type": "string" }, "isNew": { "type": "boolean" }, "inStock": { "type": "boolean" }, "finishes": { "type": "array", "items": { "type": "string" } }, "specs": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } }, "required": [ "label", "value" ] } }, "images": { "type": "array", "items": { "type": "string", "maxLength": 1024 } }, "modelUrl": { "type": [ "string", "null" ], "maxLength": 1024 }, "modelIosUrl": { "type": [ "string", "null" ], "maxLength": 1024 }, "modelPosterUrl": { "type": [ "string", "null" ], "maxLength": 1024 }, "modelCredit": { "type": [ "string", "null" ] }, "modelVariants": { "type": "object", "additionalProperties": { "type": "string" } }, "designerId": { "type": [ "string", "null" ], "format": "uuid" }, "translations": {} }, "required": [ "name", "type", "brandId", "categoryId" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "collection": { "type": [ "string", "null" ] }, "brand": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "logoUrl": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "slug", "logoUrl" ] }, "designer": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ] }, "category": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ] }, "images": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "position": { "type": "number" }, "alt": { "type": [ "string", "null" ] }, "url": { "type": "string" } }, "required": [ "id", "position", "alt", "url" ] } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "position": { "type": "number" }, "format": { "type": "string" }, "kind": { "type": "string", "enum": [ "catalogue", "bim", "cad_2d", "model_3d", "datasheet", "certificate", "other" ] }, "label": { "type": [ "string", "null" ] }, "originalName": { "type": "string" }, "size": { "type": "number" } }, "required": [ "id", "position", "format", "kind", "label", "originalName", "size" ] } }, "compareAtPrice": { "type": [ "number", "null" ] }, "countryOfOrigin": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "currency": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "dimensionUnit": { "type": "string", "enum": [ "cm", "in" ] }, "finishes": { "type": "array", "items": { "type": "string" } }, "hasBim": { "type": "boolean" }, "height": { "type": [ "number", "null" ] }, "hsCode": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "inStock": { "type": "boolean" }, "isFeatured": { "type": "boolean" }, "isNew": { "type": "boolean" }, "isPhysical": { "type": "boolean" }, "leadTimeDays": { "type": [ "number", "null" ] }, "length": { "type": [ "number", "null" ] }, "materials": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "price": { "type": [ "number", "null" ] }, "priceOnRequest": { "type": "boolean" }, "reviewNote": { "type": [ "string", "null" ] }, "sellWhenOutOfStock": { "type": [ "boolean", "null" ] }, "sku": { "type": [ "string", "null" ] }, "slug": { "type": "string" }, "specs": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ] } }, "status": { "type": "string", "enum": [ "published", "pending", "draft", "rejected" ] }, "stockQuantity": { "type": [ "number", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "trackStock": { "type": [ "boolean", "null" ] }, "translations": { "type": "object" }, "type": { "type": "string" }, "updatedAt": { "type": [ "string", "null" ] }, "weight": { "type": [ "number", "null" ] }, "weightUnit": { "type": "string", "enum": [ "kg", "lb" ] }, "width": { "type": [ "number", "null" ] }, "year": { "type": [ "number", "null" ] }, "coverUrl": { "type": "string" }, "model": { "type": [ "object", "null" ], "properties": { "url": { "type": "string" }, "credit": { "type": [ "string", "null" ] }, "variants": { "type": "object" }, "iosUrl": { "type": [ "string", "null" ] }, "posterUrl": { "type": [ "string", "null" ] } }, "required": [ "url", "credit", "variants", "iosUrl", "posterUrl" ] }, "hoverUrl": { "type": "string" }, "breadcrumbs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ] } } }, "required": [ "collection", "brand", "designer", "category", "images", "files", "compareAtPrice", "countryOfOrigin", "createdAt", "currency", "description", "dimensionUnit", "finishes", "hasBim", "height", "hsCode", "id", "inStock", "isFeatured", "isNew", "isPhysical", "leadTimeDays", "length", "materials", "name", "price", "priceOnRequest", "reviewNote", "sellWhenOutOfStock", "sku", "slug", "specs", "status", "stockQuantity", "tags", "trackStock", "translations", "type", "updatedAt", "weight", "weightUnit", "width", "year", "coverUrl", "model", "hoverUrl", "breadcrumbs" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/key/products/{id}": { "get": { "operationId": "key.products.show", "tags": [ "Products" ], "summary": "One product with all its fields, specs and images", "description": "One product with all its fields, specs and images.\n\nRequires the `products:read` scope.", "x-required-scope": "products:read", "security": [ { "apiKey": [ "products:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "collection": { "type": [ "string", "null" ] }, "brand": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "logoUrl": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "slug", "logoUrl" ] }, "designer": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ] }, "category": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ] }, "images": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "position": { "type": "number" }, "alt": { "type": [ "string", "null" ] }, "url": { "type": "string" } }, "required": [ "id", "position", "alt", "url" ] } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "position": { "type": "number" }, "format": { "type": "string" }, "kind": { "type": "string", "enum": [ "catalogue", "bim", "cad_2d", "model_3d", "datasheet", "certificate", "other" ] }, "label": { "type": [ "string", "null" ] }, "originalName": { "type": "string" }, "size": { "type": "number" } }, "required": [ "id", "position", "format", "kind", "label", "originalName", "size" ] } }, "compareAtPrice": { "type": [ "number", "null" ] }, "countryOfOrigin": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "currency": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "dimensionUnit": { "type": "string", "enum": [ "cm", "in" ] }, "finishes": { "type": "array", "items": { "type": "string" } }, "hasBim": { "type": "boolean" }, "height": { "type": [ "number", "null" ] }, "hsCode": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "inStock": { "type": "boolean" }, "isFeatured": { "type": "boolean" }, "isNew": { "type": "boolean" }, "isPhysical": { "type": "boolean" }, "leadTimeDays": { "type": [ "number", "null" ] }, "length": { "type": [ "number", "null" ] }, "materials": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "price": { "type": [ "number", "null" ] }, "priceOnRequest": { "type": "boolean" }, "reviewNote": { "type": [ "string", "null" ] }, "sellWhenOutOfStock": { "type": [ "boolean", "null" ] }, "sku": { "type": [ "string", "null" ] }, "slug": { "type": "string" }, "specs": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ] } }, "status": { "type": "string", "enum": [ "published", "pending", "draft", "rejected" ] }, "stockQuantity": { "type": [ "number", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "trackStock": { "type": [ "boolean", "null" ] }, "translations": { "type": "object" }, "type": { "type": "string" }, "updatedAt": { "type": [ "string", "null" ] }, "weight": { "type": [ "number", "null" ] }, "weightUnit": { "type": "string", "enum": [ "kg", "lb" ] }, "width": { "type": [ "number", "null" ] }, "year": { "type": [ "number", "null" ] }, "coverUrl": { "type": "string" }, "model": { "type": [ "object", "null" ], "properties": { "url": { "type": "string" }, "credit": { "type": [ "string", "null" ] }, "variants": { "type": "object" }, "iosUrl": { "type": [ "string", "null" ] }, "posterUrl": { "type": [ "string", "null" ] } }, "required": [ "url", "credit", "variants", "iosUrl", "posterUrl" ] }, "hoverUrl": { "type": "string" }, "breadcrumbs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ] } } }, "required": [ "collection", "brand", "designer", "category", "images", "files", "compareAtPrice", "countryOfOrigin", "createdAt", "currency", "description", "dimensionUnit", "finishes", "hasBim", "height", "hsCode", "id", "inStock", "isFeatured", "isNew", "isPhysical", "leadTimeDays", "length", "materials", "name", "price", "priceOnRequest", "reviewNote", "sellWhenOutOfStock", "sku", "slug", "specs", "status", "stockQuantity", "tags", "trackStock", "translations", "type", "updatedAt", "weight", "weightUnit", "width", "year", "coverUrl", "model", "hoverUrl", "breadcrumbs" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "operationId": "key.products.update", "tags": [ "Products" ], "summary": "Edits a product; a published product goes back to review, a pending one is locked (409)", "description": "Edits a product; a published product goes back to review, a pending one is locked (409).\n\nRequires the `products:write` scope.", "x-required-scope": "products:write", "security": [ { "apiKey": [ "products:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "brandId": { "type": "string", "format": "uuid" }, "categoryId": { "type": "string", "format": "uuid" }, "description": { "type": [ "string", "null" ] }, "materials": { "type": [ "string", "null" ] }, "collection": { "type": [ "string", "null" ] }, "year": { "type": [ "integer", "null" ], "minimum": 1800, "maximum": 2200 }, "price": { "type": [ "number", "null" ], "minimum": 0, "maximum": 9999999999 }, "compareAtPrice": { "type": [ "number", "null" ], "minimum": 0, "maximum": 9999999999 }, "priceOnRequest": { "type": "boolean" }, "sku": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 64 }, "trackStock": { "type": "boolean" }, "stockQuantity": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000000 }, "sellWhenOutOfStock": { "type": "boolean" }, "leadTimeDays": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 3650 }, "isPhysical": { "type": "boolean" }, "length": { "type": [ "number", "null" ], "maximum": 1000000 }, "width": { "type": [ "number", "null" ], "maximum": 1000000 }, "height": { "type": [ "number", "null" ], "maximum": 1000000 }, "dimensionUnit": { "type": "string", "enum": [ "cm" ] }, "weight": { "type": [ "number", "null" ], "maximum": 1000000 }, "weightUnit": { "type": "string", "enum": [ "kg" ] }, "countryOfOrigin": { "type": [ "string", "null" ] }, "hsCode": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 40 }, "maxLength": 30 }, "currency": { "type": "string" }, "isNew": { "type": "boolean" }, "inStock": { "type": "boolean" }, "finishes": { "type": "array", "items": { "type": "string" } }, "specs": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } }, "required": [ "label", "value" ] } }, "images": { "type": "array", "items": { "type": "string", "maxLength": 1024 } }, "modelUrl": { "type": [ "string", "null" ], "maxLength": 1024 }, "modelIosUrl": { "type": [ "string", "null" ], "maxLength": 1024 }, "modelPosterUrl": { "type": [ "string", "null" ], "maxLength": 1024 }, "modelCredit": { "type": [ "string", "null" ] }, "modelVariants": { "type": "object", "additionalProperties": { "type": "string" } }, "designerId": { "type": [ "string", "null" ], "format": "uuid" }, "translations": {} }, "required": [] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "collection": { "type": [ "string", "null" ] }, "brand": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "logoUrl": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "slug", "logoUrl" ] }, "designer": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ] }, "category": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ] }, "images": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "position": { "type": "number" }, "alt": { "type": [ "string", "null" ] }, "url": { "type": "string" } }, "required": [ "id", "position", "alt", "url" ] } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "position": { "type": "number" }, "format": { "type": "string" }, "kind": { "type": "string", "enum": [ "catalogue", "bim", "cad_2d", "model_3d", "datasheet", "certificate", "other" ] }, "label": { "type": [ "string", "null" ] }, "originalName": { "type": "string" }, "size": { "type": "number" } }, "required": [ "id", "position", "format", "kind", "label", "originalName", "size" ] } }, "compareAtPrice": { "type": [ "number", "null" ] }, "countryOfOrigin": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "currency": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "dimensionUnit": { "type": "string", "enum": [ "cm", "in" ] }, "finishes": { "type": "array", "items": { "type": "string" } }, "hasBim": { "type": "boolean" }, "height": { "type": [ "number", "null" ] }, "hsCode": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "inStock": { "type": "boolean" }, "isFeatured": { "type": "boolean" }, "isNew": { "type": "boolean" }, "isPhysical": { "type": "boolean" }, "leadTimeDays": { "type": [ "number", "null" ] }, "length": { "type": [ "number", "null" ] }, "materials": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "price": { "type": [ "number", "null" ] }, "priceOnRequest": { "type": "boolean" }, "reviewNote": { "type": [ "string", "null" ] }, "sellWhenOutOfStock": { "type": [ "boolean", "null" ] }, "sku": { "type": [ "string", "null" ] }, "slug": { "type": "string" }, "specs": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ] } }, "status": { "type": "string", "enum": [ "published", "pending", "draft", "rejected" ] }, "stockQuantity": { "type": [ "number", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "trackStock": { "type": [ "boolean", "null" ] }, "translations": { "type": "object" }, "type": { "type": "string" }, "updatedAt": { "type": [ "string", "null" ] }, "weight": { "type": [ "number", "null" ] }, "weightUnit": { "type": "string", "enum": [ "kg", "lb" ] }, "width": { "type": [ "number", "null" ] }, "year": { "type": [ "number", "null" ] }, "coverUrl": { "type": "string" }, "model": { "type": [ "object", "null" ], "properties": { "url": { "type": "string" }, "credit": { "type": [ "string", "null" ] }, "variants": { "type": "object" }, "iosUrl": { "type": [ "string", "null" ] }, "posterUrl": { "type": [ "string", "null" ] } }, "required": [ "url", "credit", "variants", "iosUrl", "posterUrl" ] }, "hoverUrl": { "type": "string" }, "breadcrumbs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ] } } }, "required": [ "collection", "brand", "designer", "category", "images", "files", "compareAtPrice", "countryOfOrigin", "createdAt", "currency", "description", "dimensionUnit", "finishes", "hasBim", "height", "hsCode", "id", "inStock", "isFeatured", "isNew", "isPhysical", "leadTimeDays", "length", "materials", "name", "price", "priceOnRequest", "reviewNote", "sellWhenOutOfStock", "sku", "slug", "specs", "status", "stockQuantity", "tags", "trackStock", "translations", "type", "updatedAt", "weight", "weightUnit", "width", "year", "coverUrl", "model", "hoverUrl", "breadcrumbs" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "key.products.destroy", "tags": [ "Products" ], "summary": "Deletes a product of the vendor", "description": "Deletes a product of the vendor.\n\nRequires the `products:delete` scope.", "x-required-scope": "products:delete", "security": [ { "apiKey": [ "products:delete" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/key/products/{id}/status": { "get": { "operationId": "key.products.status", "tags": [ "Products" ], "summary": "The review status of a product and the reviewer's note when it was rejected", "description": "The review status of a product and the reviewer's note when it was rejected.\n\nRequires the `products:read` scope.", "x-required-scope": "products:read", "security": [ { "apiKey": [ "products:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "reviewNote": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "status", "reviewNote", "updatedAt" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/key/products/{id}/submit": { "post": { "operationId": "key.products.submit", "tags": [ "Products" ], "summary": "Sends a draft or rejected product to the review queue", "description": "Sends a draft or rejected product to the review queue.\n\nRequires the `products:write` scope.", "x-required-scope": "products:write", "security": [ { "apiKey": [ "products:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "collection": { "type": [ "string", "null" ] }, "brand": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "logoUrl": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "slug", "logoUrl" ] }, "designer": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ] }, "category": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ] }, "images": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "position": { "type": "number" }, "alt": { "type": [ "string", "null" ] }, "url": { "type": "string" } }, "required": [ "id", "position", "alt", "url" ] } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "position": { "type": "number" }, "format": { "type": "string" }, "kind": { "type": "string", "enum": [ "catalogue", "bim", "cad_2d", "model_3d", "datasheet", "certificate", "other" ] }, "label": { "type": [ "string", "null" ] }, "originalName": { "type": "string" }, "size": { "type": "number" } }, "required": [ "id", "position", "format", "kind", "label", "originalName", "size" ] } }, "compareAtPrice": { "type": [ "number", "null" ] }, "countryOfOrigin": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "currency": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "dimensionUnit": { "type": "string", "enum": [ "cm", "in" ] }, "finishes": { "type": "array", "items": { "type": "string" } }, "hasBim": { "type": "boolean" }, "height": { "type": [ "number", "null" ] }, "hsCode": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "inStock": { "type": "boolean" }, "isFeatured": { "type": "boolean" }, "isNew": { "type": "boolean" }, "isPhysical": { "type": "boolean" }, "leadTimeDays": { "type": [ "number", "null" ] }, "length": { "type": [ "number", "null" ] }, "materials": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "price": { "type": [ "number", "null" ] }, "priceOnRequest": { "type": "boolean" }, "reviewNote": { "type": [ "string", "null" ] }, "sellWhenOutOfStock": { "type": [ "boolean", "null" ] }, "sku": { "type": [ "string", "null" ] }, "slug": { "type": "string" }, "specs": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ] } }, "status": { "type": "string", "enum": [ "published", "pending", "draft", "rejected" ] }, "stockQuantity": { "type": [ "number", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "trackStock": { "type": [ "boolean", "null" ] }, "translations": { "type": "object" }, "type": { "type": "string" }, "updatedAt": { "type": [ "string", "null" ] }, "weight": { "type": [ "number", "null" ] }, "weightUnit": { "type": "string", "enum": [ "kg", "lb" ] }, "width": { "type": [ "number", "null" ] }, "year": { "type": [ "number", "null" ] }, "coverUrl": { "type": "string" }, "model": { "type": [ "object", "null" ], "properties": { "url": { "type": "string" }, "credit": { "type": [ "string", "null" ] }, "variants": { "type": "object" }, "iosUrl": { "type": [ "string", "null" ] }, "posterUrl": { "type": [ "string", "null" ] } }, "required": [ "url", "credit", "variants", "iosUrl", "posterUrl" ] }, "hoverUrl": { "type": "string" }, "breadcrumbs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ] } } }, "required": [ "collection", "brand", "designer", "category", "images", "files", "compareAtPrice", "countryOfOrigin", "createdAt", "currency", "description", "dimensionUnit", "finishes", "hasBim", "height", "hsCode", "id", "inStock", "isFeatured", "isNew", "isPhysical", "leadTimeDays", "length", "materials", "name", "price", "priceOnRequest", "reviewNote", "sellWhenOutOfStock", "sku", "slug", "specs", "status", "stockQuantity", "tags", "trackStock", "translations", "type", "updatedAt", "weight", "weightUnit", "width", "year", "coverUrl", "model", "hoverUrl", "breadcrumbs" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/key/requests": { "get": { "operationId": "key.requests.index", "tags": [ "Requests" ], "summary": "The vendor's requests, filterable like the dashboard inbox; a platform key lists all requests", "description": "The vendor's requests, filterable like the dashboard inbox; a platform key lists all requests.\n\nRequires the `requests:read` scope.", "x-required-scope": "requests:read", "security": [ { "apiKey": [ "requests:read" ] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "perPage", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "new" ] } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "info" ] } }, { "name": "brand", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "unread", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "active", "suspended" ] }, "logoUrl": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "slug", "status", "logoUrl" ] }, "brand": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "logoUrl": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "slug", "logoUrl" ] }, "createdAt": { "type": "string" }, "id": { "type": "string" }, "status": { "type": "string", "enum": [ "quoted", "closed", "new", "open" ] }, "type": { "type": "string", "enum": [ "price", "info", "catalogue", "samples" ] }, "updatedAt": { "type": "string" }, "product": { "type": [ "object", "null" ], "properties": { "brand": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "logoUrl": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "slug", "logoUrl" ] }, "compareAtPrice": { "type": [ "number", "null" ] }, "currency": { "type": "string" }, "hasBim": { "type": "boolean" }, "id": { "type": "string" }, "inStock": { "type": "boolean" }, "isNew": { "type": "boolean" }, "name": { "type": "string" }, "price": { "type": [ "number", "null" ] }, "priceOnRequest": { "type": "boolean" }, "slug": { "type": "string" }, "type": { "type": "string" }, "coverUrl": { "type": "string" }, "hoverUrl": { "type": "string" } }, "required": [ "brand", "compareAtPrice", "currency", "hasBim", "id", "inStock", "isNew", "name", "price", "priceOnRequest", "slug", "type", "coverUrl", "hoverUrl" ] }, "reference": { "type": "string" }, "isGuest": { "type": "boolean" }, "messagesCount": { "type": "number" }, "subject": { "type": "string" }, "unread": { "type": "boolean" }, "contact": { "type": "object", "properties": { "name": { "type": "string" }, "country": { "type": [ "string", "null" ] }, "email": { "type": "string" }, "profession": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] } }, "required": [ "name", "country", "email", "profession", "company" ] }, "lastMessage": { "type": [ "object", "null" ], "properties": { "createdAt": { "type": "string" }, "excerpt": { "type": "string" }, "author": { "type": "string", "enum": [ "provider", "customer", "admin", "system" ] } }, "required": [ "createdAt", "excerpt", "author" ] } }, "required": [ "provider", "brand", "createdAt", "id", "status", "type", "updatedAt", "product", "reference", "isGuest", "messagesCount", "subject", "unread", "contact", "lastMessage" ] } }, "metadata": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of items across all pages." }, "perPage": { "type": "integer", "description": "Items per page." }, "currentPage": { "type": "integer", "description": "The page returned (1-based)." }, "lastPage": { "type": "integer", "description": "The last available page." }, "firstPage": { "type": "integer", "description": "Always 1." }, "firstPageUrl": { "type": "string", "description": "Relative URL of the first page." }, "lastPageUrl": { "type": "string", "description": "Relative URL of the last page." }, "nextPageUrl": { "type": [ "string", "null" ], "description": "Relative URL of the next page, null on the last page." }, "previousPageUrl": { "type": [ "string", "null" ], "description": "Relative URL of the previous page, null on the first." } }, "required": [ "total", "perPage", "currentPage", "lastPage", "firstPage", "firstPageUrl", "lastPageUrl", "nextPageUrl", "previousPageUrl" ] } }, "required": [ "data", "metadata" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/key/requests/{id}": { "get": { "operationId": "key.requests.show", "tags": [ "Requests" ], "summary": "One request with its whole thread", "description": "One request with its whole thread. Does not mark it read for the team.\n\nRequires the `requests:read` scope.", "x-required-scope": "requests:read", "security": [ { "apiKey": [ "requests:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "provider": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "active", "suspended" ] }, "logoUrl": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "slug", "status", "logoUrl" ] }, "brand": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "logoUrl": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "slug", "logoUrl" ] }, "createdAt": { "type": "string" }, "id": { "type": "string" }, "status": { "type": "string", "enum": [ "quoted", "closed", "new", "open" ] }, "type": { "type": "string", "enum": [ "price", "info", "catalogue", "samples" ] }, "updatedAt": { "type": "string" }, "product": { "type": [ "object", "null" ], "properties": { "brand": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "logoUrl": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "slug", "logoUrl" ] }, "compareAtPrice": { "type": [ "number", "null" ] }, "currency": { "type": "string" }, "hasBim": { "type": "boolean" }, "id": { "type": "string" }, "inStock": { "type": "boolean" }, "isNew": { "type": "boolean" }, "name": { "type": "string" }, "price": { "type": [ "number", "null" ] }, "priceOnRequest": { "type": "boolean" }, "slug": { "type": "string" }, "type": { "type": "string" }, "coverUrl": { "type": "string" }, "hoverUrl": { "type": "string" } }, "required": [ "brand", "compareAtPrice", "currency", "hasBim", "id", "inStock", "isNew", "name", "price", "priceOnRequest", "slug", "type", "coverUrl", "hoverUrl" ] }, "messages": { "type": "array", "items": { "type": "object", "properties": { "createdAt": { "type": "string" }, "id": { "type": "string" }, "body": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "size": { "type": [ "number", "null" ] } }, "required": [ "name", "url", "size" ] } }, "author": { "type": "string", "enum": [ "provider", "customer", "admin", "system" ] }, "authorName": { "type": "string" } }, "required": [ "createdAt", "id", "body", "attachments", "author", "authorName" ] } }, "reference": { "type": "string" }, "isGuest": { "type": "boolean" }, "messagesCount": { "type": "number" }, "subject": { "type": "string" }, "unread": { "type": "boolean" }, "contact": { "type": "object", "properties": { "name": { "type": "string" }, "country": { "type": [ "string", "null" ] }, "email": { "type": "string" }, "profession": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] } }, "required": [ "name", "country", "email", "profession", "company" ] }, "lastMessage": { "type": [ "object", "null" ], "properties": { "createdAt": { "type": "string" }, "excerpt": { "type": "string" }, "author": { "type": "string", "enum": [ "provider", "customer", "admin", "system" ] } }, "required": [ "createdAt", "excerpt", "author" ] } }, "required": [ "provider", "brand", "createdAt", "id", "status", "type", "updatedAt", "product", "messages", "reference", "isGuest", "messagesCount", "subject", "unread", "contact", "lastMessage" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "key.requests.status", "tags": [ "Requests" ], "summary": "Changes the request status (open, quoted, closed)", "description": "Changes the request status (open, quoted, closed).\n\nRequires the `requests:write` scope.", "x-required-scope": "requests:write", "security": [ { "apiKey": [ "requests:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "new" ] } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "provider": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "active", "suspended" ] }, "logoUrl": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "slug", "status", "logoUrl" ] }, "brand": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "logoUrl": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "slug", "logoUrl" ] }, "createdAt": { "type": "string" }, "id": { "type": "string" }, "status": { "type": "string", "enum": [ "quoted", "closed", "new", "open" ] }, "type": { "type": "string", "enum": [ "price", "info", "catalogue", "samples" ] }, "updatedAt": { "type": "string" }, "product": { "type": [ "object", "null" ], "properties": { "brand": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "logoUrl": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "slug", "logoUrl" ] }, "compareAtPrice": { "type": [ "number", "null" ] }, "currency": { "type": "string" }, "hasBim": { "type": "boolean" }, "id": { "type": "string" }, "inStock": { "type": "boolean" }, "isNew": { "type": "boolean" }, "name": { "type": "string" }, "price": { "type": [ "number", "null" ] }, "priceOnRequest": { "type": "boolean" }, "slug": { "type": "string" }, "type": { "type": "string" }, "coverUrl": { "type": "string" }, "hoverUrl": { "type": "string" } }, "required": [ "brand", "compareAtPrice", "currency", "hasBim", "id", "inStock", "isNew", "name", "price", "priceOnRequest", "slug", "type", "coverUrl", "hoverUrl" ] }, "messages": { "type": "array", "items": { "type": "object", "properties": { "createdAt": { "type": "string" }, "id": { "type": "string" }, "body": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "size": { "type": [ "number", "null" ] } }, "required": [ "name", "url", "size" ] } }, "author": { "type": "string", "enum": [ "provider", "customer", "admin", "system" ] }, "authorName": { "type": "string" } }, "required": [ "createdAt", "id", "body", "attachments", "author", "authorName" ] } }, "reference": { "type": "string" }, "isGuest": { "type": "boolean" }, "messagesCount": { "type": "number" }, "subject": { "type": "string" }, "unread": { "type": "boolean" }, "contact": { "type": "object", "properties": { "name": { "type": "string" }, "country": { "type": [ "string", "null" ] }, "email": { "type": "string" }, "profession": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] } }, "required": [ "name", "country", "email", "profession", "company" ] }, "lastMessage": { "type": [ "object", "null" ], "properties": { "createdAt": { "type": "string" }, "excerpt": { "type": "string" }, "author": { "type": "string", "enum": [ "provider", "customer", "admin", "system" ] } }, "required": [ "createdAt", "excerpt", "author" ] } }, "required": [ "provider", "brand", "createdAt", "id", "status", "type", "updatedAt", "product", "messages", "reference", "isGuest", "messagesCount", "subject", "unread", "contact", "lastMessage" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/key/requests/{id}/messages": { "post": { "operationId": "key.requests.messages", "tags": [ "Requests" ], "summary": "Replies to the buyer, authored as the key's creator", "description": "Replies to the buyer, authored as the key's creator.\n\nRequires the `requests:write` scope.", "x-required-scope": "requests:write", "security": [ { "apiKey": [ "requests:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 5000 }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 1024 }, "name": { "type": "string" }, "size": { "type": [ "number", "null" ], "minimum": 0 } }, "required": [ "url", "name", "size" ] }, "maxLength": 10 } }, "required": [ "body" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string" }, "id": { "type": "string" }, "body": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "size": { "type": [ "number", "null" ] } }, "required": [ "name", "url", "size" ] } }, "author": { "type": "string", "enum": [ "provider", "customer", "admin", "system" ] }, "authorName": { "type": "string" } }, "required": [ "createdAt", "id", "body", "attachments", "author", "authorName" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/key/uploads": { "post": { "operationId": "key.uploads.store", "tags": [ "Uploads" ], "summary": "Uploads an image or document (multipart field `file`) and returns its URL", "description": "Uploads an image or document (multipart field `file`) and returns its URL.\n\nRequires the `uploads:write` scope.", "x-required-scope": "uploads:write", "security": [ { "apiKey": [ "uploads:write" ] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } }, "required": [ "file" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/key/uploads/model": { "post": { "operationId": "key.uploads.model", "tags": [ "Uploads" ], "summary": "Uploads a `.glb`, `.gltf` or `.usdz` 3D model (multipart field `file`)", "description": "Uploads a `.glb`, `.gltf` or `.usdz` 3D model (multipart field `file`).\n\nRequires the `uploads:write` scope.", "x-required-scope": "uploads:write", "security": [ { "apiKey": [ "uploads:write" ] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } }, "required": [ "file" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/key/webhooks": { "get": { "operationId": "key.webhooks.index", "tags": [ "Webhooks" ], "summary": "The vendor's endpoints with their last delivery status", "description": "The vendor's endpoints with their last delivery status.\n\nRequires the `webhooks:read` scope.", "x-required-scope": "webhooks:read", "security": [ { "apiKey": [ "webhooks:read" ] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "createdAt": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "request.created", "request.updated", "product.published", "product.unpublished" ] } }, "secret": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean" }, "lastStatus": { "type": [ "string", "null" ], "enum": [ "pending", "success", "failed", null ] } }, "required": [ "createdAt", "description", "id", "url", "events", "secret", "enabled", "lastStatus" ] } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "key.webhooks.store", "tags": [ "Webhooks" ], "summary": "Adds an endpoint for `request.created`, `request.updated`, `product.published` or `product.unpublished`", "description": "Adds an endpoint for `request.created`, `request.updated`, `product.published` or `product.unpublished`. The response carries the signing secret once.\n\nRequires the `webhooks:write` scope.", "x-required-scope": "webhooks:write", "security": [ { "apiKey": [ "webhooks:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 1024 }, "events": { "type": "array", "items": { "type": "string", "enum": [ "request.created" ] }, "minLength": 1 }, "description": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean" } }, "required": [ "url", "events" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "request.created", "request.updated", "product.published", "product.unpublished" ] } }, "secret": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean" }, "lastStatus": { "type": [ "string", "null" ], "enum": [ "pending", "success", "failed", null ] } }, "required": [ "createdAt", "description", "id", "url", "events", "secret", "enabled", "lastStatus" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/key/webhooks/{id}": { "get": { "operationId": "key.webhooks.show", "tags": [ "Webhooks" ], "summary": "One endpoint", "description": "One endpoint.\n\nRequires the `webhooks:read` scope.", "x-required-scope": "webhooks:read", "security": [ { "apiKey": [ "webhooks:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "request.created", "request.updated", "product.published", "product.unpublished" ] } }, "secret": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean" }, "lastStatus": { "type": [ "string", "null" ], "enum": [ "pending", "success", "failed", null ] } }, "required": [ "createdAt", "description", "id", "url", "events", "secret", "enabled", "lastStatus" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "operationId": "key.webhooks.update", "tags": [ "Webhooks" ], "summary": "Changes the URL, events or enabled flag", "description": "Changes the URL, events or enabled flag.\n\nRequires the `webhooks:write` scope.", "x-required-scope": "webhooks:write", "security": [ { "apiKey": [ "webhooks:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 1024 }, "events": { "type": "array", "items": { "type": "string", "enum": [ "request.created" ] }, "minLength": 1 }, "description": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean" } }, "required": [] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "request.created", "request.updated", "product.published", "product.unpublished" ] } }, "secret": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean" }, "lastStatus": { "type": [ "string", "null" ], "enum": [ "pending", "success", "failed", null ] } }, "required": [ "createdAt", "description", "id", "url", "events", "secret", "enabled", "lastStatus" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "key.webhooks.destroy", "tags": [ "Webhooks" ], "summary": "Removes an endpoint and its delivery log", "description": "Removes an endpoint and its delivery log.\n\nRequires the `webhooks:write` scope.", "x-required-scope": "webhooks:write", "security": [ { "apiKey": [ "webhooks:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/key/webhooks/{id}/deliveries": { "get": { "operationId": "key.webhooks.deliveries", "tags": [ "Webhooks" ], "summary": "The delivery log of an endpoint", "description": "The delivery log of an endpoint.\n\nRequires the `webhooks:read` scope.", "x-required-scope": "webhooks:read", "security": [ { "apiKey": [ "webhooks:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "perPage", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "createdAt": { "type": "string" }, "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "success", "failed" ] }, "payload": { "type": "object" }, "attempts": { "type": "number" }, "deliveredAt": { "type": [ "string", "null" ] }, "durationMs": { "type": [ "number", "null" ] }, "error": { "type": [ "string", "null" ] }, "event": { "type": "string" }, "responseBody": { "type": [ "string", "null" ] }, "responseStatus": { "type": [ "number", "null" ] } }, "required": [ "createdAt", "id", "status", "payload", "attempts", "deliveredAt", "durationMs", "error", "event", "responseBody", "responseStatus" ] } }, "metadata": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of items across all pages." }, "perPage": { "type": "integer", "description": "Items per page." }, "currentPage": { "type": "integer", "description": "The page returned (1-based)." }, "lastPage": { "type": "integer", "description": "The last available page." }, "firstPage": { "type": "integer", "description": "Always 1." }, "firstPageUrl": { "type": "string", "description": "Relative URL of the first page." }, "lastPageUrl": { "type": "string", "description": "Relative URL of the last page." }, "nextPageUrl": { "type": [ "string", "null" ], "description": "Relative URL of the next page, null on the last page." }, "previousPageUrl": { "type": [ "string", "null" ], "description": "Relative URL of the previous page, null on the first." } }, "required": [ "total", "perPage", "currentPage", "lastPage", "firstPage", "firstPageUrl", "lastPageUrl", "nextPageUrl", "previousPageUrl" ] } }, "required": [ "data", "metadata" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/key/webhooks/{id}/deliveries/{deliveryId}/retry": { "post": { "operationId": "key.webhooks.retry", "tags": [ "Webhooks" ], "summary": "Re-sends a failed delivery", "description": "Re-sends a failed delivery.\n\nRequires the `webhooks:write` scope.", "x-required-scope": "webhooks:write", "security": [ { "apiKey": [ "webhooks:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string" }, "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "success", "failed" ] }, "payload": { "type": "object" }, "attempts": { "type": "number" }, "deliveredAt": { "type": [ "string", "null" ] }, "durationMs": { "type": [ "number", "null" ] }, "error": { "type": [ "string", "null" ] }, "event": { "type": "string" }, "responseBody": { "type": [ "string", "null" ] }, "responseStatus": { "type": [ "number", "null" ] } }, "required": [ "createdAt", "id", "status", "payload", "attempts", "deliveredAt", "durationMs", "error", "event", "responseBody", "responseStatus" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/key/webhooks/{id}/rotate-secret": { "post": { "operationId": "key.webhooks.rotate_secret", "tags": [ "Webhooks" ], "summary": "Issues a new signing secret, shown once", "description": "Issues a new signing secret, shown once.\n\nRequires the `webhooks:write` scope.", "x-required-scope": "webhooks:write", "security": [ { "apiKey": [ "webhooks:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "request.created", "request.updated", "product.published", "product.unpublished" ] } }, "secret": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean" }, "lastStatus": { "type": [ "string", "null" ], "enum": [ "pending", "success", "failed", null ] } }, "required": [ "createdAt", "description", "id", "url", "events", "secret", "enabled", "lastStatus" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/key/webhooks/{id}/test": { "post": { "operationId": "key.webhooks.test", "tags": [ "Webhooks" ], "summary": "Queues a test event to the endpoint", "description": "Queues a test event to the endpoint.\n\nRequires the `webhooks:write` scope.", "x-required-scope": "webhooks:write", "security": [ { "apiKey": [ "webhooks:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string" }, "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "success", "failed" ] }, "payload": { "type": "object" }, "attempts": { "type": "number" }, "deliveredAt": { "type": [ "string", "null" ] }, "durationMs": { "type": [ "number", "null" ] }, "error": { "type": [ "string", "null" ] }, "event": { "type": "string" }, "responseBody": { "type": [ "string", "null" ] }, "responseStatus": { "type": [ "number", "null" ] } }, "required": [ "createdAt", "id", "status", "payload", "attempts", "deliveredAt", "durationMs", "error", "event", "responseBody", "responseStatus" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/key/whoami": { "get": { "operationId": "key.whoami", "tags": [ "Whoami" ], "summary": "Which owner, integration client and scopes the presented API key carries", "description": "Which owner, integration client and scopes the presented API key carries.\n\nWorks with any valid key; no scope required.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "owner": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "provider" }, "providerId": { "type": "string" } }, "required": [ "kind", "providerId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "platform" } }, "required": [ "kind" ] } ] }, "client": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "products:read", "products:write", "products:delete", "brands:read", "brands:write", "requests:read", "requests:write", "uploads:write", "analytics:read", "team:read", "webhooks:read", "webhooks:write" ] } } }, "required": [ "owner", "client", "scopes" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "afk_...", "description": "An API key created in the vendor workspace. Send it as `Authorization: Bearer afk_...`.", "x-scopes": [ "analytics:read", "brands:read", "brands:write", "products:delete", "products:read", "products:write", "requests:read", "requests:write", "team:read", "uploads:write", "webhooks:read", "webhooks:write" ] } }, "schemas": { "Error": { "type": "object", "required": [ "errors" ], "properties": { "errors": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable code, for example `E_UNAUTHORIZED_ACCESS`." }, "field": { "type": "string", "description": "Present on validation errors: the invalid input." }, "rule": { "type": "string", "description": "Present on validation errors: the failed rule." } } } } } } }, "responses": { "Unauthorized": { "description": "The key is missing, malformed, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "errors": [ { "message": "Invalid API key", "code": "E_UNAUTHORIZED_ACCESS" } ] } } } }, "Forbidden": { "description": "The key does not carry the scope this endpoint needs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "errors": [ { "message": "Missing scope requests:read", "code": "E_AUTHORIZATION_FAILURE" } ] } } } }, "ValidationFailed": { "description": "A query parameter or body field failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "errors": [ { "message": "The perPage field must not be greater than 100", "rule": "max", "field": "perPage" } ] } } } }, "RateLimited": { "description": "Too many requests. Wait for the `Retry-After` header before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "errors": [ { "message": "Too many requests", "code": "E_TOO_MANY_REQUESTS" } ] } } } } } } }