Catalogues

Product catalogues your agents can search. Reading needs knowledge:read; creating and uploading needs knowledge:write.

List catalogues

GET /catalogues

Lists your organisation’s product catalogues with their sync state. Any valid API key can call it.

Scope: knowledge:read

Example request

curl -X GET "https://api.foan.ai/api/v1/catalogues" \
  -H "Authorization: Bearer $FOAN_API_KEY"

Response 200

{
  "success": true,
  "data": [
    {
      "id": "cat_7d21e9a4c3",
      "organisation_id": "cmf1a2b3c0000orgx5678ijkl",
      "integration_type": "upload",
      "external_id": "summer-menu",
      "name": "summer-menu",
      "base_url": "upload://summer-menu",
      "is_active": true,
      "restaurant_id": null,
      "outlet_id": null,
      "last_sync_at": "2026-09-25T09:31:10Z",
      "last_sync_status": "OK",
      "last_sync_error": null
    }
  ],
  "message": "Catalogues retrieved"
}

Errors

Code	When
401	Missing, invalid or revoked API key
403	Key lacks knowledge:read
429	Rate limited
502	Knowledge service failed or is unreachable
503	Knowledge service is not configured on this server
504	Knowledge service timed out

Create a catalogue

POST /catalogues

Creates an empty product catalogue record in your organisation. Upload its product file next with POST /catalogues/{id}/upload.

Scope: knowledge:write

Body (application/json)

Field	Type	Required	Description
integration_type	string	yes	Use upload for a file-fed catalogue.
external_id	string	no	Your identifier; file uploads are matched to the catalogue by this value.
base_url	string	no	For upload catalogues the dashboard sends upload://<external_id>.
restaurant_id	string	no
outlet_id	string	no
is_active	boolean	no

Example request

curl -X POST "https://api.foan.ai/api/v1/catalogues" \
  -H "Authorization: Bearer $FOAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"integration_type":"upload","external_id":"summer-menu","base_url":"upload://summer-menu"}'

Response 201

{
  "success": true,
  "data": {
    "id": "cat_7d21e9a4c3",
    "organisation_id": "cmf1a2b3c0000orgx5678ijkl",
    "integration_type": "upload",
    "external_id": "summer-menu",
    "name": "summer-menu",
    "base_url": "upload://summer-menu",
    "is_active": true,
    "restaurant_id": null,
    "outlet_id": null,
    "last_sync_at": null,
    "last_sync_status": null,
    "last_sync_error": null
  },
  "message": "Catalogue created"
}

Errors

Code	When
400	Rejected by the catalogue service; its message is passed through
401	Missing, invalid or revoked API key
403	Key lacks knowledge:write
422	Rejected by the catalogue service’s validation
429	Rate limited
502	Knowledge service failed or is unreachable
503	Knowledge service is not configured on this server
504	Knowledge service timed out

Upload a catalogue file

POST /catalogues/{id}/upload

Uploads the product feed for a catalogue in your organisation; it is parsed, embedded and stored within the request (up to 30 seconds). The catalogue must exist in the key’s organisation.

Scope: knowledge:write

Parameters

Name	In	Type	Required	Description
id	path	string	yes	Catalogue ID. Must belong to the key’s organisation.

Body (multipart/form-data)

Field	Type	Required	Description
file	file	yes	Product feed, .csv or .json, at most 4 MB.

Example request

curl -X POST "https://api.foan.ai/api/v1/catalogues/{id}/upload" \
  -H "Authorization: Bearer $FOAN_API_KEY"

Response 200

{
  "success": true,
  "data": {
    "catalogue_name": "summer-menu",
    "products": 128
  },
  "message": "Catalogue file uploaded"
}

Errors

Code	When
400	Rejected by the catalogue service (bad file or format)
401	Missing, invalid or revoked API key
403	Key lacks knowledge:write
404	Catalogue not found in your organisation
429	Rate limited
500	File over 4 MB or more than 5 files (upload errors are not translated to 400)
502	Knowledge service failed or is unreachable
503	Knowledge service is not configured on this server
504	Knowledge service timed out

Get catalogue sync status

GET /catalogues/{id}/status

Returns whether a catalogue is processing, ready or failed, with the last sync time and error.

Scope: knowledge:read

Parameters

Name	In	Type	Required	Description
id	path	string	yes	Catalogue ID. Must belong to the key’s organisation.

Example request

curl -X GET "https://api.foan.ai/api/v1/catalogues/{id}/status" \
  -H "Authorization: Bearer $FOAN_API_KEY"

Response 200

{
  "success": true,
  "data": {
    "catalogue_id": "cat_7d21e9a4c3",
    "status": "ready",
    "last_sync_status": "OK",
    "last_sync_at": "2026-09-25T09:31:10Z",
    "last_sync_error": null
  },
  "message": "Catalogue status retrieved"
}

Errors

Code	When
401	Missing, invalid or revoked API key
403	Key lacks knowledge:read
404	Catalogue not found in your organisation
429	Rate limited
502	Knowledge service failed or is unreachable
503	Knowledge service is not configured on this server
504	Knowledge service timed out

Search a catalogue

POST /catalogues/{id}/search

Runs a natural-language product search within one catalogue of your organisation, the same search agents use during calls.

Scope: knowledge:read

Parameters

Name	In	Type	Required	Description
id	path	string	yes	Catalogue ID. Must belong to the key’s organisation.

Body (application/json)

Field	Type	Required	Description
query	string	yes	What to look for, for example “veg pizza under 300”.

Example request

curl -X POST "https://api.foan.ai/api/v1/catalogues/{id}/search" \
  -H "Authorization: Bearer $FOAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"veg pizza under 300"}'

Response 200

{
  "success": true,
  "data": {
    "results": [
      {
        "product_id": "p_1042",
        "name": "Farmhouse Veg Pizza (Medium)",
        "category_path": [
          "Pizza",
          "Veg"
        ],
        "price": 279,
        "currency": "INR",
        "in_stock": true,
        "short_description": "Capsicum, onion, tomato and mushroom"
      }
    ]
  },
  "message": "Catalogue search complete"
}

Errors

Code	When
400	Rejected by the catalogue service (for example an empty query)
401	Missing, invalid or revoked API key
403	Key lacks knowledge:read
404	Catalogue not found in your organisation
429	Rate limited
502	Knowledge service failed or is unreachable
503	Knowledge service is not configured on this server
504	Knowledge service timed out