SprontaDocs
AuthenticationBearer YOUR_API_KEY

List projects

GET/images/projects

Returns all projects for the authenticated account.

cURL
curl -H "Authorization: Bearer spronta_img_..." \
  https://app.spronta.com/api/images/projects
Response
[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "My App",
    "slug": "my-app-a1b2c3",
    "plan": "free",
    "createdAt": "2026-03-20T10:00:00.000Z"
  }
]

Create a project

POST/images/projects

Creates a new image project with a unique slug.

Request Body

namestringrequiredProject name (1–100 chars)
cURL
curl -X POST \
  -H "Authorization: Bearer spronta_img_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "My App"}' \
  https://app.spronta.com/api/images/projects
Response
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "My App",
  "slug": "my-app-a1b2c3",
  "plan": "free",
  "createdAt": "2026-03-20T10:00:00.000Z"
}

Get project details

GET/images/projects/{projectId}

Returns a project with usage stats.

Path Parameters

projectIdstring · uuidrequiredProject ID
cURL
curl -H "Authorization: Bearer spronta_img_..." \
  https://app.spronta.com/api/images/projects/{projectId}
Response
{
  "id": "123e4567-...",
  "name": "My App",
  "slug": "my-app-a1b2c3",
  "plan": "free",
  "stats": {
    "imageCount": 42,
    "totalSize": 104857600
  }
}

Update a project

PATCH/images/projects/{projectId}

Update project name or custom domain.

Path Parameters

projectIdstring · uuidrequiredProject ID

Request Body

namestringNew name (1–100 chars)
customDomainstring | nullCustom CDN domain (max 253 chars)
cURL
curl -X PATCH \
  -H "Authorization: Bearer spronta_img_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Renamed App"}' \
  https://app.spronta.com/api/images/projects/{projectId}
Response
{
  "id": "123e4567-...",
  "name": "Renamed App",
  "slug": "my-app-a1b2c3",
  "updatedAt": "2026-03-20T12:00:00.000Z"
}

Delete a project

DELETE/images/projects/{projectId}

Permanently deletes the project and all its images.

Path Parameters

projectIdstring · uuidrequiredProject ID
cURL
curl -X DELETE \
  -H "Authorization: Bearer spronta_img_..." \
  https://app.spronta.com/api/images/projects/{projectId}
Response
{ "deleted": true }

Initiate upload

POST/images/projects/{projectId}/upload

Returns a presigned URL. Upload your file there via PUT, then call confirm.

Path Parameters

projectIdstring · uuidrequiredProject ID

Request Body

filenamestringrequiredOriginal filename (1–255 chars)
contentTypestringrequiredMIME type (e.g. image/jpeg)
fileSizeintegerrequiredFile size in bytes (max 50MB)
cURL
curl -X POST \
  -H "Authorization: Bearer spronta_img_..." \
  -H "Content-Type: application/json" \
  -d '{"filename":"hero.jpg","contentType":"image/jpeg","fileSize":2048576}' \
  https://app.spronta.com/api/images/projects/{projectId}/upload
Response
{
  "imageId": "987fcdeb-51a2-...",
  "uploadUrl": "https://storage.example.com/presigned...",
  "r2Key": "123e4567/987fcdeb/hero.jpg"
}

Confirm upload

POST/images/projects/{projectId}/upload/confirm

Finalizes the upload. Computes blurhash, detects dimensions, returns CDN URL.

Path Parameters

projectIdstring · uuidrequiredProject ID

Request Body

imageIdstring · uuidrequiredImage ID from initiate step
widthintegerOverride detected width
heightintegerOverride detected height
cURL
curl -X POST \
  -H "Authorization: Bearer spronta_img_..." \
  -H "Content-Type: application/json" \
  -d '{"imageId":"987fcdeb-51a2-..."}' \
  https://app.spronta.com/api/images/projects/{projectId}/upload/confirm
Response
{
  "id": "987fcdeb-...",
  "filename": "hero.jpg",
  "width": 1920,
  "height": 1080,
  "blurhash": "LEHV6nWB2yk8pyo0adR*.7kCMdnj",
  "uploadStatus": "confirmed",
  "url": "https://cdn.spronta.com/my-project/987fcdeb-..."
}

