Articles in this section

API builder examples

These four sample APIs show how the pieces of an API fit together, from a single lookup to a composite API that performs several actions in one call. Each example lists its steps, the request that callers send, and the responses that your API returns. Use them as models when you build your own API.

The examples use sample data for a fictional company, ACME Chocolatiers, which makes and sells chocolate through its shops. To build the steps in each example, see Configure an API request using API builder, Configure an API response using API builder, Configure lookups, imports, guardrails, AI agents, and tools in API builder, Mapping data in API builder, and Branching in API builder.

Get all shops

Relative URI: /shops/

This API has one request, one lookup, and two responses.

Step Type What it does
API request Request Accepts GET /shops/ with optional query parameters.
Get all shops Lookup Searches your database for all shops. Map the request data so that it matches your database.
Successful retrieval of shops Response Returns the list of shops.
400 Bad Request (Invalid query parameters) Response Returns an error when a query parameter is not valid.

API request

{
  "method": "GET",
  "endpoint": "/shops/",
  "headers": {
    "Authorization": "Bearer <your_api_token>",
    "Content-Type": "application/json"
  },
  "query_parameters": {
    "limit": 10,
    "offset": 0,
    "sort": "name",
    "order": "asc"
  }
}

API response: successful retrieval of shops

{
  "status": "success",
  "data": {
    "shops": [
      {
        "id": 123,
        "name": "ACME Chocolatiers - Main Street",
        "location": "123 Main St, Springfield, IL",
        "phone": "+1-555-1234",
        "hours": {
          "monday": "8 AM - 6 PM",
          "tuesday": "8 AM - 6 PM",
          "wednesday": "8 AM - 6 PM",
          "thursday": "8 AM - 6 PM",
          "friday": "8 AM - 6 PM",
          "saturday": "9 AM - 3 PM",
          "sunday": "Closed"
        }
      },
      {
        "id": 124,
        "name": "ACME Chocolatiers - Elm Street",
        "location": "456 Elm St, Austin, TX",
        "phone": "+1-555-5678",
        "hours": {
          "monday": "9 AM - 5 PM",
          "tuesday": "9 AM - 5 PM",
          "wednesday": "9 AM - 5 PM",
          "thursday": "9 AM - 5 PM",
          "friday": "9 AM - 5 PM",
          "saturday": "10 AM - 2 PM",
          "sunday": "Closed"
        }
      }
    ]
  }
}

API response: 400 Bad Request (invalid query parameters)

{
  "status": "error",
  "code": 400,
  "message": "Invalid query parameters: 'page_size' must be a positive integer.",
  "errors": {
    "page_size": "Must be greater than 0"
  }
}

Get a chocolate

Relative URI: /shops/:shopId/chocolates/:chocolateId

This API has one request, three lookups, and two responses. It retrieves the details and allergen information of one chocolate in one shop.

Step Type What it does
API request Request Accepts GET with two path parameters: shopId (123) identifies the shop, and chocolateId (101) identifies the chocolate.
Get a bar Lookup Searches your database for a chocolate bar.
Get a truffle box Lookup Searches your database for a box of truffles.
Get allergen details Lookup Searches your database for the allergen details of the bar or truffle box.
Successful retrieval of chocolate Response Returns the chocolate details.
400 Bad Request (Invalid query parameters) Response Returns the same error response as Get all shops.

API request

{
  "method": "GET",
  "endpoint": "/shops/123/chocolates/101",
  "headers": {
    "Authorization": "Bearer <your_api_token>",
    "Content-Type": "application/json"
  }
}

API response: successful retrieval of chocolate

{
  "status": "success",
  "data": {
    "id": 101,
    "name": "Dark Sea Salt Bar",
    "cocoa_percent": 70,
    "type": "Dark chocolate bar",
    "weight_g": 100,
    "shop": {
      "id": 123,
      "name": "ACME Chocolatiers - Main Street",
      "location": "123 Main St, Springfield, IL",
      "phone": "+1-555-1234"
    },
    "supplier": {
      "id": 1001,
      "name": "Cacao Coop",
      "phone": "+1-555-1234"
    },
    "last_restocked": "2024-01-15",
    "certifications": ["Fairtrade", "Organic", "Kosher"]
  }
}

