Signaturum API v1 reference

Authentication, commercial API limits, product billing, deposits, Watermark V72, managed files, desktop licensing and crawler monitoring.

Base URLhttps://signaturum.com/api/v1Billing runtime 2.1
Create or rotate keysAPI overview

Authentication and environments

Send the secret as a Bearer token. X-API-Key is supported for compatibility. Never put a key in a URL or client-side source code.

Authorization: Bearer sg_live_YOUR_API_KEY
Accept: application/json
sg_live_…Production key. It uses live API and product entitlements.
sg_test_…Sandbox key. The API plan must include api.sandbox.

Granular scopes

usage:readRead account, subscription and usage information.
deposit:readRead owned deposit records and blockchain metadata.
deposit:writeCreate deposits from a hash, upload or stored file.
watermark:readList jobs, poll status and retrieve results.
watermark:protectCreate invisible-watermark protection jobs.
watermark:detectCreate invisible-watermark detection jobs.
files:readList metadata, preview and download owned files.
files:writeUpload and delete owned files.
crawler:readRead monitored objects, jobs, candidates, alerts and sources.
crawler:writeCreate, update and delete objects and start scans.
desktop:licenseActivate and check desktop application licenses.
Compatibility: legacy read, deposit, watermark, files, crawler and desktop scopes are still mapped to the new granular permissions during migration.

Billing model

An authenticated request must pass both the API subscription check and, when the operation consumes a commercial service, the corresponding product entitlement check.

API allowanceCounts transport and infrastructure use: requests per minute, day and billing period, concurrent requests, keys, upload size, webhooks and sandbox access.
Product allowanceCounts business operations: deposit.records, watermark.generations, vault.*, embed.* and crawler.*. Product packages remain independently manageable in Billing V2.
Example: POST /watermarks/protect consumes one API request and the calculated watermark.generations cost. GET /watermarks/{task_id} normally consumes only an API request.

API plan capabilities

Limits are resolved from the active API subscription. Account overrides may replace plan values. A value is shared by every key attached to that subscription.

CapabilityAccounting windowDescription
api.requests_minuteMinuteRequests accepted in the current minute.
api.requests_dayUTC dayRequests accepted in the current UTC day.
api.requests_monthBilling periodRequests accepted in the active billing period.
api.concurrent_requestsActive leaseSimultaneous requests controlled through expiring concurrency leases.
api.max_upload_bytesPer uploadMaximum accepted request body or uploaded file size.
api.keysSubscriptionMaximum active API keys in the subscription.
api.webhooksSubscriptionMaximum webhook endpoints available to the subscription.
api.sandboxSubscriptionWhether sg_test_ sandbox credentials are allowed.

Rate-limit response headers

X-RateLimit-Limit-Minute: 30
X-RateLimit-Remaining-Minute: 29
X-RateLimit-Reset-Minute: 1787316060
X-RateLimit-Limit-Day: 10000
X-RateLimit-Remaining-Day: 9999
X-RateLimit-Reset-Day: 1787356800
X-RateLimit-Limit-Month: 100000
X-RateLimit-Remaining-Month: 99999
X-RateLimit-Reset-Month: 1788220800
Retry-After: 12
Rate limits are subscription-wide, not per key. Creating more keys does not multiply the allowance. On HTTP 429, wait for Retry-After before retrying.

Response envelope

JSON endpoints use a consistent success or error envelope. Every response includes request_id and the X-Request-ID header for tracing.

{
  "success": true,
  "data": { ... },
  "request_id": "f0d7d8a91bc43e2a"
}
{
  "success": false,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "API rate limit exceeded."
  },
  "request_id": "f0d7d8a91bc43e2a"
}

Account and usage

MethodEndpointRequired scopeDescription
GET/api/v1/—API status, public version and service metadata.
GET/api/v1/meusage:readAccount identity, key environment, resolved limits and key scopes.
GET/api/v1/usageusage:readAPI counters and product balances resolved for the current account.

Desktop licenses

MethodEndpointRequired scopeDescription
POST/api/v1/desktop/license/activatedesktop:licenseActivate a desktop license for the current account and device.
POST/api/v1/desktop/license/statusdesktop:licenseCheck the current desktop license or offline-lease status.

Deposits and records

MethodEndpointRequired scopeDescription
GET/api/v1/recordsdeposit:readList owned deposit records with pagination and status filters.
POST/api/v1/depositsdeposit:writeCreate a deposit from JSON SHA-256 metadata, multipart upload or an owned file_id. Consumes deposit.records.
GET/api/v1/records/{record_id}deposit:readRead one owned record, certificate reference and blockchain metadata.

