Tools API Overview

# Tools API Overview

Programmatic access to sboxcool.com's game development tools. Generate materials, terrain heightmaps, process 3D models, and convert animations via HTTP API.

## Authentication

All endpoints require a Tools API key. Generate one at [Settings > API Keys](/settings/api-keys).

Include it as a Bearer token in the `Authorization` header:

```
Authorization: Bearer sbox_tk_your_key_here
```

Keys are separate from Network Storage API keys. One key per account, shown once on creation.

## Rate Limits

- **100 requests per minute**
- **600 requests per hour**
- **5,000 requests per day**

Rate limit status is visible at [Settings > Rate Limits](/settings/rate-limits).

## Response Format

**Material, Terrain, and Animation** endpoints are synchronous. They return JSON with a `downloadUrl` you fetch separately:

```json
{
  "ok": true,
  "downloadUrl": "/uploads/temp/123/rock_vmat.zip"
}
```

**Model** endpoint is asynchronous. It returns a job ID you poll for status:

```json
{
  "ok": true,
  "jobId": "a1b2c3d4e5f6",
  "statusUrl": "/api/tools/model/a1b2c3d4e5f6"
}
```

**Queue API** (`/api/tools/v1/queue`) provides unified job submission for all tools with position tracking and estimated wait times. See [Queue API](/wiki/tools-api/queue-api) for details.

## Download Links

All download links are temporary and expire after **1 hour**. Fetch them promptly after generation.

## Errors

All errors return JSON:

```json
{
  "error": "Description of what went wrong."
}
```

Common HTTP status codes:
- `400` -- Invalid parameters
- `401` -- Missing or invalid API key
- `429` -- Rate limited or too many concurrent jobs
- `500` -- Server processing error

## MCP / HTTP Client Compatibility

The material, model, and animation endpoints use `multipart/form-data` for file uploads. The terrain endpoint accepts plain form fields (no file upload needed), so it works with any HTTP client.

If your MCP tool only supports JSON bodies, you'll need a wrapper for file uploads. The download step is always a simple GET request.