### Install Agentset SDK

Source: https://docs.agentset.ai/examples/quickstart

Install the Agentset SDK using your preferred package manager (npm, yarn, pnpm, or bun). This command adds the Agentset library to your project dependencies.

```JavaScript
npm install agentset
```

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

### Install Project Dependencies

Source: https://docs.agentset.ai/examples/self-hosting

After cloning the repository, run this command to install all necessary project dependencies using pnpm.

```Shell
pnpm i
```

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

### Retrieve Namespace API Call Example (cURL)

Source: https://docs.agentset.ai/examples/api-reference/endpoint/namespaces/get

Provides a cURL command example for making a GET request to retrieve a namespace. This example demonstrates how to construct the API call with the necessary authorization header.

```cURL
curl --request GET \
  --url https://api.agentset.ai/v1/namespace/{namespaceId} \
  --header 'Authorization: Bearer <token>'
```

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

### Create Namespace API Response Example

Source: https://docs.agentset.ai/examples/api-reference/endpoint/namespaces/create

Example JSON response returned upon successful creation of a namespace, detailing the namespace's ID, name, slug, organization ID, creation timestamp, and its embedding and vector store configurations.

```JSON
{
  "success": true,
  "data": {
    "id": "<string>",
    "name": "<string>",
    "slug": "<string>",
    "organizationId": "<string>",
    "createdAt": "<string>",
    "embeddingConfig": {
      "provider": "OPENAI",
      "model": "text-embedding-3-small",
      "apiKey": "<string>"
    },
    "vectorStoreConfig": {
      "provider": "PINECONE",
      "apiKey": "<string>",
      "indexHost": "https://example.svc.aped-1234-a56b.pinecone.io"
    }
  }
}
```

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

### Initialize Agentset Client

Source: https://docs.agentset.ai/examples/quickstart

Initialize the Agentset client with your API key. An API key is essential for authenticating your requests and can be obtained from the Agentset Dashboard.

```JavaScript
import { Agentset } from 'agentset';

// Initialize the client with your API key
const agentset = new Agentset({
  apiKey: 'your_api_key',
});
```

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

### Create Namespace API Request Example

Source: https://docs.agentset.ai/examples/api-reference/endpoint/namespaces/create

Example cURL command to create a new namespace for the authenticated organization, specifying its name, slug, and configurations for embedding and vector store providers.

```cURL
curl --request POST \
  --url https://api.agentset.ai/v1/namespace \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "<string>",
  "slug": "<string>",
  "embeddingConfig": {
    "provider": "OPENAI",
    "model": "text-embedding-3-small",
    "apiKey": "<string>"
  },
  "vectorStoreConfig": {
    "provider": "PINECONE",
    "apiKey": "<string>",
    "indexHost": "https://example.svc.aped-1234-a56b.pinecone.io"
  }
}'
```

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

### Agentset Financial Analysis Workflow in JavaScript

Source: https://docs.agentset.ai/examples/examples

This example demonstrates analyzing multiple financial documents by creating an Agentset agent, uploading multiple reports via ingest jobs, and performing comparative analysis using an AI model. It shows how to initialize Agentset, create namespaces, upload files with metadata, check job statuses, and use the knowledge base tool for AI-driven analysis.

```JavaScript
import { Agentset } from 'agentset';
import { makeAgentsetTool, DEFAULT_SYSTEM_PROMPT } from '@agentset/ai-sdk';
import { generateText } from 'ai';
import { createOpenAI } from '@ai-sdk/openai';
import fs from 'fs';

const openai = createOpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});
const model = openai('gpt-4o');

async function financialAnalysis() {
  // Initialize with environment variable
  const agentset = new Agentset({
    apiKey: process.env.AGENTSET_API_KEY,
  });

  // Create a namespace for financial reports
  const namespace = await agentset.namespaces.create({
    name: "Financial Reports",
  });

  // Get a reference to the namespace
  const ns = agentset.namespace(namespace.id);

  // Upload documents one by one via ingest jobs
  // Example: Create an ingest job for annual report
  const annualReportJob = await ns.ingestion.create({
    payload: {
      type: "FILE",
      fileUrl: "https://example.com/reports/annual-report-2024.pdf",
      name: "Annual Report 2024"
    },
    config: {
      metadata: {
        documentType: "annual_report",
        year: 2024
      }
    }
  });

  // Create ingest job for quarterly report
  const quarterlyReportJob = await ns.ingestion.create({
    payload: {
      type: "FILE",
      fileUrl: "https://example.com/reports/quarterly-report-q1-2024.pdf",
      name: "Quarterly Report Q1 2024"
    },
    config: {
      metadata: {
        documentType: "quarterly_report",
        year: 2024,
        quarter: "Q1"
      }
    }
  });

  // Create ingest job for benchmarks
  const benchmarksJob = await ns.ingestion.create({
    payload: {
      type: "FILE",
      fileUrl: "https://example.com/reports/industry-benchmarks-2024.pdf",
      name: "Industry Benchmarks 2024"
    },
    config: {
      metadata: {
        documentType: "benchmarks",
        year: 2024
      }
    }
  });

  console.log(`Ingest jobs created with IDs: ${annualReportJob.id}, ${quarterlyReportJob.id}, ${benchmarksJob.id}`);

  // Get all ingestion jobs and check their status
  const { jobs } = await ns.ingestion.all();
  console.log("All jobs:", jobs.map(job => ({ id: job.id, status: job.status })));

  // Run comparative analysis using chat
  const response = await generateText({
    model,
    systemPrompt: DEFAULT_SYSTEM_PROMPT,
    tools: {
      knowledgeBase: makeAgentsetTool(ns, {
        topK: 15,
        rerank: true
      }),
    },
    messages: [
      {
        role: "user",
        content: "Compare our Q1 2024 performance with annual projections and industry benchmarks. Highlight areas where we're outperforming or underperforming the industry."
      }
    ],
  });

  console.log("Analysis:", response.text);
}

financialAnalysis().catch(console.error);
```

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

