The Optimizer API

# Recast Optimizer API — R Usage Example
#
# Workflow: List → Show → Modify form → Create → Poll → Download CSV
#
# Prerequisites:
#   install.packages(c("httr2", "jsonlite"))
#   Add to .Renviron: API_PAT=gr_your_token_here

library(httr2)
library(jsonlite)

BASE_URL    <- "https://app.getrecast.com"
CLIENT_SLUG <- "democlient" #Update to your client
PAT         <- Sys.getenv("API_PAT")

parse <- \(resp) resp |> resp_body_string() |> fromJSON(simplifyVector = FALSE)

check <- function(resp, expected = 200) {
  if (resp_status(resp) != expected) {
    stop(sprintf("HTTP %d: %s", resp_status(resp), resp_body_string(resp)))
  }
  resp
}

opt_request <- function(...) {
  request(BASE_URL) |>
    req_url_path_append("api", "v1", "clients", CLIENT_SLUG, "optimizations", ...) |>
    req_auth_bearer_token(PAT) |>
    req_headers(Accept = "application/json") |>
    req_error(is_error = \(resp) FALSE)
}

# Step 1: List optimizations and pick a successful one as a template
list_resp <- opt_request() |> req_url_query(page = 1, per_page = 10) |> req_perform() |> check()
optimizations <- parse(list_resp)$data
template_id <- Filter(\(x) x$status == "success", optimizations)[[1]]$id

# Step 2: Get the full optimization and extract its form
optimization <- opt_request(template_id) |> req_perform() |> check() |> parse()
form <- optimization$form

# Step 3: Modify the form and submit a new optimization
form$target <- as.character(round(as.numeric(form$target) * 1.1))

resp <- opt_request() |>
  req_method("POST") |>
  req_headers(`Content-Type` = "application/json") |>
  req_body_json(list(
    form = form,
    name = paste("API Example -", Sys.time()),
    show_in_ui = FALSE,
    use_latest_deployments = TRUE
  ), auto_unbox = TRUE) |>
  req_perform() |>
  check(expected = 201)

new_id <- parse(resp)$id
cat(sprintf("Created optimization %d\n", new_id))

# Step 4: Poll until complete (typically 1–6 minutes)
repeat {
  result <- opt_request(new_id) |> req_perform() |> parse()
  cat(sprintf("Status: %s\n", result$status))
  if (result$status != "processing") break
  Sys.sleep(30)
}

# Step 5: Download first available CSV
dl_key  <- result$results[[1]]$downloads[[1]]$key
csv_resp <- opt_request(new_id, "downloads", dl_key) |>
  req_headers(Accept = "text/csv") |>
  req_perform() |>
  check()

csv_data <- read.csv(text = resp_body_string(csv_resp), check.names = FALSE)
head(csv_data)

# Recast Optimizer API — Python Usage Example
#
# Workflow: List → Show → Modify form → Create → Poll → Download CSV
#
# Prerequisites:
#   pip install requests pandas
#   Set environment variable: export API_PAT=gr_your_token_here

import os
import time
import io
import requests
import pandas as pd
from datetime import datetime

BASE_URL    = "https://app.getrecast.com"
CLIENT_SLUG = "democlient"  # Update to your client
PAT         = os.environ["API_PAT"]

BASE_PATH = f"{BASE_URL}/api/v1/clients/{CLIENT_SLUG}/optimizations"
HEADERS   = {"Authorization": f"Bearer {PAT}", "Accept": "application/json"}

def check(resp, expected=200):
    if resp.status_code != expected:
        raise Exception(f"HTTP {resp.status_code}: {resp.text}")
    return resp

# Step 1: List optimizations and pick a successful one as a template
optimizations = check(requests.get(BASE_PATH, headers=HEADERS, params={"page": 1, "per_page": 10})).json()["data"]
template_id = next(o["id"] for o in optimizations if o["status"] == "success")

# Step 2: Get the full optimization and extract its form
optimization = check(requests.get(f"{BASE_PATH}/{template_id}", headers=HEADERS)).json()
form = optimization["form"]

# Step 3: Modify the form and submit a new optimization
form["target"] = str(round(float(form["target"]) * 1.1))

resp = check(requests.post(BASE_PATH, headers={**HEADERS, "Content-Type": "application/json"}, json={
    "form": form,
    "name": f"API Example - {datetime.now()}",
    "show_in_ui": False,
    "use_latest_deployments": True,
}), expected=201)

new_id = resp.json()["id"]
print(f"Created optimization {new_id}")

# Step 4: Poll until complete (typically 1–6 minutes)
while True:
    result = requests.get(f"{BASE_PATH}/{new_id}", headers=HEADERS).json()
    print(f"Status: {result['status']}")
    if result["status"] != "processing":
        break
    time.sleep(30)

# Step 5: Download first available CSV
dl_key = result["results"][0]["downloads"][0]["key"]
csv_resp = check(requests.get(f"{BASE_PATH}/{new_id}/downloads/{dl_key}", headers={**HEADERS, "Accept": "text/csv"}))

csv_data = pd.read_csv(io.StringIO(csv_resp.text))
print(csv_data.head())