### Install Project Dependencies and Start Development Server

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/guides/1-getting-started.md

Install all project dependencies using yarn and then start the development server. This command launches the application locally.

```bash
yarn
yarn dev
```

--------------------------------

### E-commerce Agent Setup Cheat-Sheet

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/tutorials/10-ecommerce..md

A quick reference guide for setting up and deploying an e-commerce agent, from initial creation to sharing and order verification.

```markdown
1. New Agent → Use Template → InstaFit
2. Preview link → test chat, add to cart, place order
3. Orders tab → verify order data
4. Products & services → edit item, Generate Variants 🪄
5. Images → 🪄 Generate description
6. Configure shipping, payment, statuses
7. Share the public URL or embed widget
```

--------------------------------

### Install Open Agents Builder Client

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/1-working-with-api-client.md

Install the client library and zod for schema validation using npm or yarn.

```bash
npm install open-agents-builder-client zod
```

```bash
yarn add open-agents-builder-client zod
```

--------------------------------

### Follow-up Prompt for Document Generation

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/tutorials/60-executing-code.md

This example demonstrates how to prompt the agent to create a .docx file that combines previously generated content (a summary document and a chart). The agent is expected to handle necessary library imports, such as 'python-docx', potentially installing them if not already present, and embedding the content into the final document.

```text
Can you create a .docx that combines the summary and the chart?
```

--------------------------------

### Install and Use Node.js Version 22

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/guides/1-getting-started.md

Ensure you have Node.js version 22 installed and active for the project. Uses nvm for version management.

```bash
nvm install 22
nvm use 22
```

--------------------------------

### Example Products API Response

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/14-products-api.md

This is an example of a successful HTTP 200 response from the /api/product endpoint, showing the structure of the returned product data, including pagination details.

```json
{
  "rows": [
    {
      "id": "p-abc123",
      "sku": "SHOE-001",
      "name": "Nice Shoes",
      "price": { "value": 49.99, "currency": "USD" },
      "priceInclTax": { "value": 61.48, "currency": "USD" },
      "taxRate": 0.23,
      "taxValue": 11.49,
      "width": 0,
      "height": 0,
      "length": 0,
      "weight": 0,
      "widthUnit": "cm",
      "heightUnit": "cm",
      "lengthUnit": "cm",
      "weightUnit": "kg",
      "brand": "Some Brand",
      "status": "active",
      "imageUrl": null,
      "attributes": [],
      "variants": [],
      "images": [],
      "tags": [],
      "agentId": null,
      "createdAt": "2025-03-21T10:00:00.000Z",
      "updatedAt": "2025-03-21T10:05:00.000Z"
    },
    ...
  ],
  "total": 12,
  "limit": 5,
  "offset": 0,
  "orderBy": "name",
  "query": "shoes"
}
```

--------------------------------

### Product Data Transfer Object Example

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/14-products-api.md

An example of the structure for product data when upserting a product. Ensure all required fields are present.

```json
{
  "id": "p-abc123",
  "sku": "SHOE-001",
  "name": "Nice Shoes",
  "price": { "value": 49.99, "currency": "USD" },
  ...
}
```

--------------------------------

### Mandatory Request Headers Example

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/10-agent-api.md

This example shows the required Authorization and database-id-hash headers for API requests. Ensure you replace the placeholder values with your actual API key and database ID hash.

```text
Authorization: Bearer abc1234exampleKey
database-id-hash: 35f5c5b139a6b569d4649b788c1851831eb44d8e32b716b8411ec6431af8121d
```

--------------------------------

### Mandatory Request Headers Example

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/40-evals.md

Example of the required Authorization and database-id-hash headers, along with the optional Content-Type header for POST requests.

```text
Authorization: Bearer abc1234exampleKey
database-id-hash: 35f5c5b139a6b569d4649b788c1851831eb44d8e32b716b8411ec6431af8121d
Content-Type: application/json
```

--------------------------------

### Clone Open Agents Builder Repository

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/guides/1-getting-started.md

Clone the project repository and navigate into the project directory. This is the first step for local setup.

```bash
git clone https://github.com/CatchTheTornado/open-agents-builder
cd open-agents-builder
```

--------------------------------

### Install Open Agents Builder TypeScript Client

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/0-creating-api-key.md

Install the necessary packages for the Open Agents Builder TypeScript client using npm or yarn. This includes the client library and Zod for validation.

```bash
npm install open-agents-builder-client zod

```

```bash
yarn add open-agents-builder-client zod

```

--------------------------------

### Success Response for Session Creation

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/12-session-api.md

Example of a successful response when a new session is created.

```json
{
  "message": "Session created",
  "data": { "id": "session-XYZ" },
  "status": 200
}
```

--------------------------------

### Wrap ChatPage with ExecProvider

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/30-using-chat-endpoint.md

This example shows how to wrap your `ChatPage` component with `ExecProvider` in your root or page layout to make the context available.