### cURL Example: Retrieve Namespaces List

Source: https://docs.agentset.ai/examples/api-reference/endpoint/namespaces/list

A practical cURL command demonstrating how to send a GET request to the Agentset API to retrieve a list of namespaces, including the necessary Authorization header.

```cURL
curl --request GET \
  --url https://api.agentset.ai/v1/namespace \
  --header 'Authorization: Bearer <token>'
```

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

### Example Response for Deleted Namespace

Source: https://docs.agentset.ai/examples/api-reference/endpoint/namespaces/delete

An example JSON response body for a successful namespace deletion. This structure represents the details of the namespace that was deleted.

```JSON
{
  "success": true,
  "data": {
    "id": "<string>",
    "name": "<string>",
    "slug": "<string>",
    "organizationId": "<string>",
    "createdAt": "<string>",
    "embeddingConfig": {
      "provider": "OPENAI",
      "model": "text-embedding-3-small",
      "apiKey": "<string>"
    },
    "vectorStoreConfig": {
      "provider": "PINECONE",
      "apiKey": "<string>",
      "indexHost": "https://example.svc.aped-1234-a56b.pinecone.io"
    }
  }
}
```

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

### Agentset API Endpoint Overview

Source: https://docs.agentset.ai/examples/api-reference/introduction

An overview of the main API namespaces and their associated operations (GET, POST, PATCH, DEL) for managing namespaces, ingest jobs, documents, and search functionality.

```APIDOC
Namespaces:
  GET - Retrieve a list of namespaces
  GET - Retrieve a namespace
  POST - Create a namespace
  PATCH - Update a namespace
  DEL - Delete a namespace

Ingest Jobs:
  GET - Retrieve a list of ingest jobs
  GET - Retrieve an ingest job
  POST - Create an ingest job
  DEL - Delete an ingest job

Documents:
  GET - Retrieve a list of documents
  GET - Retrieve a document
  DEL - Delete a document

Search:
  POST - Search a namespace
```

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

### Search and Chat with Documents

Source: https://docs.agentset.ai/examples/quickstart

Perform searches or engage in conversational chat with documents stored within your Agentset namespace. Both operations support parameters like top-k results, reranking, and including metadata for search, and message history for chat.

```JavaScript
// Search the namespace
const searchResults = await ns.search("financial metrics 2024", {
  topK: 5,
  rerank: true,
  includeMetadata: true
});

console.log("Search results:", searchResults.data);

// Or have a conversation with your documents
const chatResponse = await ns.chat("What were our key financial metrics for 2024?", {
  messages: [
    { role: "user", content: "What were our key financial metrics for 2024?" }
  ],
  topK: 10,
  rerank: true
});

console.log("Answer:", chatResponse.data.text);
console.log("Sources:", chatResponse.data.sources);
```

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

### Upload Documents to Namespace

Source: https://docs.agentset.ai/examples/quickstart

Upload documents to your Agentset namespace by creating an ingest job. Documents can be specified via a file URL and include optional metadata for better organization and filtering.

```JavaScript
// Get a namespace by ID or slug
const ns = agentset.namespace("company-documentation");

// Upload documents to your namespace
const ingestJob = await ns.ingestion.create({
  payload: {
    type: "FILE",
    fileUrl: "https://example.com/annual-report-2024.pdf",
    name: "Annual Report 2024"
  },
  config: {
    metadata: {
      documentType: "financial",
      year: 2024
    }
  }
});

console.log(`Ingest job created with ID: ${ingestJob.id}`);
console.log(`Processing document: ${ingestJob.payload.name}`);
```

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

### Automate Legal Contract Review and Clause Extraction with Agentset (JavaScript)

Source: https://docs.agentset.ai/examples/examples

This JavaScript example demonstrates how to automate legal document review using Agentset. It covers creating a dedicated namespace, ingesting PDF contract files, and leveraging AI models with Agentset's knowledge base to identify and extract specific clauses like liability, termination, and payment terms from the uploaded documents.

```JavaScript
import { Agentset } from 'agentset';
import { makeAgentsetTool, DEFAULT_SYSTEM_PROMPT } from '@agentset/ai-sdk';
import { generateText } from 'ai';
import { createOpenAI } from '@ai-sdk/openai';
import fs from 'fs';

const openai = createOpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});
const model = openai('gpt-4o');

async function reviewContracts() {
  const agentset = new Agentset({
    apiKey: process.env.AGENTSET_API_KEY,
  });

  // Create namespace for legal contracts
  const namespace = await agentset.namespaces.create({
    name: "Legal Contracts"
  });

  // Get a reference to the namespace
  const ns = agentset.namespace(namespace.id);

  // Get list of contract files
  const contractFiles = fs.readdirSync('./contracts')
    .filter(file => file.endsWith('.pdf'));

  // Upload each contract as a separate ingest job
  const ingestJobs = [];
  for (const file of contractFiles) {
    // For each contract, create an ingest job
    const ingestJob = await ns.ingestion.create({
      payload: {
        type: "FILE",
        fileUrl: `https://example.com/contracts/${file}`, // In real implementation, you'd use a hosted file URL
        name: file
      },
      config: {
        metadata: {
          documentType: "legal_contract",
          filename: file
        }
      }
    });
    ingestJobs.push(ingestJob);
  }

  console.log(`Created ${ingestJobs.length} ingest jobs for contracts`);

  // List all documents in the namespace
  const { documents } = await ns.documents.all();
  console.log(`Found ${documents.length} documents in the namespace`);

  // Extract important clauses using chat
  const response = await generateText({
    model,
    systemPrompt: DEFAULT_SYSTEM_PROMPT,
    tools: {
      knowledgeBase: makeAgentsetTool(ns, {
        topK: 20,
        rerank: true,
        includeMetadata: true
      }),
    },
    messages: [
      {
        role: "user",
        content: "Identify all liability clauses, termination conditions, and payment terms across all contracts. Highlight any unusual or potentially problematic provisions."
      }
    ]
  });

  return {
    analysis: response.data.text
  };
}