List images

GET/images/projects/{projectId}/images

Returns paginated images for a project.

Path Parameters

projectIdstring · uuidrequiredProject ID

Query Parameters

limitintegerMax results, 1–100 (default 50)
offsetintegerPagination offset (default 0)
cURL
curl -H "Authorization: Bearer spronta_img_..." \
  "https://app.spronta.com/api/images/projects/{projectId}/images?limit=20"
Response
[
  {
    "id": "987fcdeb-...",
    "filename": "hero.jpg",
    "width": 1920,
    "height": 1080,
    "blurhash": "LEHV6nWB2yk8...",
    "altText": "Product hero",
    "tags": ["hero", "product"],
    "url": "https://cdn.spronta.com/my-project/987fcdeb-..."
  }
]

Update image metadata

PATCH/images/projects/{projectId}/images/{imageId}

Update alt text and tags for an image.

Path Parameters

projectIdstring · uuidrequiredProject ID
imageIdstring · uuidrequiredImage ID

Request Body

altTextstring | nullAlt text (max 1000 chars)
tagsstring[]Tags (max 50 items, each max 100 chars)
cURL
curl -X PATCH \
  -H "Authorization: Bearer spronta_img_..." \
  -H "Content-Type: application/json" \
  -d '{"altText":"Updated alt text","tags":["hero","homepage"]}' \
  https://app.spronta.com/api/images/projects/{projectId}/images/{imageId}
Response
{
  "id": "987fcdeb-...",
  "altText": "Updated alt text",
  "tags": ["hero", "homepage"],
  "updatedAt": "2026-03-20T12:00:00.000Z"
}

Delete an image

DELETE/images/projects/{projectId}/images/{imageId}

Permanently deletes the image from storage and database.

Path Parameters

projectIdstring · uuidrequiredProject ID
imageIdstring · uuidrequiredImage ID
cURL
curl -X DELETE \
  -H "Authorization: Bearer spronta_img_..." \
  https://app.spronta.com/api/images/projects/{projectId}/images/{imageId}
Response
{ "deleted": true }

List presets

GET/images/projects/{projectId}/presets

Returns all transform presets for a project.

Path Parameters

projectIdstring · uuidrequiredProject ID
cURL
curl -H "Authorization: Bearer spronta_img_..." \
  https://app.spronta.com/api/images/projects/{projectId}/presets
Response
[
  {
    "id": "abc12345-...",
    "name": "thumbnail",
    "transforms": {
      "width": 200,
      "height": 200,
      "fit": "cover",
      "gravity": "face"
    }
  }
]

Create a preset

POST/images/projects/{projectId}/presets

Create a named transform preset. Use in CDN URLs with ?t=name.

Path Parameters

projectIdstring · uuidrequiredProject ID

Request Body

namestringrequiredUnique name (alphanumeric, hyphens, underscores, 1–64 chars)
transformsobjectrequiredTransform parameters (width, height, fit, format, quality, etc.)
cURL
curl -X POST \
  -H "Authorization: Bearer spronta_img_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"thumbnail","transforms":{"width":200,"height":200,"fit":"cover","gravity":"face"}}' \
  https://app.spronta.com/api/images/projects/{projectId}/presets
Response
{
  "id": "abc12345-...",
  "name": "thumbnail",
  "transforms": {
    "width": 200,
    "height": 200,
    "fit": "cover",
    "gravity": "face",
    "format": "webp",
    "quality": 80
  },
  "createdAt": "2026-03-20T10:00:00.000Z"
}

Get a preset

GET/images/projects/{projectId}/presets/{presetId}

Returns a single preset by ID.

Path Parameters

projectIdstring · uuidrequiredProject ID
presetIdstring · uuidrequiredPreset ID
cURL
curl -H "Authorization: Bearer spronta_img_..." \
  https://app.spronta.com/api/images/projects/{projectId}/presets/{presetId}
