{
  "openapi": "3.1.0",
  "info": {
    "title": "Build by SellerMate API",
    "version": "1",
    "summary": "One API for marketplace and ad data.",
    "description": "One POST per tool, the same field names on every platform, scoped keys. Writes exist on Amazon only; every other platform is read-only. The call shape is v1 and illustrative until the contract is final. Docs: https://build.sellermate.ai/docs. Put the key in the BUILD_API_KEY environment variable of your tool.",
    "x-to-confirm": true
  },
  "servers": [
    {
      "url": "https://build-api.sellermate.ai/v1",
      "description": "Build API, v1"
    }
  ],
  "tags": [
    {
      "name": "amazon",
      "description": "Tools that work on Amazon."
    },
    {
      "name": "google-ads",
      "description": "Tools that work on Google Ads."
    }
  ],
  "security": [
    {
      "apiKey": []
    }
  ],
  "externalDocs": {
    "description": "Build docs",
    "url": "https://build.sellermate.ai/docs"
  },
  "paths": {
    "/tools/get_campaign_performance": {
      "post": {
        "operationId": "get_campaign_performance",
        "summary": "Get spend, clicks, orders, sales and ACoS for each campaign over a date range.",
        "description": "Call it for client reports, budget pacing, an exec card or a ranked board. Ask for the same dates on Amazon and Google Ads to put them side by side. Rows use the same field names on every platform.",
        "tags": [
          "amazon",
          "google-ads"
        ],
        "x-platforms": [
          "amazon",
          "google-ads"
        ],
        "x-writes": false,
        "security": [
          {
            "apiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "account": {
                    "type": "string",
                    "description": "The account to read. A key only reaches the accounts you chose when you created it.",
                    "example": "acct_123"
                  },
                  "start": {
                    "type": "string",
                    "format": "date",
                    "description": "First day, as YYYY-MM-DD.",
                    "example": "2026-10-01"
                  },
                  "end": {
                    "type": "string",
                    "format": "date",
                    "description": "Last day, as YYYY-MM-DD.",
                    "example": "2026-10-28"
                  }
                },
                "required": [
                  "account"
                ]
              },
              "example": {
                "account": "acct_123",
                "start": "2026-10-01",
                "end": "2026-10-28"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Rows and meta. meta.data_as_of says how fresh the answer is.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "rows": {
                      "type": "array",
                      "description": "Rows in the same field names on every platform.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "platform": {
                            "type": "string",
                            "description": "The platform the row came from, for example amazon or google_ads.",
                            "example": "amazon",
                            "x-to-confirm": true
                          },
                          "account_id": {
                            "type": "string",
                            "description": "The account the row belongs to.",
                            "example": "amz_northwind",
                            "x-to-confirm": true
                          },
                          "campaign_name": {
                            "type": "string",
                            "description": "The campaign, as named on the platform.",
                            "example": "SP - Bottles - Exact",
                            "x-to-confirm": true
                          },
                          "spend": {
                            "type": "number",
                            "description": "Spend over the period, in the account currency.",
                            "example": 1842.1,
                            "x-to-confirm": true
                          },
                          "clicks": {
                            "type": "number",
                            "description": "Clicks over the period.",
                            "example": 2210,
                            "x-to-confirm": true
                          },
                          "orders": {
                            "type": "number",
                            "description": "Orders over the period.",
                            "example": 161,
                            "x-to-confirm": true
                          },
                          "sales": {
                            "type": "number",
                            "description": "Sales over the period, in the account currency.",
                            "example": 6120.4,
                            "x-to-confirm": true
                          },
                          "acos": {
                            "type": "number",
                            "description": "Spend divided by sales, as a fraction.",
                            "example": 0.301,
                            "x-to-confirm": true
                          },
                          "currency": {
                            "type": "string",
                            "description": "One currency per account.",
                            "example": "USD",
                            "x-to-confirm": true
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "data_as_of": {
                          "type": "string",
                          "format": "date-time",
                          "description": "When the data was last pulled, in UTC. Quote it when you report numbers."
                        }
                      }
                    }
                  },
                  "required": [
                    "rows",
                    "meta"
                  ],
                  "x-to-confirm": true
                },
                "example": {
                  "rows": [
                    {
                      "platform": "amazon",
                      "account_id": "amz_northwind",
                      "campaign_name": "SP - Bottles - Exact",
                      "spend": 1842.1,
                      "clicks": 2210,
                      "orders": 161,
                      "sales": 6120.4,
                      "acos": 0.301,
                      "currency": "USD"
                    }
                  ],
                  "meta": {
                    "data_as_of": "2026-10-30T06:00:00Z"
                  }
                },
                "x-to-confirm": true
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "5XX": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/tools/get_search_term_performance": {
      "post": {
        "operationId": "get_search_term_performance",
        "summary": "Get search terms with their clicks, spend and orders over a date range.",
        "description": "Call it to find search terms that spend and never sell, or to keep search-term history past the window the platform holds. Amazon keeps search terms for about 60 to 95 days; Build keeps them from the day you connect.",
        "tags": [
          "amazon",
          "google-ads"
        ],
        "x-platforms": [
          "amazon",
          "google-ads"
        ],
        "x-writes": false,
        "security": [
          {
            "apiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "account": {
                    "type": "string",
                    "description": "The account to read. A key only reaches the accounts you chose when you created it.",
                    "example": "acct_123"
                  },
                  "start": {
                    "type": "string",
                    "format": "date",
                    "description": "First day, as YYYY-MM-DD.",
                    "example": "2026-10-01"
                  },
                  "end": {
                    "type": "string",
                    "format": "date",
                    "description": "Last day, as YYYY-MM-DD.",
                    "example": "2026-10-28"
                  }
                },
                "required": [
                  "account"
                ]
              },
              "example": {
                "account": "acct_123",
                "start": "2026-10-01",
                "end": "2026-10-28"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Rows and meta. meta.data_as_of says how fresh the answer is.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "rows": {
                      "type": "array",
                      "description": "Rows in the same field names on every platform.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "platform": {
                            "type": "string",
                            "description": "The platform the row came from.",
                            "x-to-confirm": true
                          },
                          "account_id": {
                            "type": "string",
                            "description": "The account the row belongs to.",
                            "x-to-confirm": true
                          },
                          "search_term": {
                            "type": "string",
                            "description": "The search term.",
                            "x-to-confirm": true
                          },
                          "clicks": {
                            "type": "number",
                            "description": "Clicks over the period.",
                            "x-to-confirm": true
                          },
                          "spend": {
                            "type": "number",
                            "description": "Spend over the period, in the account currency.",
                            "x-to-confirm": true
                          },
                          "orders": {
                            "type": "number",
                            "description": "Orders over the period.",
                            "x-to-confirm": true
                          }
                        },
                        "additionalProperties": true,
                        "x-to-confirm": true
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "data_as_of": {
                          "type": "string",
                          "format": "date-time",
                          "description": "When the data was last pulled, in UTC. Quote it when you report numbers."
                        }
                      }
                    }
                  },
                  "required": [
                    "rows",
                    "meta"
                  ],
                  "x-to-confirm": true
                },
                "example": {
                  "rows": [],
                  "meta": {
                    "data_as_of": "2026-10-30T06:00:00Z"
                  }
                },
                "x-to-confirm": true
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "5XX": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/tools/get_orders_report": {
      "post": {
        "operationId": "get_orders_report",
        "summary": "Get orders and units for an Amazon Seller account over a date range.",
        "description": "Call it for revenue and units in a weekly card, a month-end export, or days of stock. Sales keep moving for up to 14 days, and Build re-pulls those days until they settle.",
        "tags": [
          "amazon"
        ],
        "x-platforms": [
          "amazon"
        ],
        "x-writes": false,
        "security": [
          {
            "apiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "account": {
                    "type": "string",
                    "description": "The account to read. A key only reaches the accounts you chose when you created it.",
                    "example": "acct_123"
                  },
                  "start": {
                    "type": "string",
                    "format": "date",
                    "description": "First day, as YYYY-MM-DD.",
                    "example": "2026-10-01"
                  },
                  "end": {
                    "type": "string",
                    "format": "date",
                    "description": "Last day, as YYYY-MM-DD.",
                    "example": "2026-10-28"
                  }
                },
                "required": [
                  "account"
                ]
              },
              "example": {
                "account": "acct_123",
                "start": "2026-10-01",
                "end": "2026-10-28"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Rows and meta. meta.data_as_of says how fresh the answer is.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "rows": {
                      "type": "array",
                      "description": "Rows in the same field names on every platform.",
                      "items": {
                        "type": "object",
                        "properties": {},
                        "additionalProperties": true,
                        "x-to-confirm": true
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "data_as_of": {
                          "type": "string",
                          "format": "date-time",
                          "description": "When the data was last pulled, in UTC. Quote it when you report numbers."
                        },
                        "settling_from": {
                          "type": "string",
                          "format": "date-time",
                          "description": "When recent days are still moving, the first day that is still settling. Treat rows on or after it as provisional.",
                          "x-to-confirm": true
                        }
                      }
                    }
                  },
                  "required": [
                    "rows",
                    "meta"
                  ],
                  "x-to-confirm": true
                },
                "example": {
                  "rows": [],
                  "meta": {
                    "data_as_of": "2026-10-30T06:00:00Z"
                  }
                },
                "x-to-confirm": true
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "5XX": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/tools/get_inventory": {
      "post": {
        "operationId": "get_inventory",
        "summary": "Get stock and inbound units for an Amazon account.",
        "description": "Call it to work out days of stock, alert before a stock-out, or decide when to pause ads on a SKU.",
        "tags": [
          "amazon"
        ],
        "x-platforms": [
          "amazon"
        ],
        "x-writes": false,
        "security": [
          {
            "apiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "account": {
                    "type": "string",
                    "description": "The account to read. A key only reaches the accounts you chose when you created it.",
                    "example": "acct_123"
                  }
                },
                "required": [
                  "account"
                ]
              },
              "example": {
                "account": "acct_123"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Rows and meta. meta.data_as_of says how fresh the answer is.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "rows": {
                      "type": "array",
                      "description": "Rows in the same field names on every platform.",
                      "items": {
                        "type": "object",
                        "properties": {},
                        "additionalProperties": true,
                        "x-to-confirm": true
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "data_as_of": {
                          "type": "string",
                          "format": "date-time",
                          "description": "When the data was last pulled, in UTC. Quote it when you report numbers."
                        }
                      }
                    }
                  },
                  "required": [
                    "rows",
                    "meta"
                  ],
                  "x-to-confirm": true
                },
                "example": {
                  "rows": [],
                  "meta": {
                    "data_as_of": "2026-10-30T06:00:00Z"
                  }
                },
                "x-to-confirm": true
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "5XX": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/tools/update_target": {
      "post": {
        "operationId": "update_target",
        "summary": "Change a target on an Amazon Ads account, behind caps, a dry run and undo.",
        "description": "Call it to apply a bid change after your code or a person has approved it. Send dry_run first. It needs a key with the read and write scope, and works on Amazon accounts only. A change above a cap returns 422 and nothing is applied.",
        "tags": [
          "amazon"
        ],
        "x-platforms": [
          "amazon"
        ],
        "x-writes": true,
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Send a unique value so a retry never applies a change twice.",
            "schema": {
              "type": "string"
            },
            "x-to-confirm": true
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "account": {
                    "type": "string",
                    "description": "The account to read. A key only reaches the accounts you chose when you created it.",
                    "example": "acct_123"
                  },
                  "dry_run": {
                    "type": "boolean",
                    "description": "When true, check the change against the guardrails and return the result without applying it.",
                    "example": true,
                    "x-to-confirm": true
                  },
                  "changes": {
                    "type": "array",
                    "description": "The target changes to make.",
                    "example": [
                      {
                        "target_id": "tgt_41c",
                        "bid": 1.9
                      }
                    ],
                    "x-to-confirm": true
                  }
                },
                "required": [
                  "account"
                ]
              },
              "example": {
                "account": "acct_123",
                "dry_run": true,
                "changes": [
                  {
                    "target_id": "tgt_41c",
                    "bid": 1.9
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The dry-run result, or the applied change. Applied changes are logged and can be undone for 24 hours.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "rows": {
                      "type": "array",
                      "description": "Rows in the same field names on every platform.",
                      "items": {
                        "type": "object",
                        "properties": {},
                        "additionalProperties": true,
                        "x-to-confirm": true
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "data_as_of": {
                          "type": "string",
                          "format": "date-time",
                          "description": "When the data was last pulled, in UTC. Quote it when you report numbers."
                        }
                      }
                    }
                  },
                  "required": [
                    "rows",
                    "meta"
                  ],
                  "x-to-confirm": true
                },
                "example": {
                  "rows": [],
                  "meta": {
                    "data_as_of": "2026-10-30T06:00:00Z"
                  }
                },
                "x-to-confirm": true
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "5XX": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "A Build key. sm_live_ keys are read, or read and write, and scoped to accounts. sm_test_ is the read-only sandbox key on demo data."
      }
    },
    "schemas": {
      "Problem": {
        "type": "object",
        "description": "Problem Details (RFC 9457) for every 4xx and 5xx. The exact members are illustrative until the contract is final.",
        "properties": {
          "type": {
            "type": "string",
            "format": "uri-reference",
            "description": "A URI that names the kind of problem."
          },
          "status": {
            "type": "integer",
            "description": "The HTTP status."
          },
          "detail": {
            "type": "string",
            "description": "What went wrong and what to change."
          },
          "errors": {
            "type": "array",
            "description": "One entry per field that failed.",
            "items": {
              "type": "object",
              "properties": {
                "field": {
                  "type": "string",
                  "description": "The request field, for example changes[0].bid."
                },
                "code": {
                  "type": "string",
                  "description": "A short machine-readable code."
                },
                "message": {
                  "type": "string",
                  "description": "What is wrong with the field."
                }
              },
              "required": [
                "field",
                "code",
                "message"
              ]
            }
          },
          "retry": {
            "type": "integer",
            "description": "On 429: seconds to wait before retrying.",
            "x-to-confirm": true
          },
          "upgrade": {
            "type": "string",
            "format": "uri",
            "description": "On 429: where to raise the plan limit.",
            "x-to-confirm": true
          }
        },
        "required": [
          "status",
          "detail"
        ],
        "x-to-confirm": true
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "The key is missing or wrong.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "example": {
              "status": 401,
              "detail": "The X-API-Key header is missing or the key is not valid."
            }
          }
        },
        "x-to-confirm": true
      },
      "Forbidden": {
        "description": "The key cannot reach this account or tool, for example a read key on a write tool.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "example": {
              "status": 403,
              "detail": "This key cannot reach account acct_123."
            }
          }
        },
        "x-to-confirm": true
      },
      "Unprocessable": {
        "description": "The request is valid JSON but a rule refused it. On a write tool, a change above a cap is refused and nothing is applied.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "example": {
              "status": 422,
              "detail": "bid 2.40 is above this account's ceiling of 2.00.",
              "errors": [
                {
                  "field": "changes[0].bid",
                  "code": "guardrail_blocked",
                  "message": "bid 2.40 is above this account's ceiling of 2.00."
                }
              ]
            }
          }
        },
        "x-to-confirm": true
      },
      "RateLimited": {
        "description": "You went over the plan's requests per minute. Wait Retry-After seconds, then retry.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "example": {
              "status": 429,
              "detail": "Rate limit reached for this plan.",
              "retry": 12,
              "upgrade": "https://build.sellermate.ai/pricing"
            }
          }
        },
        "headers": {
          "Retry-After": {
            "description": "Seconds to wait before the next request.",
            "schema": {
              "type": "integer"
            },
            "example": 12
          }
        }
      },
      "ServerError": {
        "description": "Something failed on the Build side. Reads are safe to retry.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "example": {
              "status": 500,
              "detail": "Something went wrong. Try again."
            }
          }
        },
        "x-to-confirm": true
      }
    }
  }
}