{"openapi":"3.1.0","info":{"title":"JustIdea Prestashop DEMO — agent API","version":"1.0.2","summary":"Read-only access to catalogue, stock, shipping and policies.","description":"Every endpoint here is read-only. Nothing writes a cart, an order or customer data.\n\nMost of the surface needs no credentials. Only the MCP endpoint requires a bearer token, issued by the store owner in the PrestaShop Back Office — see /auth.md.\n\nErrors are returned as JSON when the request accepts it, with a stable `error.code`.\n\n## Versioning and deprecation policy\n\nEvery response carries `API-Version`. Version 1 is current and **not deprecated** — responses say so with `Deprecation: false`.\n\nIf a version is ever retired, responses will carry `Deprecation` with the date the decision was taken and `Sunset` with the date it stops working (RFC 8594 and RFC 9745), and a `Link` with `rel=\"deprecation\"` pointing at the migration notes. There will be at least 180 days between the two. Breaking changes get a new version rather than being applied in place; additive changes — new fields, new endpoints — may land without one.","license":{"name":"AFL-3.0","identifier":"AFL-3.0"}},"servers":[{"url":"https://prestashop.justidea.dev"}],"externalDocs":{"description":"Store overview for agents (llms.txt)","url":"https://prestashop.justidea.dev/llms.txt"},"tags":[{"name":"discovery","description":"Documents describing the store to agents."},{"name":"content","description":"Store content in agent-friendly formats."},{"name":"mcp","description":"Model Context Protocol endpoint."},{"name":"ops","description":"Operational status."}],"paths":{"/llms.txt":{"get":{"tags":["discovery"],"operationId":"getLlmsTxt","summary":"Store overview for agents","description":"Name, summary, category index, policy links and machine-readable endpoints.","parameters":[{"name":"API-Version","in":"header","required":false,"description":"Pin the response contract to a version. Current: 1. Every response echoes the version it was served under.","schema":{"type":"string","enum":["1"],"default":"1"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Accepted and echoed. Every operation is a read and therefore already idempotent, so retries are always safe.","schema":{"type":"string"}}],"responses":{"200":{"description":"Store overview for agents","content":{"text/markdown":{"schema":{"type":"string"}}}},"404":{"description":"This feature is switched off on this store.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/llms-full.txt":{"get":{"tags":["discovery"],"operationId":"getLlmsFullTxt","summary":"Expanded store overview","description":"As llms.txt, plus a per-category product sample.","parameters":[{"name":"API-Version","in":"header","required":false,"description":"Pin the response contract to a version. Current: 1. Every response echoes the version it was served under.","schema":{"type":"string","enum":["1"],"default":"1"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Accepted and echoed. Every operation is a read and therefore already idempotent, so retries are always safe.","schema":{"type":"string"}}],"responses":{"200":{"description":"Expanded store overview","content":{"text/markdown":{"schema":{"type":"string"}}}},"404":{"description":"This feature is switched off on this store.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/agent-sitemap.xml":{"get":{"tags":["discovery"],"operationId":"getAgentSitemap","summary":"Agent sitemap","description":"Catalogue URLs with last-modified dates, for deciding what to re-fetch.","parameters":[{"name":"API-Version","in":"header","required":false,"description":"Pin the response contract to a version. Current: 1. Every response echoes the version it was served under.","schema":{"type":"string","enum":["1"],"default":"1"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Accepted and echoed. Every operation is a read and therefore already idempotent, so retries are always safe.","schema":{"type":"string"}}],"responses":{"200":{"description":"Agent sitemap","content":{"application/xml":{"schema":{"type":"string"}}}},"404":{"description":"This feature is switched off on this store.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/.well-known/api-catalog":{"get":{"tags":["discovery"],"operationId":"getApiCatalog","summary":"API catalog (RFC 9727)","description":"Linkset of this store's APIs and their documentation.","parameters":[{"name":"API-Version","in":"header","required":false,"description":"Pin the response contract to a version. Current: 1. Every response echoes the version it was served under.","schema":{"type":"string","enum":["1"],"default":"1"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Accepted and echoed. Every operation is a read and therefore already idempotent, so retries are always safe.","schema":{"type":"string"}}],"responses":{"200":{"description":"API catalog (RFC 9727)","content":{"application/linkset+json":{"schema":{"type":"string"}}}},"404":{"description":"This feature is switched off on this store.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/.well-known/agent-skills/index.json":{"get":{"tags":["discovery"],"operationId":"getAgentSkills","summary":"Agent skills index","description":"Capabilities exposed to agents, each with a content digest.","parameters":[{"name":"API-Version","in":"header","required":false,"description":"Pin the response contract to a version. Current: 1. Every response echoes the version it was served under.","schema":{"type":"string","enum":["1"],"default":"1"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Accepted and echoed. Every operation is a read and therefore already idempotent, so retries are always safe.","schema":{"type":"string"}}],"responses":{"200":{"description":"Agent skills index","content":{"application/json":{"schema":{"type":"string"}}}},"404":{"description":"This feature is switched off on this store.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/.well-known/ai-catalog.json":{"get":{"tags":["discovery"],"operationId":"getAiCatalog","summary":"AI catalog (ARD)","description":"Every agent-usable surface of this store in one document.","parameters":[{"name":"API-Version","in":"header","required":false,"description":"Pin the response contract to a version. Current: 1. Every response echoes the version it was served under.","schema":{"type":"string","enum":["1"],"default":"1"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Accepted and echoed. Every operation is a read and therefore already idempotent, so retries are always safe.","schema":{"type":"string"}}],"responses":{"200":{"description":"AI catalog (ARD)","content":{"application/json":{"schema":{"type":"string"}}}},"404":{"description":"This feature is switched off on this store.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/.well-known/openapi.json":{"get":{"tags":["discovery"],"operationId":"getOpenApi","summary":"This specification","description":"The document you are reading, served live.","parameters":[{"name":"API-Version","in":"header","required":false,"description":"Pin the response contract to a version. Current: 1. Every response echoes the version it was served under.","schema":{"type":"string","enum":["1"],"default":"1"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Accepted and echoed. Every operation is a read and therefore already idempotent, so retries are always safe.","schema":{"type":"string"}}],"responses":{"200":{"description":"This specification","content":{"application/json":{"schema":{"type":"string"}}}},"404":{"description":"This feature is switched off on this store.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/.well-known/oauth-authorization-server":{"get":{"tags":["discovery"],"operationId":"getAuthorizationServerMetadata","summary":"Authorization Server Metadata (RFC 8414)","description":"Issuer and the agent_auth block describing how credentials are obtained.","parameters":[{"name":"API-Version","in":"header","required":false,"description":"Pin the response contract to a version. Current: 1. Every response echoes the version it was served under.","schema":{"type":"string","enum":["1"],"default":"1"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Accepted and echoed. Every operation is a read and therefore already idempotent, so retries are always safe.","schema":{"type":"string"}}],"responses":{"200":{"description":"Authorization Server Metadata (RFC 8414)","content":{"application/json":{"schema":{"type":"string"}}}},"404":{"description":"This feature is switched off on this store.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/.well-known/oauth-protected-resource":{"get":{"tags":["discovery"],"operationId":"getProtectedResourceMetadata","summary":"Protected Resource Metadata (RFC 9728)","description":"Which authorization server guards the MCP endpoint, and with which scopes.","parameters":[{"name":"API-Version","in":"header","required":false,"description":"Pin the response contract to a version. Current: 1. Every response echoes the version it was served under.","schema":{"type":"string","enum":["1"],"default":"1"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Accepted and echoed. Every operation is a read and therefore already idempotent, so retries are always safe.","schema":{"type":"string"}}],"responses":{"200":{"description":"Protected Resource Metadata (RFC 9728)","content":{"application/json":{"schema":{"type":"string"}}}},"404":{"description":"This feature is switched off on this store.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/.well-known/mcp":{"get":{"tags":["mcp"],"operationId":"getMcpManifest","summary":"MCP manifest","description":"Server URL, transport and authentication for the MCP endpoint.","parameters":[{"name":"API-Version","in":"header","required":false,"description":"Pin the response contract to a version. Current: 1. Every response echoes the version it was served under.","schema":{"type":"string","enum":["1"],"default":"1"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Accepted and echoed. Every operation is a read and therefore already idempotent, so retries are always safe.","schema":{"type":"string"}}],"responses":{"200":{"description":"MCP manifest","content":{"application/json":{"schema":{"type":"string"}}}},"404":{"description":"This feature is switched off on this store.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/auth.md":{"get":{"tags":["discovery"],"operationId":"getAuthMd","summary":"Agent registration instructions","description":"How to obtain credentials for the authenticated surface.","parameters":[{"name":"API-Version","in":"header","required":false,"description":"Pin the response contract to a version. Current: 1. Every response echoes the version it was served under.","schema":{"type":"string","enum":["1"],"default":"1"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Accepted and echoed. Every operation is a read and therefore already idempotent, so retries are always safe.","schema":{"type":"string"}}],"responses":{"200":{"description":"Agent registration instructions","content":{"text/markdown":{"schema":{"type":"string"}}}},"404":{"description":"This feature is switched off on this store.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/agent/md":{"get":{"tags":["content"],"operationId":"getMarkdown","summary":"Render a store resource as Markdown","description":"The same content is returned for any product, category or CMS URL requested with `Accept: text/markdown`.","parameters":[{"name":"resource","in":"query","required":true,"schema":{"type":"string","enum":["product","category","cms","home"]}},{"name":"id","in":"query","required":false,"description":"Required for every resource except `home`.","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Markdown document.","content":{"text/markdown":{"schema":{"type":"string"}}}},"400":{"description":"Unknown resource, or missing id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource on this shop.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/agent/products":{"get":{"tags":["content"],"operationId":"listProducts","summary":"List catalogue products","description":"Paginated product list with price and availability. Follow the `next` link, or pass limit/offset yourself.","parameters":[{"name":"API-Version","in":"header","required":false,"description":"Pin the response contract to a version. Current: 1. Every response echoes the version it was served under.","schema":{"type":"string","enum":["1"],"default":"1"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Accepted and echoed. Every operation is a read and therefore already idempotent, so retries are always safe.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1-100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","required":false,"description":"Number of products to skip.","schema":{"type":"integer","minimum":0,"default":0}},{"name":"category_id","in":"query","required":false,"schema":{"type":"integer","minimum":1}},{"name":"query","in":"query","required":false,"description":"Keyword matched against name, reference and EAN.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of products.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductPage"}}}},"400":{"description":"Bad pagination parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/agent/categories":{"get":{"tags":["content"],"operationId":"listCategories","summary":"List catalogue categories","description":"Category tree with live product counts.","parameters":[{"name":"API-Version","in":"header","required":false,"description":"Pin the response contract to a version. Current: 1. Every response echoes the version it was served under.","schema":{"type":"string","enum":["1"],"default":"1"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Accepted and echoed. Every operation is a read and therefore already idempotent, so retries are always safe.","schema":{"type":"string"}},{"name":"max_depth","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":10,"default":3}}],"responses":{"200":{"description":"Category list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryList"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/agent/status":{"get":{"tags":["ops"],"operationId":"getStatus","summary":"Operational status","description":"Health of the agent layer, which features are live, and catalogue size. Safe to poll; needs no credentials.","responses":{"200":{"description":"Status document.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Status"}}}}}}},"/agent/mcp":{"post":{"tags":["mcp"],"operationId":"callMcp","summary":"MCP endpoint (JSON-RPC 2.0)","description":"Methods: `initialize`, `ping`, `tools/list`, `tools/call`. Available tools: search_products, get_product, list_categories, check_availability, get_shipping_options, get_policies.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcRequest"},"examples":{"listTools":{"summary":"List available tools","value":{"jsonrpc":"2.0","id":1,"method":"tools/list"}},"searchProducts":{"summary":"Search the catalogue","value":{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_products","arguments":{"query":"shirt","limit":5}}}}}}}},"responses":{"200":{"description":"JSON-RPC response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcResponse"}}}},"202":{"description":"Notification accepted; no body."},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Method not allowed; POST only.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Token issued by the store owner. See /auth.md."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status"],"properties":{"code":{"type":"string","description":"Stable machine-readable code.","enum":["not_found","forbidden","unauthorized","rate_limited","bad_request","method_not_allowed","payload_too_large","unavailable"]},"message":{"type":"string"},"status":{"type":"integer"},"retry_after":{"type":"integer","description":"Seconds to wait; present on 429."},"resource_metadata":{"type":"string","format":"uri","description":"RFC 9728 metadata URL; present on 401."}}}}},"Status":{"type":"object","properties":{"status":{"type":"string","enum":["ok","degraded","disabled"]},"module_version":{"type":"string"},"time":{"type":"string","format":"date-time"},"currency":{"type":"string"},"language":{"type":"string"},"catalogue":{"type":"object","properties":{"products":{"type":"integer"},"categories":{"type":"integer"}}},"features":{"type":"object","additionalProperties":{"type":"boolean"}},"rate_limit_per_minute":{"type":"integer"}}},"Product":{"type":"object","required":["id","name","url"],"properties":{"id":{"type":"integer"},"name":{"type":"string"},"url":{"type":"string","format":"uri"},"reference":{"type":"string"},"gtin":{"type":"string"},"manufacturer":{"type":"string"},"price":{"type":"number","description":"Tax included."},"price_currency":{"type":"string"},"in_stock":{"type":"boolean"},"quantity":{"type":"integer"},"summary":{"type":"string"},"updated_at":{"type":"string"}}},"ProductPage":{"type":"object","required":["items","pagination"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"currency":{"type":"string"}}},"Pagination":{"type":"object","required":["limit","offset","total"],"properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"},"has_more":{"type":"boolean"},"next":{"type":["string","null"],"format":"uri","description":"URL of the next page, or null on the last one."}}},"Category":{"type":"object","required":["id","name","url"],"properties":{"id":{"type":"integer"},"parent_id":{"type":"integer"},"depth":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"product_count":{"type":"integer"},"url":{"type":"string","format":"uri"}}},"CategoryList":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"count":{"type":"integer"}}},"JsonRpcRequest":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"description":"Omit for notifications."},"method":{"type":"string","enum":["initialize","ping","tools/list","tools/call"]},"params":{"type":"object"}}},"JsonRpcResponse":{"type":"object","required":["jsonrpc"],"properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":[],"result":{"type":"object"},"error":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}}}}}}},"x-api-version":"1","security":[[],{"bearerAuth":[]}]}