```tsx
import ChatPage from "./ChatPage";
import { ExecProvider } from "@/context/exec-context";

export default function App({ params }) {
  return (
    <ExecProvider>
      <ChatPage params={params} />
    </ExecProvider>
  );
}

```

--------------------------------

### Example HTTP 200 Response for Keys

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/19-keys-api.md

This is an example of a successful (HTTP 200) response when listing keys. It shows the structure of the returned key objects, including display name, hashes, and timestamps.

```json
[
  {
    "displayName": "My Key #1",
    "keyLocatorHash": "1122334455667788aaabbbcccdddeeefff0011223344556677aaabbbcccdddee",
    "keyHash": "abc1234def5678...",
    "databaseIdHash": "35f5c5b139a6b569d4649b7...",
    "encryptedMasterKey": "base64-or-other-encrypted-string",
    "acl": null,
    "extra": null,
    "expiryDate": null,
    "updatedAt": "2025-03-21T11:00:00.000Z"
  },
  ...
]
```

--------------------------------

### Example Success Response for Product Upsert

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/14-products-api.md

This is a sample successful response when a product is upserted. It includes confirmation and the saved data.

```json
{
  "message": "Data saved successfully!",
  "data": {
    "id": "p-abc123",
    "sku": "SHOE-001",
    "name": "Nice Shoes",
    "price": { "value": 49.99, "currency": "USD" },
    "priceInclTax": { "value": 61.48, "currency": "USD" },
    "brand": "Some Brand",
    "status": "active",
    "attributes": [],
    "variants": [],
    "images": [],
    "tags": [],
    ...
    "createdAt": "2025-03-21T10:00:00.000Z",
    "updatedAt": "2025-03-21T10:05:00.000Z"
  },
  "status": 200
}
```

--------------------------------

### Query Vector Stores Request (cURL)

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/31-memory-api.md

Example cURL command to query available vector stores, with options for pagination and partial name matching.

```bash
curl -X GET \
  "https://app.example.com/api/memory/query?limit=10&offset=0&query=my" \
  -H "Authorization: Bearer abc1234exampleKey" \
  -H "database-id-hash: 35f5c5b139a6b569..."
```

--------------------------------

### GET /api/product/export

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/14-products-api.md

Exports all products as a .zip file. The ZIP contains markdown and HTML listings, individual product files, images, and a products.json file.

```APIDOC
## GET /api/product/export

### Description
Exports all products as a `.zip` file. Inside the ZIP you’ll find:

- `index.md` and `index.html` – listing products.
- For each product, a `*.md` and `*.html` – rendered from `renderProductToMarkdown()`.
- `images` folder – any product images referenced in `product.images` are embedded in the ZIP.
- `products.json` – raw JSON of all products.

### Method
GET

### Endpoint
/api/product/export

### Request Example
```bash
curl -X GET \
  "https://app.openagentsbuilder.com/api/product/export" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "database-id-hash: <YOUR_DATABASE_ID_HASH>"
```

### Response
#### Success Response (200)
- **Content-Type**: application/zip
- **Body**: Binary ZIP file containing product data.

#### Response Example
(Binary ZIP file content)
```

--------------------------------

### Example Order API Response

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/13-order-api.md

This is an example of a successful HTTP 200 response from the GET /api/order endpoint. It shows the paginated structure including order details.

```json
{
  "rows": [
    {
      "id": "ORD-2025-03-21-ABC",
      "agentId": "agent-XYZ",
      "sessionId": "session-123",
      "billingAddress": {},
      "shippingAddress": {},
      "attributes": {},
      "notes": [],
      "statusChanges": [],
      "customer": { "name": "Alice", "email": "[email protected]" },
      "status": "shipped",
      "email": "[email protected]",
      "subtotal": { "value": 100, "currency": "USD" },
      "subTotalInclTax": { "value": 123, "currency": "USD" },
      "subtotalTaxValue": { "value": 23, "currency": "USD" },
      "total": { "value": 120, "currency": "USD" },
      "totalInclTax": { "value": 150, "currency": "USD" },
      "shippingPrice": { "value": 10, "currency": "USD" },
      "shippingPriceTaxRate": 0.08,
      "shippingPriceInclTax": { "value": 10.8, "currency": "USD" },
      "items": [
        {
          "id": "line-1",
          "sku": "PROD-001",
          "variantSku": "VAR-001",
          "quantity": 2,
          ...
        }
      ],
      "createdAt": "2025-03-21T10:00:00.000Z",
      "updatedAt": "2025-03-21T10:05:00.000Z"
    },
    ...
  ],
  "total": 10,
  "limit": 5,
  "offset": 0,
  "orderBy": "status",
  "query": "shipped"
}
```

--------------------------------

### Fetch Products List with Open Agents Builder Client

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/14-products-api.md

This example demonstrates how to use the open-agents-builder-client library in TypeScript to fetch a list of products. It simplifies the process by abstracting away direct fetch calls and parameter construction.

