Documentation

Learn how to integrate ShinRAG into your applications using the REST API or our official SDK.

Quick Start

ShinRAG provides two ways to interact with your pipelines, agents, and indexes:

REST API: Direct HTTP requests for any programming language
SDK: Official TypeScript/JavaScript SDK with full type safety

1. Get Your API Key

Your API key starts with sk_ and is required for all requests.

Get your API key from the dashboard →

2. Find Your Resource IDs

Each pipeline, agent, and index has a unique ID. You can easily copy these IDs using the Copy ID button:

Pipeline ID:

Go to Pipelines, open any pipeline, and click the Copy ID button next to the pipeline name

Agent ID:

Go to Agents, open any agent, and click the Copy ID button next to the agent name

Index ID:

Go to Indexes, open any index, and click the Copy ID button next to the index name

3. Install the SDK (Optional)

For TypeScript/JavaScript projects, install our official SDK:

npm:

npm install @shinrag/sdk

pnpm:

pnpm add @shinrag/sdk

Authentication

All API requests require authentication using an API key. Your API key starts with sk_.

You can authenticate in two ways:

Option 1: X-API-Key Header

X-API-Key: sk_your_api_key_here

Option 2: Authorization Header

Authorization: Bearer sk_your_api_key_here

Querying Pipelines

Execute a pipeline with custom input and receive processed results.

import { ShinRAGClient } from '@shinrag/sdk';

const client = new ShinRAGClient({
  apiKey: 'sk_your_api_key_here'
});

const result = await client.queryPipeline('clx1234567890abcdef', {
  input: 'What are the key features mentioned in the documentation?'
});

console.log(result.output);
console.log('Tokens used:', result.totalTokensUsed);

Response Type

interface QueryPipelineResponse {
  executionId: string;
  status: "completed" | "failed" | "running";
  output?: string;
  error?: string;
  nodeResults: NodeResult[];
  totalTokensUsed: number;
}

Querying Agents

Use RAG (Retrieval-Augmented Generation) to answer questions by retrieving relevant context from assigned indexes.

import { ShinRAGClient } from '@shinrag/sdk';

const client = new ShinRAGClient({
  apiKey: 'sk_your_api_key_here'
});

const result = await client.queryAgent('agent_1234567890abcdef', {
  question: 'What are the key features?',
  maxResults: 5,
  temperature: 0.7
});

console.log(result.answer);
console.log('Sources:', result.sources);
console.log('Tokens used:', result.tokensUsed);

Response Type

interface QueryAgentResponse {
  answer: string | null;
  sources: Array<{
    index: string;
    score: number;
    text: string;
  }>;
  tokensUsed: number;
  model: string;
  warning?: string;
}

Querying Indexes

Search indexes for relevant content using semantic search.

import { ShinRAGClient } from '@shinrag/sdk';

const client = new ShinRAGClient({
  apiKey: 'sk_your_api_key_here'
});

// Search with text
const result = await client.queryIndex({
  indexId: 'index_1234567890abcdef',
  queryText: 'What are the key features?',
  limit: 10
});

console.log(`Found ${result.results.length} results`);
result.results.forEach(item => {
  console.log(`Score: ${item.score}`);
  console.log('Content:', item.payload.text);
});

Response Type

interface QueryIndexResponse {
  success: boolean;
  results: Array<{
    id: string;
    score: number;
    payload: any;
  }>;
}

Error Handling

The SDK throws ShinRAGError for API errors with detailed information.

import { ShinRAGClient, ShinRAGError } from '@shinrag/sdk';

const client = new ShinRAGClient({
  apiKey: 'sk_your_api_key_here'
});

try {
  const result = await client.queryPipeline('pipeline-id', {
    input: 'Your query here'
  });
  console.log(result.output);
} catch (error) {
  if (error instanceof ShinRAGError) {
    console.error('API Error:', error.message);
    console.error('Status Code:', error.statusCode);
    console.error('Response:', error.response);
  } else {
    console.error('Unknown error:', error);
  }
}

Error Codes

Status Code	Description
`400`	Bad Request - Invalid request body or missing required fields
`401`	Unauthorized - Invalid or missing API key
`404`	Not Found - Resource not found or doesn't belong to your account
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error - Server error occurred