AyudaAPIReferencia

Referencia de la API

Cada endpoint, parámetro y código de error de la API pública.

Esta referencia se genera directamente desde nuestro documento OpenAPI y se mantiene en inglés.

Toda solicitud parte de https://doctransform.xyz/api/v1.

Lee las respuestas como un lector tolerante: ignora cualquier campo que no reconozcas, ya que añadimos campos sin previo aviso.

La API se versiona una sola vez, en esta URL base. Si alguna vez retiramos un campo o endpoint, seguirá funcionando al menos 12 meses después de marcarlo con las cabeceras Deprecation y Sunset.

Postman → Importar → este archivo: descarga el JSON de OpenAPI de arriba y pásaselo a la importación de OpenAPI 3.1 de Postman.

View live OpenAPI document

GET`/api/v1/runs/{run_id}`

get_run

Get Run

Scope: runs:read

Parameters

run_idpath, required

Responses

200Successful Response

completed_atstring, nullable
created_atstring, required
errorobject, nullable
- codestring, required
- messagestring, required
expires_atstring, nullable
idstring, required
outputobject, nullable
- download_urlstring, required
- mime_typestring, required
- namestring, required
- size_bytesinteger, required
rows_writteninteger, nullable
statusstring, required
The Run record's closed `status` vocabulary -- every writer (`run_admission.admit_run`, this module's own `reap_record`, `run_service.execute_run`) and every reader (the Public API's `RunResponse`, `router.py`'s own status branches) uses these members, never the bare string literals a typo in one call site could drift from the others.
template_idstring, required
truncatedboolean

401API_KEY_MISSING, API_KEY_INVALID

errorstring, required
messagestring, required

API_KEY_MISSINGSend the API Key as an `Authorization: Bearer` header.
API_KEY_INVALIDThe API Key is malformed, unknown, revoked, or its account is inactive.

403INSUFFICIENT_SCOPE, NO_SUBSCRIPTION

errorstring, required
messagestring, required

INSUFFICIENT_SCOPEThe API Key does not carry the scope this operation requires.
NO_SUBSCRIPTIONThis account has no active subscription.

404TEMPLATE_NOT_FOUND, RUN_NOT_FOUND

errorstring, required
messagestring, required

TEMPLATE_NOT_FOUNDNo Template with this id exists for this account.
RUN_NOT_FOUNDNo Run with this id exists for this account. Runs are kept 30 minutes and are lost if the service restarts.

429CONCURRENCY_LIMIT_REACHED, RATE_LIMITED

errorstring, required
messagestring, required

CONCURRENCY_LIMIT_REACHEDThis account already has the maximum number of Runs in flight for its plan.
RATE_LIMITEDThis account has exceeded its request rate limit for this operation.

curl

curl -X GET "https://doctransform.xyz/api/v1/runs/{run_id}" \
  -H "Authorization: Bearer $DOCTRANSFORM_API_KEY"

GET`/api/v1/runs/{run_id}/output`

get_run_output

Get Run Output

Scope: runs:read

Parameters

run_idpath, required

Responses

200Successful Response

401API_KEY_MISSING, API_KEY_INVALID

errorstring, required
messagestring, required

API_KEY_MISSINGSend the API Key as an `Authorization: Bearer` header.
API_KEY_INVALIDThe API Key is malformed, unknown, revoked, or its account is inactive.

403INSUFFICIENT_SCOPE, NO_SUBSCRIPTION

errorstring, required
messagestring, required

INSUFFICIENT_SCOPEThe API Key does not carry the scope this operation requires.
NO_SUBSCRIPTIONThis account has no active subscription.

404TEMPLATE_NOT_FOUND, RUN_NOT_FOUND

errorstring, required
messagestring, required

TEMPLATE_NOT_FOUNDNo Template with this id exists for this account.
RUN_NOT_FOUNDNo Run with this id exists for this account. Runs are kept 30 minutes and are lost if the service restarts.

429CONCURRENCY_LIMIT_REACHED, RATE_LIMITED

