### Install Vertesia SDK using npm

Source: https://docs.vertesiahq.com/quickstart

Installs the Vertesia SDK package into your project using npm. This SDK requires Node.js version 18 or higher and the fetch API.

```bash
npm install @vertesia/client
```

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

### Install Vertesia CLI using npm

Source: https://docs.vertesiahq.com/quickstart

Installs the Vertesia CLI globally using npm. This command requires Node.js version 18 or higher.

```bash
npm -g install @vertesia/cli
```

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

### List Projects with Vertesia Client

Source: https://docs.vertesiahq.com/quickstart

Initializes the VertesiaClient and lists all projects within an organization. Requires an API key for authentication. The output includes the name and ID of each project.

```javascript
import { VertesiaClient } from "@vertesia/client"

const client = new VertesiaClient({
  site: 'api.vertesia.io',
  apikey: '<YOUR_API_KEY>',
})

const projects = await client.projects.list();

for (const project of projects) {
  console.log(project.name + ': ' + project.id);
}
```

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

### Create a Vertesia Profile

Source: https://docs.vertesiahq.com/quickstart

Creates a new profile for interacting with Vertesia environments (preview or prod). This command initiates an interactive prompt to gather necessary information.

```bash
vertesia profiles create
```

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

### Example JSON Response for Discovering Tools

Source: https://docs.vertesiahq.com/agent-runner/custom-tools

An example of the JSON response returned by the GET endpoint for discovering tools. It illustrates how a tool server can list its capabilities, including a 'weather' tool with its input schema.

```json
{
  "src": "http://localhost:5173/api/test",
  "title": "Development Tools",
  "description": "A collection of test tools for development purposes",
  "tools": [
    {
      "name": "weather",
      "description": "Get the current weather for a given location.",
      "input_schema": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "The location to get the weather for, e.g., 'New York, NY'."
          }
        },
        "required": [
          "location"
        ]
      }
    }
  ]
}

```

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

### Run Vertesia Interactions with Tags

Source: https://docs.vertesiahq.com/quickstart

Runs multiple Vertesia interactions and assigns them a 'testing' tag. This allows for easy grouping and retrieval of related run results.

```bash
vertesia run --tags testing {INTERACTION_1_ID}
vertesia run --tags testing {INTERACTION_2_ID}
```

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

### List Interactions with Vertesia Client

Source: https://docs.vertesiahq.com/quickstart

Initializes the VertesiaClient and lists interactions within a specific project. Requires an API key and project ID for authentication and project selection. The output includes the name and ID of each interaction.

```javascript
import { VertesiaClient } from "@vertesia/client"

const client = new VertesiaClient({
  site: 'api.vertesia.io',
  apikey: '<YOUR_API_KEY>',
  projectId: "<YOUR_PROJECT_ID>"
})

const interactions = await client.interactions.list();

for (const interaction of interactions) {
    console.log(interaction.name + ': ' + interaction.id);
}
```

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

### Submit Task to Multipurpose Agent

Source: https://docs.vertesiahq.com/agent-runner/getting-started

This code snippet represents the task description to be submitted to the Vertesia 'Multipurpose Agent'. It instructs the agent to generate three lease agreement documents with specific metadata, create a document type if it doesn't exist, and organize these documents into a collection named 'Office Leases'. This task involves multiple operations beyond simple LLM inference, including content generation, document management, and collection creation.

```text
Generate three lease agreement documents for commercial office space, each tailored to different specifications:

- A basic, cost-effective option suitable for approximately eight workstations.
- A mid-range option accommodating approximately twenty workstations, three meeting rooms, and two individual phone booths.
- A premium option located on the fortieth floor or above in an office building, designed to accommodate approximately fifty workstations, ten meeting rooms, and ten individual phone booths.

A lease agreement document must have the following metadata properties:
- space size in square feet
- term length
- monthly cost
- deposit amount
- state
- city
- address
- property manager

If a document type named  “Lease Agreement” doesn’t already exit, create it with properties listed above

Subsequently, these documents should be organized and stored within a collection named "Office Leases."
```

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

### Start PDF Analysis using SDK

Source: https://docs.vertesiahq.com/semantic/getting-started

This code snippet shows how to trigger the analysis of an uploaded PDF file using the Vertesia SDK's `analyze` function with the `start` method. It takes an object ID and an optional features array as input. The `start` function initiates an asynchronous analysis process.

```typescript
// Run analysis
const analysisRun = await client.objects.analyze(object.id).start({
  features: [],
});
console.log("Analysis Started", analysisRun);

```

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

### List Vertesia Interactions

Source: https://docs.vertesiahq.com/quickstart

Lists available interactions associated with the currently active Vertesia profile. This command helps in managing and viewing your defined interactions.

```bash
vertesia interactions
```

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

### Install Vertesia CLI using npm

Source: https://docs.vertesiahq.com/cli

Installs the Vertesia CLI globally on your system using npm. This command requires Node.js and npm to be pre-installed.

```bash
npm install -g @vertesia/cli
```

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

### Build Memory Pack with Vertesia CLI

Source: https://docs.vertesiahq.com/use-cases/release-notes-generation