reviewContracts().catch(console.error);
```

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

### Install Agentic AI SDK and Dependencies

Source: https://docs.agentset.ai/examples/agentic

This snippet provides the command to install the required npm packages for integrating Agentic RAG with the ai-sdk, including core AI SDK components, OpenAI integration, React utilities, and Agentset libraries.

```JavaScript
npm install ai @ai-sdk/openai @ai-sdk/react agentset @agentset/ai-sdk
```

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

### Create Agentset Namespace

Source: https://docs.agentset.ai/examples/quickstart

Create a new namespace in Agentset to organize your documents. Namespaces provide a context for Retrieval-Augmented Generation (RAG) operations and can optionally be configured with a custom embedding model.

```JavaScript
// Create a namespace
const namespace = await agentset.namespaces.create({
  name: "Company Documentation",
  // Optional: provide custom embedding model
  embeddingConfig: {
    provider: "OPENAI",
    model: "text-embedding-3-small",
    apiKey: "your_openai_api_key_here",
  },
});

console.log(`Namespace created with ID: ${namespace.id}`);
```

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

### Retrieve Agentset Ingest Jobs API Reference and cURL Example

Source: https://docs.agentset.ai/examples/api-reference/endpoint/ingest-jobs/list

This section provides the full API specification for retrieving a paginated list of ingest jobs, including authentication, request parameters (headers, path, query), and the expected JSON response structure. A cURL example demonstrates how to make the API call.

```cURL
curl --request GET \
  --url https://api.agentset.ai/v1/namespace/{namespaceId}/ingest-jobs \
  --header 'Authorization: Bearer <token>'
```

```APIDOC
Endpoint: GET /v1/namespace/{namespaceId}/ingest-jobs
Description: Retrieve a paginated list of ingest jobs for the authenticated organization.

Authorizations:
  Authorization:
    type: string
    in: header
    required: true
    description: Default authentication mechanism

Headers:
  x-tenant-id:
    type: string
    description: The tenant id to use for the request. If not provided, the default tenant will be used.

Path Parameters:
  namespaceId:
    type: string
    required: true
    description: The id of the namespace to create the ingest job for.

Query Parameters:
  statuses:
    type: enum<string>[]
    description: Statuses to filter by.
  orderBy:
    type: enum<string>
    default: createdAt
    description: The field to order by. Default is `createdAt`.
    options: createdAt
  order:
    type: enum<string>
    default: desc
    description: The sort order. Default is `desc`.
    options: asc, desc
  cursor:
    type: string
    description: The cursor to paginate by.
  cursorDirection:
    type: enum<string>
    default: forward
    description: The direction to paginate by.
    options: forward, backward
  perPage:
    type: number
    default: 30
    description: The number of records to return per page.
    range: 1 <= x <= 100

Responses:
  200 OK:
    description: Successful response
    schema:
      {
        "success": true,
        "data": [
          {
            "id": "<string>",
            "namespaceId": "<string>",
            "tenantId": null,
            "status": "BACKLOG",
            "error": null,
            "payload": {
              "type": "TEXT",
              "text": "<string>",
              "name": "<string>"
            },
            "config": null,
            "createdAt": "<string>",
            "queuedAt": null,
            "preProcessingAt": null,
            "processingAt": null,
            "completedAt": null,
            "failedAt": null
          }
        ],
        "pagination": {
          "nextCursor": "<string>"
        }
      }
  Error Codes: 400, 401, 403, 404, 409, 410, 422, 429, 500
```

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

### Successful Document List Response Example

Source: https://docs.agentset.ai/examples/api-reference/endpoint/documents/list

Example JSON response for a successful retrieval of a paginated list of documents. It includes an array of document objects, each with details like ID, status, source, and metadata, along with pagination information.

```json
{
  "success": true,
  "data": [
    {
      "id": "<string>",
      "ingestJobId": "<string>",
      "externalId": null,
      "name": null,
      "tenantId": null,
      "status": "BACKLOG",
      "error": null,
      "source": {
        "type": "TEXT",
        "text": "<string>"
      },
      "properties": null,
      "totalChunks": 123,
      "totalTokens": 123,
      "totalCharacters": 123,
      "totalPages": 123,
      "createdAt": "<string>",
      "queuedAt": null,
      "preProcessingAt": null,
      "processingAt": null,
      "completedAt": null,
      "failedAt": null
    }
  ],
  "pagination": {
    "nextCursor": "<string>"
  }
}
```

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

### Install Agentset MCP Server

Source: https://docs.agentset.ai/examples/mcp-server

Run the Agentset MCP server with your preferred package manager to enable local data access for AI assistants like Claude. This command requires your Agentset API key and a namespace ID.

```bash
AGENTSET_API_KEY=your-api-key npx @agentset/mcp --ns your-namespace-id
```

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

### Retrieve Documents with cURL

Source: https://docs.agentset.ai/examples/api-reference/endpoint/documents/list

Example cURL command to retrieve a paginated list of documents from the Agentset API. This command performs a GET request to the specified endpoint and requires an Authorization Bearer token.

```curl
curl --request GET \
  --url https://api.agentset.ai/v1/namespace/{namespaceId}/documents \
  --header 'Authorization: Bearer <token>'