```typescript
import { OpenAgentsBuilderClient } from "open-agents-builder-client";

const client = new OpenAgentsBuilderClient({
  apiKey: "YOUR_API_KEY",
  databaseIdHash: "YOUR_DATABASE_ID_HASH"
});

async function listProductsClientExample() {
  // The client.product.listProducts() method accepts optional query parameters.
  const products = await client.product.listProducts({
    limit: 5,
    offset: 0,
    orderBy: "name",
    query: "shoes"
  });
  console.log("Products from client:", products);
}

listProductsClientExample();
```

--------------------------------

### Get Specific Vector Store Records (cURL)

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/31-memory-api.md

Example cURL command to fetch all records from a specific vector store. This endpoint retrieves raw JSON data and does not perform vector search.

```bash
curl -X GET \
  https://app.example.com/api/memory/my-new-store \
  -H "Authorization: Bearer abc1234exampleKey" \
  -H "database-id-hash: 35f5c5b139a6b569..."
```

--------------------------------

### Retrieve Aggregated Stats with TypeScript API Client

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/18-stats-api.md

This example shows how to get aggregated stats using the TypeScript API client. It calls the `getAggregatedStats` method on the client's stats object.

```typescript
async function getAggregatedStatsClientExample() {
  const aggregated = await client.stats.getAggregatedStats();
  console.log("Aggregated stats via client:", aggregated);
}

getAggregatedStatsClientExample();
```

--------------------------------

### Example Project Structure for Tools

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/extensibility/20-new-tool-integration.md

Illustrates the typical file organization for custom tools within an Open Agents Builder project, including tool implementations and their configurators.

```tree
src/
  tools/
    googleSearchTool.ts             # Your new tool
    googleSearchTool-configurator.tsx   # Tool configurator
    calendarListTool.ts
    calendarScheduleTool.ts
    calendarScheduleTool-configurator.tsx
    ...
    registry.ts                     # Tools registry (toolRegistry.init)
    configurators.ts                # Tools configurators registry
...
```

--------------------------------

### Example Success Response for GET /api/stats/aggregated

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/18-stats-api.md

This JSON shows the structure of the aggregated stats response. It includes usage data broken down by this month, last month, and today, detailing tokens, costs, and requests.

```json
{
  "message": "Stats aggregated!",
  "data": {
    "thisMonth": {
      "overallTokens": 9999,
      "promptTokens": 4000,
      "completionTokens": 5999,
      "overalUSD": 4.50,
      "requests": 27
    },
    "lastMonth": {
      "overallTokens": 3000,
      "promptTokens": 1000,
      "completionTokens": 2000,
      "overalUSD": 2.30,
      "requests": 10
    },
    "today": {
      "overallTokens": 999,
      "promptTokens": 400,
      "completionTokens": 599,
      "overalUSD": 0.45,
      "requests": 2
    }
  },
  "status": 200
}
```

--------------------------------

### Upsert Calendar Event Request Body Example

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/15-calendar-api.md

This JSON object represents the structure for creating or updating a calendar event. It includes fields like title, agentId, start and end times, description, location, and participants.

```json
{
  "id": "evt-001",
  "title": "Meeting with Bob",
  "agentId": "agent-123",
  "start": "2025-04-01T10:00:00.000Z",
  "end": "2025-04-01T11:00:00.000Z",
  "description": "Discuss project updates",
  "location": "Conference Room",
  "participants": "[{{\"name\":\"Bob\",\"email\":\"[email protected]\"}}]"
}
```

--------------------------------

### Initialize and Use OpenAgentsBuilderClient

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/1-working-with-api-client.md

Demonstrates the complete workflow of initializing the client, creating an agent, engaging in a chat, storing the conversation, and tracking statistics. Requires databaseIdHash and apiKey for initialization.

```typescript
// 1	·	Init
const client = new OpenAgentsBuilderClient({
  databaseIdHash: "YOUR_DB_HASH",
  apiKey: "YOUR_API_KEY"
});

// 2	·	Create an Agent
const agent = await client.agent.upsertAgent({
  displayName: "Helper",
  prompt: "You are very helpful"
});

// 3	·	Chat
const history = [ { role: "user", content: "Hello" } ];
const { messages, sessionId } = await client.chat.collectMessages(history, { agentId: agent.id! });
console.log("Assistant says:", messages.at(-1)?.content);

// 4	·	Store the conversation in vector memory
await client.memory.createStore("conversations");
await client.memory.createRecord("conversations", {
  id: sessionId!,
  content: JSON.stringify(messages),
  embedding: (await client.memory.generateEmbeddings(messages.at(-1)?.content ?? "")).embedding,
  metadata: { agentId: agent.id }
});

// 5	·	Stats
await client.stats.putStats({ eventName: "chat", promptTokens: 15, completionTokens: 25 });

// 6	·	Evaluate the Agent after an update
const { testCases } = await client.evals.generateTestCases(agent.id!, agent.prompt);
await client.evals.runTestCases(agent.id!, testCases); // stream & assert in CI

```

