Types

Pydantic data models returned by SDK methods. Treat them as read-only — they carry data, not behaviour.

File

The record returned by client.files.upload. Represents an uploaded artifact on the backend; pass it into job-creation methods rather than re-uploading.

class File:
    file_id: str
    filename: str
    size: int                    # bytes
    content_type: str
    created_at: datetime
    job_id: str | None
    is_input: bool

ConvertJob

The lifecycle handle for a turbo-lane conversion job. Returned by client.convert.create / create_and_wait.

class ConvertJob:
    job_id: str
    status: Literal["queued", "processing", "completed", "failed"]
    processor_type: str
    progress: float | None       # 0.0–1.0 when reported
    result_files: list[ResultFile]
    error: JobError | None
    created_at: datetime
    updated_at: datetime

Convention follows OpenAI / Stripe: the model carries data only; behaviour lives in the resource class. Use methods on client.convert to act on a ConvertJob (poll, download, etc.).

ResultFile

A single output file produced by a completed job.

class ResultFile:
    filename: str
    size: int
    mimetype: str
    url: str                     # presigned download URL

JobError

Structured error envelope attached to a failed job. Mirrors the wire format.

class JobError:
    code: str
    message: str

GoalJob

Lifecycle handle for a goal-lane (multi-step workflow) job.

class GoalJob:
    job_spec_id: str
    status: Literal["queued", "running", "slots_pending", "completed", "failed"]
    workflow_id: str
    progress: float | None
    result_files: list[ResultFile]
    pending_slots: list[PendingSlot]
    created_at: datetime
    updated_at: datetime

GoalEvent

A single event from a goal-lane event stream (received via the WebSocket transport when calling client.goals.listen_events).

class GoalEvent:
    type: Literal["progress", "slot_pending", "completed", "failed"]
    timestamp: datetime
    data: dict[str, Any]

PendingSlot

A human-in-the-loop interrupt point on a goal-lane job. When a workflow reaches a slot, it pauses and surfaces the question through pending_slots on the GoalJob.

class PendingSlot:
    slot_id: str
    slot_type: str
    question: str
    options: list[str] | None    # null when free-text
    required: bool

Resolve a slot by calling client.goals.fill_slot(slot_id, value).

Type usage notes

• All models are Pydantic — .model_dump() gives a JSON-safe dict, .model_dump_json() gives a string.
• Fields typed as datetime are timezone-aware (UTC) and serialize as ISO 8601.
• The SDK does not mutate returned models. If you need to retain a snapshot, store the model itself (not a derived dict).