Builds a Memory Pack for release notes using the `vertesia memo build` command. It uploads the pack to a specified Vertesia bucket path, including the GitHub Run ID and commit SHA. The `start` and `end` variables define the range of release notes to be processed. This command requires the `vertesia` CLI to be installed and configured.

```yaml
- name: Gather information
  run: |
    vertesia memo build \
        --out "memory:release-notes/${GITHUB_RUN_ID}-${GITHUB_SHA::7}" \
        --var-start "${{ env.PREVIOUS_TAG }}" \
        --var-end "${{ env.TARGET_TAG }}" \
        examples/api-doc-gen/recipes/release-notes.ts
```

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

### Run a Vertesia Interaction

Source: https://docs.vertesiahq.com/quickstart

Executes a specified Vertesia interaction using its unique ID. This command can take options for input data and tagging runs for later retrieval.

```bash
vertesia run {INTERACTION_ID}
```

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

### Retrieve Vertesia Runs by Tag

Source: https://docs.vertesiahq.com/quickstart

Searches and retrieves past Vertesia run results that have been tagged with 'testing'. This is useful for inspecting specific sets of interaction executions.

```bash
vertesia runs --tags testing
```

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

### Verify Vertesia CLI Installation

Source: https://docs.vertesiahq.com/cli

Checks if the Vertesia CLI has been installed correctly by displaying its current version. This command is useful after installation or updates.

```bash
vertesia --version
```

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

### Install Vertesia CLI Globally

Source: https://docs.vertesiahq.com/use-cases/release-notes-generation

This command installs the Vertesia CLI globally on the GitHub Actions runner using npm. This makes the 'vertesia' command available for use in subsequent steps of the workflow, allowing for interactions with the Vertesia service.

```bash
- run: npm install -g @vertesia/cli
```

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

### Execute Interaction with Vertesia Client

Source: https://docs.vertesiahq.com/quickstart

Executes a specific interaction within a project using the VertesiaClient. Requires an API key and interaction ID. It sends data to the interaction and logs the LLM's result. The input data format can vary based on the interaction's requirements.

```javascript
import { VertesiaClient } from "@vertesia/client"

const client = new VertesiaClient({
  site: 'api.vertesia.io',
  apikey: '<YOUR_API_KEY>',
  projectId: "<YOUR_PROJECT_ID>"
})

// Note that the interactionId argument must be a valid interaction ID which belongs to the project you are connected to.
const run = await client.interactions.execute(interactionId, {
    data: { object: "sky" }
});

console.log(run.result);
```

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

### Start Training API

Source: https://docs.vertesiahq.com/api/training

Initiates a training session for a specified session ID.

```APIDOC
## Start Training

### Description
Initiates a training session for a specified session ID.

### Method
POST

### Endpoint
/api/v1/training/<SESSION_ID>/start

### Parameters
#### Path Parameters
- **<SESSION_ID>** (string) - Required - The ID of the training session.

#### Request Body
This endpoint does not have a request body.

### Request Example
```json
{
  "message": "Example request"
}
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the job.
- **status** (string) - The status of the job (e.g., "pending").
- **created_at** (string) - Timestamp of creation.
- **updated_at** (string) - Timestamp of last update.

#### Response Example
```json
{
  "id": "<JOB_ID>",
  "status": "pending",
  "created_at": "2023-08-22T14:12:34.567Z",
  "updated_at": "2023-08-22T14:12:34.567Z"
}
```
```

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

### Get Vertesia CLI Help

Source: https://docs.vertesiahq.com/cli

Provides general help information for the Vertesia CLI. It can also be used to get specific help for individual commands by appending '--help' or using the 'help [command]' syntax.

```bash
vertesia --help
```

```bash
vertesia help [command]
```

```bash
vertesia <command> --help
```

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

### Example Intake Workflow Definition (JSON)

Source: https://docs.vertesiahq.com/workflows/configuration

This JSON defines an example intake workflow triggered by a new text document upload. It includes steps for setting document status, extracting text, generating content types and properties, chunking documents, and generating embeddings. It utilizes variables for interaction names and conditional logic based on extracted text.

```json
{
  "name": "MyWorkflow",
  "description": "This is my workflow.",
  "vars": {
    "interactionsNames": {
      "extractInformation": "sys:ExtractInformation",
      "selectDocumentType": "sys:SelectDocumentType",
      "generateMetadataModel": "sys:GenerateMetadataModel",
      "chunkDocument": "sys:ChunkDocument"
    }
  },
  "steps": [
    {
      "name": "setDocumentStatus",
      "params": {
        "status": "processing"
      }
    },
    {
      "title": "Extract text from the current document",
      "name": "generateObjectText",
      "type": "workflow",
      "output": "extractResult"
    },
    {
      "title": "Generate or assign a content type for the current document",
      "name": "generateOrAssignContentType",
      "import": ["interactionsNames"],
      "params": {
        "interactionNames": {
          "generateMetadataModel": "${interactionsNames.generateMetadataModel}",
          "selectDocumentType": "${interactionsNames.selectDocumentType}"
        }
      },
      "condition": {
        "extractResult.hasText": {
          "$eq": true
        }
      }
    },
    {
      "title": "Generate document properties from text content",
      "name": "generateDocumentProperties",
      "import": ["interactionsNames"],
      "params": {
        "interactionName": "${interactionsNames.extractInformation}"
      },
      "condition": {
        "extractResult.hasText": {
          "$eq": true
        }
      }
    },
    {
      "title": "Chunk the current document text",
      "name": "chunkDocument",
      "import": ["interactionsNames"],
      "params": {
        "interactionName": "${interactionsNames.chunkDocument}",
        "createParts": true
    },
      "condition": {
        "extractResult.hasText": {
        "$eq": true
        }
    }
    },
    {
      "name": "generateEmbeddings",
      "title": "Generate embeddings for text",
      "params": {
        "type": "text",
        "force": false
      }
    },
    {
      "name": "setDocumentStatus",
      "params": {
        "status": "completed"
      }
    }
  ]
}
```

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

### Set Up Node.js for Vertesia CLI in GitHub Actions

Source: https://docs.vertesiahq.com/use-cases/release-notes-generation

This YAML snippet configures the GitHub Actions environment to use Node.js version 22. This is a prerequisite for installing and running the Vertesia CLI, ensuring the necessary runtime environment is available for the subsequent installation steps.

```yaml
- uses: actions/setup-node@v4
  with:
    node-version: 22
