> ## Documentation Index
> Fetch the complete documentation index at: https://docs.visent.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Forge API

> Automate GPU benchmarking and performance validation through the Visent Forge API

# Forge API

Automate GPU benchmarking, performance validation, and results analysis through the Visent Forge API. Trigger benchmark jobs, monitor execution status, and retrieve detailed performance reports programmatically.

Supports asynchronous job execution, result querying, and integration with CI/CD pipelines for automated performance testing.

## Base URL

```
https://api.visent.ai/forge
```

## Benchmark Execution

### Start Benchmark

```bash theme={null}
# Trigger a benchmark job
POST /benchmarks

# Example request
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ml-training",
    "gpu": "h100",
    "config": {
      "model": "resnet50",
      "batch_size": 32,
      "iterations": 100
    }
  }' \
  "https://api.visent.ai/forge/benchmarks"

# Example response
{
  "job_id": "bench_12345",
  "status": "queued",
  "estimated_duration": "15m",
  "created_at": "2024-01-15T10:30:00Z"
}
```

### Check Job Status

```bash theme={null}
# Monitor benchmark progress
GET /benchmarks/{job_id}

# Example response
{
  "job_id": "bench_12345",
  "status": "running",
  "progress": 45,
  "started_at": "2024-01-15T10:31:00Z",
  "estimated_completion": "2024-01-15T10:42:00Z"
}
```

### Get Results

Coming soon - retrieving benchmark results and performance reports.

## Benchmark Types

### Machine Learning

Coming soon - ML training and inference benchmark configurations.

### Scientific Computing

Coming soon - HPC and simulation benchmark options.

### Custom Benchmarks

Coming soon - defining and running custom benchmark scenarios.

## Job Management

### List Jobs

```bash theme={null}
# Get all benchmark jobs
GET /benchmarks

# Filter by status
GET /benchmarks?status=completed&limit=10
```

### Cancel Job

Coming soon - canceling running benchmark jobs.

### Job History

Coming soon - accessing historical benchmark data and trends.

## Results and Reports

### Download Reports

```bash theme={null}
# Get benchmark report
GET /benchmarks/{job_id}/report

# Specify format
GET /benchmarks/{job_id}/report?format=pdf
```

### Metrics Export

Coming soon - exporting raw benchmark metrics and data.

### Comparison Reports

Coming soon - generating comparison reports between benchmark runs.

## Configuration

### Benchmark Profiles

Coming soon - managing reusable benchmark configurations.

### Hardware Targets

Coming soon - specifying target hardware for benchmark execution.

## Webhooks

Coming soon - webhook notifications for benchmark completion and status updates.

## Rate Limits

Coming soon - API rate limiting and concurrent job limits.

## Error Handling

Coming soon - error codes and troubleshooting guide.

## Code Examples

### Python

```python theme={null}
import requests
import time

# Start benchmark
response = requests.post(
    "https://api.visent.ai/forge/benchmarks",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "type": "ml-training",
        "gpu": "h100",
        "config": {"model": "resnet50", "batch_size": 32}
    }
)
job = response.json()
job_id = job["job_id"]

# Monitor progress
while True:
    status_response = requests.get(
        f"https://api.visent.ai/forge/benchmarks/{job_id}",
        headers={"Authorization": "Bearer YOUR_API_KEY"}
    )
    status = status_response.json()
    if status["status"] == "completed":
        break
    time.sleep(30)
```

## Next Steps

* [Review authentication guide](authentication) for API setup
* [Explore CLI tools](../forge/cli-reference) for local benchmarking
* [Use Python SDK](../sdk/python) for simplified automation