> ## 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. # Reserve a presigned upload slot > Reserve an upload slot and return a presigned Supabase Storage URL. The caller PUTs the file bytes directly to ``upload_url`` — the API never sees the bytes. Supabase enforces the signed-URL TTL (currently 2 hours) on its side; after that the caller must request a new slot. The catalogue row returned here lives for 7 days if no job references this ``upload_id``; once referenced, retention tracks the job. **Validation.** ``content_type`` must be one of ``chemical/x-pdb``, ``text/plain``, or ``application/octet-stream``. ``size_bytes`` is capped at 50 MB. Violations return ``400 invalid_request``. **Plan gate.** None. Uploads are free; paywalls live at downstream submit endpoints (e.g. complex prediction requires the Complex plan). Cost: **write** — burns rate + quota. Does not debit credits. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/uploads 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/uploads: post: tags: - uploads summary: Reserve a presigned upload slot description: |- Reserve an upload slot and return a presigned Supabase Storage URL. The caller PUTs the file bytes directly to ``upload_url`` — the API never sees the bytes. Supabase enforces the signed-URL TTL (currently 2 hours) on its side; after that the caller must request a new slot. The catalogue row returned here lives for 7 days if no job references this ``upload_id``; once referenced, retention tracks the job. **Validation.** ``content_type`` must be one of ``chemical/x-pdb``, ``text/plain``, or ``application/octet-stream``. ``size_bytes`` is capped at 50 MB. Violations return ``400 invalid_request``. **Plan gate.** None. Uploads are free; paywalls live at downstream submit endpoints (e.g. complex prediction requires the Complex plan). Cost: **write** — burns rate + quota. Does not debit credits. operationId: create_upload_v1_uploads_post requestBody: content: application/json: schema: $ref: '#/components/schemas/UploadCreate' required: true responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Upload' '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' '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: UploadCreate: properties: filename: type: string maxLength: 255 minLength: 1 title: Filename description: >- Original filename — used for logging and the ``Content-Disposition`` header when the file is re-served. Not used to pick a storage path; paths are opaque UUIDs. examples: - antigen.pdb content_type: type: string title: Content Type description: >- MIME type of the bytes the client will PUT. One of ``chemical/x-pdb``, ``text/plain``, or ``application/octet-stream``. examples: - chemical/x-pdb size_bytes: type: integer maximum: 52428800 exclusiveMinimum: 0 title: Size Bytes description: >- Byte count the client will upload. Must be positive and at most 50 MB. Larger payloads are rejected ``400``. examples: - 12345 type: object required: - filename - content_type - size_bytes title: UploadCreate description: Body for ``POST /v1/uploads``. example: content_type: chemical/x-pdb filename: antigen.pdb size_bytes: 12345 Upload: properties: id: type: string title: Id description: >- Opaque upload identifier (UUID). Pass this to downstream submit endpoints. examples: - dddd4444-eeee-5555-ffff-666677778888 object: type: string const: upload title: Object description: Polymorphic discriminator. Always ``upload``. default: upload filename: type: string title: Filename description: Echo of the caller's filename. content_type: type: string title: Content Type description: Echo of the caller's declared content type. size_bytes: type: integer title: Size Bytes description: Echo of the caller's declared byte count. upload_url: type: string title: Upload Url description: >- Presigned Supabase Storage URL. PUT the file bytes to this URL within the TTL. Include the ``token`` field as an ``Authorization: Bearer`` header if your HTTP client can't follow the query-string auth baked into the URL. examples: - >- https://.supabase.co/storage/v1/object/upload/sign/api-uploads/... token: type: string title: Token description: >- Bearer token matching ``upload_url``. Only needed by clients that issue the PUT without preserving the URL's query string. storage_path: type: string title: Storage Path description: >- Object path within the ``api-uploads`` bucket. Stable for the lifetime of this upload; use it if you later need to fetch the bytes server-side. examples: - >- aaaa1111-2222-3333-4444-555566667777/dddd4444-eeee-5555-ffff-666677778888/antigen.pdb created_at: type: string title: Created At description: ISO-8601 timestamp (UTC) when the upload slot was reserved. expires_at: type: string title: Expires At description: >- ISO-8601 timestamp (UTC) when the unreferenced upload is eligible for deletion (7 days after creation). Once the upload is referenced by a submitted job, it's retained for the job's lifetime. type: object required: - id - filename - content_type - size_bytes - upload_url - token - storage_path - created_at - expires_at title: Upload description: Catalogue entry + presigned URL for one client upload. example: content_type: chemical/x-pdb created_at: '2026-04-23T14:15:00+00:00' expires_at: '2026-04-30T14:15:00+00:00' filename: antigen.pdb id: dddd4444-eeee-5555-ffff-666677778888 object: upload size_bytes: 12345 storage_path: >- aaaa1111-2222-3333-4444-555566667777/dddd4444-eeee-5555-ffff-666677778888/antigen.pdb token: eyJhbGciOi... upload_url: >- https://.supabase.co/storage/v1/object/upload/sign/api-uploads/... 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 securitySchemes: HTTPBearer: type: http scheme: bearer ````