Skip to main content

​
Workflow Overview

  1. Authentication
    • Establish a secure session by authenticating against the API.
    • Include your API key in the Authorization header as Bearer <YOUR_API_KEY>.
  2. Dataset Upload
    • Upload tabular training data by sending a POST request to /api/datasets.
    • System Response: Returns a dataset_id which you will use for training.
  3. Model Training Initiation
    • Trigger a training job via a POST request to /api/models/train.
    • Provide the model_name, model_type (e.g., prediction), dataset_id, and label_column in the JSON payload.
    • System Response: Returns a unique model_id and an initial status of processing.
  4. Training Status Monitoring
    • Monitor job progress by polling the model details via a GET request to /api/models/{model_id}.
    • Wait for the status to transition to ready before proceeding.
  5. Inference Execution
    • Synchronous: Send a POST request to /api/models/{model_id}/infer with a multipart file upload. Returns results immediately.
    • Batch: Send a POST request to /api/models/{model_id}/infer-batch with a dataset_id reference. Runs asynchronously.

​
Example Requests

Set your environment variables: 
export WOODWIDE_API_KEY="sk_your_api_key_here"
export BASE_URL="https://beta.woodwide.ai"

​
List Datasets

curl -X GET "$BASE_URL/api/datasets" \
  -H "Authorization: Bearer $WOODWIDE_API_KEY"

​
Create a New Dataset

curl -X POST "$BASE_URL/api/datasets" \
  -H "Authorization: Bearer $WOODWIDE_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@mydata.csv" \
  -F "dataset_name=mydata" \
  -F "overrides=true"

​
Train a New Model

curl -X POST "$BASE_URL/api/models/train" \
  -H "Authorization: Bearer $WOODWIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "my_model",
    "model_type": "prediction",
    "dataset_id": "YOUR_DATASET_ID",
    "label_column": "target_column"
  }'

​
Check Model Status

curl -X GET "$BASE_URL/api/models/{model_id}" \
  -H "Authorization: Bearer $WOODWIDE_API_KEY"

​
Run Synchronous Inference

curl -X POST "$BASE_URL/api/models/{model_id}/infer" \
  -H "Authorization: Bearer $WOODWIDE_API_KEY" \
  -F "file=@test_data.csv" \
  -F "output_type=csv"

​
Example Script for Training and Inference

This script automates the end-to-end process of uploading a dataset, training a prediction model, and running inference. 
#!/bin/sh

export BASE_URL="https://beta.woodwide.ai"

usage() {
    echo "Usage: $0 -k API_KEY -m MODEL_NAME -d DATASET_NAME -r TRAIN_DATA -t TEST_DATA -l LABEL_COLUMN [-o OUTPUT_FILE]"
    exit 1
}

if ! command -v jq > /dev/null 2>&1; then
    echo "Error: jq is required but not installed."
    exit 1
fi

while getopts ":k:m:d:r:t:l:o:" opt; do
  case $opt in
    k) WOODWIDE_API_KEY="$OPTARG" ;;
    m) MODEL_NAME="$OPTARG" ;;
    d) DATASET_NAME="$OPTARG" ;;
    r) TRAIN_DATA="$OPTARG" ;;
    t) TEST_DATA="$OPTARG" ;;
    l) LABEL_COLUMN="$OPTARG" ;;
    o) OUTPUT_FILE="$OPTARG" ;;
    \?) usage ;;
  esac
done

if [ -z "$WOODWIDE_API_KEY" ] || [ -z "$MODEL_NAME" ] || [ -z "$DATASET_NAME" ] || [ -z "$TRAIN_DATA" ] || [ -z "$TEST_DATA" ] || [ -z "$LABEL_COLUMN" ]; then
    usage
fi

get_id() {
    echo "$1" | jq -r "$2 // empty"
}

echo "Step 1: Uploading Training Dataset..."
UPLOAD_RESP=$(curl -s -X POST "$BASE_URL/api/datasets" \
  -H "Authorization: Bearer $WOODWIDE_API_KEY" \
  -F "file=@$TRAIN_DATA" \
  -F "dataset_name=$DATASET_NAME" \
  -F "overrides=true")

DATASET_ID=$(get_id "$UPLOAD_RESP" ".dataset_id")
if [ -z "$DATASET_ID" ]; then 
    echo "Upload failed: $UPLOAD_RESP"
    exit 1
fi
echo "Dataset ID: $DATASET_ID"

echo "Step 2: Starting Model Training..."
TRAIN_RESP=$(curl -s -X POST "$BASE_URL/api/models/train" \
  -H "Authorization: Bearer $WOODWIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model_name\": \"$MODEL_NAME\",
    \"model_type\": \"prediction\",
    \"dataset_id\": \"$DATASET_ID\",
    \"label_column\": \"$LABEL_COLUMN\"
  }")

MODEL_ID=$(get_id "$TRAIN_RESP" ".model_id")
if [ -z "$MODEL_ID" ]; then 
    echo "Training failed to start: $TRAIN_RESP"
    exit 1
fi
echo "Model ID: $MODEL_ID"

echo "Step 3: Waiting for Model to be ready..."
while true; do
    STATUS_RESP=$(curl -s -X GET "$BASE_URL/api/models/$MODEL_ID" \
      -H "Authorization: Bearer $WOODWIDE_API_KEY")
    STATUS=$(get_id "$STATUS_RESP" ".status")
    
    if [ "$STATUS" = "ready" ]; then
        echo "Model is ready."
        break
    elif [ "$STATUS" = "failed" ]; then
        echo "Model training failed."
        exit 1
    fi
    echo "Status: $STATUS. Sleeping 5s..."
    sleep 5
done

echo "Step 4: Running Synchronous Inference..."
INFER_RESP=$(curl -s -X POST "$BASE_URL/api/models/$MODEL_ID/infer" \
  -H "Authorization: Bearer $WOODWIDE_API_KEY" \
  -F "file=@$TEST_DATA" \
  -F "output_type=csv")

if [ ! -z "$OUTPUT_FILE" ]; then
    echo "$INFER_RESP" > "$OUTPUT_FILE"
    echo "Results saved to $OUTPUT_FILE"
else
    echo "Inference Results:"
    echo "$INFER_RESP"
fi