--------------------------------

### Key DTO Example

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/19-keys-api.md

Example of the request body structure for the Key DTO, used when upserting or creating keys.

```json
{
  "displayName": "My Key #1",
  "keyLocatorHash": "1122334455667788aaabbbcccdddeeefff0011223344556677aaabbbcccdddee",
  "keyHash": "abc123def456...",
  "keyHashParams": "some-params",
  "databaseIdHash": "35f5c5b139a6b569d4649b7...",
  "encryptedMasterKey": "some-encrypted-value",
  "acl": "{\"role\":\"owner\"}"
}
```

--------------------------------

### Get Current Date Tool Configuration

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/guides/6-available-ai-tools.md

Configuration for the 'Get current date' tool. This tool requires no parameters.

```typescript
{
  displayName: 'Get current date',
  parameters: {} // No parameters required
}
```

--------------------------------

### List Agents using open-agents-builder-client

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/10-agent-api.md

This TypeScript example shows how to list agents using the official client library. Initialize the client with your API key and database hash, then call the `listAgents` method.

```typescript
import { OpenAgentsBuilderClient } from "open-agents-builder-client";

const client = new OpenAgentsBuilderClient({
  databaseIdHash: "35f5c5b139a6b569d4649b7...",
  apiKey: "abc1234exampleKey"
});

async function listAgents() {
  const agents = await client.agent.listAgents({ limit: 10, offset: 0 });
  console.log("Agents:", agents);
}
```

--------------------------------

### List Keys using Open Agents Builder Client

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/19-keys-api.md

This example shows how to list keys using the official Open Agents Builder TypeScript client library. Initialize the client with your API key and database ID hash, then call the listKeys method.

```typescript
import { OpenAgentsBuilderClient } from "open-agents-builder-client";

const client = new OpenAgentsBuilderClient({
  apiKey: "<YOUR_API_KEY>",
  databaseIdHash: "<YOUR_DATABASE_ID_HASH>"
});

async function listKeysClientExample() {
  const keys = await client.keys.listKeys({ databaseIdHash: "35f5c5b139a6b569d4649b7..." });
  console.log("Keys (via client):", keys);
}

listKeysClientExample();
```

--------------------------------

### Chat API Request Body Example

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/30-using-chat-endpoint.md

This is an example of the JSON request body for the chat API. It includes a system message to initiate the conversation.

```json
{
  "messages": [
    {
      "role": "system",
      "content": "Hello, how can I assist you today?"
    }
  ]
}
```

--------------------------------

### Example cURL Request to Execute Flow

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/20-executing-flow.md

Demonstrates how to execute a flow using cURL, including necessary headers like Authorization and Content-Type, and the request body. Ensure your API key and database-id-hash are correctly substituted.

```bash
curl -X POST \
  -H "Authorization: Bearer ${OPEN_AGENT_BUILDER_API_KEY}" \
  -H "database-id-hash: 35f5c5b139a6b569d4649b788c1851831eb44d8e32b716b8411ec6431af8121d" \
  -H "Content-Type: application/json" \
  -d '{"flow":"import","execMode":"sync","outputMode":"stream"}' \
  https://app.openagentsbuilder.com/api/agent/m8r22uvT2_KsMODoEw9ag/exec
```

--------------------------------

### Fetch Orders using open-agents-builder-client

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/13-order-api.md

This example shows how to retrieve orders using the open-agents-builder-client library. Instantiate the client with your API credentials and call the listOrders method.

```typescript
import { OpenAgentsBuilderClient } from "open-agents-builder-client";

const client = new OpenAgentsBuilderClient({
  apiKey: "YOUR_API_KEY",
  databaseIdHash: "YOUR_DATABASE_ID_HASH"
});

async function listOrdersClientExample() {
  const orders = await client.order.listOrders({ limit: 5, offset: 0, orderBy: "status", query: "shipped" });
  console.log("Orders via client:", orders);
}
```

--------------------------------

### Order API Success Response Example

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/13-order-api.md

This is an example of a successful HTTP 200 response when upserting an order. It includes the full order details as returned by the API.

```json
{
  "status": 200,
  "data": {
    "id": "ORD-2025-03-21-ABC",
    "agentId": "agent-XYZ",
    "sessionId": null,
    "billingAddress": {},
    "shippingAddress": {},
    "status": "new",
    "email": "[email protected]",
    "items": [
      {
        "id": "line-1",
        "productSku": "PROD-ABC",
        "variantSku": "VAR-ABC",
        "quantity": 2,
        "price": { "value": 50, "currency": "USD" }
      }
    ],
    "createdAt": "2025-03-21T10:00:00.000Z",
    "updatedAt": "2025-03-21T10:05:00.000Z"
  }
}
```

--------------------------------

### Example Success Response for PUT /api/stats

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/18-stats-api.md

