Skip to main content

Tutorials

Python usage example​

The following example uses the v2 API and X-API-Key authentication.

Dependency​

pip install requests

Configuration and upload​

from pathlib import Path

import requests


class VeraquoAPI:
    def __init__(self, base_url: str, api_key: str):
        self.base_url = base_url.rstrip("/")
        self.session = requests.Session()
        self.session.headers.update({"X-API-Key": api_key})

    def upload_file(self, path: str) -> dict:
        file_path = Path(path)
        with file_path.open("rb") as file_handle:
            response = self.session.post(
                f"{self.base_url}/files",
                files={"file": (file_path.name, file_handle)},
            )
        response.raise_for_status()
        return response.json()

The current upload endpoint is POST /files; its required multipart field is file and it returns one file object. Save the response id.

Create a run and check its status​

class VeraquoAPI(VeraquoAPI):
    def create_run(self, file_id: str, workers: list[str] | None = None) -> dict:
        response = self.session.post(
            f"{self.base_url}/runs",
            json={
                "file_id": file_id,
                "run_schemas": None,
                "workers": workers,
            },
        )
        response.raise_for_status()
        return response.json()

    def get_run(self, run_id: str) -> dict:
        response = self.session.get(f"{self.base_url}/runs/{run_id}")
        response.raise_for_status()
        return response.json()

    def get_results(self, run_id: str) -> dict:
        response = self.session.get(f"{self.base_url}/runs/{run_id}/results")
        response.raise_for_status()
        return response.json()

    def delete_file(self, file_id: str) -> None:
        response = self.session.delete(f"{self.base_url}/files/{file_id}")
        response.raise_for_status()

There is no separate /status endpoint in v2. Poll GET /runs/{run_id} until status is ready, ok, alert, or error, then retrieve results with GET /runs/{run_id}/results.

Complete flow​

api = VeraquoAPI(
    "https://veraquo.gradiant.org/api/v2",
    "{API_KEY}",
)

file_info = api.upload_file("./file.webp")
run_info = api.create_run(file_info["id"])
results = api.get_results(run_info["id"])
print(results)

For asynchronous processing, call api.get_run(run_info["id"]) periodically before calling get_results.