> ## Documentation Index > Fetch the complete documentation index at: https://benchgen.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Launch a benchmark run > The unified run endpoint, the same one the Evaluate page uses: resolves the model, builds the run scaffolding (per-run key, data, containers) and queues the submission. The model source is auto-detected from the body: pass `model_id` (integer platform model id) or `model` (24-hex catalogue id, numeric id, or model name; names resolve server-side, preferring a running instance) for platform models, `model_url` + `model_token` + `model_name` with `model_source: "external"` for an external endpoint, or `hf_model_path` with `model_source: "huggingface"`. Join the competition first (POST /api/competitions/{id}/register/). The run spends the caller's credits and lands on the competition leaderboard. Requires the `benchmark:run` scope. ## OpenAPI ````yaml POST /models/api/queue_benchmark_run openapi: 3.0.3 info: title: BenchGen Platform API version: 1.0.0 description: >- One API for the whole BenchGen platform: model catalogue and serving, fine-tuning and benchmarks, datasets (knowledge), and billing. ## Authentication Every request uses the same credential: a platform API token sent as `Authorization: Bearer bgn_...`. Create tokens in the web app under Profile Settings > Platform API tokens (the secret is shown exactly once), or via `POST /api/tokens/` with an interactive session. Revoking a token disables it platform-wide within 60 seconds. ## Scopes A token carries scopes chosen at creation; a request outside the token's scopes gets `403` with an explanatory message. | scope | grants | |---|---| | `models:read` | read model catalogues, job status, logs, GPU info | | `models:write` | deploy, train, merge, stop models and jobs | | `benchmark:read` | read benchmark runs and results | | `benchmark:run` | launch benchmark runs | | `benchmark:create` | create benchmarks in your account (drafts, Excel, bundles, specs); counts toward the creation limit | | `benchmark:manage` | edit and delete benchmarks you own or collaborate on | | `benchmark:publish` | publish and unpublish benchmarks you own or collaborate on | | `knowledge:read` | read your datasets and fine-tuning data | | `knowledge:write` | create, edit and delete datasets and fine-tuning data | | `billing:read` | read your balance and usage | | `agents:chat` | chat with your own agents through the API | | `agents:manage` | manage your agents, knowledge bases and channels | | `admin` | everything the account can do (staff accounts only) | ## For agents This document plus `/api/llms.txt` are the machine-readable entry points. Responses are JSON. Errors use conventional status codes; the body carries `error` or `message`. Knowledge endpoints return `[{"data": [...], "meta": {...}}]`. The complete auto-generated schema of every endpoint (including internal ones) lives at `/api/public-docs.json` (Swagger 2.0); this document is the curated, stable, supported surface. contact: url: https://benchgen.com servers: - url: https://api.benchgen.com security: - platformToken: [] tags: - name: auth description: Token introspection for services and integrations - name: tokens description: Manage your platform API tokens - name: models description: Model catalogue and serving - name: finetune description: Fine-tuning jobs, inference deployments, GPUs - name: knowledge description: Datasets and fine-tuning data (knowledge API) - name: billing description: Balance and usage - name: agents description: Chat with your agents (OpenAI-compatible facade) - name: benchmark description: Public benchmark (competition) listings. paths: /models/api/queue_benchmark_run: post: tags: - benchmark summary: Launch a benchmark run description: >- The unified run endpoint, the same one the Evaluate page uses: resolves the model, builds the run scaffolding (per-run key, data, containers) and queues the submission. The model source is auto-detected from the body: pass `model_id` (integer platform model id) or `model` (24-hex catalogue id, numeric id, or model name; names resolve server-side, preferring a running instance) for platform models, `model_url` + `model_token` + `model_name` with `model_source: "external"` for an external endpoint, or `hf_model_path` with `model_source: "huggingface"`. Join the competition first (POST /api/competitions/{id}/register/). The run spends the caller's credits and lands on the competition leaderboard. Requires the `benchmark:run` scope. requestBody: required: true content: application/json: schema: type: object required: - competition_id properties: competition_id: type: integer model_id: type: integer description: >- Platform model id (integer, preferred). Get it from the model catalogue; an already-running model is benchmarked against its live endpoint, no second deploy. model: type: string description: >- Catalogue model id (24-hex), a numeric platform id, or a model name (display or litellm). Names are resolved server-side against the catalogue, preferring a running instance; an unknown name is passed through and will fail the run, so prefer ids when scripting. phase_id: type: integer description: Optional phase override; defaults to the current phase model_source: type: string enum: - platform - external - huggingface env_vars: type: object description: Extra env for the run container temperature: type: number max_tokens: type: integer top_p: type: number responses: '201': description: Run queued content: application/json: schema: type: object properties: submission_id: type: integer submission_status: type: string resolved_model: type: object description: How the model was resolved (model name, endpoint) competition_id: type: integer phase_id: type: integer poll_path: type: string description: GET this path for the full run record run_status_path: type: string description: >- GET this path to follow the run: state, score and link in one small answer run_path: type: string nullable: true description: Web app path of the run page '400': description: 'Bad body: unknown competition, unresolvable model' '402': description: Not enough credits for the run '403': description: Token lacks the benchmark:run scope security: - platformToken: [] components: securitySchemes: platformToken: type: http scheme: bearer bearerFormat: bgn_ opaque token description: >- Platform API token created under Profile Settings > Platform API tokens. Scopes are fixed at creation. ````