```

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

### GET /projects

Source: https://docs.vertesiahq.com/api/projects

Lists all projects, optionally filtered by account.

```APIDOC
## List Projects

### Description
Retrieves a list of all projects, with an option to filter by account.

### Method
GET

### Endpoint
/projects

#### Query Parameters
- **account** (string[]) - Optional - An optional list of Account IDs to filter by.

#### Headers
- **Authorization** (string) - Required - Bearer <YOUR_JWT_TOKEN>

### Request Example
#### List all Projects
```curl
curl --location --request GET 'https://api.vertesia.io/api/v1/projects' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'
```
#### List Projects for an Account
```curl
curl --location --request GET 'https://api.vertesia.io/api/v1/projects?account=<ACCOUNT_ID>' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the project.
- **name** (string) - The name of the project.
- **account** (string) - The ID of the account the project belongs to.

#### Response Example
```json
[
  {
    "id": "<PROJECT_ID>",
    "name": "My Project",
    "account": "<ACCOUNT_ID>"
  }
]
```
```

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

### Start Conversation Activity

Source: https://docs.vertesiahq.com/workflows/activities-catalog

Initiates a new conversation with specified parameters for tools, visibility, and search scope.

```APIDOC
## POST /activities/startConversation

### Description
Initiates a new conversation. This activity allows for setting up conversation parameters such as visibility, tool usage, and search scope.

### Method
POST

### Endpoint
/activities/startConversation

### Parameters
#### Request Body
- **type** (string) - Required - Must be 'activity'.
- **name** (string) - Required - Must be 'startConversation'.
- **params** (object) - Required - Parameters for the conversation.
  - **payload** (object) - Required - Defines the conversation's payload.
    - **type** (string) - Required - Must be 'conversation'.
    - **visibility** (string) - Optional - 'private' or 'project'.
    - **tool_names** (string[]) - Optional - List of tool names to be used.
    - **max_iterations** (number) - Optional - Maximum number of iterations for the conversation.
    - **interactive** (boolean) - Optional - Whether the conversation is interactive.
    - **disable_interaction_tools** (boolean) - Optional - Whether to disable interaction tools.
    - **search_scope** (string) - Optional - Scope for search operations.
    - **collection_id** (string) - Optional - ID of the collection for the conversation.
    - **checkpoint_tokens** (number) - Optional - Number of checkpoint tokens.
    - **task_id** (string) - Optional - ID of the task associated with the conversation.
    - **debug_mode** (boolean) - Optional - Enables debug mode.
    - **max_nested_conversation_depth** (number) - Optional - Maximum depth for nested conversations.
  - **tools** (array) - Optional - Array of tool definitions.
    - **name** (string) - Required - Tool name.
    - **description** (string) - Optional - Tool description.
    - **input_schema** (object) - Optional - JSON schema for tool input.
  - **tool_reference** (object) - Optional - Reference to stored tools.
    - **storage_key** (string) - Required - Key for storage.
    - **tool_count** (number) - Required - Number of tools.
    - **stored_at** (string) - Required - Timestamp of storage.
- **output** (string) - Required - Specifies the output format, typically 'renditions'.

### Request Example
```json
{
  "type": "activity",
  "name": "startConversation",
  "params": {
    "payload": {
      "type": "conversation",
      "visibility": "private",
      "tool_names": ["tool1", "tool2"],
      "max_iterations": 10,
      "interactive": true,
      "search_scope": "project",
      "collection_id": "coll_123",
      "task_id": "task_abc",
      "debug_mode": false,
      "max_nested_conversation_depth": 5
    },
    "tools": [
      {
        "name": "calculator",
        "description": "Performs mathematical calculations.",
        "input_schema": {
          "type": "object",
          "properties": {
            "expression": {"type": "string"}
          },
          "required": ["expression"]
        }
      }
    ],
    "tool_reference": {
      "storage_key": "ref_key_456",
      "tool_count": 1,
      "stored_at": "2023-10-27T10:00:00Z"
    }
  },
  "output": "renditions"
}
```

### Response
#### Success Response (200)
- **renditions** (object) - The output of the activity, typically containing conversation results.
```

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