```

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

### Retrieve Ingest Job with cURL

Source: https://docs.agentset.ai/examples/api-reference/endpoint/ingest-jobs/get

Example cURL command to make a GET request to retrieve an ingest job from the Agentset API.

```bash
curl --request GET \
  --url https://api.agentset.ai/v1/namespace/{namespaceId}/ingest-jobs/{jobId} \
  --header 'Authorization: Bearer <token>'
```

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

### Retrieve First Page of Ingest Jobs (cURL)

Source: https://docs.agentset.ai/examples/api-reference/pagination

Demonstrates how to retrieve the first page of 10 ingest jobs from a specific namespace using a GET request with cURL, requiring an authorization token.

```cURL
curl --request GET \
  --url https://api.agentset.ai/v1/namespace/{namespace_id}/ingest-jobs?perPage=10 \
  --header 'Authorization: Bearer <token>'
```

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

### cURL Example: Update Agentset Namespace

Source: https://docs.agentset.ai/examples/api-reference/endpoint/namespaces/update

Example cURL command to update an Agentset namespace using a PATCH request. Replace `<token>`, `<namespaceId>`, `<string>` for name, and `<string>` for slug with actual values.

```cURL
curl --request PATCH \
  --url https://api.agentset.ai/v1/namespace/{namespaceId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "<string>",
  "slug": "<string>"
}'
```

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

### Example Response Body for Document Object

Source: https://docs.agentset.ai/examples/api-reference/endpoint/documents/delete

An example JSON structure representing a document object, which might be returned by the Agentset API in various contexts, such as retrieving a document or as part of a successful operation's data payload.

```JSON
{
  "success": true,
  "data": {
    "id": "<string>",
    "ingestJobId": "<string>",
    "externalId": null,
    "name": null,
    "tenantId": null,
    "status": "BACKLOG",
    "error": null,
    "source": {
      "type": "TEXT",
      "text": "<string>"
    },
    "properties": null,
    "totalChunks": 123,
    "totalTokens": 123,
    "totalCharacters": 123,
    "totalPages": 123,
    "createdAt": "<string>",
    "queuedAt": null,
    "preProcessingAt": null,
    "processingAt": null,
    "completedAt": null,
    "failedAt": null
  }
}
```

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

### API Reference: GET /v1/namespace

Source: https://docs.agentset.ai/examples/api-reference/endpoint/namespaces/list

Detailed API documentation for retrieving a list of namespaces. Specifies the endpoint, required authorization, and the structure of the successful JSON response, including embedding and vector store configurations.

```APIDOC
Endpoint: GET /v1/namespace
Description: Retrieve a list of namespaces for the authenticated organization.

Authorizations:
  Authorization:
    Type: string
    Location: header
    Required: true
    Description: Default authentication mechanism (Bearer token).

Responses:
  200 OK:
    Content-Type: application/json
    Description: The retrieved namespaces.
    Schema:
      success: boolean
      data: array of objects
        - id: string
        - name: string
        - slug: string
        - organizationId: string
        - createdAt: string
        - embeddingConfig: object
            provider: string (e.g., "OPENAI")
            model: string (e.g., "text-embedding-3-small")
            apiKey: string
        - vectorStoreConfig: object
            provider: string (e.g., "PINECONE")
            apiKey: string
            indexHost: string (e.g., "https://example.svc.aped-1234-a56b.pinecone.io")
```

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

### Next.js API Route for AgenticEngine Chat

Source: https://docs.agentset.ai/examples/agentic

This example demonstrates how to create a Next.js API route (app/api/chat/route.ts) that utilizes AgenticEngine from @agentset/ai-sdk to process chat messages. It initializes an Agentset client, defines a namespace, and configures the engine with a language model for query generation, evaluation, and answering steps.

```TypeScript
import { AgenticEngine } from '@agentset/ai-sdk';
import { llmModel } from '@/lib/llm';
import { Agentset } from 'agentset';

const agentset = new Agentset({
  apiKey: process.env.AGENTSET_API_KEY,
});
const ns = agentset.namespace(process.env.AGENTSET_NAMESPACE_ID);

export const POST = async (req: Request) => {
  const { messages } = await req.json();
  return AgenticEngine(ns, {
    messages,
    generateQueriesStep: { model: llmModel },
    evaluateQueriesStep: { model: llmModel },
    answerStep: { model: llmModel },
    // maxEvals: 3, (optional, default is 3)
    // tokenBudget: 4096, (optional, default is 4096)
    // queryOptions: {...}, (optional, default is `{ topK: 50, rerankLimit: 15, rerank: true }`)
  });
};
```

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

### Agentset Namespace Search API Success Response Example

Source: https://docs.agentset.ai/examples/api-reference/endpoint/search

This JSON object illustrates the structure of a successful response from the Agentset namespace search API, detailing the format of returned documents including ID, score, text, relationships, and various metadata fields such as file information and links.

```json
{
  "success": true,
  "data": [
    {
      "id": "<string>",
      "score": 0.5,
      "text": "<string>",
      "relationships": {},
      "metadata": {
        "file_directory": "<string>",
        "filename": "<string>",
        "filetype": "<string>",
        "link_texts": [
          "<any>"
        ],
        "link_urls": [
          "<any>"
        ],
        "languages": [
          "<any>"
        ],
        "sequence_number": 123
      }
    }
  ]
}
```

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

### Agentset API Error Response Example

Source: https://docs.agentset.ai/examples/api-reference/errors

This JSON object illustrates the typical structure of an error response from the Agentset API, including a success flag, an error code, a human-readable message, and a link to relevant documentation for more details.

```JSON
{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "The requested resource was not found.",
    "doc_url": "https://docs.agentset.ai/api-reference/errors#not-found"
  }
}
```

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

### Retrieve Documents API Request (cURL)

Source: https://docs.agentset.ai/examples/api-reference/endpoint/documents/list

This snippet demonstrates how to make a GET request to retrieve documents from the AgentSet.AI API using cURL. It shows the required URL and authorization header.

```cURL
curl --request GET \
  --url https://api.agentset.ai/v1/namespace/{namespaceId}/documents \
  --header 'Authorization: Bearer <token>'