This is an example of a successful response when aggregating stats. It shows the updated aggregated data, including the incremented counter and tokens.

```json
{
  "message": "Stats aggregated!",
  "data": {
    "id": 42,
    "eventName": "chat",
    "promptTokens": 200,    // if we already had 100, now 100 more added
    "completionTokens": 300,// if 150 more added
    "createdAt": "2025-03-21T10:00:00.000Z",
    "createdMonth": 2,
    "createdDay": 21,
    "createdYear": 2025,
    "createdHour": 10,
    "counter": 2
  },
  "status": 200
}
```

--------------------------------

### cURL Example for Session API

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/12-session-api.md

Demonstrates how to use cURL to send a POST request to create or retrieve a session, including necessary headers and the request body.

```bash
curl -X POST \
  "https://app.openagentsbuilder.com/api/exec/session/session-XYZ" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "database-id-hash: <YOUR_DATABASE_ID_HASH>" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent-123",
    "userName": "Alice",
    "userEmail": "[email protected]",
    "acceptTerms": "true"
}'
```

--------------------------------

### cURL Example for Upserting a Key

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/19-keys-api.md

Demonstrates how to upsert a key using a cURL command. Ensure to replace placeholders with your actual API key and database ID hash.

```bash
curl -X PUT \
  "https://app.openagentsbuilder.com/api/keys" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "database-id-hash: 35f5c5b139a6b5..." \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "My Key #1",
    "keyLocatorHash": "1122334455667788aaabbbcccdddeeefff0011223344556677aaabbbcccdddee",
    "keyHash": "abc123def456...",
    "keyHashParams": "some-params",
    "databaseIdHash": "35f5c5b139a6b569d4649b7...",
    "encryptedMasterKey": "some-encrypted-value"
  }'
```

--------------------------------

### Get Day Name Tool Configuration

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/guides/6-available-ai-tools.md

Configuration for the 'Get the day name' tool. Requires an ISO date string and optionally accepts a locale for localization.

```typescript
{
  displayName: 'Get the day name',
  parameters: {
    locale?: string, // Optional locale like 'en-US', 'pl-PL'
    date: string     // ISO date (e.g. '2025-05-18T00:00:00Z')
  }
}
```

--------------------------------

### Extend Product API Client for Description Generation

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/14-products-api.md

Example of extending the BaseClient to add a custom method for generating product descriptions. This approach uses fetch internally and requires API key and database ID hash for authentication.

```typescript
class ExtendedProductApi extends BaseClient {
  public async describeProduct(storageKey: string, productData: Partial<ProductDTO>) {
    const url = `${this.baseUrl}/api/product/descriptor/${storageKey}`;
    const resp = await fetch(url, {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${this.apiKey}`,
        "database-id-hash": this.databaseIdHash,
        "Content-Type": "application/json"
      },
      body: JSON.stringify(productData)
    });
    if (!resp.ok) {
      throw new Error(`Error describing product: ${resp.statusText}`);
    }
    return resp.json();
  }
}

// Usage:
(async () => {
  const extendedProductApi = new ExtendedProductApi({
    apiKey: "YOUR_API_KEY",
    databaseIdHash: "YOUR_DATABASE_ID_HASH"
  });

  const result = await extendedProductApi.describeProduct("unique-image-storage-key", {
    sku: "DES-123",
    name: "From LLM",
    price: { value: 19.99, currency: "USD" }
  });

  console.log("LLM-based described product:", result);
})();
```

--------------------------------

### Fetch Products List with cURL

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/14-products-api.md

Use this cURL command to make a GET request to the /api/product endpoint. It demonstrates how to specify query parameters for pagination, sorting, and searching.

```bash
curl -X GET \
  "https://app.openagentsbuilder.com/api/product?limit=5&offset=0&orderBy=name&query=shoes" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "database-id-hash: <YOUR_DATABASE_ID_HASH>"
```

--------------------------------

### Install Python Dependencies for Attachments Module

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/guides/1-getting-started.md

Install necessary Python packages like markitdown and poppler using pipx for isolated environments. This is required for the Attachments module.

```bash
pipx install markitdown
pipx install poppler
```

--------------------------------

### Example Response for Creating Audit Log

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/17-audit-log-api.md

This is an example of a successful HTTP 200 response when creating an audit log entry. It includes a success message, the saved data, and status code.

```json
{
  "message": "Data saved successfully!",
  "data": {
    "id": 77,
    "eventName": "updateUserProfile",
    "recordLocator": "{\"userId\":\"user-123\"}",
    "diff": "ENCRYPTED_OR_PLAINTEXT_DIFF",
    "ip": "203.0.113.42",
    "ua": "Mozilla/5.0 ...",
    "databaseIdHash": "35f5c5b139a6b569d4649b7...",
    "createdAt": "2025-03-21T12:34:56.000Z"
  },
  "status": 200
}
```

--------------------------------

### Initialize Open Agents Builder TypeScript Client

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/0-creating-api-key.md

Set up the Open Agents Builder client with your API credentials and base URL. Ensure you provide your specific database ID hash and API key.

```typescript
import { OpenAgentsBuilderClient } from "open-agents-builder-client";