### POST /api/v1/commands/onboarding/init-samples

Source: https://docs.vertesiahq.com/api/commands

Initializes onboarding samples for Vertesia.

```APIDOC
## POST /api/v1/commands/onboarding/init-samples

### Description
Initializes onboarding samples for Vertesia. This endpoint is used to set up initial data or configurations for new users or projects.

### Method
POST

### Endpoint
/api/v1/commands/onboarding/init-samples

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "example": "curl -X POST \n  'https://api.vertesia.io/api/v1/commands/onboarding/init-samples' \n  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>'"
}
```

### Response
#### Success Response (200)
This endpoint does not specify a success response body in the provided documentation.

#### Response Example
```json
{
  "example": ""
}
```
```

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

### Get Run Filter Options using cURL

Source: https://docs.vertesiahq.com/api/runs

This snippet demonstrates how to fetch filter options for the 'environment' field using a cURL command. It requires an Authorization header with a Bearer token. The example shows a GET request to the specified endpoint.

```bash
curl --location 'https://api.vertesia.io/api/v1/runs/filter-options/environment' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'
```

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

### Onboarding API

Source: https://docs.vertesiahq.com/api/commands

Endpoint for initializing onboarding samples.

```APIDOC
## POST /commands/onboarding/init-samples

### Description
Initializes sample data for onboarding purposes.

### Method
POST

### Endpoint
`/commands/onboarding/init-samples`

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication. Example: `Bearer <YOUR_JWT_TOKEN>`

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation (e.g., "success").
- **message** (string) - A confirmation message (e.g., "Samples initialized").

### Response Example
```json
{
  "status": "success",
  "message": "Samples initialized"
}
```
```

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

### Get Object Content Source using cURL

Source: https://docs.vertesiahq.com/api/objects

This cURL example shows how to get the content source details of an object from the Vertesia API. It requires the object ID and an authorization token. The response includes the source URI, MIME type, original name, and etag.

```bash
curl -X GET \
  https://api.vertesia.io/api/v1/objects/<OBJECT_ID>/content-source \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>'
```

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

### Initialize Samples - cURL

Source: https://docs.vertesiahq.com/api/commands

Initializes sample data for onboarding. Requires an Authorization header with a JWT token. Uses POST method.

```cURL
curl -X POST \
  'https://api.vertesia.io/api/v1/commands/onboarding/init-samples' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>'
```

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

### Change Project ID in Vertesia Client

Source: https://docs.vertesiahq.com/quickstart

Demonstrates how to change the active project ID for an existing VertesiaClient instance. This allows switching to a different project without re-initializing the client.

```javascript
client.project = "New Project ID"
```

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

### API Error Response Example

Source: https://docs.vertesiahq.com/errors

This JSON object represents a typical error response from the API. It includes an error code and a detailed message explaining the issue, such as rate limiting. This helps in debugging and understanding the cause of a failed request.

```json
{
  "code": "error",
  "message": "429 Rate limit reached for gpt-4 in organization on tokens per min.
  Limit: 10000 / min.
  Please try again in 6ms.
  Contact us through our help center at help.openai.com if you continue to have issues."
  }
```

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

### Example LLM System Prompt for Release Notes

Source: https://docs.vertesiahq.com/use-cases/release-notes-generation

This JavaScript template demonstrates how to create a system prompt for an LLM to generate release notes. It sets a persona for the LLM as a Release Manager specializing in SaaS products and specifies the target audience.

```javascript
return `
## Instructions

You need to write release notes on release ${release_version}, highlighting
changes between the current version ${release_version} and the previous version
${previous_version}.

...
`
```

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

### POST /projects

Source: https://docs.vertesiahq.com/api/projects

Creates a new project.

```APIDOC
## Create a Project

### Description
Creates a new project with the specified details.

### Method
POST

### Endpoint
/projects

#### Headers
- **Authorization** (string) - Required - Bearer <YOUR_JWT_TOKEN>
- **Content-Type** (string) - Required - application/json

#### Request Body
- **name** (string) - Required - The name of the Project.
- **namespace** (string) - Required - The namespace of the Project.
- **description** (string) - Optional - The description of the Project.

