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 or Session
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, 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. |
429 | Rate limited. The message contains the literal 429 Too Many Requests for compatibility with clients that match on it.… |
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 or Session
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, 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 or Session
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, 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. |
429 | Rate limited. The message contains the literal 429 Too Many Requests for compatibility with clients that match on it.… |
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 or Session
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, 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. |
409 | The request is well formed; the resource is not in a state that allows it.… |
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. |
429 | Rate limited. The message contains the literal 429 Too Many Requests for compatibility with clients that match on it.… |
Example request
curl -X POST https://api.signclad.com/api/v1/files/{id}/retry \
-H "X-Api-Key: $SIGNCLAD_API_KEY"