{"openapi":"3.1.0","info":{"title":"SNCF Open Data (BYOK) API","version":"0.1.0","description":"SNCF Open Data (BYOK) lets an AI assistant read your own SNCF Open Data data through the SNCF Open Data API with a key you supply (SNCF Open Data portal API key). Read-only: 7 tools (list_datasets, get_dataset, query_records, get_record, get_dataset_facets, get_catalog_facets, list_dataset_attachments). The BYOK key travels with each request, is used for that one call only and is never stored,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-sncfopendata.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-sncfopendata/docs"},"termsOfService":"https://connectorbay.com/byok-sncfopendata/terms"},"servers":[{"url":"https://byok-sncfopendata.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-sncfopendata/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/list_datasets":{"post":{"operationId":"list_datasets","summary":"List and search the datasets of the portal catalog with ODSQL filters, facet refinements, ordering and paging. Each entr","description":"List and search the datasets of the portal catalog with ODSQL filters, facet refinements, ordering and paging. Each entry carries its id, metadata and field definitions. Use for \"Which datasets about train stations does the SNCF Open Data portal have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"select":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated fields or ODSQL expressions to return, for example 'name, size * 2 as bigger_size'.","title":"Select"},"where":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"ODSQL filter: a full-text search or conditions, for example \"title like 'transport'\" or \"population > 1000 AND city = 'Paris'\".","title":"Where"},"order_by":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Sort expression, for example 'modified desc'.","title":"Order By"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Number of items to return (1 to 100; offset plus limit must stay below 10000).","title":"Limit"},"offset":{"anyOf":[{"maximum":10000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Index of the first item to return, starting at 0 (offset plus limit must stay below 10000).","title":"Offset"},"refine":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Facet filter in the form facet:value, for example 'modified:2024'; only one value is accepted per call.","title":"Refine"},"exclude":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Facet exclusion in the form facet:value; only one value is accepted per call.","title":"Exclude"},"lang":{"anyOf":[{"enum":["en","fr","nl","pt","it","ar","de","es","ca","eu","sv"],"type":"string"},{"type":"null"}],"default":null,"description":"Language for formatting and labels.","title":"Lang"},"timezone":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Timezone for datetime fields, an IANA id such as Europe/Paris (default UTC).","title":"Timezone"}},"title":"list_datasetsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_dataset":{"post":{"operationId":"get_dataset","summary":"Get one dataset's metadata and the definition of its fields (name, label, type, description). Use for \"What fields does ","description":"Get one dataset's metadata and the definition of its fields (name, label, type, description). Use for \"What fields does the train stations dataset have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dataset_id":{"description":"Dataset identifier from list_datasets (shown in the dataset's Information tab or in its URL after /datasets/).","maxLength":200,"title":"Dataset Id","type":"string"},"select":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated fields or ODSQL expressions to return, for example 'name, size * 2 as bigger_size'.","title":"Select"},"lang":{"anyOf":[{"enum":["en","fr","nl","pt","it","ar","de","es","ca","eu","sv"],"type":"string"},{"type":"null"}],"default":null,"description":"Language for formatting and labels.","title":"Lang"},"timezone":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Timezone for datetime fields, an IANA id such as Europe/Paris (default UTC).","title":"Timezone"}},"required":["dataset_id"],"title":"get_datasetArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/query_records":{"post":{"operationId":"query_records","summary":"Query the records of a dataset with ODSQL: select fields, filter with where/refine/exclude, group and aggregate, order a","description":"Query the records of a dataset with ODSQL: select fields, filter with where/refine/exclude, group and aggregate, order and page. Field names depend on the dataset (see get_dataset). Use for \"Show the first 20 records of the train stations dataset\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dataset_id":{"description":"Dataset identifier from list_datasets (shown in the dataset's Information tab or in its URL after /datasets/).","maxLength":200,"title":"Dataset Id","type":"string"},"select":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated fields or ODSQL expressions to return, for example 'name, size * 2 as bigger_size'.","title":"Select"},"where":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"ODSQL filter: a full-text search or conditions, for example \"title like 'transport'\" or \"population > 1000 AND city = 'Paris'\".","title":"Where"},"group_by":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Grouping expression for aggregations, for example 'city as c'.","title":"Group By"},"order_by":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated sort, for example 'population desc, name asc'.","title":"Order By"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Number of items to return (1 to 100; offset plus limit must stay below 10000).","title":"Limit"},"offset":{"anyOf":[{"maximum":10000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Index of the first item to return, starting at 0 (offset plus limit must stay below 10000).","title":"Offset"},"refine":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Facet filter in the form facet:value, for example 'modified:2024'; only one value is accepted per call.","title":"Refine"},"exclude":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Facet exclusion in the form facet:value; only one value is accepted per call.","title":"Exclude"},"lang":{"anyOf":[{"enum":["en","fr","nl","pt","it","ar","de","es","ca","eu","sv"],"type":"string"},{"type":"null"}],"default":null,"description":"Language for formatting and labels.","title":"Lang"},"timezone":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Timezone for datetime fields, an IANA id such as Europe/Paris (default UTC).","title":"Timezone"}},"required":["dataset_id"],"title":"query_recordsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_record":{"post":{"operationId":"get_record","summary":"Read one record of a dataset by its record id. Use for \"Show a single record of the train stations dataset by its id\".","description":"Read one record of a dataset by its record id. Use for \"Show a single record of the train stations dataset by its id\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dataset_id":{"description":"Dataset identifier from list_datasets (shown in the dataset's Information tab or in its URL after /datasets/).","maxLength":200,"title":"Dataset Id","type":"string"},"record_id":{"description":"Record identifier (the _id of a record from query_records).","maxLength":200,"title":"Record Id","type":"string"},"select":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated fields or ODSQL expressions to return, for example 'name, size * 2 as bigger_size'.","title":"Select"},"lang":{"anyOf":[{"enum":["en","fr","nl","pt","it","ar","de","es","ca","eu","sv"],"type":"string"},{"type":"null"}],"default":null,"description":"Language for formatting and labels.","title":"Lang"},"timezone":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Timezone for datetime fields, an IANA id such as Europe/Paris (default UTC).","title":"Timezone"}},"required":["dataset_id","record_id"],"title":"get_recordArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_dataset_facets":{"post":{"operationId":"get_dataset_facets","summary":"Enumerate the values of a dataset's facet fields with their record counts, optionally narrowed by a filter. Use for \"Whi","description":"Enumerate the values of a dataset's facet fields with their record counts, optionally narrowed by a filter. Use for \"Which categories appear in the train stations dataset and how many records each\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dataset_id":{"description":"Dataset identifier from list_datasets (shown in the dataset's Information tab or in its URL after /datasets/).","maxLength":200,"title":"Dataset Id","type":"string"},"facet":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Name of the facet field to enumerate; leave empty for all facets.","title":"Facet"},"where":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"ODSQL filter: a full-text search or conditions, for example \"title like 'transport'\" or \"population > 1000 AND city = 'Paris'\".","title":"Where"},"refine":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Facet filter in the form facet:value, for example 'modified:2024'; only one value is accepted per call.","title":"Refine"},"exclude":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Facet exclusion in the form facet:value; only one value is accepted per call.","title":"Exclude"},"lang":{"anyOf":[{"enum":["en","fr","nl","pt","it","ar","de","es","ca","eu","sv"],"type":"string"},{"type":"null"}],"default":null,"description":"Language for formatting and labels.","title":"Lang"},"timezone":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Timezone for datetime fields, an IANA id such as Europe/Paris (default UTC).","title":"Timezone"}},"required":["dataset_id"],"title":"get_dataset_facetsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_catalog_facets":{"post":{"operationId":"get_catalog_facets","summary":"Enumerate the values of the catalog's dataset facets (themes, publishers, keywords and similar) with counts. Use for \"Wh","description":"Enumerate the values of the catalog's dataset facets (themes, publishers, keywords and similar) with counts. Use for \"Which themes do the datasets of the SNCF Open Data portal use\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"facet":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Name of the facet field to enumerate; leave empty for all facets.","title":"Facet"},"where":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"ODSQL filter: a full-text search or conditions, for example \"title like 'transport'\" or \"population > 1000 AND city = 'Paris'\".","title":"Where"},"refine":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Facet filter in the form facet:value, for example 'modified:2024'; only one value is accepted per call.","title":"Refine"},"exclude":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Facet exclusion in the form facet:value; only one value is accepted per call.","title":"Exclude"},"timezone":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Timezone for datetime fields, an IANA id such as Europe/Paris (default UTC).","title":"Timezone"}},"title":"get_catalog_facetsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_dataset_attachments":{"post":{"operationId":"list_dataset_attachments","summary":"List the files attached to a dataset (documentation, PDFs, archives) with their titles and URLs. Use for \"Are there docu","description":"List the files attached to a dataset (documentation, PDFs, archives) with their titles and URLs. Use for \"Are there documents attached to the train stations dataset\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dataset_id":{"description":"Dataset identifier from list_datasets (shown in the dataset's Information tab or in its URL after /datasets/).","maxLength":200,"title":"Dataset Id","type":"string"}},"required":["dataset_id"],"title":"list_dataset_attachmentsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}