---
title: "POST /v1/jobs"
method: POST
path: "/v1/jobs"
tags: ["Conversion"]
---

# POST /v1/jobs

`POST /v1/jobs`

## Request

- Base URL: `https://markovo.net`
- URL: `https://markovo.net/v1/jobs`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-markovo-job-token`

## Request body

- union
  - object
    - `upload_id` string, required
    - `max_credit_units` integer, required
    - `max_credits` union
      - number
      - string
    - `client_request_id` string: Optional idempotency key for this confirmation. Resending the same key replays the already-created job instead of queueing a duplicate; released when the job is deleted.
    - `webhook_url` string, uri: Optional HTTPS endpoint that receives a signed POST when the job reaches a terminal state (job.succeeded, job.failed, job.cancelled, job.timed_out). Must use port 443 or the default, no userinfo, and no IP-literal host; invalid values return invalid_webhook_url. Deliveries carry a Markovo-Signature HMAC header verifiable with the organization's whsec_ secret from Account → API settings (GET/POST /v1/account/webhook-secret).
  - object
    - `upload_id` string, required
    - `max_credit_units` integer
    - `max_credits` union, required
      - number
      - string
    - `client_request_id` string: Optional idempotency key for this confirmation. Resending the same key replays the already-created job instead of queueing a duplicate; released when the job is deleted.
    - `webhook_url` string, uri: Optional HTTPS endpoint that receives a signed POST when the job reaches a terminal state (job.succeeded, job.failed, job.cancelled, job.timed_out). Must use port 443 or the default, no userinfo, and no IP-literal host; invalid values return invalid_webhook_url. Deliveries carry a Markovo-Signature HMAC header verifiable with the organization's whsec_ secret from Account → API settings (GET/POST /v1/account/webhook-secret).

## Response `200`

Idempotent replay of an already confirmed job

- ConfirmedJob
  - `job_id` string, required
  - `status` 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled' | 'timed_out', required
  - `capability_id` string, required
  - `estimated_credits` number, required
  - `credit_scale` unknown, required
  - `credit_model_version` string, required
  - `rate_card_version` string, required
  - `estimated_credit_units` integer, required
  - `job_token` string: Returned only for an anonymous guest job.

## Other responses

- `201`: New job queued
- `402`: Machine-readable safe error
- `409`: Machine-readable safe error
- `503`: Machine-readable safe error

---

[API](https://skmtc.dev/markovo/apis/markovo-conversion-api.md) · [All operations](https://skmtc.dev/markovo/apis/markovo-conversion-api/llms.txt) · [OpenAPI document](https://skmtc.dev/markovo/apis/markovo-conversion-api/revisions/e080e7b85e2e?raw)