- TypeScript
- Python
- PHP
TypeScript / Node.js Client
import axios, { AxiosInstance } from "axios";
import * as fs from "fs";
interface Workspace {
id: number;
name: string;
icon: string;
}
interface Template {
id: string;
name: string;
description?: string;
schema_json: object;
}
interface Session {
id: string;
name: string;
created_at: string;
}
interface ExtractionResult {
id: string;
status: "created" | "parsing_pending" | "processing" | "completed" | "failed";
data: Record<string, any>;
reasoning?: Record<string, any>;
}
export class RaydocsClient {
private client: AxiosInstance;
constructor(apiKey: string, baseUrl: string = "https://api.raydocs.com") {
this.client = axios.create({
baseURL: baseUrl,
headers: {
Authorization: `Bearer ${apiKey}`,
"Content-Type": "application/json",
Accept: "application/json",
},
});
}
// ─────────────────────────────────────────────────────────────
// Workspaces
// ─────────────────────────────────────────────────────────────
async listWorkspaces(): Promise<Workspace[]> {
const { data } = await this.client.get("/workspaces");
return data.data;
}
async createWorkspace(
name: string,
icon: string = "📊"
): Promise<Workspace> {
const { data } = await this.client.post("/workspaces/create", {
name,
icon,
});
return data;
}
// ─────────────────────────────────────────────────────────────
// Templates
// ─────────────────────────────────────────────────────────────
async listTemplates(workspaceId: number): Promise<Template[]> {
const { data } = await this.client.get(
`/workspaces/${workspaceId}/extractions/templates`
);
return data.data;
}
async createTemplate(
workspaceId: number,
name: string,
schema: object,
description?: string
): Promise<Template> {
const { data } = await this.client.post("/extractions/templates", {
workspace_id: workspaceId,
name,
schema_json: schema,
description,
});
return data;
}
async getTemplate(templateId: string): Promise<Template> {
const { data } = await this.client.get(
`/extractions/templates/${templateId}`
);
return data;
}
// ─────────────────────────────────────────────────────────────
// File Upload
// ─────────────────────────────────────────────────────────────
async uploadFile(filePath: string): Promise<string> {
// Get signed upload URL (content_type defaults to 'application/octet-stream')
const { data: uploadData } = await this.client.post(
"/vapor/signed-storage-url",
{
visibility: "private",
}
);
// Upload directly to S3
const fileBuffer = fs.readFileSync(filePath);
await axios.put(uploadData.url, fileBuffer, {
headers: uploadData.headers,
});
return uploadData.key;
}
// ─────────────────────────────────────────────────────────────
// Batch Operations
// ─────────────────────────────────────────────────────────────
async batchCreateSessions(
templateId: string,
fileKeys: string[],
autoExtract: boolean = true
): Promise<Session[]> {
const { data } = await this.client.post(
`/extractions/templates/${templateId}/sessions/batch`,
{
files: fileKeys,
settings: { auto_extract: autoExtract },
}
);
return data;
}
// ─────────────────────────────────────────────────────────────
// Sessions & Results
// ─────────────────────────────────────────────────────────────
async getSession(sessionId: string): Promise<any> {
const { data } = await this.client.get(
`/extractions/sessions/${sessionId}`
);
return data;
}
async getResults(sessionId: string): Promise<ExtractionResult[]> {
const { data } = await this.client.get(
`/extractions/sessions/${sessionId}/results`
);
return data.data;
}
async getResult(resultId: string): Promise<ExtractionResult> {
const { data } = await this.client.get(
`/extractions/results/${resultId}`
);
return data;
}
// ─────────────────────────────────────────────────────────────
// Workspace Documents
// ─────────────────────────────────────────────────────────────
async listWorkspaceDocuments(
workspaceId: number,
params?: { query?: string; status?: string; page?: number; per_page?: number }
): Promise<{ data: any[]; meta: any }> {
const { data } = await this.client.get(
`/workspaces/${workspaceId}/documents`,
{ params }
);
return data;
}
async getWorkspaceDocument(
workspaceId: number,
documentId: string
): Promise<any> {
const { data } = await this.client.get(
`/workspaces/${workspaceId}/documents/${documentId}`
);
return data;
}
async createWorkspaceDocument(
workspaceId: number,
key: string,
filename?: string
): Promise<any> {
const { data } = await this.client.post(
`/workspaces/${workspaceId}/documents`,
{ key, filename }
);
return data;
}
async importWorkspaceDocumentUrl(
workspaceId: number,
url: string,
filename?: string
): Promise<any> {
const { data } = await this.client.post(
`/workspaces/${workspaceId}/documents:importUrl`,
{ url, filename }
);
return data;
}
async reparseWorkspaceDocument(
workspaceId: number,
documentId: string,
configHash: string,
force?: boolean
): Promise<any> {
const { data } = await this.client.post(
`/workspaces/${workspaceId}/documents/${documentId}/reparse`,
{ config_hash: configHash, force }
);
return data;
}
}
Installation
npm install axios
raydocs-client.ts:import { RaydocsClient } from "./raydocs-client";
const client = new RaydocsClient("your_api_token");
Python Client
import requests
import os
from typing import Optional, List, Dict, Any
class RaydocsClient:
"""
Raydocs API client for document extraction.
Usage:
client = RaydocsClient("your_api_token")
workspaces = client.list_workspaces()
"""
def __init__(self, api_key: str, base_url: str = "https://api.raydocs.com"):
self.base_url = base_url
self.headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
"Accept": "application/json"
}
def _request(self, method: str, endpoint: str, **kwargs) -> Any:
"""Make an API request with error handling."""
url = f"{self.base_url}{endpoint}"
response = requests.request(method, url, headers=self.headers, **kwargs)
response.raise_for_status()
return response.json() if response.content else {}
# ─────────────────────────────────────────────────────────────
# Workspaces
# ─────────────────────────────────────────────────────────────
def list_workspaces(self) -> List[Dict]:
"""List all accessible workspaces."""
return self._request("GET", "/workspaces")["data"]
def create_workspace(self, name: str, icon: str = "📊") -> Dict:
"""Create a new workspace."""
return self._request("POST", "/workspaces/create", json={
"name": name,
"icon": icon
})
# ─────────────────────────────────────────────────────────────
# Templates
# ─────────────────────────────────────────────────────────────
def list_templates(self, workspace_id: int) -> List[Dict]:
"""List templates in a workspace."""
return self._request("GET", f"/workspaces/{workspace_id}/extractions/templates")["data"]
def create_template(self, workspace_id: int, name: str, schema: Dict,
description: str = None) -> Dict:
"""Create an extraction template."""
payload = {
"workspace_id": workspace_id,
"name": name,
"schema_json": schema
}
if description:
payload["description"] = description
return self._request("POST", "/extractions/templates", json=payload)
def get_template(self, template_id: str) -> Dict:
"""Get a template by ID."""
return self._request("GET", f"/extractions/templates/{template_id}")
# ─────────────────────────────────────────────────────────────
# File Upload
# ─────────────────────────────────────────────────────────────
def upload_file(self, file_path: str) -> str:
"""
Upload a file and return the storage key.
Args:
file_path: Path to the file to upload
Returns:
File key to use in batch_create_sessions
"""
# Get signed upload URL (content_type defaults to 'application/octet-stream')
upload_data = self._request("POST", "/vapor/signed-storage-url", json={
"visibility": "private"
})
# Upload directly to S3
with open(file_path, 'rb') as f:
response = requests.put(
upload_data['url'],
data=f,
headers=upload_data.get('headers', {})
)
response.raise_for_status()
return upload_data['key']
# ─────────────────────────────────────────────────────────────
# Batch Operations
# ─────────────────────────────────────────────────────────────
def batch_create_sessions(self, template_id: str, file_keys: List[str],
auto_extract: bool = True) -> List[Dict]:
"""
Create sessions from uploaded files.
Args:
template_id: Template UUID
file_keys: List of file keys from upload_file()
auto_extract: Start extraction automatically (default: True)
"""
return self._request(
"POST",
f"/extractions/templates/{template_id}/sessions/batch",
json={
"files": file_keys,
"settings": {"auto_extract": auto_extract}
}
)
# ─────────────────────────────────────────────────────────────
# Sessions & Results
# ─────────────────────────────────────────────────────────────
def get_session(self, session_id: str) -> Dict:
"""Get session details."""
return self._request("GET", f"/extractions/sessions/{session_id}")
def get_results(self, session_id: str) -> List[Dict]:
"""Get extraction results for a session."""
return self._request("GET", f"/extractions/sessions/{session_id}/results")["data"]
def get_result(self, result_id: str) -> Dict:
"""Get a specific extraction result with full data."""
return self._request("GET", f"/extractions/results/{result_id}")
# ─────────────────────────────────────────────────────────────
# Workspace Documents
# ─────────────────────────────────────────────────────────────
def list_workspace_documents(self, workspace_id: int,
query: str = None, status: str = None,
page: int = None, per_page: int = None) -> Dict:
"""List workspace documents with optional filters."""
params = {k: v for k, v in [
("query", query), ("status", status),
("page", page), ("per_page", per_page)
] if v is not None}
return self._request("GET", f"/workspaces/{workspace_id}/documents",
params=params)
def get_workspace_document(self, workspace_id: int,
document_id: str) -> Dict:
"""Get a workspace document by ID."""
return self._request("GET",
f"/workspaces/{workspace_id}/documents/{document_id}")
def create_workspace_document(self, workspace_id: int, key: str,
filename: str = None) -> Dict:
"""Create or reuse a workspace document from an upload key."""
payload = {"key": key}
if filename:
payload["filename"] = filename
return self._request("POST", f"/workspaces/{workspace_id}/documents",
json=payload)
def import_workspace_document_url(self, workspace_id: int, url: str,
filename: str = None) -> Dict:
"""Import a document from URL into the workspace."""
payload = {"url": url}
if filename:
payload["filename"] = filename
return self._request("POST",
f"/workspaces/{workspace_id}/documents:importUrl",
json=payload)
def reparse_workspace_document(self, workspace_id: int, document_id: str,
config_hash: str, force: bool = False) -> Dict:
"""Request parsing for a document with a specific config hash."""
return self._request("POST",
f"/workspaces/{workspace_id}/documents/{document_id}/reparse",
json={"config_hash": config_hash, "force": force})
Installation
pip install requests
RaydocsClient class into your project or save as raydocs_client.py:from raydocs_client import RaydocsClient
client = RaydocsClient("your_api_token")
PHP Client (Guzzle)
<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';
use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;
class RaydocsClient
{
private Client $client;
private string $baseUrl;
public function __construct(string $apiKey, string $baseUrl = 'https://api.raydocs.com')
{
$this->baseUrl = $baseUrl;
$this->client = new Client([
'base_uri' => $baseUrl,
'headers' => [
'Authorization' => 'Bearer ' . $apiKey,
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
]);
}
private function request(string $method, string $endpoint, ?array $data = null): array
{
$options = [];
if ($data !== null) {
$options['json'] = $data;
}
$response = $this->client->request($method, $endpoint, $options);
$body = $response->getBody()->getContents();
return $body ? json_decode($body, true) : [];
}
// ─────────────────────────────────────────────────────────────
// Workspaces
// ─────────────────────────────────────────────────────────────
public function listWorkspaces(): array
{
return $this->request('GET', '/workspaces')['data'];
}
public function createWorkspace(string $name, string $icon = '📊'): array
{
return $this->request('POST', '/workspaces/create', [
'name' => $name,
'icon' => $icon,
]);
}
// ─────────────────────────────────────────────────────────────
// Templates
// ─────────────────────────────────────────────────────────────
public function listTemplates(int $workspaceId): array
{
return $this->request('GET', "/workspaces/{$workspaceId}/extractions/templates")['data'];
}
public function createTemplate(
int $workspaceId,
string $name,
array $schema,
?string $description = null
): array {
$payload = [
'workspace_id' => $workspaceId,
'name' => $name,
'schema_json' => $schema,
];
if ($description !== null) {
$payload['description'] = $description;
}
return $this->request('POST', '/extractions/templates', $payload);
}
public function getTemplate(string $templateId): array
{
return $this->request('GET', "/extractions/templates/{$templateId}");
}
// ─────────────────────────────────────────────────────────────
// File Upload
// ─────────────────────────────────────────────────────────────
public function uploadFile(string $filePath): string
{
// Get signed upload URL (content_type defaults to 'application/octet-stream')
$uploadData = $this->request('POST', '/vapor/signed-storage-url', [
'visibility' => 'private',
]);
// Upload directly to S3 using Guzzle
$s3Client = new Client();
$s3Client->put($uploadData['url'], [
'body' => fopen($filePath, 'r'),
'headers' => $uploadData['headers'] ?? [],
]);
return $uploadData['key'];
}
// ─────────────────────────────────────────────────────────────
// Batch Operations
// ─────────────────────────────────────────────────────────────
public function batchCreateSessions(
string $templateId,
array $fileKeys,
bool $autoExtract = true
): array {
return $this->request(
'POST',
"/extractions/templates/{$templateId}/sessions/batch",
[
'files' => $fileKeys,
'settings' => ['auto_extract' => $autoExtract],
]
);
}
// ─────────────────────────────────────────────────────────────
// Sessions & Results
// ─────────────────────────────────────────────────────────────
public function getSession(string $sessionId): array
{
return $this->request('GET', "/extractions/sessions/{$sessionId}");
}
public function getResults(string $sessionId): array
{
return $this->request('GET', "/extractions/sessions/{$sessionId}/results")['data'];
}
public function getResult(string $resultId): array
{
return $this->request('GET', "/extractions/results/{$resultId}");
}
// ─────────────────────────────────────────────────────────────
// Workspace Documents
// ─────────────────────────────────────────────────────────────
public function listWorkspaceDocuments(
int $workspaceId,
array $params = []
): array {
$query = http_build_query(array_filter($params));
$endpoint = "/workspaces/{$workspaceId}/documents" . ($query ? "?{$query}" : '');
return $this->request('GET', $endpoint);
}
public function getWorkspaceDocument(int $workspaceId, string $documentId): array
{
return $this->request('GET', "/workspaces/{$workspaceId}/documents/{$documentId}");
}
public function createWorkspaceDocument(
int $workspaceId,
string $key,
?string $filename = null
): array {
$payload = ['key' => $key];
if ($filename !== null) {
$payload['filename'] = $filename;
}
return $this->request('POST', "/workspaces/{$workspaceId}/documents", $payload);
}
public function importWorkspaceDocumentUrl(
int $workspaceId,
string $url,
?string $filename = null
): array {
$payload = ['url' => $url];
if ($filename !== null) {
$payload['filename'] = $filename;
}
return $this->request('POST', "/workspaces/{$workspaceId}/documents:importUrl", $payload);
}
public function reparseWorkspaceDocument(
int $workspaceId,
string $documentId,
string $configHash,
bool $force = false
): array {
return $this->request('POST', "/workspaces/{$workspaceId}/documents/{$documentId}/reparse", [
'config_hash' => $configHash,
'force' => $force,
]);
}
}
Installation
composer require guzzlehttp/guzzle
RaydocsClient.php:<?php
require_once 'vendor/autoload.php';
require_once 'RaydocsClient.php';
$client = new RaydocsClient('your_api_token');
Next Steps
Uploading Documents
Learn how to upload files for extraction
Quick Start
Extract data from documents in 3 steps
Full Workflow
Complete example with template creation
List Workspace Documents
List and filter workspace-scoped documents