API Reference

BeaverYard Public API

Version 1.0.0

Programmatic access to BeaverYard fine-tuning. Submit training runs, check status, download artifacts, and manage your account balance through a simple REST API.

Base URL

https://api.beaveryard.com/api/v1

Quick start

Create an API key in the dashboard under the API section.
Include it in every request: Authorization: Bearer beaveryard_your-key
Call GET /api/v1/models to verify connectivity.
Submit a run with POST /api/v1/runs.

Verify

curl https://api.beaveryard.com/api/v1/models \
  -H "Authorization: Bearer beaveryard_your-key"

Authentication

All endpoints require a Bearer API key sent in the Authorization header. Keys are created and managed in the API section of the dashboard. Each account can have up to 3 active keys.

Key format

All keys start with beaveryard_ followed by a random string. Store keys securely — they cannot be retrieved after creation.

Deleting keys

Delete a key permanently from the API section in the dashboard. Deleted keys immediately stop working — all subsequent requests return 401 invalid_api_key.

Authorization header

Authorization: Bearer beaveryard_your-key

Security note: Never expose API keys in client-side code, public repositories, or logs.

Errors

Code	HTTP	Description
`invalid_api_key`	401	API key is missing or invalid. Create a new key in the dashboard API section.
`rate_limited`	429	Too many requests. Back off and retry after a short delay.
`validation_failed`	422	Request body failed validation (missing fields, bad format, limits exceeded).
`not_found`	404	The requested resource does not exist.
`insufficient_balance`	402	Account balance is too low to cover the run cost.
`model_not_available`	422	The requested model is not currently available.
`consent_required`	422	Required consent fields were not accepted.
`idempotency_conflict`	409	Idempotency key was already used with different parameters.

Example

{
  "error": {
    "code": "error_code",
    "message": "Human-readable description."
  }
}

GET/api/v1/models

List available models

Returns all models currently available for fine-tuning, including terms and use-policy URLs. Model choice does not affect pricing.

Requires Bearer API key

Responses

200Successful Response

Request

curl https://api.beaveryard.com/api/v1/models \
  -H "Authorization: Bearer beaveryard_your-key"

Response

{
  "data": [
    {
      "model_id": "llama-3.1-8b",
      "name": "Llama 3.1 8B Instruct",
      "provider": "Meta",
      "available": true,
      "terms_url": "https://www.llama.com/llama3_1/license/",
      "use_policy_url": "https://www.llama.com/llama3_1/use-policy/"
    },
    {
      "model_id": "mistral-7b",
      "name": "Mistral 7B Instruct",
      "provider": "Mistral AI",
      "available": true,
      "terms_url": "https://mistral.ai/news/announcing-mistral-7b",
      "use_policy_url": null
    },
    {
      "model_id": "gemma-7b",
      "name": "Gemma 1.1 7B Instruct",
      "provider": "Google",
      "available": true,
      "terms_url": "https://ai.google.dev/gemma/terms",
      "use_policy_url": "https://ai.google.dev/gemma/prohibited_use_policy"
    }
  ]
}

POST/api/v1/runs

Submit a training run

Submit a new fine-tuning run. Upload your JSONL dataset as multipart form data along with model selection and required consents. The run is validated, priced, and queued in a single request.

Requires Bearer API key

Parameters

Idempotency-Keystring (UUID)header

Optional request header supplied by the client to prevent accidental duplicate submissions. Reuse the same key only when retrying the exact same request within 24 hours. If omitted, retries may create duplicate runs.

Request Body

Content-Type: multipart/form-data

datasetfilerequired

JSONL dataset file (max 600 MB).

model_idstringrequired

Model to fine-tune, e.g. "llama-3.1-8b".

labelstring

Optional human-readable label for the run (max 255 chars).

model_terms_acceptedbooleanrequired

Must be true. Confirms you accept the model provider's license terms.

data_policy_acceptedbooleanrequired

Must be true. Confirms you accept BeaverYard's data policy, dataset rights, and that results are not guaranteed.

priority_processingboolean

Enable priority queue placement (add-on pricing applies, or included with Plus/Pro subscription). Default: false.

Idempotency-Keystring (UUID)

Sent as a request header (not a form field). Prevents duplicate submissions when retrying the same request. Reuse the same key within 24 hours.

Responses

201Run created and queued

