A project owns its files, API keys, signing keys, watermark presets, recipes and a delivery host. Projects belong to your organization and are managed from the dashboard (PATCH /v1/projects/{slug} with a dashboard session). Project API keys can read and upload files, sign URLs and manage presets and recipes, but cannot change project settings.
project_slug is a DNS label of up to 63 characters and addresses the project in every API path. The project is served on default_delivery_host, which is {project_slug}.i2scd.net; no DNS setup is needed. Custom domains are set up by img2site staff and appear in custom_domains.
project_id and organization_id are opaque identifiers; webhook payloads use them.
Changing settings
PATCH https://api.img2.site/v1/projects/my-store
Authorization: Bearer <dashboard session>
Content-Type: application/json
{
"delivery_access": "public",
"resolution_presets": { "small": "resize/480x/format/webp", "large": "resize/1600x/format/webp" },
"allowed_transform_chains": ["preset:small", "preset:large", "resize/256x256/smart"],
"raw_download_enabled": false,
"callback_url": "https://www.my-store.example/webhooks/img2site"
}| Field | What it does |
|---|---|
name | Display name. |
delivery_access | public (default): anyone with a URL can fetch it. protected: every delivery URL must be signed; unsigned requests answer 403 signature_required. See signing. |
resolution_presets | Up to 32 named chains, used in URLs as preset:{name} (one per URL). Names match ^[a-z0-9][a-z0-9._-]{0,63}$. |
allowed_transform_chains | Up to 64 chains. When set, unsigned derived URLs must use one of them (403 transform_chain_not_allowed otherwise). Originals are exempt. On a public project, minting a signed URL with a chain outside the list fails with 400 transform_chain_not_allowed; protected projects do not use the list. |
default_watermark_preset_id | A watermark preset applied to every derived image. See delivery URLs for how explicit presets interact with it. |
raw_download_enabled | Enables /download/raw/f/{slug}, which returns the sanitized image with its saved metadata restored as an attachment. Off by default (404). |
callback_url | An https URL that receives webhooks. Setting it the first time, or sending rotate_callback_secret: true, returns callback_secret once. |
status | active or suspended. DELETE /v1/projects/{slug} also suspends; there is no hard delete. |
Unknown fields are refused with 400. Changes to delivery access, status, presets, allowed chains, the default watermark or raw downloads purge the project's cached images, so existing URLs pick up the change promptly.
A suspended project answers 403 project_suspended on delivery and refuses uploads; its API keys stop authenticating. suspended_by says who suspended it (owner or staff). A staff suspension can only be lifted by staff (403 project_suspended_by_staff).
storage_hard_limit_bytes comes from your plan (storage_limit_source: "plan") or is set by staff ("staff"). An upload that would exceed it is refused with 403 storage_quota_exceeded. file_count and storage_bytes show current use.
Created, listed, rotated and revoked in the dashboard (dashboard session only). Up to 100 active keys per project. The full key is shown once at creation; lists show prefix, last_four, scopes, status and last_used_at. Rotation issues a new key and revokes the old one in one step. See authentication for scopes.
Each project has one active signing key (active_signing_kid) used by POST /v1/projects/{slug}/signed-url. Rotating it keeps the previous key valid for 24 hours so issued URLs keep working. See signing.
A watermark preset is { name, file_slug, x_offset, y_offset, opacity }, where file_slug names a ready image in the same project; upload the watermark image first. Recipes are named transform chains you save for your own tooling (/v1/projects/{slug}/recipes).