Raydocs 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})

pip install requests

from raydocs_client import RaydocsClient

client = RaydocsClient("your_api_token")

<?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,
        ]);
    }
}

composer require guzzlehttp/guzzle

<?php

require_once 'vendor/autoload.php';
require_once 'RaydocsClient.php';

$client = new RaydocsClient('your_api_token');