422Validation Error

Request

# With Idempotency-Key (recommended for retries)
curl -X POST https://api.beaveryard.com/api/v1/runs \
  -H "Authorization: Bearer beaveryard_your-key" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -F "dataset=@training_data.jsonl" \
  -F "model_id=llama-3.1-8b" \
  -F "model_terms_accepted=true" \
  -F "data_policy_accepted=true" \
  -F "label=My first run"

# Without Idempotency-Key (simpler, but retries may create duplicates)
curl -X POST https://api.beaveryard.com/api/v1/runs \
  -H "Authorization: Bearer beaveryard_your-key" \
  -F "dataset=@training_data.jsonl" \
  -F "model_id=llama-3.1-8b" \
  -F "model_terms_accepted=true" \
  -F "data_policy_accepted=true"

Response

{
  "run_id": "f195d554-8a3b-4e1c-9f2d-1a2b3c4d5e6f",
  "status": "queued",
  "price_cents": 700,
  "currency": "USD",
  "balance_after_cents": 2500,
  "plan_name": "Launch M"
}

GET/api/v1/runs

List runs

Returns all runs for the authenticated user, ordered by creation date (newest first). Uses cursor-based pagination — pass the `next_cursor` value from the previous response to fetch the next page.

Requires Bearer API key

Parameters

limitintegerquery

Max results per page. Default: 20, max: 100.

cursorstringquery

Pagination cursor from a previous response. Omit for the first page.

Responses

200Successful Response

Request

# List all runs (first page, default limit)
curl https://api.beaveryard.com/api/v1/runs \
  -H "Authorization: Bearer beaveryard_your-key"

# Paginate with limit and cursor
curl "https://api.beaveryard.com/api/v1/runs?limit=5&cursor=eyJjcmVhdGVkX2F0Ijoi..." \
  -H "Authorization: Bearer beaveryard_your-key"

Response

{
  "data": [
    {
      "run_id": "f195d554-8a3b-4e1c-9f2d-1a2b3c4d5e6f",
      "status": "complete",
      "model_id": "llama-3.1-8b",
      "created_at": "2026-03-19T12:00:00Z",
      "artifacts_available": true,
      "artifacts_expires_at": "2026-03-26T12:00:00Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

GET/api/v1/runs/{run_id}

Get run details

Returns full details for a single run, including status, pricing, and timestamps.

Requires Bearer API key

Parameters

run_idstringpathrequired

The run ID returned when the run was created.

Responses

200Successful Response

404Run not found

Request

curl https://api.beaveryard.com/api/v1/runs/YOUR_RUN_ID \
  -H "Authorization: Bearer beaveryard_your-key"

Response

{
  "run": {
    "run_id": "f195d554-8a3b-4e1c-9f2d-1a2b3c4d5e6f",
    "status": "completed",
    "model_id": "llama-3.1-8b",
    "label": "My first run",
    "plan": "Launch M",
    "price_cents": 700,
    "created_at": "2026-03-19T12:00:00Z",
    "started_at": "2026-03-19T12:05:00Z",
    "completed_at": "2026-03-19T13:42:00Z"
  }
}

POST/api/v1/runs/{run_id}/artifacts/download

Get artifact download URLs

Returns temporary download URLs for the completed run's artifacts. URLs expire after 30 minutes. Only available for runs with status "completed" within the retention window.

Requires Bearer API key

Parameters

run_idstringpathrequired

The run ID of a completed run.

Responses

200Successful Response

404Run not found or not completed

Request

curl -X POST https://api.beaveryard.com/api/v1/runs/YOUR_RUN_ID/artifacts/download \
  -H "Authorization: Bearer beaveryard_your-key"

Response

{
  "artifacts": [
    {
      "artifact_type": "model",
      "url": "https://artifacts.beaveryard.com/…?signature=…&expires=1800",
      "expires_in": 1800,
      "filename": "artifacts.tar.gz"
    }
  ]
}

GET/api/v1/balance

Get account balance

Returns the current account balance in cents. Balance is deducted when a run is submitted and validated.

Requires Bearer API key

Responses

200Successful Response

Request

curl https://api.beaveryard.com/api/v1/balance \
  -H "Authorization: Bearer beaveryard_your-key"

Response

{
  "balance_cents": 2500,
  "currency": "USD"
}