const client = new OpenAgentsBuilderClient({
  // This URL can be changed if you're self-hosting.
  baseUrl: "https://app.openagentsbuilder.com", 
  databaseIdHash: "YOUR_DATABASE_ID_HASH",
  apiKey: "YOUR_API_KEY" // or set process.env.OPEN_AGENTS_BUILDER_API_KEY
});

```

--------------------------------

### Create or Update Agent with Axios

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/10-agent-api.md

This TypeScript example demonstrates creating or updating an agent using the axios library. It shows how to configure headers and send agent data in the request body.

```typescript
import axios from "axios";

async function createOrUpdateAgent(agentData: any) {
  const response = await axios.put(
    "https://app.openagentsbuilder.com/api/agent",
    agentData,
    {
      headers: {
        "Authorization": "Bearer abc1234exampleKey",
        "database-id-hash": "35f5c5b139a6b569d4649b788c1851831eb44d8e32b716b8411ec6431af8121d",
        "Content-Type": "application/json"
      }
    }
  );
  console.log("Operation successful. Returned data:", response.data);
}

// Usage example:
createOrUpdateAgent({
  "id": "agent-XYZ",
  "displayName": "Updated Agent",
  "prompt": "New prompt"
});
```

--------------------------------

### Customer API Endpoint (GET & PUT)

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/extensibility/0-new-endpoint-entity.md

Handles GET requests to list customers and PUT requests to upsert customer records. Includes audit logging for create and update operations.

```typescript
// src/app/api/customer/route.ts
import { NextRequest, NextResponse } from "next/server";
import { customerDTOSchema, CustomerDTO } from "@/data/dto";
import ServerCustomerRepository from "@/data/server/server-customer-repository";
import { genericGET, genericPUT } from "@/lib/generic-api";
import { auditLog, authorizeSaasContext } from "@/lib/generic-api";
import { authorizeRequestContext } from "@/lib/authorization-api";
import { getErrorMessage } from "@/lib/utils";
import { detailedDiff } from "deep-object-diff";

export async function GET(request: NextRequest, response: NextResponse) {
  try {
    const requestContext = await authorizeRequestContext(request, response);
    const saasContext = await authorizeSaasContext(request);

    const repo = new ServerCustomerRepository(requestContext.databaseIdHash);
    // We can reuse the genericGET utility for listing
    const list = await genericGET<CustomerDTO>(request, repo, 50, 0);
    return Response.json(list);
  } catch (error) {
    return Response.json({ message: getErrorMessage(error), status: 500 }, { status: 500 });
  }
}

export async function PUT(request: NextRequest, response: NextResponse) {
  try {
    const requestContext = await authorizeRequestContext(request, response);
    const saasContext = await authorizeSaasContext(request);

    const inputObj = await request.json();
    const repo = new ServerCustomerRepository(requestContext.databaseIdHash);

    // If we want to handle "upsert" or "create" specifically:
    const existing = inputObj.id ? await repo.findOne({ id: inputObj.id }) : null;
    const apiResult = await genericPUT<CustomerDTO>(inputObj, customerDTOSchema, repo, "id");

    if (!existing && apiResult.status === 200) {
      // new record
      auditLog(
        {
          eventName: "createCustomer",
          diff: JSON.stringify(inputObj),
          recordLocator: JSON.stringify({ id: apiResult.data?.id }),
        },
        request,
        requestContext,
        saasContext
      );
    } else if (existing && apiResult.status === 200) {
      // update
      const changes = detailedDiff(existing, apiResult.data || {});
      auditLog(
        {
          eventName: "updateCustomer",
          diff: JSON.stringify(changes),
          recordLocator: JSON.stringify({ id: apiResult.data?.id }),
        },
        request,
        requestContext,
        saasContext
      );
    }

    return Response.json(apiResult, { status: apiResult.status });
  } catch (error) {
    return Response.json({ message: getErrorMessage(error), status: 500 }, { status: 500 });
  }
}
```

--------------------------------

### Example Chat Interaction with Knowledge Base

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/tutorials/40-knowledge-graph.md

This snippet demonstrates a typical user interaction with the AI agent after documents have been processed and stored. It shows how a user can ask questions about company relationships and specific document details, and how the agent responds by retrieving and summarizing information from the knowledge base.

```text
User: what relationship do we have with Acme?
Agent: We have a Consulting Services Agreement with Acme Ltd… (plus two invoices and an NDA)

