> ## 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. # Batch-submit humanization jobs > Submit up to 50 humanization jobs in a single call. Always returns ``202 Accepted``; poll each job via ``GET /v1/humanizations/{id}``. ``Prefer: wait`` is not supported on the batch endpoint — synchronous execution of 50 jobs would exceed the request timeout. **Pre-flight credit check.** The endpoint checks that the org balance covers ``len(items) × credit_cost`` before submitting any jobs. This is a best-effort guard with a TOCTOU window — if credits are consumed between the check and the loop, individual ``submit_job`` calls will raise ``402`` and the batch stops. Jobs already submitted in that run stay ``pending`` and are charged normally. Cost: **write** — burns rate + quota, and debits 1 credit per item. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/humanizations/batch 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: /v1/humanizations/batch: post: tags: - humanizations summary: Batch-submit humanization jobs description: |- Submit up to 50 humanization jobs in a single call. Always returns ``202 Accepted``; poll each job via ``GET /v1/humanizations/{id}``. ``Prefer: wait`` is not supported on the batch endpoint — synchronous execution of 50 jobs would exceed the request timeout. **Pre-flight credit check.** The endpoint checks that the org balance covers ``len(items) × credit_cost`` before submitting any jobs. This is a best-effort guard with a TOCTOU window — if credits are consumed between the check and the loop, individual ``submit_job`` calls will raise ``402`` and the batch stops. Jobs already submitted in that run stay ``pending`` and are charged normally. Cost: **write** — burns rate + quota, and debits 1 credit per item. operationId: batch_submit_humanizations_v1_humanizations_batch_post requestBody: content: application/json: schema: $ref: '#/components/schemas/BatchHumanizationSubmit' required: true responses: '202': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/BatchHumanizationResponse' '400': description: Malformed request body or parameter. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' '401': description: Missing or invalid API token. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' '402': description: >- Payment required — insufficient credits or the caller's plan is below the required tier. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' '404': description: Resource does not exist in the caller's organization. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' '422': description: Request failed validation. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' '429': description: >- Rate limit or monthly write quota exceeded. `Retry-After` holds the number of seconds until the next admitted request. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' headers: Retry-After: description: Seconds until the caller may retry. Present on 429 responses. schema: type: integer minimum: 1 X-RateLimit-Limit: description: Per-minute rate ceiling for this API token's plan. schema: type: integer X-RateLimit-Remaining: description: Requests remaining in the current rate window. schema: type: integer X-RateLimit-Reset: description: HTTP-date when the rate window resets. schema: type: string format: http-date X-Quota-Limit: description: Monthly write ceiling for this API token's plan. schema: type: integer X-Quota-Remaining: description: Writes remaining in the current monthly window. schema: type: integer X-Quota-Reset: description: >- HTTP-date when the monthly write quota resets (always the 1st of next month UTC). schema: type: string format: http-date security: - HTTPBearer: [] components: schemas: BatchHumanizationSubmit: properties: items: items: $ref: '#/components/schemas/HumanizationSubmit' type: array maxItems: 50 minItems: 1 title: Items description: One to 50 humanization submit payloads. type: object required: - items title: BatchHumanizationSubmit description: Body for ``POST /v1/humanizations/batch``. BatchHumanizationResponse: properties: items: items: $ref: '#/components/schemas/Humanization' type: array title: Items type: object required: - items title: BatchHumanizationResponse description: Response for ``POST /v1/humanizations/batch``. ProblemDetails: additionalProperties: true description: RFC 9457 problem+json body returned by every non-2xx response. example: code: insufficient_credits credit_balance: 0 credit_cost: 1 detail: Humanization costs 1 credit; balance is 0. instance: /v1/jobs request_id: req_01JBX6Y6ZK6N8Q7YJ0F5VX2C3D status: 402 title: Insufficient credits type: https://docs.kallima.bio/errors/insufficient_credits properties: type: description: >- Stable URI identifying the error class. Dereferenceable at docs.kallima.bio/errors/{code}. examples: - https://docs.kallima.bio/errors/insufficient_credits title: Type type: string title: description: Short human-readable summary of the error class. examples: - Insufficient credits title: Title type: string status: description: HTTP status code. Matches the response status line. examples: - 402 title: Status type: integer detail: description: Human-readable explanation with values substituted. examples: - Humanization costs 1 credit; balance is 0. title: Detail type: string instance: description: The specific request URI that failed. examples: - /v1/jobs title: Instance type: string code: description: >- Machine-readable short code. SDKs switch on this, not on `title`. See app.errors.ErrorCode for the full taxonomy. examples: - insufficient_credits title: Code type: string request_id: anyOf: - type: string - type: 'null' default: null description: ULID stamped on every request. Include when contacting support. examples: - req_01JBX6Y6ZK6N8Q7YJ0F5VX2C3D title: Request Id required: - type - title - status - detail - instance - code title: ProblemDetails type: object HumanizationSubmit: properties: variant_id: type: string title: Variant Id description: >- UUID of the variant to humanize. Must belong to the caller's org. Strategy selection is not yet settable via the API — the pipeline runs all configured strategies on every submit. examples: - 11112222-3333-4444-5555-666677778888 type: object required: - variant_id title: HumanizationSubmit description: Body for ``POST /v1/humanizations``. example: variant_id: 11112222-3333-4444-5555-666677778888 Humanization: properties: id: type: string title: Id description: Opaque humanization identifier (UUID). examples: - dddd1111-eeee-2222-ffff-333344445555 object: type: string const: humanization title: Object description: Polymorphic discriminator. Always ``humanization`` on this endpoint. default: humanization status: type: string enum: - pending - running - completed - failed - canceled title: Status description: >- Lifecycle state. ``pending`` → ``running`` → ``completed`` | ``failed``. ``canceled`` is terminal and only reachable via ``POST /v1/humanizations/{id}/cancel`` on a still-pending job. examples: - pending created_at: type: string title: Created At description: ISO-8601 timestamp (UTC) when the job was submitted. examples: - '2026-04-22T14:15:00+00:00' started_at: anyOf: - type: string - type: 'null' title: Started At description: ISO-8601 timestamp when execution started. ``null`` while pending. completed_at: anyOf: - type: string - type: 'null' title: Completed At description: >- ISO-8601 timestamp when the job completed successfully. ``null`` otherwise. failed_at: anyOf: - type: string - type: 'null' title: Failed At description: >- ISO-8601 timestamp when the job failed. ``null`` unless ``status=failed``. Synthesized from the underlying job's terminal timestamp — the DB does not carry a separate ``failed_at`` column. canceled_at: anyOf: - type: string - type: 'null' title: Canceled At description: >- ISO-8601 timestamp when the job was canceled via ``POST /v1/humanizations/{id}/cancel``. ``null`` unless ``status=canceled``. error: anyOf: - $ref: '#/components/schemas/HumanizationError' - type: 'null' description: Populated only when ``status=failed``. Same shape as problem+json. credit_cost: type: integer title: Credit Cost description: Credits debited at submission for this job type. examples: - 1 inputs: $ref: '#/components/schemas/HumanizationInputs' description: >- Echo of the caller's submit body — useful for clients that don't cache. results: anyOf: - items: $ref: '#/components/schemas/HumanizationResultEntry' type: array - type: 'null' title: Results description: >- Per-strategy humanization outputs. ``null`` until ``status=completed``; empty list is valid if the pipeline produced no viable strategies. type: object required: - id - status - created_at - credit_cost - inputs title: Humanization description: |- Humanization job envelope — pipeline status + typed results. Field layout matches the shared spec in ``docs/strategy/api-plan.md`` so the next 5 resource-per-job-type endpoints can ship identical envelopes and the Python SDK can define one ``Job`` base class. example: completed_at: '2026-04-22T14:15:28+00:00' created_at: '2026-04-22T14:15:00+00:00' credit_cost: 1 id: dddd1111-eeee-2222-ffff-333344445555 inputs: variant_id: 11112222-3333-4444-5555-666677778888 object: humanization results: - humanized_vh: EVQLVESGGGLVQPGGSLRLSCAAS... humanized_vl: DIQMTQSPSSLSASVGDRVTITCRASQ... liabilities: glycosylation: [] oxidation: - H100 mutations: vh: 12 vl: 8 oasis_score: mean: 0.91 median: 0.93 strategy: cdr_grafting started_at: '2026-04-22T14:15:02+00:00' status: completed HumanizationError: properties: type: type: string title: Type description: Stable URI identifying the error class. examples: - https://docs.kallima.bio/errors/job_failed title: type: string title: Title description: Short human summary. examples: - Job failed status: type: integer title: Status description: HTTP-like status code. examples: - 500 detail: type: string title: Detail description: Human-readable failure reason, from the executor. examples: - 'SequenceValidationError: VH must start with Q or E' code: type: string title: Code description: Machine-readable code. SDKs switch on this. examples: - job_failed type: object required: - type - title - status - detail - code title: HumanizationError description: |- Problem-details-shaped error surfaced on a failed humanization. Same field set as a top-level problem+json response so SDKs can reuse a single ``ProblemDetails`` type for both transport-level errors and job-level failures. ``code`` is ``job_failed`` today; a finer taxonomy (``sequence_invalid``, ``executor_timeout``, …) lands with the error- taxonomy PR in a later phase. HumanizationInputs: properties: variant_id: type: string title: Variant Id description: Variant the humanization ran against. examples: - 11112222-3333-4444-5555-666677778888 type: object required: - variant_id title: HumanizationInputs description: What the caller submitted when creating this humanization. HumanizationResultEntry: properties: strategy: type: string title: Strategy description: >- Humanization strategy that produced this row. One of ``cdr_grafting``, ``resurfacing``, ``sdr_grafting``, or ``germline``. examples: - cdr_grafting humanized_vh: type: string title: Humanized Vh description: Humanized heavy-chain variable region amino-acid sequence. examples: - EVQLVESGGGLVQPGGSLRLSCAAS... humanized_vl: anyOf: - type: string - type: 'null' title: Humanized Vl description: Humanized light-chain variable region. ``null`` for nanobodies. examples: - DIQMTQSPSSLSASVGDRVTITCRASQ... oasis_score: anyOf: - additionalProperties: true type: object - type: 'null' title: Oasis Score description: >- OASis humanness score summary (``mean``, ``median``, per-chain breakdown). examples: - mean: 0.91 median: 0.93 mutations: anyOf: - additionalProperties: true type: object - type: 'null' title: Mutations description: Mutation counts + positions relative to the parent variant. examples: - vh: 12 vl: 8 liabilities: anyOf: - additionalProperties: true type: object - type: 'null' title: Liabilities description: Detected liability motifs (aggregation, deamidation, oxidation, …). examples: - glycosylation: [] oxidation: - H100 numbering: anyOf: - additionalProperties: true type: object - type: 'null' title: Numbering description: >- Per-residue Kabat / IMGT numbering tables. Present when the pipeline emits them. vhh_analysis: anyOf: - additionalProperties: true type: object - type: 'null' title: Vhh Analysis description: VHH-specific analysis (nanobodies only). scfv_analysis: anyOf: - additionalProperties: true type: object - type: 'null' title: Scfv Analysis description: scFv-specific analysis (scFv molecule type only). fc_analysis: anyOf: - additionalProperties: true type: object - type: 'null' title: Fc Analysis description: Fc-region analysis (when the parent variant includes Fc). type: object required: - strategy - humanized_vh title: HumanizationResultEntry description: One strategy row — a humanized antibody produced by the pipeline. securitySchemes: HTTPBearer: type: http scheme: bearer ````