Create a new chocolate

Relative URI: /shops/:shopId/chocolates/

This API has one request, one import, four branches, and four responses. Each branch ends in a different response.

In this example, the request data and the response data are identical. In your API, the request data can include different or additional fields, and mapping converts it to the response schema.

Step Type What it does
API request Request Accepts POST /shops/123/chocolates/ to create a chocolate in shop 123. The body includes the SKU, type, and production history.
Create a new chocolate Import Sends the request data to your database to add the chocolate. Map the import data and the response data.
Branch Receives Response
Success Requests that succeed. 201 Created. Returns the new chocolate's unique ID and a created_at timestamp. Add API response mapping to include them.
Bad request Requests with missing data. Bad Request (missing required fields).
401 Unauthorized Requests with an invalid API token. 401 Unauthorized (invalid API token).
409 Conflict Requests with duplicate information, such as an existing SKU. 409 Conflict (duplicate SKU).

API request body

{
  "name": "Dark Sea Salt Bar",
  "cocoa_percent": 70,
  "type": "Dark chocolate bar",
  "weight_g": 100,
  "sku": "ACME-DSB-070",
  "supplier": {
    "id": 1001,
    "name": "Cacao Coop",
    "phone": "+1-555-1234"
  },
  "last_restocked": "2024-01-15",
  "certifications": ["Fairtrade", "Organic", "Kosher"],
  "production_history": [
    {
      "date": "2023-06-10",
      "batch": "B-2306",
      "note": "Added sea salt"
    },
    {
      "date": "2022-09-05",
      "batch": "B-2209",
      "note": "Switched to single-origin cacao"
    }
  ],
  "ingredients": {
    "cocoa_origin": "Ecuador",
    "sugar_type": "Cane sugar",
    "allergens": ["Milk", "Soy"]
  },
  "storage": {
    "temperature_c": 18,
    "shelf_life_days": 180,
    "display_note": "Keep away from sunlight"
  }
}

API response: successful chocolate creation

{
  "status": "success",
  "message": "Chocolate record created successfully.",
  "data": {
    "id": 201,
    "name": "Dark Sea Salt Bar",
    "cocoa_percent": 70,
    "type": "Dark chocolate bar",
    "weight_g": 100,
    "sku": "ACME-DSB-070",
    "shop": {
      "id": 123,
      "name": "ACME Chocolatiers - Main Street",
      "location": "123 Main St, Springfield, IL"
    },
    "supplier": {
      "id": 1001,
      "name": "Cacao Coop",
      "phone": "+1-555-1234"
    },
    "last_restocked": "2024-01-15",
    "certifications": ["Fairtrade", "Organic", "Kosher"],
    "production_history": [
      {
        "date": "2023-06-10",
        "batch": "B-2306",
        "note": "Added sea salt"
      },
      {
        "date": "2022-09-05",
        "batch": "B-2209",
        "note": "Switched to single-origin cacao"
      }
    ],
    "ingredients": {
      "cocoa_origin": "Ecuador",
      "sugar_type": "Cane sugar",
      "allergens": ["Milk", "Soy"]
    },
    "storage": {
      "temperature_c": 18,
      "shelf_life_days": 180,
      "display_note": "Keep away from sunlight"
    },
    "created_at": "2025-02-10T14:30:00Z"
  }
}

API response: Bad Request (missing required fields)

{
  "status": "error",
  "message": "Missing required fields: name, type"
}

API response: 401 Unauthorized (invalid API token)

{
  "status": "error",
  "message": "Unauthorized. Invalid API token."
}

API response: 409 Conflict (duplicate SKU)

{
  "status": "error",
  "message": "A chocolate with this SKU already exists."
}

Composite API

Relative URI: /v1/composite

A composite API performs several related actions in one call. This example gets a chocolate by its SKU, adds the chocolate if it doesn't exist, and places a restock order if it does.