```

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

### Configuring Agentic RAG Behavior for Namespaces and Chat

Source: https://docs.agentset.ai/examples/features/agentic-rag

This example illustrates how to customize Agentic RAG behavior in Agentset. It covers two primary methods: configuring retrieval and reasoning options when creating a new namespace, and overriding agentic settings like `maxProcessingTime` directly during a chat session for fine-grained control.

```JavaScript
// Configure when creating a namespace
const namespace = await agentset.namespaces.create({
  name: "Financial Reports",
  description: "Contains financial reports and analysis",
  options: {
    // Configure retrieval behavior
    retrieval: {
      // Number of documents to retrieve in each step
      docsPerRetrieval: 5,
      // Maximum number of retrieval steps
      maxRetrievalSteps: 3,
    },
    // Configure reasoning behavior
    reasoning: {
      // Whether to enable multi-step reasoning
      enableMultiStep: true,
      // Whether to verify answers against sources
      verifyAnswers: true,
    }
  }
});

// Or configure during chat
const response = await agentset.chat({
  namespaceId: namespace.id,
  messages: [{ role: "user", content: "Analyze our Q1 performance" }],
  options: {
    agentic: {
      // Whether to enable agentic RAG features
      enabled: true,
      // Maximum time to spend on deep research
      maxProcessingTime: 60, // seconds
    }
  }
});
```

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

### Agentset API Endpoint: Retrieve a Document

Source: https://docs.agentset.ai/examples/api-reference/endpoint/documents/get

Comprehensive API documentation for the GET /v1/namespace/{namespaceId}/documents/{documentId} endpoint. This section details the required authorization, header parameters, path parameters, and the structure of the successful 200 OK response, along with a list of possible error codes.

```APIDOC
Endpoint: GET /v1/namespace/{namespaceId}/documents/{documentId}
Authorizations:
  Authorization:
    Type: string
    Location: header
    Required: true
    Description: Default authentication mechanism
Headers:
  x-tenant-id:
    Type: string
    Description: The tenant id to use for the request. If not provided, the default tenant will be used.
Path Parameters:
  namespaceId:
    Type: string
    Required: true
    Description: The id of the namespace to retrieve.
  documentId:
    Type: string
    Required: true
    Description: The id of the document to retrieve.
Response:
  200 OK:
    Content-Type: application/json
    Description: The retrieved ingest job. The response is of type 'object'.
  Error Codes: 400, 401, 403, 404, 409, 410, 422, 429, 500
```

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

### Example JSON Response for Ingest Jobs Retrieval

Source: https://docs.agentset.ai/examples/api-reference/endpoint/ingest-jobs/list

This JSON object illustrates the successful response structure when retrieving ingest jobs. It includes an array of ingest job objects, each detailing its ID, namespace ID, status, and payload, along with pagination information for subsequent requests.

```JSON
{
  "success": true,
  "data": [
    {
      "id": "<string>",
      "namespaceId": "<string>",
      "tenantId": null,
      "status": "BACKLOG",
      "error": null,
      "payload": {
        "type": "TEXT",
        "text": "<string>",
        "name": "<string>"
      },
      "config": null,
      "createdAt": "<string>",
      "queuedAt": null,
      "preProcessingAt": null,
      "processingAt": null,
      "completedAt": null,
      "failedAt": null
    }
  ],
  "pagination": {
    "nextCursor": "<string>"
  }
}
```

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

### Example JSON Response for Document Retrieval

Source: https://docs.agentset.ai/examples/api-reference/endpoint/documents/get

This JSON object illustrates the successful data structure returned by the Agentset API when a document is successfully retrieved. It contains detailed information about the document, including its ID, ingest job, status, source, and various metadata counts.

```JSON
{
  "success": true,
  "data": {
    "id": "<string>",
    "ingestJobId": "<string>",
    "externalId": null,
    "name": null,
    "tenantId": null,
    "status": "BACKLOG",
    "error": null,
    "source": {
      "type": "TEXT",
      "text": "<string>"
    },
    "properties": null,
    "totalChunks": 123,
    "totalTokens": 123,
    "totalCharacters": 123,
    "totalPages": 123,
    "createdAt": "<string>",
    "queuedAt": null,
    "preProcessingAt": null,
    "processingAt": null,
    "completedAt": null,
    "failedAt": null
  }
}
```

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

### Delete Namespace API Call with cURL

Source: https://docs.agentset.ai/examples/api-reference/endpoint/namespaces/delete

Example cURL command to delete a specific namespace by its ID. This operation requires an Authorization Bearer token for authentication.

```cURL
curl --request DELETE \
  --url https://api.agentset.ai/v1/namespace/{namespaceId} \
  --header 'Authorization: Bearer <token>'
```

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

### Retrieve Namespace API Endpoint

Source: https://docs.agentset.ai/examples/api-reference/endpoint/namespaces/get

Defines the HTTP GET endpoint for retrieving a specific namespace by its ID within the Agentset API. This endpoint requires an authorization token and a namespace ID.

```APIDOC
GET /v1/namespace/{namespaceId}
```

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

### Retrieve Ingest Jobs with cURL

Source: https://docs.agentset.ai/examples/api-reference/endpoint/ingest-jobs/list

This cURL command demonstrates how to make a GET request to the AgentSet AI API to retrieve ingest jobs for a specific namespace. It requires an authorization token in the header for authentication.

```cURL
curl --request GET \
  --url https://api.agentset.ai/v1/namespace/{namespaceId}/ingest-jobs \
  --header 'Authorization: Bearer <token>'