POST /deposits

curl -X POST https://signaturum.com/api/v1/deposits \
  -H "Authorization: Bearer sg_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: deposit-order-18472" \
  -d '{"sha256":"0123456789abcdef...64 hex chars","filename":"work.psd"}'

Storage and files

MethodEndpointRequired scopeDescription
GET/api/v1/filesfiles:readList owned stored files with pagination, type and search filters.
POST/api/v1/filesfiles:writeUpload one validated file. Storage, file-count, PDF-page and video-duration limits are enforced.
GET/api/v1/files/{file_id}files:readRead metadata and measured media properties for one owned file.
DELETE/api/v1/files/{file_id}files:writePermanently delete an owned file and its database record.
GET/api/v1/files/{file_id}/downloadfiles:readDownload an owned stored file.
GET/api/v1/files/{file_id}/previewfiles:readStream an inline preview; HTTP Range is supported for compatible video.

Watermark V72

MethodEndpointRequired scopeDescription
GET/api/v1/watermarks/jobswatermark:readList recent watermark jobs for the account.
POST/api/v1/watermarks/protectwatermark:protectProtect an uploaded or stored file. Returns 202 and consumes the calculated watermark.generations cost.
POST/api/v1/watermarks/detectwatermark:detectDetect an invisible watermark in an uploaded or stored file. Returns 202.
GET/api/v1/watermarks/{task_id}watermark:readPoll or finalize one watermark task and read processing metadata.
GET/api/v1/watermarks/{task_id}/resultwatermark:readDownload a completed protected result while it remains available.

POST /watermarks/protect

curl -X POST https://signaturum.com/api/v1/watermarks/protect \
  -H "Authorization: Bearer sg_live_YOUR_API_KEY" \
  -H "Idempotency-Key: wm-job-5501" \
  -F "file=@photo.jpg" \
  -F "embed_metadata=1"

Crawler

MethodEndpointRequired scopeDescription
GET/api/v1/crawler/objectscrawler:readList monitored objects owned by the account.
POST/api/v1/crawler/objectscrawler:writeCreate a monitored object; crawler.objects is enforced.
GET/api/v1/crawler/objects/{id}crawler:readRead one monitored object and its settings.
PATCH/api/v1/crawler/objects/{id}crawler:writeUpdate an owned monitored object and scan configuration.
DELETE/api/v1/crawler/objects/{id}crawler:writeDelete an owned monitored object.
POST/api/v1/crawler/objects/{id}/scancrawler:writeStart an asynchronous scan. Enforces crawler.runs, pages, interval, sources and candidates limits.
GET/api/v1/crawler/objects/{id}/candidatescrawler:readList match candidates for one monitored object.
GET/api/v1/crawler/jobscrawler:readList crawler jobs and processing state.
GET/api/v1/crawler/candidatescrawler:readList candidates across all owned monitored objects.
GET/api/v1/crawler/alertscrawler:readList crawler alerts for the account.
GET/api/v1/crawler/sourcescrawler:readList supported or configured crawler sources.

POST /crawler/objects/{id}/scan

curl -X POST https://signaturum.com/api/v1/crawler/objects/42/scan \
  -H "Authorization: Bearer sg_live_YOUR_API_KEY" \
  -H "Idempotency-Key: crawler-scan-42-20260821"
Crawler limits are separate product capabilities: crawler.objects, crawler.runs, crawler.pages_scanned, crawler.min_interval_minutes, crawler.sources_per_object, crawler.candidates_per_run and crawler.priority_queue.

Idempotency and safe retries

For POST, PUT, PATCH and DELETE, send an Idempotency-Key of 8–120 characters using A–Z, a–z, 0–9, dot, underscore, colon or hyphen. Reusing a key with another body returns 409 idempotency_conflict. A stored replay returns X-Idempotent-Replay: true.

Idempotency-Key: order-2026-08-21-000184
X-Idempotent-Replay: true

HTTP status and errors

Use the HTTP status together with error.code in application logic. Preserve request_id when contacting support.

HTTPMeaning
200 / 201 / 202Successful response, resource created or asynchronous job accepted.
400 / 422Invalid request or validation failure.
401Missing, invalid, revoked or expired API key.
402Required product quota is exhausted or unavailable.
403Missing scope, sandbox access, account permission or IP allowlist match.
404Endpoint or owned resource was not found.
409Idempotency conflict, request already in progress or resource is busy.
413 / 415Payload is too large or media type is rejected.
429Minute, day, month or concurrency limit exceeded; inspect Retry-After.
500 / 502Internal or downstream processing error. Retry only safe/idempotent requests.