Documentation

Welcome to the VEDA API reference. This guide is split into instructions for human developers setting up the integration, and rules for autonomous AI agents interacting with the platform directly.

For Human Developers

Get started with VEDA by registering an agent, topping up their balance, and understanding the core discovery-to-purchase flow.

1. Getting Started

Notice: The API endpoints on VEDA are strictly designed for autonomous AI Agents. Human operators should not use the API for dataset discovery or procurement. Instead, human users must use the web dashboard and the shopping cart interface to purchase datasets.

To enable your AI agents to purchase datasets programmatically, you must create an agent via the user dashboard to obtain an Agent API key. All API requests made by the agent must be authenticated using this key.

2. Authentication & Limits

Agent API endpoints require the api_key passed in the JSON request body. All requests are rate-limited per standard tier limits. Ensure you keep your API keys secure.

3. API Endpoint Reference

Endpoint	Method	Description
/register	POST	Self-register a new agent to obtain an `api_key` and `agent_id`.
/api/payments/topup	POST	Add tokens to an agent's balance using the configured payment provider.
/discover	GET	Human-readable marketplace overview containing live catalog summary.
/query	POST	Submit a natural-language description to search datasets, or a `purchase_dataset_id` to buy instantly.
/ledger/{api_key}	GET	Retrieve the complete transaction history and token balance for the specified agent.
/download/{token}	GET	Proxy endpoint for one-time dataset downloads. Invalidates the token on the first request.
/status/{job_id}	GET	Deprecated Async job polling has been removed in favor of instantaneous dataset delivery.

4. Selling on VEDA

Registered users can list and sell datasets. By creating a listing on the dashboard, VEDA automatically generates the SEO metadata, XML sitemap entry, and exposes it to AI crawlers. Platform fees (standard 15%) are deducted automatically, and your net earnings are logged to your seller balance.

Python Example

import requests

# 1. Register an Agent
res = requests.post("https://veda.techgenesys.ai/register", json={"name": "Analysis Agent"})
api_key = res.json()["api_key"]

# 2. Query for Data
query_res = requests.post(
    "https://veda.techgenesys.ai/query",
    json={"api_key": api_key, "request_text": "brain MRI datasets"}
)
print(query_res.json())

For AI Agents

The following instructions are formatted for semantic parsing by LLMs and autonomous agents utilizing the Model Context Protocol (MCP) or direct HTTP requests.

System Overview

VEDA is an agent-native dataset marketplace. You (the agent) can discover, procure, and download data completely autonomously.

Discovery Flow

Root Discovery: Fetch GET https://veda.techgenesys.ai/llms.txt for a plain-text summary of available datasets and endpoints.
Machine Catalog: Fetch GET https://veda.techgenesys.ai/.well-known/agent-card.json to read the DataCatalog schema describing the platform capabilities.
Catalog Query: Use POST /query with a JSON payload containing request_text to search the catalog in natural language. Do not include a purchase_dataset_id if you only want to search.

Purchase & 402 Handling

To purchase a dataset, send POST /query with your api_key and the integer purchase_dataset_id.

If your balance is sufficient, the server deducts tokens and returns HTTP 200 with a download string containing the URL path (e.g., /download/uuid-token).
If your balance is insufficient, the server returns HTTP 402 Insufficient Balance and includes a payment_url in the JSON response. You must halt and present this URL to your human operator to top up your balance.
Downloading an already-purchased dataset is free and does not deduct additional tokens.

One-Time Download Rules

The download URL you receive is a one-time proxy link. The moment you execute a GET request against it, the server marks the token as used = true and redirects you to the raw file. Any subsequent request to the exact same download token will return a 410 Gone HTTP status, regardless of expiration time.

cURL Example (For Agents)

# Execute a direct purchase
curl -X POST https://veda.techgenesys.ai/query \
  -H "Content-Type: application/json" \
  -d '{"api_key": "YOUR_KEY", "purchase_dataset_id": 3}'