{"openapi":"3.1.0","info":{"title":"Attaché Data API","version":"1.0.0","description":"Read-only access to the GA4, Google Ads, Search Console and Meta Ads data shared with one Attaché site. Server-side only. Start with list_sources to get the resource ids."},"servers":[{"url":"https://app.attache.studio"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer"}}},"paths":{"/api/v1/data/list_sources":{"post":{"operationId":"list_sources","summary":"List shared sources","description":"List the connected platforms and the resources (GA4 properties, Google Ads accounts, GSC sites, Meta ad accounts) shared with this connector.","security":[{"bearer":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Raw result of the underlying Google / Meta API, as JSON."},"400":{"description":"{ \"error\": string } — bad parameters or resource not shared."},"401":{"description":"Missing, unknown or revoked key."},"403":{"description":"Called from a browser — call from your backend."},"429":{"description":"Rate limit: 60 requests per minute per key."}}}},"/api/v1/data/get_glossary":{"post":{"operationId":"get_glossary","summary":"Metric glossary","description":"Metric definitions and cross-platform caveats (ROAS, CPA, attribution…). Read before comparing platforms.","security":[{"bearer":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Raw result of the underlying Google / Meta API, as JSON."},"400":{"description":"{ \"error\": string } — bad parameters or resource not shared."},"401":{"description":"Missing, unknown or revoked key."},"403":{"description":"Called from a browser — call from your backend."},"429":{"description":"Rate limit: 60 requests per minute per key."}}}},"/api/v1/data/ga4_run_report":{"post":{"operationId":"ga4_run_report","summary":"GA4 report","description":"Run a GA4 report. Dimensions/metrics use GA4 API names (e.g. sessionDefaultChannelGroup, sessions, keyEvents).","security":[{"bearer":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"property_id":{"type":"string","description":"GA4 property id, from list_sources"},"metrics":{"type":"array","items":{"type":"string"},"minItems":1},"dimensions":{"type":"array","items":{"type":"string"}},"start_date":{"type":"string","description":"YYYY-MM-DD or NdaysAgo or yesterday"},"end_date":{"type":"string"},"limit":{"type":"integer","maximum":1000},"order_bys":{"type":"array","items":{"type":"object","additionalProperties":{}},"description":"GA4 orderBys objects"},"dimension_filter":{"type":"object","additionalProperties":{},"description":"GA4 FilterExpression object"}},"required":["property_id","metrics","start_date","end_date"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Raw result of the underlying Google / Meta API, as JSON."},"400":{"description":"{ \"error\": string } — bad parameters or resource not shared."},"401":{"description":"Missing, unknown or revoked key."},"403":{"description":"Called from a browser — call from your backend."},"429":{"description":"Rate limit: 60 requests per minute per key."}}}},"/api/v1/data/ga4_realtime":{"post":{"operationId":"ga4_realtime","summary":"GA4 realtime report","description":"GA4 realtime report (last 30 minutes).","security":[{"bearer":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"property_id":{"type":"string"},"metrics":{"type":"array","items":{"type":"string"},"minItems":1,"description":"e.g. activeUsers"},"dimensions":{"type":"array","items":{"type":"string"}},"limit":{"type":"integer","maximum":250}},"required":["property_id","metrics"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Raw result of the underlying Google / Meta API, as JSON."},"400":{"description":"{ \"error\": string } — bad parameters or resource not shared."},"401":{"description":"Missing, unknown or revoked key."},"403":{"description":"Called from a browser — call from your backend."},"429":{"description":"Rate limit: 60 requests per minute per key."}}}},"/api/v1/data/gads_run_report":{"post":{"operationId":"gads_run_report","summary":"Google Ads report (GAQL)","description":"Run a read-only Google Ads GAQL report (SELECT … FROM campaign/ad_group/…). Costs are in micros: divide cost_micros by 1e6.","security":[{"bearer":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string","description":"Google Ads customer id (digits, dashes ok), from list_sources"},"query":{"type":"string","description":"GAQL SELECT query"},"login_customer_id":{"type":"string","description":"MCC id if the account is accessed through a manager"}},"required":["customer_id","query"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Raw result of the underlying Google / Meta API, as JSON."},"400":{"description":"{ \"error\": string } — bad parameters or resource not shared."},"401":{"description":"Missing, unknown or revoked key."},"403":{"description":"Called from a browser — call from your backend."},"429":{"description":"Rate limit: 60 requests per minute per key."}}}},"/api/v1/data/gsc_search_analytics":{"post":{"operationId":"gsc_search_analytics","summary":"Search Console performance","description":"Search Console performance: clicks, impressions, CTR, position by query/page/device/country/date.","security":[{"bearer":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"site_url":{"type":"string","description":"Exact siteUrl from list_sources (e.g. sc-domain:example.com)"},"start_date":{"type":"string","description":"YYYY-MM-DD"},"end_date":{"type":"string"},"dimensions":{"type":"array","items":{"type":"string","enum":["query","page","country","device","date","searchAppearance"]}},"row_limit":{"type":"integer","maximum":1000},"dimension_filter_groups":{"type":"array","items":{"type":"object","additionalProperties":{}}}},"required":["site_url","start_date","end_date"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Raw result of the underlying Google / Meta API, as JSON."},"400":{"description":"{ \"error\": string } — bad parameters or resource not shared."},"401":{"description":"Missing, unknown or revoked key."},"403":{"description":"Called from a browser — call from your backend."},"429":{"description":"Rate limit: 60 requests per minute per key."}}}},"/api/v1/data/meta_insights":{"post":{"operationId":"meta_insights","summary":"Meta Ads insights","description":"Meta Ads insights at account/campaign/adset/ad level (spend, impressions, clicks, ROAS…).","security":[{"bearer":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"ad_account_id":{"type":"string","description":"act_<id>, from list_sources"},"level":{"type":"string","enum":["account","campaign","adset","ad"]},"fields":{"type":"array","items":{"type":"string"}},"date_preset":{"type":"string","description":"e.g. last_7d, last_30d, this_month"},"time_range":{"type":"object","properties":{"since":{"type":"string"},"until":{"type":"string"}},"required":["since","until"],"additionalProperties":false},"breakdowns":{"type":"array","items":{"type":"string"}},"limit":{"type":"integer","maximum":500}},"required":["ad_account_id"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Raw result of the underlying Google / Meta API, as JSON."},"400":{"description":"{ \"error\": string } — bad parameters or resource not shared."},"401":{"description":"Missing, unknown or revoked key."},"403":{"description":"Called from a browser — call from your backend."},"429":{"description":"Rate limit: 60 requests per minute per key."}}}},"/api/v1/data/prestashop_sales_report":{"post":{"operationId":"prestashop_sales_report","summary":"PrestaShop sales","description":"The shop's own sales over a period: valid orders, revenue (tax incl. and excl.), average order value, shipping, discounts, unique customers — totals plus a breakdown by day, week, month, order status or payment method, per currency. The shop's numbers are the reference against GA4 or ad-platform revenue.","security":[{"bearer":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"shop_url":{"type":"string","description":"Shop URL exactly as in list_sources (prestashop resource), e.g. https://www.example.com"},"start_date":{"type":"string","description":"YYYY-MM-DD"},"end_date":{"type":"string","description":"YYYY-MM-DD, inclusive"},"group_by":{"type":"string","enum":["day","week","month","status","payment","none"],"description":"Default: day"},"include_invalid":{"type":"boolean","description":"Also count unpaid, cancelled and refunded orders. Default false."}},"required":["shop_url","start_date","end_date"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Raw result of the underlying Google / Meta API, as JSON."},"400":{"description":"{ \"error\": string } — bad parameters or resource not shared."},"401":{"description":"Missing, unknown or revoked key."},"403":{"description":"Called from a browser — call from your backend."},"429":{"description":"Rate limit: 60 requests per minute per key."}}}},"/api/v1/data/prestashop_top_products":{"post":{"operationId":"prestashop_top_products","summary":"PrestaShop best sellers","description":"Best-selling products over a period, from the order lines of valid orders: quantity, number of orders, revenue tax incl. and excl.","security":[{"bearer":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"shop_url":{"type":"string","description":"Shop URL exactly as in list_sources (prestashop resource), e.g. https://www.example.com"},"start_date":{"type":"string","description":"YYYY-MM-DD"},"end_date":{"type":"string","description":"YYYY-MM-DD, inclusive"},"limit":{"type":"integer","minimum":1,"maximum":200,"description":"Default 20"},"include_invalid":{"type":"boolean"}},"required":["shop_url","start_date","end_date"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Raw result of the underlying Google / Meta API, as JSON."},"400":{"description":"{ \"error\": string } — bad parameters or resource not shared."},"401":{"description":"Missing, unknown or revoked key."},"403":{"description":"Called from a browser — call from your backend."},"429":{"description":"Rate limit: 60 requests per minute per key."}}}},"/api/v1/data/prestashop_query":{"post":{"operationId":"prestashop_query","summary":"PrestaShop data","description":"Read any allowed PrestaShop Webservice resource directly (orders, order_details, products, stock_availables, cart_rules…) with PrestaShop filters, for questions the sales and best-seller reports do not cover. Customer and address data is not available. Max 500 rows per call; page with offset.","security":[{"bearer":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"shop_url":{"type":"string","description":"Shop URL exactly as in list_sources (prestashop resource), e.g. https://www.example.com"},"resource":{"type":"string","enum":["orders","order_details","order_states","order_histories","order_carriers","products","combinations","categories","manufacturers","stock_availables","carriers","currencies","cart_rules","shops"]},"display":{"type":"string","description":"\"full\" (default) or a field list like [id,reference,price,active]"},"filters":{"type":"object","additionalProperties":{"type":"string"},"description":"PrestaShop filters by field, e.g. {\"active\":\"[1]\",\"date_add\":\"[2026-01-01,2026-01-31]\",\"reference\":\"%[ABC]%\"}"},"sort":{"type":"string","description":"e.g. [date_add_DESC]"},"limit":{"type":"integer","minimum":1,"maximum":500},"offset":{"type":"integer","minimum":0},"language":{"type":"integer","description":"Language id, to get plain strings instead of per-language arrays"}},"required":["shop_url","resource"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Raw result of the underlying Google / Meta API, as JSON."},"400":{"description":"{ \"error\": string } — bad parameters or resource not shared."},"401":{"description":"Missing, unknown or revoked key."},"403":{"description":"Called from a browser — call from your backend."},"429":{"description":"Rate limit: 60 requests per minute per key."}}}}}}