Tools

Tools are the actions an MCP client invokes on your behalf. The client sends a JSON-RPC tools/call with the tool name and an arguments object; each tool below lists those arguments and shows an example. Every tool requires an API key with the right access level for the libraries it touches, and returns the same payload shape as the matching REST endpoint.

Tool	Access	Purpose
`whoami`	Read	Resolve your key's organization + library scope.
`create_organization`	Anonymous	Create an organization + library + API key for an agent — no account needed.
`create_library`	Write	Create a library in an organization you have a key for.
`rename_library`	Write	Rename a library.
`list_libraries`	Read	List libraries in an organization.
`list_assets`	Read	List assets in a library (paginated, tag filter).
`get_asset`	Read	Get one asset by id.
`search_assets`	Read	Search assets across libraries (ranked, highlights).
`list_tags`	Read	List a library's tags, by usage count.
`upload_asset`	Write	Upload one file from a URL or inline base64.
`upload_assets`	Write	Upload up to 20 files in one call.
`delete_assets`	Write	Move up to 100 assets to trash (soft delete).
`tag_assets`	Write	Apply up to 20 tags to up to 100 assets.
`untag_assets`	Write	Remove up to 20 tags from up to 100 assets.
`update_asset_description`	Write	Replace one asset's description (verbatim).
`transfer_assets`	Write	Move up to 100 assets between libraries.

`whoami`

Resolves the organization and libraries your API key can act on. Takes no arguments — it reads your Bearer key. Call this first when you have only a key: it returns the organizationId (and authorized library ids + plan) every other tool needs as input.

Parameters

None.

Returns

{ organizationId, organizationName, plan, libraries } — libraries is the list of library ids your key authorizes (use list_libraries for their names and counts); organizationName and plan are null when unavailable.

Example

{}

`create_organization`

Lets an AI agent create a brand-new organization (with a starter library) and start uploading files on someone's behalf — no Raster account or API key needed up front. Pass the person's email and it returns a ready-to-use API key (for the upload, list, and search tools) plus a link they click to claim the organization into their Raster account. The library and everything in it is held for 30 days so they can claim it; once claimed, it becomes a permanent part of their account. If you already have an organization and key and just need another library, use create_library instead.

Parameters

Prop

Type

Returns

Everything the agent needs to start uploading:

organizationId and libraryId — the target for upload_asset and the other tools. Pass both on every call.
apiKey — the key those calls authenticate with. Returned once, so save it.
claimUrl — the link the user opens to claim the library into their Raster account.
expiresAt — when the 30-day claim window closes.
emailSent — true if the claim link was emailed. If false, show the user the claimUrl directly so they can still claim it.

Example

{ "email": "[email protected]", "name": "Sample library" }

Response:

{
  "organizationId": "k3m9x7p2qar8zt",
  "libraryId": "b7n2w4j8x1c5dq",
  "emailSent": true,
  "apiKey": "rk_…",
  "claimUrl": "https://raster.app/claim/…",
  "expiresAt": "2026-06-27T00:00:00.000Z"
}

The agent then calls upload_asset (and the rest) with the minted apiKey as the Bearer token, passing the returned organizationId + libraryId as the target.

`create_library`

Creates a new library inside an organization you already have an API key for. The new library is added to your key's allowlist (so you can upload to it right away) and is shown to your whole team in the Raster app. To create a library with no account or key up front, use create_organization instead.

Parameters

Prop

Type

Returns

The new Library — zeroed counters, no tags. Fails when the key is invalid, the slug is taken, or a free-plan library cap is reached.

Example

{ "organizationId": "acme-co", "name": "Marketing", "slug": "marketing" }

`rename_library`

Renames a library your API key has access to. Updates the library name everywhere it's shown (including each team member's view); the URL slug is unchanged.

Parameters

Prop

Type

Returns

The updated Library. Fails with 404 when the key is not authorized for the library or the library does not exist.

Example

{ "organizationId": "acme-co", "libraryId": "marketing", "name": "Marketing 2026" }

`list_libraries`

Lists the libraries in an organization that your API key can reach.

Parameters

Prop

Type

Returns

An array of Library objects.

Example

{
  "organizationId": "acme-co"
}

Pagination for list_libraries is zero-based (page 0 is the first page), while list_assets and search_assets are 1-based (page 1 is the first page). This matches the REST and GraphQL APIs.

`list_assets`

Lists assets in a library, paginated and optionally filtered by tag.

Parameters

Prop

Type

Returns

An array of Asset objects.

Example

{
  "organizationId": "acme-co",
  "libraryId": "barcelona",
  "page": 1,
  "pageSize": 20,
  "tags": ["landscape", "nature"]
}

`get_asset`

Fetches a single asset by id — the same Asset payload list_assets returns, for one asset. Use it to read one asset's url, tags, description, and dimensions without paging the list.

Parameters

Prop

Type

Returns

The Asset. Fails with a 404 when the key is not authorized for the library, or the asset does not exist, belongs to another library, or is trashed.

Example

{ "organizationId": "acme-co", "libraryId": "marketing", "assetId": "k3m9x7p2qar8zt" }

`search_assets`

Searches assets across the libraries your API key authorizes, returning relevance-ranked hits with optional highlighted snippets. Organization-scoped — omit libraries to search every authorized library, or pass an explicit subset.

Parameters

Prop

Type

Returns

A SearchResult — { hits, found, page }, where each SearchHit is an Asset plus optional highlights (matched snippets, with <mark> tags on the name field) and a relevance score.

