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

# Create Variant



## OpenAPI

````yaml /api-reference/openapi.json post /variants
openapi: 3.1.0
info:
  title: Kallima API
  description: >-
    Antibody design API — humanization, structure, stability, immunogenicity,
    complex prediction, and codon optimization.
  version: 0.1.0
servers: []
security: []
tags:
  - name: identity
    description: >-
      Caller identity and credit balance — use ``GET /v1/me`` to inspect the
      resolved org, plan, and compute budget before submitting jobs.
  - name: projects
    description: >-
      Projects — top-level containers for source antibodies and therapeutic
      candidates.
  - name: source-antibodies
    description: Source (parental) antibody sequences registered under a project.
  - name: variants
    description: >-
      Variants descended from a therapeutic candidate — the unit of work for
      pipelines.
  - name: jobs
    description: >-
      Long-running pipeline jobs: humanization, structure, stability,
      immunogenicity. Submit and poll. Deprecated in favor of
      resource-per-job-type endpoints (``humanizations`` and the other Phase 3
      resources); scheduled for removal in ``/v2``.
  - name: humanizations
    description: >-
      Humanization pipeline runs — typed submit body and typed per-strategy
      results. First of the Phase 3 resource-per-job-type endpoints; the generic
      ``/v1/jobs`` shape is deprecated in favor of this.
  - name: structure-predictions
    description: >-
      ImmuneBuilder structure predictions — typed submit body and typed PDB /
      pLDDT / CDR results. Phase 3 resource-per-job-type endpoint.
  - name: stability-analyses
    description: >-
      Stability analyses — typed submit body and typed thermostability /
      aggregation / developability scorecard. Phase 3 resource-per-job-type
      endpoint.
  - name: immunogenicity-analyses
    description: >-
      Immunogenicity analyses — typed submit body and typed MHC-I / MHC-II /
      B-cell epitope + risk-score results. Phase 3 resource-per-job-type
      endpoint.
  - name: uploads
    description: >-
      Presigned Supabase Storage slots for caller-supplied files (e.g. antigen
      PDBs for complex prediction). The API never proxies bytes — clients PUT
      directly to the returned URL.
  - name: antigens
    description: >-
      Target protein sequences scoped to a project — the docking partner in a
      complex prediction. Register once, reference by ``antigen_id`` at submit
      time.
  - name: complex-predictions
    description: >-
      Boltz-2 antibody-antigen complex predictions — typed submit body and typed
      docked-PDB / iptm / interface-residues results. Phase 3
      resource-per-job-type endpoint. Complex runs are long-running (~20–40 min
      on GPU); always poll, never hold the connection.
  - name: therapeutic-candidates
    description: >-
      Therapeutic candidates — the top-of-lineage object under a project.
      Creating one auto-creates a baseline variant (``v1``) and its chain rows
      atomically; pipelines submit against the variant. Junction endpoints
      manage many-to-many links to source antibodies and antigens.
  - name: adc-designs
    description: >-
      ADC (antibody-drug conjugate) designs — catalog records attaching a linker
      + payload + conjugation method to a therapeutic candidate. Run the
      rule-based developability analysis via ``POST
      /v1/adc-designs/{id}/analysis``; pass ``structure_job_id`` to include
      SASA-based conjugation-site accessibility.
  - name: codon-exports
    description: >-
      Codon optimization exports — submit a batch of jobs (one per variant),
      poll until ``variable_cds`` is populated, then download the assembled CDS
      as FASTA, CSV, or GenBank+ZIP. Requires the Structure plan or above.
  - name: webhooks
    description: >-
      Webhook endpoint registration — register HTTPS URLs to receive signed
      event deliveries when jobs complete or fail. Signing uses HMAC-SHA256; see
      ``POST /v1/webhooks`` for verification details.
  - name: webhook-deliveries
    description: >-
      Webhook delivery log — inspect past delivery attempts and manually retry
      failed ones via ``POST /v1/webhook_deliveries/{id}/retry``.
paths:
  /variants:
    post:
      tags:
        - variants
      summary: Create Variant
      operationId: create_variant_variants_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VariantCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VariantWithChains'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
        - HTTPBearer: []
components:
  schemas:
    VariantCreate:
      properties:
        candidate_id:
          type: string
          format: uuid
          title: Candidate Id
        name:
          type: string
          maxLength: 120
          minLength: 1
          title: Name
        parent_variant_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Parent Variant Id
        notes:
          anyOf:
            - type: string
            - type: 'null'
          title: Notes
        chains:
          items:
            $ref: '#/components/schemas/VariantChainSpec'
          type: array
          minItems: 1
          title: Chains
          description: At least one chain must be specified.
      type: object
      required:
        - candidate_id
        - name
        - chains
      title: VariantCreate
      description: Payload to create a new variant under a therapeutic candidate.
    VariantWithChains:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        candidate_id:
          type: string
          format: uuid
          title: Candidate Id
        name:
          type: string
          title: Name
        parent_variant_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Parent Variant Id
        parent_job_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Parent Job Id
        is_baseline:
          type: boolean
          title: Is Baseline
        notes:
          anyOf:
            - type: string
            - type: 'null'
          title: Notes
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        chains:
          items:
            $ref: '#/components/schemas/VariantChain'
          type: array
          title: Chains
      type: object
      required:
        - id
        - candidate_id
        - name
        - parent_variant_id
        - parent_job_id
        - is_baseline
        - notes
        - created_at
        - updated_at
      title: VariantWithChains
      description: A variant together with its chain rows.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    VariantChainSpec:
      properties:
        chain_id:
          type: string
          maxLength: 8
          minLength: 1
          title: Chain Id
          description: 'Short label: H, L, H1, H2, L1, L2, scFv, etc.'
        role:
          type: string
          enum:
            - heavy
            - light
            - vhh
            - scfv
            - fc_only
            - peptide_linker
            - targeting_domain
          title: Role
        variable_sequence:
          anyOf:
            - type: string
            - type: 'null'
          title: Variable Sequence
        constant_region_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Constant Region Id
        source_antibody_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Source Antibody Id
      type: object
      required:
        - chain_id
        - role
      title: VariantChainSpec
      description: >-
        Specification for one chain within a variant.


        variable_sequence is required for roles that carry a sequence (heavy,
        light,

        vhh, scfv, fc_only, targeting_domain). peptide_linker rows may omit it.
    VariantChain:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        variant_id:
          type: string
          format: uuid
          title: Variant Id
        chain_id:
          type: string
          title: Chain Id
        role:
          type: string
          enum:
            - heavy
            - light
            - vhh
            - scfv
            - fc_only
            - peptide_linker
            - targeting_domain
          title: Role
        variable_sequence:
          anyOf:
            - type: string
            - type: 'null'
          title: Variable Sequence
        constant_region_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Constant Region Id
        source_antibody_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Source Antibody Id
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
        - id
        - variant_id
        - chain_id
        - role
        - variable_sequence
        - constant_region_id
        - source_antibody_id
        - created_at
      title: VariantChain
      description: A variant chain row as returned by the API.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````