```

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

### Delete Document using cURL

Source: https://docs.agentset.ai/examples/api-reference/endpoint/documents/delete

Example cURL command to delete a document by specifying the namespace and document IDs, along with an authorization token. This command sends a DELETE request to the Agentset API.

```cURL
curl --request DELETE \
  --url https://api.agentset.ai/v1/namespace/{namespaceId}/documents/{documentId} \
  --header 'Authorization: Bearer <token>'
```

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

### Retrieve a Document using cURL

Source: https://docs.agentset.ai/examples/api-reference/endpoint/documents/get

This cURL command demonstrates how to make a GET request to the Agentset API to retrieve a specific document. It requires an Authorization Bearer token and includes the namespace ID and document ID in the URL path.

```cURL
curl --request GET \
  --url https://api.agentset.ai/v1/namespace/{namespaceId}/documents/{documentId} \
  --header 'Authorization: Bearer <token>'
```

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

### Delete Ingest Job using cURL

Source: https://docs.agentset.ai/examples/api-reference/endpoint/ingest-jobs/delete

Example cURL command to delete an ingest job. It includes the DELETE request method, the API endpoint URL with placeholder path parameters, and the Authorization header with a bearer token.

```cURL
curl --request DELETE \
  --url https://api.agentset.ai/v1/namespace/{namespaceId}/ingest-jobs/{jobId} \
  --header 'Authorization: Bearer <token>'
```

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

### Configure Initial Environment Variables

Source: https://docs.agentset.ai/examples/self-hosting

Convert the '.env.example' file to '.env' and populate it with initial configuration for default vector database, Cohere API key, and Azure OpenAI model settings. These are used when users select Agentset managed options.

```Shell
# Default vector database (used when users select the Agentset managed option)
DEFAULT_PINECONE_API_KEY=pcsk_xxx
DEFAULT_PINECONE_HOST="https://xxx.svc.xxx-xxx-xxx.pinecone.io"

# Cohere API key (used for re-ranking)
DEFAULT_COHERE_API_KEY=xxx

# Default models (used when users select the Agentset managed option)
DEFAULT_AZURE_BASE_URL=https://xxx.cognitiveservices.azure.com/openai/deployments
DEFAULT_AZURE_API_KEY=xxx
DEFAULT_AZURE_TEXT_3_LARGE_EMBEDDING_DEPLOYMENT=text-embedding-3-large
DEFAULT_AZURE_TEXT_3_LARGE_EMBEDDING_VERSION=2023-05-15
DEFAULT_AZURE_GPT_4_1_DEPLOYMENT=gpt-4.1
DEFAULT_AZURE_GPT_4_1_VERSION=2025-01-01-preview
```

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

### Clone Agentset Repository

Source: https://docs.agentset.ai/examples/self-hosting

First, clone the Agentset repository from GitHub to your local machine.

```Shell
git clone https://github.com/agentset-ai/agentset.git
```

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

### Push Agentset Repository to GitHub

Source: https://docs.agentset.ai/examples/self-hosting

Commands to initialize and push the cloned Agentset repository to GitHub. This is a prerequisite for deploying the application to Vercel, ensuring the codebase is available in a remote repository.

```shell
git add .
git commit -m "Initial commit"
git push origin main
```

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

### Configure Partitioner API Environment Variables

Source: https://docs.agentset.ai/examples/self-hosting

Once the partitioner API is running, set its URL and API key in your '.env' file. Ensure Redis connection details match your Upstash Redis database.

```Shell
PARTITION_API_URL= // the URL of the partitioner API (e.g. https://example.modal.run/ingest)
PARTITION_API_KEY= // the API key for the partitioner API
```

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

### API Reference: Create Namespace Endpoint

Source: https://docs.agentset.ai/examples/api-reference/endpoint/namespaces/create

Comprehensive API documentation for the POST /v1/namespace endpoint, detailing the required authorization, request body structure, and the successful response schema.

```APIDOC
Endpoint: POST /v1/namespace
Description: Create a namespace for the authenticated organization.

Authorizations:
  - Name: Authorization
    Type: string
    Location: header
    Required: true
    Description: Default authentication mechanism (Bearer token).

Request Body:
  Content-Type: application/json
  Example Schema:
    {
      "name": "<string>",
      "slug": "<string>",
      "embeddingConfig": {
        "provider": "OPENAI",
        "model": "text-embedding-3-small",
        "apiKey": "<string>"
      },
      "vectorStoreConfig": {
        "provider": "PINECONE",
        "apiKey": "<string>",
        "indexHost": "https://example.svc.aped-1234-a56b.pinecone.io"
      }
    }

Responses:
  201 OK:
    Content-Type: application/json
    Description: The created namespace.
    Example Schema:
      {
        "success": true,
        "data": {
          "id": "<string>",
          "name": "<string>",
          "slug": "<string>",
          "organizationId": "<string>",
          "createdAt": "<string>",
          "embeddingConfig": {
            "provider": "OPENAI",
            "model": "text-embedding-3-small",
            "apiKey": "<string>"
          },
          "vectorStoreConfig": {
            "provider": "PINECONE",
            "apiKey": "<string>",
            "indexHost": "https://example.svc.aped-1234-a56b.pinecone.io"
          }
        }
      }
  Error Codes: 400, 401, 403, 404, 409, 410, 422, 429, 500