Example

{
  "organizationId": "acme-co",
  "q": "sunset",
  "libraries": ["barcelona", "lisbon"],
  "page": 1,
  "pageSize": 10
}

Naming an unauthorized library fails the whole call with API_KEY_NOT_AUTHORIZED_FOR_LIBRARY. Omit libraries to search every library the key authorizes.

Lists the tags used in a library, sorted by usage count (descending).

Parameters

Prop

Type

Returns

An array of Tag objects.

Example

{
  "organizationId": "acme-co",
  "libraryId": "barcelona",
  "limit": 10
}

The `Source` shape

upload_asset and upload_assets take their file payloads as a Source, a tagged union on kind. A source is either a remote URL the server fetches or an inline base64 payload:

// kind: "url" — the server fetches the file.
{ "kind": "url", "url": "https://example.com/cat.jpg" }

// kind: "base64" — you supply the bytes inline.
{
  "kind": "base64",
  "filename": "screenshot.png",
  "mimeType": "image/png",
  "data": "iVBORw0KGgoAAAANSUhEUgAA..."
}

The url variant must be an http(s) URL — other schemes are rejected at parse time, and for security, URLs that resolve to private or internal network addresses are rejected. The base64 variant requires filename and mimeType. Either way the per-file size cap (1 GB) is enforced before the bytes are accepted.

`upload_asset`

Uploads a single file to a library.

Parameters

Prop

Type

Returns

The same UploadedAssets shape as the REST upload endpoint — assets is a one-element array of Asset, each with a permanent CDN url (the canonical reference for the image) and an id (usable for other API calls).

Upload is asynchronous. The response returns immediately with the asset's url and id, but the image is still processing — the url starts serving (and the asset starts appearing in list_assets / search_assets) only once processing finishes, typically a few seconds later. Hold onto the url; it's permanent and goes live as soon as processing completes.

Example

Fetch from a URL:

{
  "organizationId": "acme-co",
  "libraryId": "barcelona",
  "source": { "kind": "url", "url": "https://example.com/cat.jpg" }
}

Upload bytes you generated locally (e.g. a screenshot):

{
  "organizationId": "acme-co",
  "libraryId": "barcelona",
  "source": {
    "kind": "base64",
    "filename": "screenshot.png",
    "mimeType": "image/png",
    "data": "iVBORw0KGgoAAAANSUhEUgAA..."
  }
}

`upload_assets`

Uploads between 1 and 20 files in a single call. Sources may mix url and base64.

Parameters

Prop

Type

Returns

UploadedAssets with one Asset per source, each with a permanent CDN url and an id. On full success assets[i] corresponds to sources[i].

As with upload_asset, upload is asynchronous: each url is returned immediately but starts serving — and the asset appears in list_assets / search_assets — only once processing finishes (typically a few seconds later).

Example

{
  "organizationId": "acme-co",
  "libraryId": "barcelona",
  "sources": [
    { "kind": "url", "url": "https://example.com/a.jpg" },
    { "kind": "url", "url": "https://example.com/b.jpg" }
  ]
}

Every source is validated (schema, address safety, size) before any byte is stored. If any source is invalid, the entire batch is rejected — there are no partial uploads.

`delete_assets`

Moves between 1 and 100 assets by id to trash (soft delete, like the Raster app). They leave list and search results right away, stay recoverable from trash, and are permanently removed after 30 days.

Parameters

Prop

Type

Returns

{ success, message, ids } — the same DeletedAssets payload as the REST delete endpoint. ids is the assets actually moved to trash (idempotent: re-deleting already-trashed ids returns "Moved 0 assets to trash", ids: [], success: true). Full semantics: DELETE /assets.

Example

{
  "organizationId": "acme-co",
  "libraryId": "barcelona",
  "ids": ["asset-123", "asset-456"]
}

`tag_assets`

Applies between 1 and 20 tags to between 1 and 100 assets in a single library, in one batched write.

Parameters

Prop

Type

Returns

{ taggedCount } — counts only (asset, tag) pairs that actually changed. Pairs the asset already carries are silent skips.

Example

{
  "organizationId": "acme-co",
  "libraryId": "barcelona",
  "assetIds": ["asset-123", "asset-456"],
  "tags": ["sunset", "landscape"]
}

{
  "organizationId": "acme-co",
  "libraryId": "barcelona",
  "assetIds": ["asset-123", "asset-456"],
  "tags": ["draft"]
}

{
  "organizationId": "acme-co",
  "libraryId": "barcelona",
  "assetId": "asset-123",
  "description": "Golden hour over the Mediterranean."
}

{
  "organizationId": "acme-co",
  "sourceLibraryId": "barcelona",
  "targetLibraryId": "archive",
  "assetIds": ["asset-123", "asset-456"]
}

Cross-organization transfer is rejected with BAD_USER_INPUT.

Limits

Tool	Cap
`list_assets`	At most 5 tags in the `tags` filter.
`search_assets`	`pageSize` clamps to 50 (default 10).
`upload_asset` / `upload_assets`	1 GB per file; up to 20 files per `upload_assets` call.
`delete_assets`	Up to 100 ids per call.
`tag_assets` / `untag_assets`	Up to 100 asset ids and 20 tag names per call.
`update_asset_description`	Up to 2000 characters.
`transfer_assets`	Up to 100 asset ids per call.

Exceeding a cap fails the call with BAD_USER_INPUT (400) — or PAYLOAD_TOO_LARGE (413) for the per-file size limit — before any write. See Errors.

On this page