### Request Example
```curl
curl --location --request POST 'https://api.vertesia.io/api/v1/projects' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{ \
    "name": "My Project", \
    "namespace": "my-project", \
    "description": "This is my project." \
}'
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the newly created project.
- **name** (string) - The name of the project.
- **namespace** (string) - The namespace of the project.
- **description** (string) - A description of the project.
- **account** (string) - The ID of the account the project belongs to.
- **configuration** (object) - Project configuration details.
- **integrations** (object) - Project integrations.
- **created_by** (string) - Identifier for the user who created the project.
- **updated_by** (string) - Identifier for the user who last updated the project.
- **created_at** (string) - Timestamp of when the project was created.
- **updated_at** (string) - Timestamp of when the project was last updated.

#### Response Example
```json
{
  "id": "<PROJECT_ID>",
  "name": "My Project",
  "namespace": "my-project",
  "description": "This is my project.",
  "account": "<ACCOUNT_ID>",
  "configuration": {
    "human_context": "You are a helpful AI assistant.",
    "embeddings": {}
  },
  "integrations": {},
  "created_by": "user:<USER_ID>",
  "updated_by": "user:<USER_ID>",
  "created_at": "2023-07-19T13:54:12.854Z",
  "updated_at": "2023-07-19T13:54:12.854Z"
}
```
```

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

### Upload PDF to Vertesia using SDK

Source: https://docs.vertesiahq.com/semantic/getting-started

This code snippet demonstrates how to upload a PDF file to Vertesia using the Vertesia SDK. It initializes the client, creates a readable stream from the file path, and then creates an object with the file content. Dependencies include `@vertesia/client` and `node-web-stream-adapters`.

```typescript
import { StreamSource, VertesiaClient } from "@vertesia/client";
import { createReadableStreamFromReadable } from "node-web-stream-adapters";

// Initialize client
const client = new VertesiaClient({
  apikey,
});

const stream = createReadStream(<FILE_PATH>);
const content = new StreamSource(
  createReadableStreamFromReadable(stream),
  path.basename(<FILE_PATH>),
  "application/pdf",
);
const object = await client.objects.create({
  content: content,
});

```

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

### Get PDF Analysis Results using SDK

Source: https://docs.vertesiahq.com/semantic/getting-started

This code snippet illustrates how to fetch the complete results of a completed PDF analysis using the Vertesia SDK. After the analysis is finished, the `getResult` function can be called with the object ID to retrieve the processed document data. The results object contains a `document` property with the analysis output.

```typescript
// Get Results
const results = await client.objects.analyze(object.id).getResults();
console.log(results.document);

```

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

### Key Features

Source: https://docs.vertesiahq.com/api/introduction

Overview of the core capabilities offered by the Vertesia Platform API, including asynchronous execution, semantic document preparation, enhanced search, and workflow management.

```APIDOC
## Key Features

### Description

The Vertesia Platform API provides several powerful capabilities to enhance your document processing and interaction workflows:

*   **Asynchronous Interaction Execution:** Supports long-running conversations and tool usage through asynchronous execution endpoints, allowing for non-blocking operations.
*   **Semantic DocPrep:** Offers advanced document analysis features, including:
    *   Deep linking to specific content locations within documents.
    *   Automatic table detection and extraction.
    *   Image analysis for meaningful content detection.
    *   Visual layout understanding for better document comprehension.
*   **Enhanced Search:** Provides comprehensive search capabilities across runs, workflows, and content, with support for faceted filtering to refine search results.
*   **Workflow Management:** Enables users to create, monitor, and control complex document processing workflows.
```

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

### Prompt Content for Lease Agreement Generation

Source: https://docs.vertesiahq.com/agent-runner/configuration

Provides the core instructions for the AI agent to generate lease agreement documents based on provided specifications and metadata.

```javascript
return `
Generate ${agreements.length} lease agreement documents for commercial office space, each tailored to different specifications:

${agreements.map((agreement,index) => `${index+1}. ${agreement}`).join('\n')}

A lease agreement document must have the following metadata properties:
- space size in square feet
- term length
- monthly cost
- deposit amount
- state
- city
- address
- property manager

If a document type named  ${documentType} doesn’t already exit, create it with properties listed above

Subsequently, these documents should be organized and stored within a collection named ${collectionName}". Create a collection only if doesn't already exists
`
```

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

### Manage Vertesia CLI Profiles

Source: https://docs.vertesiahq.com/cli

Commands for managing configuration profiles, which allow switching between different Vertesia accounts and projects. Includes showing, using, adding, editing, refreshing, deleting, and locating profile configuration files.

```bash
vertesia profiles show [name]
```

```bash
vertesia profiles use [name]
```

```bash
vertesia profiles add [name] --target <environment>
```

```bash
vertesia profiles edit [name]
```

```bash
vertesia profiles refresh
```

```bash
vertesia profiles delete <name>
```

```bash
vertesia profiles file
```

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

### Get Embeddings Status - cURL

Source: https://docs.vertesiahq.com/api/commands

Retrieves the current status of embeddings for a specified type. Requires an Authorization header with a JWT token. Uses GET method.

```cURL
curl -X GET \
  'https://api.vertesia.io/api/v1/commands/embeddings/text/status' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>'
```

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

### Get Object Revisions using cURL

Source: https://docs.vertesiahq.com/api/objects

Fetches revisions for a specified object via a GET request. Authentication is handled through the Authorization header, and the objectId is a required path parameter.

```bash
curl -X GET \
  https://api.vertesia.io/api/v1/objects/<OBJECT_ID>/revisions \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>'
```

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

### Vertesia CLI Usage for Running Interactions

