Raydocs Client

This page provides ready-to-use API client implementations that you can copy into your projects. These clients are used throughout the cookbook examples.

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" | "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;
    }
}

Installation

npm install axios

Save the client as 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}")

Installation

pip install requests

Copy the 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}");
    }
}

Installation

composer require guzzlehttp/guzzle

Save the client as 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

Overview

Cookbook

Workspaces

Workspace Users

Extraction Templates

Extraction Sessions

Batch Operations

Documents

Results

TypeScript / Node.js Client

Installation

Python Client

Installation

PHP Client (Guzzle)

Installation

Next Steps

Uploading Documents

Quick Start

Full Workflow

Overview

Cookbook

Workspaces

Workspace Users

Extraction Templates

Extraction Sessions

Batch Operations

Documents

Results

​TypeScript / Node.js Client

​Installation

​Python Client

​Installation

​PHP Client (Guzzle)

​Installation

​Next Steps

Uploading Documents

Quick Start

Full Workflow

TypeScript / Node.js Client

Installation

Python Client

Installation

PHP Client (Guzzle)

Installation

Next Steps