Files API
Upload a file once and reference it by id everywhere a file is accepted.
Updated
4 operations, generated from
openapi/signclad.v1.yaml. Try them in the
interactive reference, browse
every endpoint group, or read the
guides for the prose version.
- GET
/files/{id}Get a file - DELETE
/files/{id}Release an uploaded file - GET
/files/{id}/contentDownload a file's normalized PDF - POST
/files/{id}/retryRetry file preparation
GET /files/{id}
Get a file Extension
Ingest state and a preview link for one uploaded file. A file in another workspace is a
404, indistinguishable from one that does not exist.
- Base URL
https://api.signclad.com/api/v1- Authentication
- API key or OAuth 2.1 access token
Path parameters
| Name | Type | Description |
|---|---|---|
id | string | The file's id. |
Responses
| Status | Description |
|---|---|
200 | The file. |
401 | Missing or invalid credentials. Unauthenticated requests are rate limited at 50 per minute.… |
403 | Authenticated, but not allowed to do this: an insufficient role, a credential type the route refuses, an unenrolled second factor, or a signer acting out of turn. meta.error always says which.… |
404 | No such record for this workspace. Signclad never answers 404 for a record that exists: a 404 is authoritative. |
Example request
curl -X GET https://api.signclad.com/api/v1/files/{id} \
-H "X-Api-Key: $SIGNCLAD_API_KEY" DELETE /files/{id}
Release an uploaded file Extension
Queues deletion of an upload and all of its stored derivatives when no live document, template, attachment request, or application references it. Referenced files are retained.
- Base URL
https://api.signclad.com/api/v1- Authentication
- API key or OAuth 2.1 access token
Path parameters
| Name | Type | Description |
|---|---|---|
id | string | The file's id. |
Responses
| Status | Description |
|---|---|
204 | Cleanup was accepted. |
401 | Missing or invalid credentials. Unauthenticated requests are rate limited at 50 per minute.… |
403 | Authenticated, but not allowed to do this: an insufficient role, a credential type the route refuses, an unenrolled second factor, or a signer acting out of turn. meta.error always says which.… |
404 | No such record for this workspace. Signclad never answers 404 for a record that exists: a 404 is authoritative. |
Example request
curl -X DELETE https://api.signclad.com/api/v1/files/{id} \
-H "X-Api-Key: $SIGNCLAD_API_KEY" GET /files/{id}/content
Download a file's normalized PDF Extension
The normalized PDF bytes, inline, for a viewer. This is what preview_url points at: the
same route carrying expires and signature, so a rendered page can be fetched without
putting an API key in a URL. Present either parameter and the signature must verify.
An expired or tampered link is a 404 whose meta.message reads
This preview link has expired. — a distinct message on an otherwise identical body.
- Base URL
https://api.signclad.com/api/v1- Authentication
- API key or OAuth 2.1 access token
Path parameters
| Name | Type | Description |
|---|---|---|
id | string |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
expires | integer | Optional | From preview_url. Part of what the signature covers. |
signature | string | Optional | From preview_url. |
Responses
| Status | Description |
|---|---|
200 | The PDF bytes, inline with the file's sanitized name. |
401 | Missing or invalid credentials. Unauthenticated requests are rate limited at 50 per minute.… |
403 | Authenticated, but not allowed to do this: an insufficient role, a credential type the route refuses, an unenrolled second factor, or a signer acting out of turn. meta.error always says which.… |
404 | No such file, the bytes are gone, or the preview link has expired. The expired case is the only one with its own meta.message. |
Example request
curl -X GET https://api.signclad.com/api/v1/files/{id}/content \
-H "X-Api-Key: $SIGNCLAD_API_KEY" POST /files/{id}/retry
Retry file preparation Extension
Requeues the stored original after a retryable malware-scanner failure. Known malware, conversion failures, and files whose original is missing must be replaced instead.
- Base URL
https://api.signclad.com/api/v1- Authentication
- API key or OAuth 2.1 access token
Path parameters
| Name | Type | Description |
|---|---|---|
id | string | The file's id. |
Responses
| Status | Description |
|---|---|
200 | The file was returned to its pending preparation state. |
401 | Missing or invalid credentials. Unauthenticated requests are rate limited at 50 per minute.… |
403 | Authenticated, but not allowed to do this: an insufficient role, a credential type the route refuses, an unenrolled second factor, or a signer acting out of turn. meta.error always says which.… |
404 | No such record for this workspace. Signclad never answers 404 for a record that exists: a 404 is authoritative. |
422 | Validation failed. errors maps a field name to a message string, or to an object keyed by an error code or by a per-item key. Values are never arrays. |
Example request
curl -X POST https://api.signclad.com/api/v1/files/{id}/retry \
-H "X-Api-Key: $SIGNCLAD_API_KEY"