```

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

### Apply Prisma Database Migrations for Supabase

Source: https://docs.agentset.ai/examples/self-hosting

These commands are used to generate the Prisma client and apply database migrations to a PostgreSQL database, such as Supabase. This ensures the database schema is up-to-date with the application's requirements.

```terminal
pnpm run db:generate
```

```terminal
pnpm run db:deploy
```

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

### Run MCP Server with Custom Tool Description

Source: https://docs.agentset.ai/examples/mcp-server

Customize the tool description that the MCP server exposes to AI assistants. Use the -d flag to provide a specific description for better clarity and integration.

```bash
AGENTSET_API_KEY=your-api-key npx @agentset/mcp --ns your-namespace-id -d "Your custom tool description"
```

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

### Agentset API Reference

Source: https://docs.agentset.ai/examples/features/agentic-rag

Comprehensive documentation for the Agentset API, covering endpoints for managing namespaces, ingest jobs, documents, and search functionalities.

```API_ENDPOINT
Namespaces:
  GET /namespaces
    Description: Retrieve a list of namespaces.
  GET /namespaces/{id}
    Description: Retrieve a specific namespace.
  POST /namespaces
    Description: Create a namespace.
  PATCH /namespaces/{id}
    Description: Update a namespace.
  DEL /namespaces/{id}
    Description: Delete a namespace.
```

```API_ENDPOINT
Ingest Jobs:
  GET /ingest-jobs
    Description: Retrieve a list of ingest jobs.
  GET /ingest-jobs/{id}
    Description: Retrieve an ingest job.
  POST /ingest-jobs
    Description: Create an ingest job.
  DEL /ingest-jobs/{id}
    Description: Delete an ingest job.
```

```API_ENDPOINT
Documents:
  GET /documents
    Description: Retrieve a list of documents.
  GET /documents/{id}
    Description: Retrieve a document.
  DEL /documents/{id}
    Description: Delete a document.
```

```API_ENDPOINT
Search:
  POST /search
    Description: Search a namespace.
```

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

### Agentset API Key Format

Source: https://docs.agentset.ai/examples/api-reference/tokens

Illustrates the format of an Agentset API key, typically stored as an environment variable for secure access.

```Shell
AGENTSET_API_KEY=agentset_xxxxxxxx
```

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

### Initiating Agentic RAG Chat with Reasoning Steps

Source: https://docs.agentset.ai/examples/features/agentic-rag

This snippet demonstrates how to initiate a chat conversation using Agentset's agentic RAG capabilities. It shows how to include detailed reasoning steps in the response and subsequently access them for analysis, providing transparency into the agent's thought process.

```JavaScript
const response = await agentset.chat({
  namespaceId: namespace.id,
  messages: [
    { role: "user", content: "How did our Q1 sales in Europe compare to Q4 last year?" }
  ],
  options: {
    // Enable detailed reasoning steps in response
    includeReasoningSteps: true,
  }
});

// Access the reasoning steps
console.log(response.reasoningSteps);
```

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

### Agentset Search Namespace API Endpoint Documentation

Source: https://docs.agentset.ai/examples/api-reference/endpoint/search

Detailed API documentation for the POST /v1/namespace/{namespaceId}/search endpoint, covering required authorization, optional headers, path parameters, the structure of the request body (application/json), and the expected successful response (200 application/json).

```APIDOC
Endpoint: POST /v1/namespace/{namespaceId}/search

Authorizations:
  Authorization:
    type: string
    in: header
    required: true
    description: Default authentication mechanism

Headers:
  x-tenant-id:
    type: string
    description: The tenant id to use for the request. If not provided, the default tenant will be used.

Path Parameters:
  namespaceId:
    type: string
    required: true
    description: The id of the namespace to search.

Body:
  Content-Type: application/json
  Example Schema:
    query: "<string>"
    topK: 10
    rerank: true
    rerankLimit: 50.5
    filter: {}
    minScore: 0.5
    includeRelationships: false
    includeMetadata: true

Response:
  Status: 200
  Content-Type: application/json
  Description: The retrieved namespace
  Example Schema:
    success: true
    data:
      - id: "<string>"
        score: 0.5
        text: "<string>"
        relationships: {}
        metadata:
          file_directory: "<string>"
          filename: "<string>"
          filetype: "<string>"
          link_texts: ["<any>"]
          link_urls: ["<any>"]
          languages: ["<any>"]
          sequence_number: 123
```

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

### Agentset API Standard HTTP Response Codes

Source: https://docs.agentset.ai/examples/api-reference/introduction

The Agentset API returns standard HTTP response codes to indicate the success or failure of an API request. This table lists common codes and their descriptions.

```APIDOC
Code | Description
--- | ---
200 | The request was successful.
400 | The request was invalid or cannot be served.
401 | The request requires user authentication.
403 | The server understood the request, but refuses to authorize it.
404 | The requested resource could not be found.
429 | Too many requests.
500 | The server encountered an unexpected condition which prevented it from fulfilling the request.
```

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

### Agentset API: Create Ingest Job Endpoint Reference

Source: https://docs.agentset.ai/examples/api-reference/endpoint/ingest-jobs/create

Detailed API documentation for the POST /v1/namespace/{namespaceId}/ingest-jobs endpoint. This section outlines the required authorization, optional headers, path parameters, the structure of the request body (payload and config), and the expected JSON response for a successful operation (201) and various error codes.

```APIDOC
Endpoint: POST /v1/namespace/{namespaceId}/ingest-jobs
Description: Create an ingest job for the authenticated organization.

Authorizations:
  Authorization:
    Type: string
    Location: header
    Required: true
    Description: Default authentication mechanism

Heders:
  x-tenant-id:
    Type: string
    Description: The tenant id to use for the request. If not provided, the default tenant will be used.

Path Parameters:
  namespaceId:
    Type: string
    Required: true
    Description: The id of the namespace to create the ingest job for.

Request Body (application/json):
  payload:
    type: object
    properties:
      type: string (e.g., "TEXT")
      text: string
      name: string
  config:
    type: object
    properties:
      chunkSize: number (e.g., 123)
      chunkOverlap: number (e.g., 123)
      metadata: object
      chunkingStrategy: string (e.g., "basic")
      strategy: string (e.g., "auto")