Source: https://docs.vertesiahq.com/use-cases/release-notes-generation

Basic usage pattern for the Vertesia CLI to run an interaction. It specifies the command and the placeholder for the interaction name, which can include namespaces and tags/versions.

```bash
vertesia run [options] <interaction>
```

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

### GET /interactions/names

Source: https://docs.vertesiahq.com/api/interactions

Retrieves a list of all interaction names available within the project. This endpoint is useful for quickly getting an overview of available interactions without fetching full details.

```APIDOC
## List Interaction Names

### Description
Retrieves a list of all interaction names available within the project. This endpoint is useful for quickly getting an overview of available interactions without fetching full details.

### Method
GET

### Endpoint
`/interactions/names`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
This request does not have a request body.

### Request Example
There is no JSON body with this request.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the interaction.
- **name** (string) - The display name of the interaction.

#### Response Example
```json
[
  {
    "id": "<INTERACTION_ID>",
    "name": "My Interaction"
  }
]
```
```

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

### Authentication

Source: https://docs.vertesiahq.com/api/introduction

Details on how to authenticate API requests using JWT tokens and API Keys for both Studio API and Zeno API.

```APIDOC
## Authentication

### Description

Both the Studio API and the Zeno API use JWT tokens to authenticate API requests. Only the Studio API can authenticate API requests using an API Key. It's best practice to exchange an API Key for a JWT Token. This simplifies authentication so you can use the same authentication, regardless of the API.

### JWT Token Authentication

Use a valid JWT token in the `Authorization` header of your requests:

```
Authorization: Bearer YOUR_JWT_TOKEN
```

### API Key Authentication (Studio API Only)

To authenticate with an API Key, you typically need to exchange it for a JWT token first. The process for obtaining a JWT token from an API Key is usually detailed in the 'Getting Started' section or a dedicated authentication endpoint.

*It's recommended to use the JWT token for subsequent API calls after obtaining it with your API Key.*
```

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

### Get Object Renditions using cURL

Source: https://docs.vertesiahq.com/api/objects

Retrieves a list of renditions for a specific object using a GET request. Requires an Authorization header with a JWT token and the objectId as a path parameter.

```bash
curl -X GET \
  https://api.vertesia.io/api/v1/objects/<OBJECT_ID>/renditions \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>'
```

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

### Vertesia CLI Command for Running Interactions

Source: https://docs.vertesiahq.com/use-cases/release-notes-generation

This command demonstrates how to run a Vertesia interaction, specifically 'GenerateReleaseNotes', with data mappings provided via the -d or --data option. It shows how to map Memory Packs and specific files to interaction parameters.

```bash
mappings=$(cat << EOF\n{\n    "@memory": "release-notes/${GITHUB_RUN_ID}-${GITHUB_SHA::7}",\n    "@": "@",\n    "issues": "@content:issues/*",\n    "pull_requests": "@content:pull_requests/*",\n    "code_diff": "@content:range_diff.txt",\n    "commits": "@content:commits.txt"\n}\nEOF\n)\n\nvertesia run GenerateReleaseNotes -d "$mappings"
```

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

### Get All Projects in Account (cURL)

Source: https://docs.vertesiahq.com/api/account

Retrieves a list of all projects associated with the current account using a GET request. Requires an Authorization header with a Bearer token. No request body is needed.

```cURL
curl --location --request GET 'https://api.vertesia.io/api/v1/account/projects' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'
```

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

### Initialize Vertesia Client with TypeScript SDK

Source: https://docs.vertesiahq.com/agent-runner/sdk

This snippet shows how to initialize the Vertesia client using the TypeScript SDK. Ensure you replace '<YOUR_API_KEY>' with your actual API key. This client instance is used for all subsequent interactions with Vertesia services.

```typescript
import { VertesiaClient } from "@vertesia/client";
import { AgentMessageType } from "@vertesia/common";

const vertesia = new VertesiaClient({
  site: 'api.vertesia.io',
  apikey: '<YOUR_API_KEY>',
});

```

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

### Get Current Account Details (cURL)

Source: https://docs.vertesiahq.com/api/account

Retrieves all account information for the current account using a GET request. Requires an Authorization header with a Bearer token. No request body is needed.

```cURL
curl --location --request GET 'https://api.vertesia.io/api/v1/account' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'
```

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

### Example App Manifest with Tool Collections (JSON)

Source: https://docs.vertesiahq.com/apps/overview

Illustrates a JSON object representing an application manifest, specifically highlighting the inclusion of the `tool_collections` property to register custom tool servers.

```json
{
  "name": "my-tools",
  ...
  "tool_collections": ["https://my-tools-server.com/endpoint"]
}
```

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

### POST /training

Source: https://docs.vertesiahq.com/api/training

Creates a new Training Session. This endpoint allows you to set up a new training session with a specified name, environment, and model.