errorstring, required
messagestring, required

CONCURRENCY_LIMIT_REACHEDThis account already has the maximum number of Runs in flight for its plan.
RATE_LIMITEDThis account has exceeded its request rate limit for this operation.

curl

curl -X GET "https://doctransform.xyz/api/v1/runs/{run_id}/output" \
  -H "Authorization: Bearer $DOCTRANSFORM_API_KEY"

GET`/api/v1/templates`

list_templates

List Templates

Scope: templates:read

Responses

200Successful Response

dataarray, required
- items[]object
  - descriptionstring, nullable
  - idstring, required
  - namestring, nullable
  - output_formatstring, nullable

401API_KEY_MISSING, API_KEY_INVALID

errorstring, required
messagestring, required

API_KEY_MISSINGSend the API Key as an `Authorization: Bearer` header.
API_KEY_INVALIDThe API Key is malformed, unknown, revoked, or its account is inactive.

403INSUFFICIENT_SCOPE, NO_SUBSCRIPTION

errorstring, required
messagestring, required

INSUFFICIENT_SCOPEThe API Key does not carry the scope this operation requires.
NO_SUBSCRIPTIONThis account has no active subscription.

429CONCURRENCY_LIMIT_REACHED, RATE_LIMITED

errorstring, required
messagestring, required

CONCURRENCY_LIMIT_REACHEDThis account already has the maximum number of Runs in flight for its plan.
RATE_LIMITEDThis account has exceeded its request rate limit for this operation.

curl

curl -X GET "https://doctransform.xyz/api/v1/templates" \
  -H "Authorization: Bearer $DOCTRANSFORM_API_KEY"

POST`/api/v1/templates/{template_id}/runs`

create_run

Create Run

Runs `template_id` on one uploaded file. Answers `201` with a finished Run if it completes within about 30 seconds, else `202` with `Location`/`Retry-After` while it keeps running in the background -- poll `GET /runs/{id}` for its outcome. An optional `Idempotency-Key` header makes a retry of the same request replay the Run it already started or finished, rather than starting (and charging) a second one; the same key with a different request answers `409`.

Scope: runs:write

Parameters

template_idpath, required
Idempotency-Keyheader, optional
Replays the Run already started or finished for this key rather than starting a second one; a different request with the same key answers `409 IDEMPOTENCY_KEY_REUSED`.

Body

multipart/form-data: file, delimiter, header_row

Responses

200OK

completed_atstring, nullable
created_atstring, required
errorobject, nullable
- codestring, required
- messagestring, required
expires_atstring, nullable
idstring, required
outputobject, nullable
- download_urlstring, required
- mime_typestring, required
- namestring, required
- size_bytesinteger, required
rows_writteninteger, nullable
statusstring, required
The Run record's closed `status` vocabulary -- every writer (`run_admission.admit_run`, this module's own `reap_record`, `run_service.execute_run`) and every reader (the Public API's `RunResponse`, `router.py`'s own status branches) uses these members, never the bare string literals a typo in one call site could drift from the others.
template_idstring, required
truncatedboolean

201Successful Response

completed_atstring, nullable
created_atstring, required
errorobject, nullable
- codestring, required
- messagestring, required
expires_atstring, nullable
idstring, required
outputobject, nullable
- download_urlstring, required
- mime_typestring, required
- namestring, required
- size_bytesinteger, required
rows_writteninteger, nullable
statusstring, required
The Run record's closed `status` vocabulary -- every writer (`run_admission.admit_run`, this module's own `reap_record`, `run_service.execute_run`) and every reader (the Public API's `RunResponse`, `router.py`'s own status branches) uses these members, never the bare string literals a typo in one call site could drift from the others.
template_idstring, required
truncatedboolean

202Accepted

