Stashr docs

API access, projects, uploads, clean links, transforms, usage, and billing.

API Reference

Use the versioned management API from a server, CMS, build process, or trusted automation:

https://stashr.dev/api/v1

The machine-readable OpenAPI 3.1 contract includes every supported method, request body, response schema, and error status.

Authentication

Send one of these headers:

Authorization: Bearer stshr_live_...

X-API-Key: stshr_live_...

API keys are server-side credentials. Do not place them in browser JavaScript, mobile bundles, public repositories, or URLs.

Scopes

Scope	Access
`assets:read`	Read workspace details, projects, folders, assets, usage, and upload settings.
`assets:write`	Create, update, move, upload, and delete DAM resources, and change upload settings.

Existing keys keep their scopes and automatically work with the expanded DAM endpoints.

Endpoints

Method	Path	Scope	Purpose
`GET`	`/workspace`	Read	Get the key's workspace and slug.
`GET`, `POST`	`/projects`	Read, Write	List or create projects.
`GET`, `PATCH`, `DELETE`	`/projects/{projectId}`	Read, Write	Read, update, or delete one project.
`GET`, `POST`	`/assets`	Read, Write	List or upload assets.
`GET`	`/assets/lookup`	Read	Resolve JSON metadata from `projectSlug` and `path`.
`GET`, `PATCH`, `DELETE`	`/assets/{assetId}`	Read, Write	Read, update, move, rename, or delete an asset.
`GET`	`/assets/{assetId}/file`	Read	Fetch a file through a `302` delivery redirect.
`GET`, `DELETE`	`/assets/by-path/{projectSlug}/{assetPath}`	Read, Write	Fetch or delete a file by path.
`GET`, `POST`, `DELETE`	`/folders`	Read, Write	List, create, or delete folders by path.
`GET`, `PATCH`, `DELETE`	`/folders/{folderId}`	Read, Write	Read, update, move, or delete a folder.
`GET`	`/usage`	Read	Read storage, delivery, project, and asset usage.
`GET`, `PATCH`	`/settings/optimization`	Read, Write	Read or change upload optimization defaults.

Paths in this table are relative to https://stashr.dev/api/v1.

Asset Upload Requests

Uploads use multipart/form-data with two parts:

Part	Status	Content
`file`	Required	The binary file, up to 100 MB.
`metadata`	Required for new integrations	A JSON object containing `projectSlug` or `projectId` plus any optional asset metadata.

Inside metadata, at least one project identifier is required. folderPath, title, altText, tags, and storeOriginalImages are optional. Existing flat multipart metadata fields remain compatible, but they cannot be mixed with the JSON metadata part. See Uploads and API recipes for language-selectable examples.

Asset Listing

Uploads and asset listings require projectSlug or projectId. Prefer stable project slugs in integrations.

By default, listing returns every asset directly in the selected folder. Omit folderPath to list the project root.

For a paginated whole-project scan:

GET /api/v1/assets?projectSlug=website&recursive=true&page=1&limit=100

limit can be from 1 to 100. Sending either page or limit activates pagination. Responses include:

{
  "assets": [],
  "pagination": {
    "page": 1,
    "limit": 100,
    "total": 0,
    "totalPages": 0,
    "nextPage": null
  }
}

Add folderPath, q, or kind=image|pdf|audio|video|file to narrow results. Original and optimized image files are returned as one logical asset with an optional variants array.

Delivery Paths

Asset responses contain relative deliveryUrl and publicPath values. Prefix the returned value with the Stashr origin:

const publicUrl = new URL(asset.deliveryUrl, "https://stashr.dev").href;

Always use the returned path. Image optimization can change the stored extension or add a variant suffix.

File endpoints return 302; use a client that follows redirects, or use the public delivery URL directly. Public delivery is subject to the workspace delivery allowance.

Errors

Errors use JSON:

{
  "error": "Project is required",
  "code": "PROJECT_REQUIRED"
}

Validation errors can also include issues. Common status codes are:

Status	Meaning
`400`	Invalid fields, paths, filters, or uploaded content.
`401`	API key missing, revoked, or invalid.
`402`	Delivery allowance exhausted.
`403`	Scope, plan, storage, or media restriction.
`404`	Resource is not in the key's workspace.
`409`	Duplicate path/slug, non-empty folder, or confirmation required.
`429`	Rate limit exceeded; inspect `Retry-After` and `RateLimit` headers.
`502`	The media service could not complete the operation.

The external API allows 300 requests per minute, mutations allow 120 per minute, and uploads allow 30 per minute. The most restrictive applicable limit wins.

Management Versus Delivery

The management API uses a private API key to organize and update assets. Public delivery links do not use an API key. Image transforms are also public delivery URL parameters, not management endpoints. See Image transforms.