> ## Documentation Index > Fetch the complete documentation index at: https://docs.anythingmd.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a conversion job > Starts an asynchronous conversion. Credits for the estimated pages are reserved now and settled on the pages actually converted. Send an Idempotency-Key so a retry returns the same job instead of starting a second one. Returns 402 when the workspace does not have enough credits, and 413 when the document is over the page limit. ## OpenAPI ````yaml /openapi.json post /api/v1/jobs openapi: 3.1.0 info: title: AnythingMD API version: 1.0.0-preview description: >- Convert PDFs, Office documents, spreadsheets and images into Markdown. Guides, pricing and limits: https://docs.anythingmd.com. Preview: available to workspaces that have purchased credits. servers: - url: https://anythingmd.com description: Production security: - BearerAuth: [] tags: - name: Uploads description: Stage a source document for conversion - name: Jobs description: Create and observe async conversion work - name: Artifacts description: Retrieve job outputs - name: Quotes description: See what a conversion would cost before starting it. - name: Receipts description: What a job was charged. Receipts outlive the job. paths: /api/v1/jobs: post: tags: - Jobs summary: Create a conversion job description: >- Starts an asynchronous conversion. Credits for the estimated pages are reserved now and settled on the pages actually converted. Send an Idempotency-Key so a retry returns the same job instead of starting a second one. Returns 402 when the workspace does not have enough credits, and 413 when the document is over the page limit. operationId: createJob parameters: - name: Idempotency-Key in: header required: false schema: type: string minLength: 1 description: >- If reused within the retention window, replay the original result instead of a second mutation requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateJobRequest' responses: '200': description: Existing job returned for a replayed idempotency key content: application/json: schema: $ref: '#/components/schemas/CreateJobResponse' '201': description: Job accepted content: application/json: schema: $ref: '#/components/schemas/CreateJobResponse' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/ApiError' '401': description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/ApiError' '402': description: >- Payment required. Body carries topUpPath and optional requiredCredits/availableCredits. Quote is omitted unless a saved quote is attached; Job stays amount-free. content: application/json: schema: $ref: '#/components/schemas/PaymentRequiredError' '403': description: >- Authenticated, but the credential lacks the scope this operation requires (code: insufficient_scope). Reads need documents:read, uploads and job creation need documents:write, cancel needs documents:delete. Checked before the resource is looked up, so this never reveals whether the resource exists. content: application/json: schema: $ref: '#/components/schemas/ApiError' '404': description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ApiError' '413': description: >- The document's estimated pages exceed the per-conversion ceiling (code: document_too_large; default 1000 pages). Refused before any credits are reserved; the job is kept as failed. content: application/json: schema: $ref: '#/components/schemas/DocumentTooLargeError' security: - BearerAuth: [] components: schemas: CreateJobRequest: type: object properties: operation: default: convert description: Work to perform type: string enum: - convert capabilityVersion: default: '1' description: Capability version to invoke; defaults to 1 type: string minLength: 1 source: oneOf: - type: object properties: type: type: string const: document documentId: type: string minLength: 1 description: Id of an uploaded source document required: - type - documentId additionalProperties: false - type: object properties: type: type: string const: external fileUrl: type: string minLength: 1 description: Caller-supplied URL for the server to fetch fileName: description: Original file name; defaults to "document" if omitted type: string required: - type - fileUrl additionalProperties: false description: Where the input document comes from includeImages: default: false description: >- If true, save image artifacts with download URLs; if false, skip image bodies type: boolean force_refresh: description: If true, bypass document cache and perform a full conversion type: boolean forceRefresh: description: Alias for force_refresh type: boolean allowPartial: description: >- If true and the workspace cannot pay for the whole document, convert as many pages as its credits cover instead of returning 402. The job reports partial: true and nextStartPage. type: boolean startPage: description: >- First page to convert (1-based). Use nextStartPage from a partial job to convert the rest. type: integer minimum: 1 maximum: 100000 content_hash: description: Optional SHA-256 payload checksum (e.g. sha256:) type: string minLength: 1 contentHash: description: Alias for content_hash type: string minLength: 1 idempotencyKey: description: >- If the same key is reused within the idempotency window, return the original job instead of creating a duplicate type: string minLength: 1 webhookUrl: description: >- Optional callback URL when the job reaches a terminal status (future; polling remains required) type: string format: uri required: - operation - capabilityVersion - source - includeImages additionalProperties: false CreateJobResponse: type: object properties: id: type: string minLength: 1 description: Id of an async job operation: type: string enum: - convert capabilityVersion: type: string minLength: 1 description: >- Pinned version of this capability. Quotes, receipts, rate cards, and Skills key off operation + version. status: type: string enum: - queued - running - input_required - succeeded - failed - canceled - expired source: oneOf: - type: object properties: type: type: string const: document documentId: type: string minLength: 1 description: Id of an uploaded source document required: - type - documentId additionalProperties: false - type: object properties: type: type: string const: external fileUrl: type: string minLength: 1 description: Caller-supplied URL for the server to fetch fileName: description: Original file name; defaults to "document" if omitted type: string required: - type - fileUrl additionalProperties: false fileSource: type: string enum: - managed - external includeImages: type: boolean cached: description: True when results were returned from content-hash cache type: boolean pageRange: description: Pages this job converted (1-based, inclusive), when known type: object properties: start: type: integer minimum: 1 maximum: 9007199254740991 end: type: integer minimum: 1 maximum: 9007199254740991 required: - start - end additionalProperties: false partial: description: >- True when the job stopped at the pages its credits covered; convert the rest with startPage = nextStartPage type: boolean nextStartPage: description: 'Present on partial jobs: the first page not yet converted' type: integer minimum: 2 maximum: 9007199254740991 estimatedTotalPages: description: >- Page count read from the file before converting, when it could be read type: integer minimum: -9007199254740991 maximum: 9007199254740991 createdAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ description: ISO-8601 creation time updatedAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ description: ISO-8601 last status change startedAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ finishedAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ error: description: Present when status is failed type: string errorCode: description: >- Stable machine code when status is failed. `stranded_running` means the worker or client disappeared; it is not a conversion failure. type: string idempotencyKey: type: string usage: description: Natural usage units for this job; never credits or currency type: object properties: inputBytes: description: Source document size in bytes type: integer minimum: 0 maximum: 9007199254740991 discoveredPages: description: Pages detected in the source type: integer minimum: 0 maximum: 9007199254740991 ocrPages: description: Pages that required OCR type: integer minimum: 0 maximum: 9007199254740991 outputBytes: description: Produced artifact bytes type: integer minimum: 0 maximum: 9007199254740991 durationMs: description: Wall-clock processing time in milliseconds type: integer minimum: 0 maximum: 9007199254740991 additionalProperties: false stage: description: Fine-grained phase within the current status type: string enum: - preparing - converting - finalizing - complete - error stageProgress: description: 0–100 progress within the current stage type: number minimum: 0 maximum: 100 message: description: Human-readable status for display type: string required: - id - operation - capabilityVersion - status - source - createdAt - updatedAt additionalProperties: false ApiError: type: object properties: error: type: string description: User-facing error message code: description: Optional machine-readable error code (e.g. invalid_request) type: string required: - error additionalProperties: false PaymentRequiredError: type: object properties: error: type: string description: User-facing error message code: description: Optional machine-readable error code (e.g. invalid_request) type: string quote: description: Quote that must be funded before the mutation can proceed type: object properties: id: type: string minLength: 1 description: Quote id operation: type: string enum: - convert capabilityVersion: type: string minLength: 1 description: >- Pinned version of this capability. Quotes, receipts, rate cards, and Skills key off operation + version. estimatedUsage: type: object properties: inputBytes: description: Source document size in bytes type: integer minimum: 0 maximum: 9007199254740991 discoveredPages: description: Pages detected in the source type: integer minimum: 0 maximum: 9007199254740991 ocrPages: description: Pages that required OCR type: integer minimum: 0 maximum: 9007199254740991 outputBytes: description: Produced artifact bytes type: integer minimum: 0 maximum: 9007199254740991 durationMs: description: Wall-clock processing time in milliseconds type: integer minimum: 0 maximum: 9007199254740991 additionalProperties: false description: Estimated natural units; not a bill estimatedCredits: type: number minimum: 0 description: Expected credits if work matches the estimate maximumCredits: type: number minimum: 0 description: >- Credits that will be reserved when the job starts; the workspace needs at least this many priceVersion: type: string minLength: 1 description: Rate-card version this quote is pinned to expiresAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ description: ISO-8601 quote expiration createdAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ required: - id - operation - capabilityVersion - estimatedUsage - estimatedCredits - maximumCredits - priceVersion - expiresAt - createdAt additionalProperties: false topUpPath: description: >- Control-plane path or URL where the payer can add funds (not an amount) type: string requiredCredits: description: >- Credits needed to start this operation (reserved, not the final charge) type: number minimum: 0 availableCredits: description: Credits currently available to this account type: number minimum: 0 required: - error additionalProperties: false DocumentTooLargeError: type: object properties: error: type: string description: User-facing error message code: type: string const: document_too_large maxPages: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 description: Page ceiling per conversion estimatedPages: description: Pages estimated from the file before converting type: integer exclusiveMinimum: 0 maximum: 9007199254740991 jobId: description: The refused job, kept as failed with errorCode document_too_large type: string required: - error - code - maxPages additionalProperties: false securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: API key description: >- Create a key under Settings → API Keys and send it as `Authorization: Bearer amd_live_…`. See https://docs.anythingmd.com/authentication. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.