Skip to main content

​
Installation

  npm install @alchemystai/sdk

​
Authentication

Set your API key via environment variable or pass it directly when initializing the client.
  • Recommended env var: ALCHEMYST_AI_API_KEY
export ALCHEMYST_AI_API_KEY="your_api_key_here"

​
Quickstart

import AlchemystAI from '@alchemystai/sdk';

const client = new AlchemystAI({
    apiKey: process.env.ALCHEMYST_AI_API_KEY,
});

async function main() {
  const res = await client.v1.context.view.retrieve();
  console.log(res);
}

main().catch(console.error);

​
Usage by Endpoint

All methods return a promise you can await. Types are available out-of-the-box in TypeScript.

​
Context: Add

import AlchemystAI from '@alchemystai/sdk';

const client = new AlchemystAI({
    apiKey: process.env.ALCHEMYST_AI_API_KEY,
});

await client.v1.context.add({
  documents: [
            {
              content: 'The content of the document',
            },
          ],
          context_type: 'resource',
          source: 'web-upload',
          scope: 'internal',
          metadata: {
            fileName: 'notes.txt',
            fileType: 'text/plain',
            lastModified: new Date().toISOString(),
            fileSize: 1024,
            groupName: ['group1', 'group2'],
        },
});
Version Requirements: The groupName field is introduced in TypeScript SDK version 0.6.0. If you use groupName in previous versions, you will encounter an error. If groupName is not provided, it will be set to a default value automatically.
groupName: The group name acts like a namespace which creates a scope for context. Documents with the same group name will be grouped together for better organization and retrieval.Example Use Cases:
  • ['project-alpha'] - Group all documents related to a specific project
  • ['customer-support', 'tier-1'] - Organize support documentation by department and priority
  • ['legal', 'contracts'] - Categorize legal documents by type and category
  • ['training', 'onboarding'] - Group training materials for new employee onboarding
import AlchemystAI from '@alchemystai/sdk';

const client = new AlchemystAI({
    apiKey: process.env.ALCHEMYST_AI_API_KEY,
});

const { contexts } = await client.v1.context.search({
        query: 'Your search query here',
        similarity_threshold: 0.8,
        minimum_similarity_threshold: 0.5,
        scope: 'internal',
        metadata: {          // Optional - can be null
            size: 100,
            fileType: 'ai/conversation',
            fileName: 'chatgpt-convo-1',
            groupName: ['project-name']
        },
});

console.log(contexts);

​
Context: Delete

import AlchemystAI from '@alchemystai/sdk';

const client = new AlchemystAI({
    apiKey: process.env.ALCHEMYST_AI_API_KEY,
});

await client.v1.context.delete({
  source: 'web-upload',
  user_id: 'your_user_id',          // optional
  organization_id: 'your_organization_id',  // optional
  by_doc: true,                // optional
  by_id: false,                // optional
});

​
Context: View (per-user)

import AlchemystAI from '@alchemystai/sdk';

const client = new AlchemystAI({
    apiKey: process.env.ALCHEMYST_AI_API_KEY,
});

const docs = await client.v1.context.view.docs();
Per-user View: This endpoint gives the authenticated user their own context from the organization.

​
Context: Traces

import AlchemystAI from '@alchemystai/sdk';

const client = new AlchemystAI({
    apiKey: process.env.ALCHEMYST_AI_API_KEY,
});

const { traces } = await client.v1.context.traces.list();

await client.v1.context.traces.delete('traceId');

​
Organization: View Context

import AlchemystAI from '@alchemystai/sdk';

const client = new AlchemystAI({
    apiKey: process.env.ALCHEMYST_AI_API_KEY,
});

const res = await client.v1.org.context.view({
  userIds: ['your_user_id', 'your_user_id_2'],
});
Organization View: This endpoint allows you to fetch context based on specific user IDs within your organization.