Response
{
  "id": "abc12345-...",
  "name": "thumbnail",
  "transforms": { "width": 200, "height": 200, "fit": "cover" }
}

Update a preset

PATCH/images/projects/{projectId}/presets/{presetId}

Update a preset's name or transforms.

Path Parameters

projectIdstring · uuidrequiredProject ID
presetIdstring · uuidrequiredPreset ID

Request Body

namestringNew name
transformsobjectNew transforms (replaces existing)
cURL
curl -X PATCH \
  -H "Authorization: Bearer spronta_img_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"thumb-v2","transforms":{"width":300,"height":300,"fit":"cover"}}' \
  https://app.spronta.com/api/images/projects/{projectId}/presets/{presetId}
Response
{
  "id": "abc12345-...",
  "name": "thumb-v2",
  "transforms": { "width": 300, "height": 300, "fit": "cover" },
  "updatedAt": "2026-03-20T12:00:00.000Z"
}

Delete a preset

DELETE/images/projects/{projectId}/presets/{presetId}

Permanently deletes a preset.

Path Parameters

projectIdstring · uuidrequiredProject ID
presetIdstring · uuidrequiredPreset ID
cURL
curl -X DELETE \
  -H "Authorization: Bearer spronta_img_..." \
  https://app.spronta.com/api/images/projects/{projectId}/presets/{presetId}
Response
{ "deleted": true }

Get signing config

GET/images/projects/{projectId}/signing

Returns the current signing configuration. Secret is masked.

Path Parameters

projectIdstring · uuidrequiredProject ID
cURL
curl -H "Authorization: Bearer spronta_img_..." \
  https://app.spronta.com/api/images/projects/{projectId}/signing
Response
{
  "enabled": true,
  "requireSignedUrls": false,
  "signingSecret": "spronta_sign_...abcd"
}

Enable or disable signing

POST/images/projects/{projectId}/signing

Set enabled:true to generate a new secret (shown once). Set enabled:false to disable.

Path Parameters

projectIdstring · uuidrequiredProject ID

Request Body

enabledbooleantrue = generate new secret, false = disable
requireSignedUrlsbooleanWhen true, unsigned CDN URLs return 403
cURL
curl -X POST \
  -H "Authorization: Bearer spronta_img_..." \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}' \
  https://app.spronta.com/api/images/projects/{projectId}/signing
Response
{
  "enabled": true,
  "requireSignedUrls": false,
  "signingSecret": "spronta_sign_a1b2c3d4e5f6..."
}

Generate a signed URL

PUT/images/projects/{projectId}/signing

Server-side HMAC-SHA256 signed URL generation. Requires signing to be enabled.

Path Parameters

projectIdstring · uuidrequiredProject ID

Request Body

pathstringrequiredImage path (e.g. /my-project/hero.jpg)
paramsobjectTransform params as key-value strings
expiresInintegerExpiration in seconds (60–604800)
cURL
curl -X PUT \
  -H "Authorization: Bearer spronta_img_..." \
  -H "Content-Type: application/json" \
  -d '{"path":"/my-project/hero.jpg","params":{"w":"800","f":"webp"},"expiresIn":3600}' \
  https://app.spronta.com/api/images/projects/{projectId}/signing
Response
{
  "url": "/my-project/hero.jpg?exp=1711152000&f=webp&w=800&s=a1b2c3...",
  "signature": "a1b2c3d4e5f6...",
  "expiresAt": 1711152000
}

Get usage metrics

GET/images/projects/{projectId}/usage

Returns per-day request, bandwidth, and transform metrics.

Path Parameters

projectIdstring · uuidrequiredProject ID

Query Parameters

daysintegerLookback period, 1–90 (default 30)
cURL
curl -H "Authorization: Bearer spronta_img_..." \
  "https://app.spronta.com/api/images/projects/{projectId}/usage?days=7"
Response
{
  "daily": [
    {
      "date": "2026-03-15",
      "requests": 12450,
      "bandwidth": 524288000,
      "transforms": 8320
    }
  ],
  "totals": {
    "requests": 12450,
    "bandwidth": 524288000,
    "transforms": 8320
  }
}