{"openapi":"3.1.0","info":{"title":"Mercader storefront API","version":"1.0.0","description":"Lets AI agents and scripts edit the storefront of the merchant who authorized them: profile, products, events and links. Authenticate with a personal token (create one at https://app.mercader.app/admin?tab=agents) or an OAuth 2.1 access token. The same operations are available as MCP tools at https://web.mercader.app/api/mcp/me. Changes are published on the storefront immediately. Never invent prices or product details: ask the merchant."},"servers":[{"url":"https://web.mercader.app/api/v1"}],"security":[{"bearer":[]},{"oauth":["profile:write","catalog:write"]}],"paths":{"/me":{"get":{"operationId":"get_storefront","summary":"Profile, plan, products, events and links of the token owner","responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/profile":{"patch":{"operationId":"update_profile","summary":"Update name, bio, colour, language, currency or images","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfilePatch"}}}},"responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/products":{"get":{"operationId":"list_products","summary":"List products","responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"create_product","summary":"Create a product","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductInput"}}}},"responses":{"201":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/products/{id}":{"patch":{"operationId":"update_product","summary":"Update a product","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductPatch"}}}},"responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"delete":{"operationId":"delete_product","summary":"Delete a product","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/events":{"get":{"operationId":"list_events","summary":"List events and markets","responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"create_event","summary":"Create an event or market","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventInput"}}}},"responses":{"201":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/events/{id}":{"patch":{"operationId":"update_event","summary":"Update an event","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventPatch"}}}},"responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"delete":{"operationId":"delete_event","summary":"Delete an event","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/social-links":{"get":{"operationId":"list_social_links","summary":"List social and contact links","responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"create_social_link","summary":"Add a social or contact link","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SocialLinkInput"}}}},"responses":{"201":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/social-links/{id}":{"patch":{"operationId":"update_social_link","summary":"Update a link","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SocialLinkPatch"}}}},"responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"delete":{"operationId":"delete_social_link","summary":"Delete a link","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/uploads":{"post":{"operationId":"create_upload","summary":"Get a signed URL to upload an image, then use its public_url","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadRequest"}}}},"responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Personal token (mk_live_…) or OAuth access token."},"oauth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://web.mercader.app/oauth/authorize","tokenUrl":"https://web.mercader.app/oauth/token","refreshUrl":"https://web.mercader.app/oauth/token","scopes":{"profile:write":"Edit the profile and links","catalog:write":"Edit products and events"}}}}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"error":{"type":"string"},"error_description":{"type":"string"}},"required":["error"]}}}}},"schemas":{"ProfilePatch":{"type":"object","additionalProperties":false,"properties":{"display_name":{"type":"string","maxLength":80},"bio":{"type":["string","null"],"maxLength":1000},"theme":{"type":["string","null"],"pattern":"^#[0-9a-fA-F]{6}$"},"language":{"type":"string","enum":["es","en","pt","fr","de","it","nl"]},"country":{"type":["string","null"],"description":"ISO 3166-1 alpha-2"},"currency":{"type":["string","null"],"description":"ISO 4217"},"avatar_url":{"type":["string","null"],"description":"Public URL in the profile-images bucket, returned by POST /uploads."},"header_url":{"type":["string","null"],"description":"Public URL in the profile-images bucket, returned by POST /uploads."}}},"ProductInput":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","maxLength":120},"description":{"type":["string","null"],"maxLength":2000},"price":{"type":"number","minimum":0,"description":"In the storefront currency (see profile.currency)."},"image_url":{"type":["string","null"],"description":"Public URL in the product-images bucket, returned by POST /uploads."},"image_alt":{"type":["string","null"],"maxLength":200},"is_available":{"type":"boolean"},"display_order":{"type":"integer","minimum":0}},"required":["name","price"]},"ProductPatch":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","maxLength":120},"description":{"type":["string","null"],"maxLength":2000},"price":{"type":"number","minimum":0,"description":"In the storefront currency (see profile.currency)."},"image_url":{"type":["string","null"],"description":"Public URL in the product-images bucket, returned by POST /uploads."},"image_alt":{"type":["string","null"],"maxLength":200},"is_available":{"type":"boolean"},"display_order":{"type":"integer","minimum":0}}},"EventInput":{"type":"object","additionalProperties":false,"properties":{"title":{"type":"string","maxLength":120},"description":{"type":["string","null"],"maxLength":2000},"start_date":{"type":"string","format":"date-time"},"end_date":{"type":["string","null"],"format":"date-time"},"location":{"type":["string","null"],"maxLength":300,"description":"Address or Google Maps link."},"location_text":{"type":["string","null"],"maxLength":120,"description":"Link text shown for the location."},"image_url":{"type":["string","null"],"description":"Public URL in the event-images bucket, returned by POST /uploads."},"is_active":{"type":"boolean"},"display_order":{"type":"integer","minimum":0}},"required":["title","start_date"]},"EventPatch":{"type":"object","additionalProperties":false,"properties":{"title":{"type":"string","maxLength":120},"description":{"type":["string","null"],"maxLength":2000},"start_date":{"type":"string","format":"date-time"},"end_date":{"type":["string","null"],"format":"date-time"},"location":{"type":["string","null"],"maxLength":300,"description":"Address or Google Maps link."},"location_text":{"type":["string","null"],"maxLength":120,"description":"Link text shown for the location."},"image_url":{"type":["string","null"],"description":"Public URL in the event-images bucket, returned by POST /uploads."},"is_active":{"type":"boolean"},"display_order":{"type":"integer","minimum":0}}},"SocialLinkInput":{"type":"object","additionalProperties":false,"properties":{"platform":{"type":"string","enum":["Instagram","Facebook","Twitter","LinkedIn","YouTube","TikTok","Pinterest","Website","WhatsApp","Telegram","Email","Other"]},"url":{"type":"string","description":"Full https URL; for Email, an email address."},"display_order":{"type":"integer","minimum":0}},"required":["platform","url"]},"SocialLinkPatch":{"type":"object","additionalProperties":false,"properties":{"platform":{"type":"string","enum":["Instagram","Facebook","Twitter","LinkedIn","YouTube","TikTok","Pinterest","Website","WhatsApp","Telegram","Email","Other"]},"url":{"type":"string","description":"Full https URL; for Email, an email address."},"display_order":{"type":"integer","minimum":0}}},"UploadRequest":{"type":"object","additionalProperties":false,"properties":{"kind":{"type":"string","enum":["product","event","avatar","header"]},"content_type":{"type":"string","enum":["image/jpeg","image/png","image/webp"]}},"required":["kind","content_type"]}}}}