Sources API

Manage your ImageBoss sources programmatically — list, create, update, and delete sources via a REST API.


Authentication

All requests must include your API key via the imageboss-api-key header. You can find your API key in the Dashboard under API Keys. 

curl \
  --location \
  --request GET 'https://api.imageboss.me/v1/sources' \
  --header 'imageboss-api-key: <YOUR_API_KEY_HERE>'

Base URL

All endpoints are relative to the public API host: 

https://api.imageboss.me/v1/sources

Endpoints

Method Path Description
GET /api/v1/sources List all sources in your account.
GET /api/v1/sources/:id Fetch a single source by id.
POST /api/v1/sources Create a new source.
PATCH /api/v1/sources/:id Update an existing source (partial update).
DELETE /api/v1/sources/:id Delete a source and remove it from DynamoDB.

Rate limits & access

  • All operations are scoped to the authenticated account; you can only manage your own sources.

List sources

Request

curl \
  --location \
  --request GET 'https://api.imageboss.me/v1/sources' \
  --header 'imageboss-api-key: <YOUR_API_KEY_HERE>'

Response

[
  {
    "id": "69a99ae507f19000072d0125",
    "source": "my-images",
    "source_type": "s3",
    "credentials": {
      "bucket": "my-bucket",
      "region": "us-east-1",
      "access_key_id": "AKIA...",
      "secret_access_key": "****",
      "require_token": "true",
      "secret_token": "a1b2c3d4e5f6..."
    },
    "created_at": "2026-03-05T14:10:00Z",
    "updated_at": "2026-03-05T14:10:00Z"
  }
]

Storage provider secrets (secret_access_key, secret, sas_token) are redacted as "****". The secret_token field is your URL-signing key for that source and can be used to sign URLs programmatically.


Create a source

The payload mirrors the fields you configure in the Dashboard. Required credential fields depend on the source_type (S3, GCS, DO Spaces, R2, Akamai, Wasabi, Azure, or URL).

Required fields per source type

source_type Required credential_attributes
s3 access_key_id, secret_access_key, bucket, region
gcs access_key, secret, bucket
dos (DigitalOcean Spaces) access_key, secret, bucket, region
r2 (Cloudflare R2) access_key, secret, bucket
akamai access_key, secret, bucket, endpoint
wasabi access_key, secret, bucket
azure account_name, service_type, sas_token
plus: container_name (when service_type = "blob") or share_name (when service_type = "file-share")
url (Web Proxy) url

Request (S3 example)

curl \
  --location \
  --request POST 'https://api.imageboss.me/v1/sources' \
  --header 'Content-Type: application/json' \
  --header 'imageboss-api-key: <YOUR_API_KEY_HERE>' \
  --data-raw '{
    "source": {
      "source": "my-images",
      "source_type": "s3",
      "credential_attributes": {
        "access_key_id": "AKIA...",
        "secret_access_key": "wJalr...",
        "bucket": "my-bucket",
        "region": "us-east-1",
        "require_token": "true"
      }
    }
  }'

Successful response

{
  "id": "69a99ae507f19000072d0125",
  "source": "my-images",
  "source_type": "s3",
  "credentials": {
    "bucket": "my-bucket",
    "region": "us-east-1",
    "access_key_id": "AKIA...",
    "secret_access_key": "****",
    "require_token": "true",
    "secret_token": "a1b2c3d4e5f6..."
  },
  "created_at": "2026-03-05T14:10:00Z",
  "updated_at": "2026-03-05T14:10:00Z"
}

Error responses

On validation errors, you get 422 Unprocessable Entity with a list of error messages:

{
  "errors": [
    "Credential access_key_id is required for s3 sources",
    "Source has already been taken"
  ]
}

Update a source

Use PATCH /api/v1/sources/:id with the same payload shape as create. Only the provided fields are updated. 

curl \
  --location \
  --request PATCH 'https://api.imageboss.me/v1/sources/<SOURCE_ID>' \
  --header 'Content-Type: application/json' \
  --header 'imageboss-api-key: <YOUR_API_KEY_HERE>' \
  --data-raw '{
    "source": {
      "credential_attributes": {
        "require_token": "false"
      }
    }
  }'

Delete a source

Delete a source and remove it from DynamoDB. This does not delete any images from your underlying storage. 

curl \
  --location \
  --request DELETE 'https://api.imageboss.me/v1/sources/<SOURCE_ID>' \
  --header 'imageboss-api-key: <YOUR_API_KEY_HERE>'

On success, the API returns an empty JSON object: {}.