completed_atstring, nullable
created_atstring, required
errorobject, nullable
- codestring, required
- messagestring, required
expires_atstring, nullable
idstring, required
outputobject, nullable
- download_urlstring, required
- mime_typestring, required
- namestring, required
- size_bytesinteger, required
rows_writteninteger, nullable
statusstring, required
The Run record's closed `status` vocabulary -- every writer (`run_admission.admit_run`, this module's own `reap_record`, `run_service.execute_run`) and every reader (the Public API's `RunResponse`, `router.py`'s own status branches) uses these members, never the bare string literals a typo in one call site could drift from the others.
template_idstring, required
truncatedboolean

400MALFORMED_FILE

errorstring, required
messagestring, required

MALFORMED_FILEThe file could not be read: it is empty, corrupt, or not encoded as expected.

401API_KEY_MISSING, API_KEY_INVALID

errorstring, required
messagestring, required

API_KEY_MISSINGSend the API Key as an `Authorization: Bearer` header.
API_KEY_INVALIDThe API Key is malformed, unknown, revoked, or its account is inactive.

402EXPORT_LIMIT_REACHED

errorstring, required
messagestring, required
quotaobject, required
- limitinteger, required
- resets_atstring, required
- usedinteger, required

EXPORT_LIMIT_REACHEDThis account has used its Quota for the current billing period.

403INSUFFICIENT_SCOPE, NO_SUBSCRIPTION

errorstring, required
messagestring, required

INSUFFICIENT_SCOPEThe API Key does not carry the scope this operation requires.
NO_SUBSCRIPTIONThis account has no active subscription.

404TEMPLATE_NOT_FOUND, RUN_NOT_FOUND

errorstring, required
messagestring, required

TEMPLATE_NOT_FOUNDNo Template with this id exists for this account.
RUN_NOT_FOUNDNo Run with this id exists for this account. Runs are kept 30 minutes and are lost if the service restarts.

409IDEMPOTENCY_KEY_REUSED

errorstring, required
messagestring, required

IDEMPOTENCY_KEY_REUSEDThis `Idempotency-Key` was already used for a different request.

413FILE_TOO_LARGE, ROW_LIMIT_EXCEEDED

errorstring, required
messagestring, required

FILE_TOO_LARGEThe uploaded file exceeds this plan's upload size ceiling.
ROW_LIMIT_EXCEEDEDThe uploaded file exceeds this plan's row ceiling.

415UNSUPPORTED_FILE_TYPE

errorstring, required
messagestring, required

UNSUPPORTED_FILE_TYPEThis file type is not supported.

422INVALID_PARSE_PARAMS, INVALID_IDEMPOTENCY_KEY, TEMPLATE_COLUMNS_MISSING

errorstring, required
messagestring, required

INVALID_PARSE_PARAMS`delimiter` must be one printable character; `header_row` must be a non-negative integer within the row ceiling.
INVALID_IDEMPOTENCY_KEY`Idempotency-Key` must be 1-255 printable characters.
TEMPLATE_COLUMNS_MISSINGThe uploaded file is missing one or more columns this Template's operations require.

429CONCURRENCY_LIMIT_REACHED, RATE_LIMITED

errorstring, required
messagestring, required

CONCURRENCY_LIMIT_REACHEDThis account already has the maximum number of Runs in flight for its plan.
RATE_LIMITEDThis account has exceeded its request rate limit for this operation.

503SERVER_BUSY

errorstring, required
messagestring, required

SERVER_BUSYThis worker is at its memory budget; retry shortly.

curl

curl -X POST "https://doctransform.xyz/api/v1/templates/{template_id}/runs" \
  -H "Authorization: Bearer $DOCTRANSFORM_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -F "file=@/path/to/your/file.csv"

Referencia de la API

GET/api/v1/runs/{run_id}

Parameters

Responses

curl

GET/api/v1/runs/{run_id}/output

Parameters

Responses

curl

GET/api/v1/templates

Responses

curl

POST/api/v1/templates/{template_id}/runs

Parameters

Body

Responses

curl

GET`/api/v1/runs/{run_id}`

GET`/api/v1/runs/{run_id}/output`

GET`/api/v1/templates`

POST`/api/v1/templates/{template_id}/runs`