Response (201 application/json):
  Description: The created ingest job
  Type: object
  Properties:
    success: boolean
    data:
      type: object
      properties:
        id: string
        namespaceId: string
        tenantId: null
        status: string (e.g., "BACKLOG")
        error: null
        payload: object (same as request payload structure)
        config: null
        createdAt: string
        queuedAt: null
        preProcessingAt: null
        processingAt: null
        completedAt: null
        failedAt: null

Possible HTTP Status Codes: 201, 400, 401, 403, 404, 409, 410, 422, 429, 500
```

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

### Agentset API Base URL

Source: https://docs.agentset.ai/examples/api-reference/introduction

The base URL for all Agentset API endpoints, built on REST principles and served over HTTPS to ensure data privacy.

```Terminal
https://api.agentset.ai
```

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

### Configure Agentset MCP Server in Claude Settings

Source: https://docs.agentset.ai/examples/mcp-server

Integrate the MCP server with Claude by adding this JSON configuration to your Claude settings. It specifies the command to run the MCP server and sets necessary environment variables for API key and namespace ID.

```json
{
  "mcpServers": {
    "agentset": {
      "command": "npx",
      "args": ["-y", "@agentset/mcp@latest"],
      "env": {
        "AGENTSET_API_KEY": "agentset_xxx",
        "AGENTSET_NAMESPACE_ID": "ns_xxx"
      }
    }
  }
}
```

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

### Agentset API Authentication Header

Source: https://docs.agentset.ai/examples/api-reference/introduction

Authentication to Agentset’s API is performed via the Authorization header with a Bearer token. This snippet shows the required header format for API requests.

```Terminal
Authorization: Bearer <Your-Token>
```

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

### Run MCP Server with Namespace ID via Environment Variable

Source: https://docs.agentset.ai/examples/mcp-server

Instead of a command-line argument, you can pass the namespace ID to the MCP server as an environment variable. This method provides an alternative way to configure the server.

```bash
AGENTSET_API_KEY=your-api-key AGENTSET_NAMESPACE_ID=your-namespace-id npx @agentset/mcp
```

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

### Configure Cloudflare R2 Environment Variables for S3 Storage

Source: https://docs.agentset.ai/examples/self-hosting

This snippet shows the environment variables required to connect Agentset to Cloudflare R2 for file storage. It includes the access key, secret key, S3 API endpoint, and the bucket name, enabling the application to store and retrieve files.

```env
S3_ACCESS_KEY= // this is the Access Key ID value from Step 2
S3_SECRET_KEY= // this is the Secret Access Key value from Step 2
S3_ENDPOINT= // this is the S3 API value from Step 1
S3_BUCKET= // this is the name of the bucket you created in Step 1
```

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

### Agentset API Error Codes Reference

Source: https://docs.agentset.ai/examples/api-reference/errors

A comprehensive list of machine-readable error codes returned by the Agentset API, detailing their HTTP status, the problem they indicate, and recommended solutions for troubleshooting API requests.

```APIDOC
Error Codes:
  bad_request:
    Status: 400
    Problem: The request is malformed, either missing required fields, using wrong datatypes, or being syntactically incorrect.
    Solution: Check the request and make sure it is properly formatted.
  unauthorized:
    Status: 401
    Problem: The request has not been applied because it lacks valid authentication credentials for the target resource.
    Solution: Make sure you are using the correct API key or access token.
  forbidden:
    Status: 403
    Problem: The server understood the request, but is refusing to fulfill it because the client lacks proper permission.
    Solution: Make sure you have the necessary permissions to access the resource.
  not_found:
    Status: 404
    Problem: The server has not found anything matching the request URI.
    Solution: Check the request and make sure the resource exists.
  conflict:
    Status: 409
    Problem: Another resource already uses the same identifier. For example, workspace slug must be unique.
    Solution: Change the identifier to a unique value.
  invite_expired:
    Status: 410
    Problem: The invite has expired.
    Solution: Generate a new invite.
  unprocessable_entity:
    Status: 422
    Problem: The server was unable to process the request because it contains invalid data.
    Solution: Check the request and make sure input data is valid.
  rate_limit_exceeded:
    Status: 429
    Problem: The request has been rate limited.
    Solution: Wait for a while and try again.
```

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

### Agentset Namespaces API Operations Overview

Source: https://docs.agentset.ai/examples/concepts/namespaces

This section outlines the core API operations available for interacting with Namespaces in Agentset. It covers actions such as listing all namespaces, retrieving details for a specific namespace, creating new namespaces, modifying existing ones, and deleting namespaces along with their contents.

```APIDOC
Available Operations for Namespaces:
- List:
    Description: Retrieve all namespaces in your account
    Endpoint: /api-reference/endpoint/namespaces/list
- Get:
    Description: Retrieve details of a specific namespace
    Endpoint: /api-reference/endpoint/namespaces/get
- Create:
    Description: Create a new namespace
    Endpoint: /api-reference/endpoint/namespaces/create
- Update:
    Description: Modify an existing namespace
    Endpoint: /api-reference/endpoint/namespaces/update
- Delete:
    Description: Remove a namespace and its contents
    Endpoint: /api-reference/endpoint/namespaces/delete
```

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

### Agentset Ingest Jobs API Operations Overview

Source: https://docs.agentset.ai/examples/concepts/ingest-jobs

Overview of the available API operations for managing Ingest Jobs in Agentset, including methods to retrieve, create, and delete document ingestion processes.

```APIDOC
IngestJobs API:
  List:
    Description: Retrieve all ingest jobs in your account
    Reference: /api-reference/endpoint/ingest-jobs/list
  Get:
    Description: Retrieve details of a specific ingest job
    Reference: /api-reference/endpoint/ingest-jobs/get
  Create:
    Description: Create a new ingest job to process documents
    Reference: /api-reference/endpoint/ingest-jobs/create
  Delete:
    Description: Remove an ingest job from your account
    Reference: /api-reference/endpoint/ingest-jobs/delete
```