The request and response data are identical in this example. In your API, mapping converts the request data to the response schema.

Step Type What it does
API request Request Accepts POST with a transactions array. Each transaction has an id, a method, an endpoint, and an optional dependsOn and condition that set the order.
Get a chocolate Lookup Retrieves the chocolate details (get_chocolate).
Add a chocolate Import Creates the chocolate from the get_chocolate result (create_chocolate).
Create an order Import Places the restock order after get_chocolate succeeds (restock_chocolate).
Successful Response Returns the result of every transaction in one aggregated response.
Bad request, 401 Unauthorized, 409 Conflict Responses Return the same error responses as Create a new chocolate.

API request body

{
  "transactions": [
    {
      "id": "get_chocolate",
      "method": "GET",
      "endpoint": "/chocolates",
      "query_parameters": {
        "sku": "ACME-DSB-070"
      }
    },
    {
      "id": "create_chocolate",
      "method": "POST",
      "endpoint": "/chocolates",
      "dependsOn": "get_chocolate",
      "condition": "not_found",
      "body": {
        "name": "Dark Sea Salt Bar",
        "cocoa_percent": 70,
        "type": "Dark chocolate bar",
        "weight_g": 100,
        "sku": "ACME-DSB-070",
        "supplier": {
          "id": 1001,
          "name": "Cacao Coop",
          "phone": "+1-555-1234"
        },
        "last_restocked": "2024-01-15",
        "certifications": ["Fairtrade", "Organic", "Kosher"],
        "production_history": [
          {
            "date": "2023-06-10",
            "batch": "B-2306",
            "note": "Added sea salt"
          }
        ],
        "ingredients": {
          "cocoa_origin": "Ecuador",
          "sugar_type": "Cane sugar",
          "allergens": ["Milk", "Soy"]
        }
      }
    },
    {
      "id": "restock_chocolate",
      "method": "POST",
      "endpoint": "/shops/123/orders",
      "dependsOn": "get_chocolate",
      "condition": "success",
      "body": {
        "order_type": "restock",
        "chocolate_id": "$get_chocolate.id",
        "shop_id": 123,
        "cocoa_origin": "$get_chocolate.ingredients.cocoa_origin",
        "quantity_kg": 5,
        "order_date": "2025-02-10T14:30:00Z",
        "status": "Processing",
        "delivery_time": "2025-02-11T10:00:00Z",
        "special_requests": "Fairtrade lot if available"
      }
    }
  ]
}

API response: successful

The response returns 201 Created and combines the result of each transaction. Add API response mapping to include the unique ID and any other data you want to return.

{
  "status": "success",
  "transactions": [
    {
      "id": "get_chocolate",
      "status": "success",
      "code": 200,
      "message": "Chocolate found in the system.",
      "data": {
        "id": 201,
        "name": "Dark Sea Salt Bar",
        "cocoa_percent": 70,
        "type": "Dark chocolate bar",
        "weight_g": 100,
        "sku": "ACME-DSB-070",
        "supplier": {
          "id": 1001,
          "name": "Cacao Coop",
          "phone": "+1-555-1234"
        },
        "ingredients": {
          "cocoa_origin": "Ecuador",
          "sugar_type": "Cane sugar",
          "allergens": ["Milk", "Soy"]
        }
      }
    },
    {
      "id": "create_chocolate",
      "status": "skipped",
      "code": 304,
      "message": "Chocolate already exists. No need to create a new record."
    },
    {
      "id": "restock_chocolate",
      "status": "success",
      "code": 201,
      "message": "Restock order placed successfully.",
      "data": {
        "order_id": 5012,
        "chocolate_id": 201,
        "shop_id": 123,
        "cocoa_origin": "Ecuador",
        "quantity_kg": 5,
        "order_date": "2025-02-10T14:30:00Z",
        "status": "Processing",
        "delivery_time": "2025-02-11T10:00:00Z",
        "special_requests": "Fairtrade lot if available"
      }
    }
  ]
}