User: Tell me about the risks we have out of this NDA?
Agent: … (summarises confidentiality obligations, liability caps, etc.)
```

--------------------------------

### Example Response for Listing Audit Logs

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/17-audit-log-api.md

This is an example of a successful HTTP 200 response when listing audit logs. It returns an array of log objects, each containing details like ID, event name, and creation timestamp.

```json
[
  {
    "id": 75,
    "eventName": "createAgent",
    "recordLocator": "{\"id\":\"agent-XYZ\"}",
    "diff": "...",
    "databaseIdHash": "35f5c5b139a6b569d4...",
    "createdAt": "2025-02-15T09:12:00.000Z",
    "ip": "203.0.113.55",
    "ua": "Mozilla/5.0 (Macintosh; ...)",
    ...
  },
  {
    "id": 76,
    "eventName": "updateAgent",
    "diff": "ENCRYPTED_OR_PLAINTEXT_DIFF",
    "createdAt": "2025-02-15T09:13:22.000Z",
    ...
  }
]
```

--------------------------------

### List Products Tool Parameters

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/guides/6-available-ai-tools.md

Defines the parameters for listing products. This tool supports optional filtering by query, and pagination with limit and offset.

```typescript
{
  displayName: 'List products',
  parameters: {
    query?: string,    // Optional filter by SKU or name
    limit?: number,    // Number of products to return (default: 10)
    offset?: number    // Pagination offset (default: 0)
  }
}
```

--------------------------------

### Success Response for Existing Session

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/12-session-api.md

Example of a successful response when a session already exists.

```json
{
  "message": "Session already exists",
  "data": { "id": "session-XYZ" }
}
```

--------------------------------

### Create Vector Store Request (cURL)

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/31-memory-api.md

Example cURL command to create a new vector store. Ensure the store name is unique and adheres to filesystem constraints.

```bash
curl -X POST \
  https://app.example.com/api/memory/create \
  -H "Authorization: Bearer abc1234exampleKey" \
  -H "database-id-hash: 35f5c5b139a6b569..." \
  -H "Content-Type: application/json" \
  -d '{
    "storeName": "my-new-store"
  }'
```

--------------------------------

### GET /api/memory/query

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/31-memory-api.md

Lists existing vector stores. Supports filtering by name and pagination.

```APIDOC
## GET /api/memory/query

### Description
List existing stores (with metadata, pagination, and optional name filter).

### Method
GET

### Endpoint
/api/memory/query

### Parameters
#### Query Parameters
- **name** (string) - Optional - Filter stores by name.
- **limit** (integer) - Optional - The maximum number of stores to return. Defaults to 10.
- **offset** (integer) - Optional - The number of stores to skip before returning results. Defaults to 0.

### Response
#### Success Response (200 OK)
- **stores** (array) - An array of store objects.
  - **id** (string) - The unique identifier for the store.
  - **name** (string) - The name of the store.
  - **description** (string) - The description of the store.
  - **createdAt** (string) - The timestamp when the store was created.

#### Response Example
```json
{
  "stores": [
    {
      "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "name": "my_store_1",
      "description": "First store",
      "createdAt": "2023-10-27T10:00:00Z"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-2345-67890abcdef1",
      "name": "my_store_2",
      "description": "Second store",
      "createdAt": "2023-10-27T10:05:00Z"
    }
  ]
}
```
```

--------------------------------

### Export Products using cURL

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/14-products-api.md

Use this cURL command to export all products as a .zip file. Ensure you replace placeholders with your actual API key and database ID hash. The output is saved to 'products-export.zip'.

```bash
curl -X GET \
  "https://app.openagents.com/api/product/export" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "database-id-hash: <YOUR_DATABASE_ID_HASH>" \
  -o products-export.zip
```

--------------------------------

### Synchronous Streaming API Request for Product Description

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/tutorials/50-shopify-product-descriptor.md

Use this curl command to send a product photo to the API for synchronous processing with streaming output. Replace placeholders with your actual database ID hash, API token, and file path.

```bash
curl -X POST \
  -H "database-id-hash: 35f5c5b139a6b569d4649b788c1851831eb44d8e32b716b8411ec6431af8121d" \
  -H "Content-Type: application/json" \
  -F flow=describe-product \
  -F execution=synchronous \
  -F output=stream \
  -F productPhoto=@/path/to/photo.jpg \
  https://app.openagentsbuilder.com/exec
```

--------------------------------

### GET /api/agent

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/10-agent-api.md

Retrieve a list of agents. This endpoint allows you to fetch all available agents.

```APIDOC
## GET /api/agent

### Description
Retrieve a list of agents.

### Method
GET

### Endpoint
/api/agent

### Parameters
#### Query Parameters
- **`Authorization`** (string) - Required - Used for authentication. Replace `<OPEN_AGENT_BUILDER_API_KEY>` with your actual API key.
- **`database-id-hash`** (string) - Required - A constant key per user’s database. Obtain this hash from the *API tab* in the administration panel.

### Response
#### Success Response (200)
- **`agents`** (array) - Description of the agents array
  - **`id`** (string) - The unique identifier for the agent.
  - **`displayName`** (string) - The display name of the agent.
  - **`createdAt`** (string) - The timestamp when the agent was created.
  - **`updatedAt`** (string) - The timestamp when the agent was last updated.

