Skip to main content
POST
/
v1
/
humanizations
Submit a humanization job
curl --request POST \
  --url https://api.example.com/v1/humanizations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "variant_id": "11112222-3333-4444-5555-666677778888"
}
'
{
  "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"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Body for POST /v1/humanizations.

​
variant_id
string
required

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.

Example:

"11112222-3333-4444-5555-666677778888"

Response

Successful Response

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.

​
id
string
required

Opaque humanization identifier (UUID).

Example:

"dddd1111-eeee-2222-ffff-333344445555"

​
status
enum<string>
required

Lifecycle state. pending → running → completed | failed. canceled is terminal and only reachable via POST /v1/humanizations/{id}/cancel on a still-pending job.

Available options:
pending,
running,
completed,
failed,
canceled
Example:

"pending"

​
created_at
string
required

ISO-8601 timestamp (UTC) when the job was submitted.

Example:

"2026-04-22T14:15:00+00:00"

​
credit_cost
integer
required

Credits debited at submission for this job type.

Example:

1

​
inputs
HumanizationInputs · object
required

Echo of the caller's submit body — useful for clients that don't cache.

​
object
string
default:humanization

Polymorphic discriminator. Always humanization on this endpoint.

Allowed value: "humanization"
​
started_at
string | null

ISO-8601 timestamp when execution started. null while pending.

​
completed_at
string | null

ISO-8601 timestamp when the job completed successfully. null otherwise.

​
failed_at
string | null

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
string | null

ISO-8601 timestamp when the job was canceled via POST /v1/humanizations/{id}/cancel. null unless status=canceled.

​
error
HumanizationError · object

Populated only when status=failed. Same shape as problem+json.

​
results
HumanizationResultEntry · object[] | null

Per-strategy humanization outputs. null until status=completed; empty list is valid if the pipeline produced no viable strategies.