AjudaAPIReferência

Referência da API

Cada endpoint, parâmetro e código de erro da API pública.

Esta referência é gerada diretamente do nosso documento OpenAPI e permanece em inglês.

Toda requisição parte de https://doctransform.xyz/api/v1.

Leia as respostas como um leitor tolerante: ignore qualquer campo que não reconheça, já que adicionamos campos sem aviso prévio.

A API é versionada uma única vez, nesta URL base. Se algum dia retirarmos um campo ou endpoint, ele continuará funcionando por pelo menos 12 meses depois de ser marcado com os cabeçalhos Deprecation e Sunset.

Postman → Import → este arquivo: baixe o JSON OpenAPI acima e entregue-o à importação OpenAPI 3.1 do 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"

Referência da 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`