> ## Documentation Index > Fetch the complete documentation index at: https://docs.sqwish.ai/llms.txt > Use this file to discover all available pages before exploring further. # Start a family > Start a new family with its first fine-tune, from a base or one of your models (`from`), on a dataset version, its newest unless you name one. Its model joins the family as family@1 if it passes its gate. To train an existing family on new rows, continue it (`POST /v1/families/{family}/continue`). While a large dataset version's training tokens are first counted, it answers 503 tokens_counting with Retry-After and starts nothing. ## OpenAPI ````yaml /openapi.json post /v1/families openapi: 3.1.0 info: title: OneHot API description: >- Decisions your application can act on: send a context and the questions you want answered, and get a probability for every answer you allow. Authenticate with `Authorization: Bearer onehot_sk_...`. A short guide for coding agents is at /llms.txt. An API key reads its account but never changes it: keys, billing and settings change in the console. Money fields ending in _usd are exact decimal strings, never integer cents. Over a rate limit a request gets 429 with Retry-After, and one with more input tokens than your minute allows gets 422 too_many_tokens. version: 0.1.0 servers: - url: https://api.sqwish.ai security: [] tags: - name: Decisions description: Probabilities for questions with fixed outcomes. - name: Models description: Base models, and fine-tuned models by their numbers. - name: Families description: >- Lines of models trained on one dataset, and the switches that let them answer calls. - name: Datasets description: >- Validated training examples. A dataset grows in versions, and a version never changes. - name: Evaluations description: Reusable model results on a dataset's fixed evaluation rows. - name: Fine-tuning description: Training jobs, their events and held-out results. - name: Prompt tuning description: Better wording for a decision, tested on your rows. Words, not weights. - name: Labeling description: Teacher labels for real queries, reviewed by you. - name: Accounts description: Email OTP sign-in, revocable sessions, security and API keys. - name: Billing description: Exact USD balances, purchases, automatic top-ups and referrals. - name: Integrations description: Endpoints other tools call, such as Claude Code. - name: System description: Health and discovery. paths: /v1/families: post: tags: - Families summary: Start a family description: >- Start a new family with its first fine-tune, from a base or one of your models (`from`), on a dataset version, its newest unless you name one. Its model joins the family as family@1 if it passes its gate. To train an existing family on new rows, continue it (`POST /v1/families/{family}/continue`). While a large dataset version's training tokens are first counted, it answers 503 tokens_counting with Retry-After and starts nothing. operationId: createFamily parameters: - name: idempotency-key in: header required: false schema: anyOf: - type: string - type: 'null' title: Idempotency-Key description: >- Reuse the same key and body after a lost response. A replay returns the job that key queued, with `Idempotency-Replayed: true`. A changed body conflicts. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/JobCreate' responses: '201': description: Successful Response content: application/json: schema: properties: id: type: string title: Id dataset_id: type: string title: Dataset Id model: type: string title: Model method: type: string enum: - sft - reward title: Method hyperparameters: $ref: '#/components/schemas/ResolvedHyperparameters' dataset_evaluation: anyOf: - $ref: '#/components/schemas/Evaluation' - type: 'null' family: anyOf: - type: string - type: 'null' title: Family description: The family the job adds a model to. family_deleted: type: boolean title: Family Deleted description: >- True once you deleted that family. The job and its charge stay. parent: anyOf: - type: string - type: 'null' title: Parent description: The id of the model it trains from, or null from a base. dataset_version: type: integer title: Dataset Version description: The version of its dataset it trains on. status: type: string enum: - queued - running - cancelling - succeeded - failed - cancelled title: Status outcome: anyOf: - type: string enum: - joined - gate_failed - failed - cancelled - rolled_back - type: 'null' title: Outcome description: >- How it ended for its family: its model joined the family with the next number, or failed its gate and is not kept for you, or the run failed or was cancelled, or a rollback discarded the model that joined. Only a failed run or a cancellation is free and leaves the data for another try. Null while it runs. created_at: type: number title: Created At updated_at: type: number title: Updated At output_model: anyOf: - type: string - type: 'null' title: Output Model metrics: anyOf: - additionalProperties: true type: object - type: 'null' title: Metrics description: Evaluation groups and the gate, when complete. error: anyOf: - type: string - additionalProperties: true type: object - type: 'null' title: Error progress: anyOf: - additionalProperties: true type: object - type: 'null' title: Progress curve: anyOf: - items: $ref: '#/components/schemas/CurvePoint' type: array - type: 'null' title: Curve description: >- The training loss over steps, at most 300 points, each the means of a run of consecutive steps. Null until the job succeeds, or when its trainer kept none. Lists of jobs leave it out. limits: additionalProperties: type: integer type: object title: Limits description: 'max_questions: the most decisions a row of it may ask.' split: additionalProperties: type: integer type: object title: Split description: >- train_rows and validation_rows, and trained_tokens: the training tokens the job trains, each decision of a row with the row's whole text, tokenized as input tokens are (an outcome at least 8, a row of n decisions at least 24 × n for each), each time a step takes the row. A priced fine-tune's fee is fine_tune_million_tokens_usd for them, at least fine_tune_minimum_usd. lineage: anyOf: - additionalProperties: true type: object - type: 'null' title: Lineage price_usd: type: string title: Price Usd description: The fee held for this job, as exact USD. charge: type: string enum: - free - reserved - charged - released title: Charge description: >- What the fee is doing: held while the job runs, charged if it succeeds, released if it fails or is cancelled. rows_deleted: type: boolean title: Rows Deleted description: >- True once a dataset whose rows its specification held was deleted: the job, its model and its metrics stay, but its held-out records are gone. type: object required: - id - dataset_id - model - method - hyperparameters - family - family_deleted - parent - dataset_version - status - outcome - created_at - updated_at - output_model - metrics - error - progress - limits - split - lineage - price_usd - charge title: FineTuningJob headers: Idempotency-Replayed: description: >- `true` when this response replays an earlier request that used the same `Idempotency-Key`. Absent when the request ran. schema: type: string enum: - 'true' 4XX: description: >- Client error. On a 422, `error.details` lists each field that failed. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 5XX: description: Server error. A 503 names what is not running on this server. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] components: schemas: JobCreate: properties: dataset_id: type: string pattern: ^ds_[a-f0-9]{24}$ title: Dataset Id from: type: string maxLength: 140 minLength: 1 title: From description: >- Where the family starts: a base model that can be fine-tuned, or one of your models as family@N, which it trains from on that model's base. Left out, core. default: kettei-core family: type: string maxLength: 63 pattern: ^[a-z](?:-?[a-z0-9]){1,62}$ title: Family description: >- The new family's name: lowercase letters and digits, with single hyphens between them, 2 to 63 characters. A name already taken is refused with family_exists. method: type: string enum: - sft - reward title: Method default: sft hyperparameters: $ref: '#/components/schemas/Hyperparameters' dataset_version: anyOf: - type: integer minimum: 1 - type: 'null' title: Dataset Version description: >- The version of the dataset to train on, its newest when left out. The family trains on every training row of that version, and continues from it. max_price_usd: anyOf: - type: string pattern: ^\d{1,9}(\.\d{1,9})?$ - type: 'null' title: Max Price Usd description: >- The most you agree to pay for this job, in USD, such as the price you were shown. It is a decimal string, such as `"2.500000000"`, never a JSON number, so no precision is lost: a number is refused with invalid_request, naming this field. If it costs more when it is admitted, it is refused with price_changed and nothing is held. additionalProperties: false type: object required: - dataset_id - family title: JobCreate description: A new family's first fine-tune, from a base or one of your models. ResolvedHyperparameters: properties: steps: type: integer title: Steps learning_rate: type: number title: Learning Rate lora_rank: type: integer title: Lora Rank seed: type: integer title: Seed type: object required: - steps - learning_rate - lora_rank - seed title: ResolvedHyperparameters description: >- What a job trains with, as its owner chose or the defaults gave it. The trainer's own settings stay on the server. Evaluation: properties: id: type: string title: Id dataset_id: type: string title: Dataset Id dataset_version: type: integer title: Dataset Version description: The dataset version whose evaluation rows it scores. model_id: type: string title: Model Id model_sha256: type: string title: Model Sha256 model_label: type: string title: Model Label model_name: anyOf: - type: string - type: 'null' title: Model Name version: anyOf: - type: integer - type: 'null' title: Version status: type: string enum: - queued - running - cancelling - succeeded - failed - cancelled title: Status created_at: type: number title: Created At updated_at: type: number title: Updated At generation: type: integer title: Generation training_job_id: anyOf: - type: string - type: 'null' title: Training Job Id dataset_sha256: type: string title: Dataset Sha256 evaluation_sha256: type: string title: Evaluation Sha256 method: type: string enum: - sft - reward title: Method evaluation_rows: type: integer title: Evaluation Rows decisions: type: integer title: Decisions named: type: string title: Named description: >- The family, or the model by its number, the request named, whose idle clock the run moves when it finishes. completed_rows: type: integer title: Completed Rows metrics: anyOf: - additionalProperties: true type: object - type: 'null' title: Metrics description: >- Null until the evaluation succeeds. Then `n`, the decisions scored, with `accuracy`, `loss`, `brier` and `ece` for expected answers or `expected_reward` for rewards, and `latency_ms`, the median server milliseconds per request, when it was measured. A result taken from a fine-tune's own held-out scoring sends no request, so it has none. error: anyOf: - additionalProperties: true type: object - type: 'null' title: Error type: object required: - id - dataset_id - dataset_version - model_id - model_sha256 - model_label - model_name - version - status - created_at - updated_at - generation - training_job_id - dataset_sha256 - evaluation_sha256 - method - evaluation_rows - decisions - completed_rows - metrics - error title: Evaluation CurvePoint: properties: step: type: integer title: Step description: The last training step the point covers. loss: type: number title: Loss description: The mean training loss over the steps it covers. learning_rate: type: number title: Learning Rate description: The mean learning rate. type: object required: - step - loss - learning_rate title: CurvePoint ErrorResponse: description: The body of every error. properties: error: $ref: '#/components/schemas/ErrorBody' required: - error title: ErrorResponse type: object Hyperparameters: properties: steps: anyOf: - type: integer minimum: 1 - type: 'null' title: Steps description: >- Training steps. Left out, the policy's default passes over the actual training split, with a minimum of 20 steps. At most the policy's allowed passes, or 20 steps: more gets 422 too_many_steps, which gives the most. The fee is per training token trained, so more steps train more tokens and cost more. learning_rate: type: number maximum: 0.01 exclusiveMinimum: 0 title: Learning Rate default: 0.00005 lora_rank: type: integer minimum: 1 title: Lora Rank description: >- The LoRA rank of the adapter, from 1 to 16, the highest at launch. Left out, 8. A rank above 16 is refused with `rank_unsupported` when the job is accepted. A continuation keeps its parent's rank. default: 8 seed: type: integer maximum: 2147483647 minimum: 0 title: Seed default: 42 additionalProperties: false type: object title: Hyperparameters ErrorBody: properties: code: description: A stable code to branch on, such as invalid_request. title: Code type: string message: description: What went wrong and what to change, in plain words. title: Message type: string retryable: description: >- True when another attempt may succeed; it does not prove that no work was done. Respect Retry-After when present. Only operations that support Idempotency-Key replay a prior result, including /v1/decide for 24 hours. title: Retryable type: boolean request_id: description: Also sent as X-Request-ID. Quote it in bug reports. title: Request Id type: string details: anyOf: - items: $ref: '#/components/schemas/ErrorDetail' type: array - type: 'null' default: null description: On validation errors, one entry for each field that failed. title: Details required: - code - message - retryable - request_id title: ErrorBody type: object ErrorDetail: properties: path: description: Where the problem is, such as ["body", "decisions", 0, "outcomes"]. items: anyOf: - type: string - type: integer title: Path type: array message: title: Message type: string type: anyOf: - type: string - type: 'null' default: null title: Type required: - path - message title: ErrorDetail type: object securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: onehot_sk_... description: Create an API key in the console. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.