{"openapi":"3.1.0","info":{"title":"PaperLink API","version":"1.0.0","description":"PaperLink Public REST API for managing products and documents.","contact":{"name":"PaperLink Support","url":"https://paperlink.online"}},"servers":[{"url":"https://app.paperlink.online/api/v1","description":"Production"}],"security":[{"BearerAuth":[]}],"paths":{"/products":{"get":{"operationId":"listProducts","summary":"List products","tags":["Products"],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["active","archived","all"],"default":"active"}},{"name":"after","in":"query","schema":{"type":"string","format":"uuid"},"description":"Cursor for pagination"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Product list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductListResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"createProduct","summary":"Create a product","tags":["Products"],"parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string"},"description":"Unique key for idempotent requests"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProductRequest"}}}},"responses":{"201":{"description":"Product created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"description":"Duplicate SKU"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/products/{id}":{"get":{"operationId":"getProduct","summary":"Get a product","tags":["Products"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Product detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Product not found"}}},"patch":{"operationId":"updateProduct","summary":"Update a product","tags":["Products"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProductRequest"}}}},"responses":{"200":{"description":"Product updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Product not found"},"422":{"$ref":"#/components/responses/ValidationError"}}},"delete":{"operationId":"archiveProduct","summary":"Archive a product","tags":["Products"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Product archived"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Product not found"}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key from Settings > Integrations > API Keys"}},"schemas":{"Product":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"unitPrice":{"type":"number"},"currency":{"type":"string"},"description":{"type":"string","nullable":true},"sku":{"type":"string","nullable":true},"taxRate":{"type":"number","nullable":true},"type":{"type":"string"},"unitOfMeasure":{"type":"string"},"status":{"type":"string","enum":["active","archived"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"ProductResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"}}},"ProductListResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"hasMore":{"type":"boolean"},"nextCursor":{"type":"string","nullable":true}}}}},"CreateProductRequest":{"type":"object","required":["name","unitPrice","currency"],"properties":{"name":{"type":"string","maxLength":255},"unitPrice":{"type":"number","minimum":0},"currency":{"type":"string","minLength":3,"maxLength":3},"description":{"type":"string","maxLength":2000},"sku":{"type":"string","maxLength":100},"taxRate":{"type":"number","minimum":0,"maximum":100},"type":{"type":"string","maxLength":50},"unitOfMeasure":{"type":"string","maxLength":50}}},"UpdateProductRequest":{"type":"object","properties":{"name":{"type":"string","maxLength":255},"unitPrice":{"type":"number","minimum":0},"currency":{"type":"string","minLength":3,"maxLength":3},"description":{"type":"string","nullable":true,"maxLength":2000},"sku":{"type":"string","nullable":true,"maxLength":100},"taxRate":{"type":"number","nullable":true,"minimum":0,"maximum":100},"type":{"type":"string","maxLength":50},"unitOfMeasure":{"type":"string","maxLength":50}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","required":["type","code","message","request_id"],"properties":{"type":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}}}}}},"responses":{"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ValidationError":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"RateLimited":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}