Documentation

Dynjandi stores your images and serves resized, cropped and re-encoded variants of them from cdn.dynjandi.dev. This page covers the URLs, uploading, API keys, usage and the MCP server.

• URLs
• Upload
• API keys
• Usage
• MCP server

Reference documents:

• The management API, as an OpenAPI 3.1 document. It lists the routes an API key can reach.
• The public-key API, as an OpenAPI document in the public repository.
• @dynjandi/transform-grammar on npm: the URL grammar, which parses and builds variant URLs.
• @dynjandi/sdk on npm: a TypeScript SDK for Dynjandi.

URLs

A variant URL is the file id followed by operations. Each operation starts with /-/, and operations apply in order. The file id alone, https://cdn.dynjandi.dev/{id}, is the original.

https://cdn.dynjandi.dev/{id}/-/resize/800x/-/format/webp/-/quality/75/
https://cdn.dynjandi.dev/{id}/-/crop/400x400/center/
https://cdn.dynjandi.dev/{id}/-/scale_crop/1280x400/focal/0.42x0.18/
https://cdn.dynjandi.dev/{id}/-/scale_crop/1280x400/face,attention/

Operations

Limits and values

Positions

• A position names where a crop is anchored. focal/{x}x{y} anchors it on a point, with each coordinate a fraction between 0 and 1.
• face runs face detection. When no face is found the crop falls back to the next position, so face,attention tries a face and then attention. A bare face means face,center.
• A fallback chain is face followed by one position from the table above. focal cannot be part of a chain.

Uploadcare URLs

Uploadcare spellings are accepted and normalised to the canonical form, so both spellings share one cache entry.

Caching

A variant is rendered on its first request and served from the cache after that. Variants are served with Cache-Control: public, max-age=31536000, immutable. A URL the grammar rejects answers 400.

Upload

There are two ways to upload. Both take a multipart/form-data body with a file part and, optionally, focalX and focalY parts. The focal point is set with both fields or neither.

With a public key

POST https://cdn.dynjandi.dev/upload
X-Public-Key: {public key}
Content-Type: multipart/form-data

The public key is the only credential this route checks, so send it from your server and not from a page. A successful upload answers 201 with file, id, url, focalX and focalY. The response is Cache-Control: no-store.

This route reports an error as { "error": "message" }, with a string message.

With an API key

POST https://app.dynjandi.dev/api/projects/{id}/files
Authorization: Bearer dyn_...
Content-Type: multipart/form-data

This route reports an error as a JSON body such as { "error": { "code": "NOT_FOUND", "message": "…" } }, where code and message are strings and an optional details object may sit beside them. The statuses are 400, 401, 403, 404 and 429, and, for this route, 402, 413 and 502. A 429 carries Retry-After.

API keys

An API key lets a server call the management API without a browser session.

• A member creates a key for their own workspace in the dashboard, on the API keys page at app.dynjandi.dev/api-keys. A key cannot reach the routes that create, list or revoke keys, so a leaked key cannot mint its own replacement.
• A key expires in 30, 90 or 365 days, and 90 is the default. A key never lasts without an expiry.
• A workspace holds at most 10 unexpired keys. The name is 1 to 64 characters.
• A key starts with dyn_. The key itself is shown once, when it is created, and cannot be read back afterwards. A member can revoke a key from the dashboard.
• A key acts as a member of the one workspace it was created for, and never as a superadmin.

Sending a key

GET https://app.dynjandi.dev/api/workspace
Authorization: Bearer dyn_...

• The key goes in the Authorization: Bearer header. When that header is present the session cookie is never read, so an invalid key does not fall back to a cookie.
• A key is meant for servers: the management API is called by servers with a key, and it has no CORS.
• Treat a key like a password. Keep it out of URLs and out of version control.

When a request is refused

Routes a key can reach

Only these routes accept a key. Every route in the table also accepts HEAD, except /api/files/{id}/focal-suggestion, which is GET only.

Usage

GET /api/workspace/usage reports on the one workspace the key was created for. GET /api/workspace returns the same body. A key names no workspace in the request, because it has exactly one. The body holds:

• id, name, status, plan, billingStatus and cancelAtPeriodEnd;
• periodStart and periodEnd;
• caps, with storageBytes, variants and projects, where null means uncapped; and
• usage, with storageBytes, newVariants and projects.

It does not report delivery bandwidth. Every response is Cache-Control: no-store, and errors use the { "error": { "code": "…", "message": "…" } } body of every management API route.

GET https://app.dynjandi.dev/api/workspace/usage
Authorization: Bearer dyn_...

MCP server

An agent can manage a workspace, build and check variant URLs and read these docs through a remote MCP server. It uses the same API key as the management API.

https://mcp.dynjandi.dev/mcp

Connecting

• The server speaks MCP over Streamable HTTP, and every request is a POST to /mcp.
• Every request carries Authorization: Bearer followed by an API key, set once in the client's configuration. There is no sign-in flow and no OAuth.
• The server is for MCP clients that run on a server or on your own machine. It answers any request that carries an Origin header with 403 and has no CORS, so a web page cannot call it.
• A request with no bearer header, or one that is not 1 to 256 characters without spaces, answers 401 with WWW-Authenticate: Bearer realm="dynjandi". A client address is limited to 120 requests a minute, and a 429 carries Retry-After: 60.

The field names differ between clients. The URL and the header are what they all need:

{
  "mcpServers": {
    "dynjandi": {
      "type": "http",
      "url": "https://mcp.dynjandi.dev/mcp",
      "headers": {
        "Authorization": "Bearer dyn_..."
      }
    }
  }
}

Keep the configuration file out of version control, as for any other key.

Tools

There are twelve tools. The first nine act on the one workspace the key was created for, and the dashboard checks the key on each of those calls. The last three need no key that is real, only a well-formed bearer, and they never call the dashboard.

A tool failure comes back as an error result with an error code and a message, not as an HTTP status. A key the dashboard refuses is one such result.

What is not a tool

Uploading a file and deleting a file are not tools. Both stay on the REST API: see Upload and API keys. A project's public key is never returned by a tool.