#### Response Example
{
  "agents": [
    {
      "id": "agent-123",
      "displayName": "Customer Support Bot",
      "createdAt": "2023-10-27T10:00:00Z",
      "updatedAt": "2023-10-27T10:00:00Z"
    }
  ]
}
```

--------------------------------

### GET /api/session

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/12-session-api.md

Retrieves all sessions, with the option to filter by session ID or agent ID.

```APIDOC
## GET /api/session

### Description
Returns all sessions, optionally filtered by query parameters.

### Method
GET

### Endpoint
/api/session

### Parameters
#### Query Parameters
- **id** (string) - Optional - Filter by session ID.
- **agentId** (string) - Optional - Filter by specific agent.

### Request Example
```bash
curl -X GET \
  "https://app.openagentsbuilder.com/api/session?agentId=agent-123" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "database-id-hash: <YOUR_DATABASE_ID_HASH>"
```

### Response
#### Success Response (200)
- **Array of SessionDTO objects** - Each session is a decrypted SessionDTO.

#### Response Example
```json
[
  {
    "id": "session-001",
    "agentId": "agent-123",
    "userName": "Alice",
    "userEmail": "[email protected]",
    "acceptTerms": "true",
    "messages": "[{{\"role\":\"user\",\"content\":\"Hello\"}}]",
    "promptTokens": 34,
    "completionTokens": 76,
    "createdAt": "2025-03-21T10:00:00.000Z",
    "updatedAt": "2025-03-21T10:05:00.000Z",
    "finalizedAt": null
  }
]
```

#### Error Response
- **message** (string) - Server error details.
- **status** (number) - Error status code (e.g., 499 or 500).
```

--------------------------------

### GET /storage/product/[databaseIdHash]/[id]

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/14-products-api.md

Serves a binary attachment, such as a product image, from the `commerce` partition. The `[id]` is the `storageKey` referencing the attachment, and the server sets `Content-Type` based on the attachment's stored `mimeType`.

```APIDOC
## GET /storage/product/[databaseIdHash]/[id]

### Description
Serves a binary attachment (e.g., product image) from the `commerce` partition. The `[id]` is the `storageKey` referencing the attachment.

### Method
GET

### Endpoint
`/storage/product/[databaseIdHash]/[id]`

### Parameters
#### Path Parameters
- **databaseIdHash** (string) - Required - The hash identifying the database.
- **id** (string) - Required - The `storageKey` referencing the attachment.

### Response
#### Success Response (200)
- **binary data** - The binary content of the attachment (e.g., image data).

*(The server sets `Content-Type` based on the attachment’s stored `mimeType`.)*
```

--------------------------------

### API Key Deletion Not Found Response

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/19-keys-api.md

Example of an error response when the key to be deleted is not found.

```json
{ "message": "Data not found!", "status": 400 }
```

--------------------------------

### Error Response for Missing Fields

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/12-session-api.md

Example of an error response when required fields are missing in the request.

```json
{
  "message": "Invalid request, missing required fields",
  "status": 400
}
```

--------------------------------

### Copy Default Environment Variables

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/guides/1-getting-started.md

Copy the default environment variables file to a local configuration file. This sets up the initial configuration for the application.

```bash
cp .env.defaults .env.local
```

--------------------------------

### GET /api/memory/[filename]

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/31-memory-api.md

Fetches all records from a specific vector store. This does not perform vector-based search.

```APIDOC
## GET /api/memory/[filename]

### Description
Fetches all records (`items`) stored in `filename` as raw JSON. Does not perform vector-based search. Returns an array of stored items (full embeddings included).

### Method
GET

### Endpoint
/api/memory/[filename]

### Parameters
#### Path Parameters
- **filename** (string) - Required - The name of the vector store to retrieve records from.

### Request Example
```bash
curl -X GET \
  https://app.example.com/api/memory/my-new-store \
  -H "Authorization: Bearer abc1234exampleKey" \
  -H "database-id-hash: 35f5c5b139a6b569..."
```

### Response
#### Success Response (200)
- Returns an array of vector store records, each with `id`, `content`, `embedding`, and optional `metadata`, `createdAt`, `updatedAt`.

#### Response Example
```json
[
  {
    "id": "record-123",
    "content": "Some content here...",
    "embedding": [0.12, -0.08, ...],
    "metadata": { "source": "docs" }
  }
]
```

#### Error Response (404)
- **error** (string) - Message indicating the store was not found.

#### Error Response Example
```json
{
  "error": "Store not found"
}
```
```

--------------------------------

### Get All Agents

Source: https://github.com/catchthetornado/open-agents-builder-docs/blob/main/src/content/docs/api/10-agent-api.md

Retrieves a list of all agents. This endpoint can optionally be filtered using query parameters.

```APIDOC
## GET /api/agent

### Description
Get all agents (optionally filter with query parameters).

### Method
GET

### Endpoint
/api/agent
```