```APIDOC
## POST /training

### Description
Creates a new Training Session. This endpoint allows you to set up a new training session with a specified name, environment, and model.

### Method
POST

### Endpoint
/training

#### Headers
- **Authorization** (string) - Required - `Bearer <YOUR_JWT_TOKEN>`

#### Request Body
- **name** (string) - Required - The name of the Training Session
- **env** (string) - Required - The ID of the environment to use for training
- **model** (string) - Required - The ID of the model to use for training

### Request Example
```json
{
  "name": "My Training Session",
  "env": "<ENVIRONMENT_ID>",
  "model": "<MODEL_ID>"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the training session.
- **project** (string) - The project ID associated with the training session.
- **name** (string) - The name of the training session.
- **env** (object) - Details about the training environment.
  - **id** (string) - The environment ID.
  - **name** (string) - The environment name.
  - **provider** (string) - The environment provider (e.g., "openai").
- **model** (string) - The ID of the model used for training.
- **status** (string) - The current status of the training session (e.g., "created").
- **runs** (array) - An array of runs associated with the session.
- **dataset** (any) - Information about the dataset used, or null.
- **job** (object) - Details about the training job.
- **created_by** (string) - The user ID who created the session.
- **updated_by** (string) - The user ID who last updated the session.
- **created_at** (string) - The timestamp when the session was created.
- **updated_at** (string) - The timestamp when the session was last updated.

#### Response Example
```json
{
  "id": "<SESSION_ID>",
  "project": "<PROJECT_ID>",
  "name": "My Training Session",
  "env": {
    "id": "<ENVIRONMENT_ID>",
    "name": "<ENVIRONMENT_NAME>",
    "provider": "openai"
  },
  "model": "<MODEL_ID>",
  "status": "created",
  "runs": [],
  "dataset": null,
  "job": {},
  "created_by": "user:<USER_ID>",
  "updated_by": "user:<USER_ID>",
  "created_at": "2023-08-22T14:12:34.567Z",
  "updated_at": "2023-08-22T14:12:34.567Z"
}
```
```

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

### Get Training Data URL (cURL)

Source: https://docs.vertesiahq.com/api/training

Retrieves the URL for accessing the generated training data for a specific session. This is a GET request that returns a JSON object containing the dataset URL. Requires an Authorization header.

```cURL
curl -X GET \
  https://api.vertesia.io/api/v1/training/<SESSION_ID>/url \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>'
```

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

### Get Training Job Status - cURL

Source: https://docs.vertesiahq.com/api/training

Retrieves the status of a training job using a GET request. Requires the job ID and JWT for authorization. Supports an optional 'sync' query parameter to wait for job completion.

```cURL
curl -X GET \
  https://api.vertesia.io/api/v1/training/job/<JOB_ID>?sync=true \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>'
```

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

### Build Memory Pack using Vertesia CLI

Source: https://docs.vertesiahq.com/use-cases/release-notes-generation

This command builds a memory pack using the Vertesia CLI. It allows specifying the output location (local or Google Cloud via `memory:` prefix), and version ranges for tracking changes. The command takes a TypeScript recipe file as input.

```shell
vertesia memo build \
    --out "memory:release_notes/my_package-1_2_0" \
    --var-start "my_package/v1.1.0" \
    --var-end "my_package/v1.2.0" \
    recipes/release-notes.ts
```

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

### Get Onboarding Progress (cURL)

Source: https://docs.vertesiahq.com/api/account

Sends a GET request to retrieve the onboarding progress for the current account. Requires the JWT token for authorization. Returns a JSON object indicating completion status for various onboarding steps.

```cURL
curl --location --request GET 'https://api.vertesia.io/api/v1/account/onboarding' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'
```

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

### Create an Environment

Source: https://docs.vertesiahq.com/api/environments

Creates a new environment with the specified details. Requires authentication.

```APIDOC
## Create an Environment

### Description
Creates a new environment with the specified details. Requires authentication.

### Method
POST

### Endpoint
/environments

### Request Body
- **name** (string) - Required - The name of the environment.
- **provider** (string) - Required - The provider of the environment (e.g., 'openai').
- **description** (string) - Optional - An optional description of the environment.
- **endpoint_url** (string) - Optional - The endpoint URL of the environment.
- **default_model** (string) - Optional - The default model for the environment.
- **apiKey** (string) - Required - The API key for the environment.
- **config** (object) - Optional - The configuration for the environment.
- **allowed_projects** (string[]) - Optional - The projects that are allowed to use the environment.

### Request Example
```json
{
  "name": "My OpenAI Environment",
  "provider": "openai",
  "description": "My OpenAI environment",
  "endpoint_url": "https://api.openai.com/v1",
  "default_model": "text-davinci-003",
  "apiKey": "sk-...",
  "config": {},
  "allowed_projects": [
    "<PROJECT_ID>"
  ]
}
```

### Response
#### Success Response (200 or 201)
- **id** (string) - The unique identifier for the newly created environment.
- **name** (string) - The name of the environment.
- **provider** (string) - The cloud provider for the environment.
- **description** (string) - The description of the environment.
- **endpoint_url** (string) - The endpoint URL of the environment.
- **default_model** (string) - The default model for the environment.
- **apiKey** (string) - The API key for the environment (often masked in responses).
- **config** (object) - The configuration for the environment.
- **account** (string) - The account ID associated with the environment.
- **allowed_projects** (string[]) - An array of project IDs that are allowed to use this environment.
- **created_by** (string) - Identifier for the user who created the environment.
- **updated_by** (string) - Identifier for the user who last updated the environment.
- **created_at** (string) - The timestamp when the environment was created.
- **updated_at** (string) - The timestamp when the environment was last updated.

#### Response Example
```json
{
  "id": "<ENVIRONMENT_ID>",
  "name": "My OpenAI Environment",
  "provider": "openai",
  "description": "My OpenAI environment",
  "endpoint_url": "https://api.openai.com/v1",
  "default_model": "text-davinci-003",
  "apiKey": "sk-************************",
  "config": {},
  "account": "<ACCOUNT_ID>",
  "allowed_projects": [
    "<PROJECT_ID>"
  ],
  "created_by": "user:<USER_ID>",
  "updated_by": "user:<USER_ID>",
  "created_at": "2023-10-26T15:23:04.443Z",
  "updated_at": "2023-10-26T15:23:04.443Z"
}
```
```

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

### Get Account Members (cURL)

Source: https://docs.vertesiahq.com/api/account

Sends a GET request to retrieve a list of users associated with the current account. Requires the JWT token for authorization. Returns an array of user objects, each containing details like ID, email, and name.

```cURL
curl --location --request GET 'https://api.vertesia.io/api/v1/account/members' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'
```

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

### Test Data for Lease Agreement Prompt

Source: https://docs.vertesiahq.com/agent-runner/configuration

Sample input data used to test the 'Agent Lease Agreement' prompt configuration, including agreement descriptions and collection/document types.

```json
{
  "agreements": [
    "A basic, cost-effective option suitable for approximately eight workstations.",
    "A mid-range option accommodating approximately twenty workstations, three meeting rooms, and two individual phone booths.",
    "A premium option located on the fortieth floor or above in an office building, designed to accommodate approximately fifty workstations, ten meeting rooms, and ten individual phone booths."
  ],
  "collectionName": "Commercial Lease Agreements",
  "documentType": "CommercialLeaseAgreement"
}
```

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

### Configure App Card Color

Source: https://docs.vertesiahq.com/apps/installation-settings

Set the UI card color for an installed application using the 'color' property in the application settings JSON. This allows for customization of the application's appearance within the Vertesia App Portal. Ensure the color name is one of the predefined available options.

```json
{
  "color": "<color_name>"
}
```

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

### List Vertesia Environments

Source: https://docs.vertesiahq.com/cli

Lists the environments available within the current project or displays details for a specific environment if an 'envId' is provided.

```bash
vertesia envs [envId]
```

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

### GET /projects/<PROJECT_ID>

Source: https://docs.vertesiahq.com/api/projects

Retrieves a specific project by its ID.

```APIDOC
## Retrieve a Project

### Description
Retrieves a specific project using its unique identifier.

### Method
GET

### Endpoint
/projects/<PROJECT_ID>

#### Path Parameters
- **PROJECT_ID** (string) - Required - The ID of the Project to retrieve.

#### Headers
- **Authorization** (string) - Required - Bearer <YOUR_JWT_TOKEN>

### Request Example
```curl
curl --location --request GET 'https://api.vertesia.io/api/v1/projects/<PROJECT_ID>' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the project.
- **name** (string) - The name of the project.
- **namespace** (string) - The namespace of the project.
- **description** (string) - A description of the project.
- **account** (string) - The ID of the account the project belongs to.
- **configuration** (object) - Project configuration details.
- **integrations** (object) - Project integrations.
- **created_by** (string) - Identifier for the user who created the project.
- **updated_by** (string) - Identifier for the user who last updated the project.
- **created_at** (string) - Timestamp of when the project was created.
- **updated_at** (string) - Timestamp of when the project was last updated.

#### Response Example
```json
{
  "id": "<PROJECT_ID>",
  "name": "My Project",
  "namespace": "my-project",
  "description": "This is my project.",
  "account": "<ACCOUNT_ID>",
  "configuration": {
    "human_context": "You are a helpful AI assistant.",
    "default_environment": "<ENVIRONMENT_ID>",
    "default_model": "gpt-3.5-turbo",
    "embeddings": {
        "text": {
            "environment": "<ENVIRONMENT_ID>",
            "enabled": true,
            "dimensions": 1536
        }
    }
  },
  "integrations": {},
  "created_by": "user:<USER_ID>",
  "updated_by": "user:<USER_ID>",
  "created_at": "2023-07-19T13:54:12.854Z",
  "updated_at": "2023-07-19T13:54:12.854Z"
}
```
```

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

### JSON Schema for Lease Agreement Prompt

Source: https://docs.vertesiahq.com/agent-runner/configuration

Defines the structure for the 'Agent Lease Agreement' prompt, specifying required fields like agreements, collectionName, and documentType.

```json
{
  "type": "object",
  "properties": {
    "agreements": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "editor": "textarea",
      "format": "textarea"
    },
    "collectionName": {
      "type": "string"
    },
    "documentType": {
      "type": "string"
    }
  },
  "required": [
    "agreements",
    "collectionName",
    "documentType"
  ]
}
```