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"
}
}
]
}